# AI on Upsun
Source: https://developer.upsun.com/ai

Deploy AI agents, MCP servers, and intelligent applications on Upsun products

<div>
  <div>
    <div>
      # AI on Upsun

      <p>
        Let <span>Upsun Dispatch<sup>™</sup></span> plan, code, and review your software with governed AI-agent workflows. Use <span>Upsun Cloud</span> to deploy AI agents, MCP servers, RAG applications, and chatbots. Integrate with Claude, GPT, Gemini, and any LLM API.
      </p>
    </div>

    <div>
      <div>
        Agents
      </div>

      <div />
    </div>

    <div>
      <div>
        <div>
          <div>
            <svg>
              <path />
            </svg>

            Agentic Automation
          </div>

          <h2>
            <span>
              Upsun Dispatch
            </span>
          </h2>

          <p>
            Governed AI-agent workflows that plan, code, review, and optimize your software. Connect a repository, leave a comment, and Upsun Dispatch takes it from there.
          </p>

          <div>
            <div>
              <div>
                <svg>
                  <path />
                </svg>
              </div>

              <div>
                <h4>Turn issues into pull requests</h4>
                <p>Comment <span>@upsun-dispatch implement</span> on a GitHub, Jira, or Linear issue and Upsun Dispatch opens or updates a pull or merge request</p>
              </div>
            </div>

            <div>
              <div>
                <svg>
                  <path />
                </svg>
              </div>

              <div>
                <h4>Automated code review</h4>
                <p>Upsun Dispatch reviews GitHub pull requests and GitLab merge requests, publishing checks, comments, and summaries</p>
              </div>
            </div>

            <div>
              <div>
                <svg>
                  <path />
                </svg>
              </div>

              <div>
                <h4>Full visibility into every run</h4>
                <p>Monitor run status, logs, timelines, and usage from the Upsun Dispatch console</p>
              </div>
            </div>
          </div>

          <div>
            <a href="/dispatch">
              Explore Upsun Dispatch

              <svg>
                <path />
              </svg>
            </a>

            <a href="/dispatch/docs/get-started/quickstart">
              Quickstart
            </a>
          </div>
        </div>

        <div>
          <div>
            <div>
              <Icon icon="users" />
            </div>

            <div>
              <h3>Everyone works from the same run</h3>
              <p>Captured as it happens. Visible to the whole team, not just whoever kicked it off.</p>
            </div>
          </div>

          <div>
            <img alt="Upsun Dispatch run timeline showing an approved plan step and a live code step" />
          </div>
        </div>
      </div>
    </div>

    <div>
      <div>
        <div>
          <div>
            <div>
              <Icon icon="list-checks" />
            </div>

            <div>
              <h3>Findings are prioritized and actionable</h3>
              <p>A summary and recommendation, then findings ranked by impact.</p>
            </div>
          </div>

          <div>
            <img alt="Upsun Cloud performance-agent task report showing a summary, a recommendation, and a ranked list of findings" />
          </div>
        </div>

        <div>
          <div>
            <svg>
              <path />
            </svg>

            New: AI Observability
          </div>

          ## Upsun Cloud Performance Agent

          <p>
            Find performance bottlenecks without writing a profiling script or reading through hours of trace data. Get a report with actionable fixes.
          </p>

          <div>
            <div>
              <div>
                <svg>
                  <path />
                </svg>
              </div>

              <div>
                <h4>Correlates every signal you have</h4>
                <p>Profiling data, live traffic, and your source code, all analyzed in one pass</p>
              </div>
            </div>

            <div>
              <div>
                <svg>
                  <path />
                </svg>
              </div>

              <div>
                <h4>Nothing to install</h4>
                <p>Bring your own LLM API key and get a report in minutes</p>
              </div>
            </div>

            <div>
              <div>
                <svg>
                  <path />
                </svg>
              </div>

              <div>
                <h4>Findings with suggested diffs</h4>
                <p>Each report ranks bottlenecks and proposes a code fix, not just a graph</p>
              </div>
            </div>
          </div>

          <div>
            <a href="/docs/get-started/ai/upsun-cloud-performance-agent">
              Get Started with the Performance Agent

              <svg>
                <path />
              </svg>
            </a>
          </div>
        </div>
      </div>
    </div>

    <div>
      <div>
        Tools
      </div>

      <div />
    </div>

    <div>
      <div>
        <div>
          <div>
            <svg>
              <path />
            </svg>

            Model Context Protocol
          </div>

          ## Upsun MCP Server

          <p>
            Give Claude direct access to your Upsun infrastructure. Manage projects, environments, and deployments through natural language conversations.
          </p>

          <div>
            <div>
              <div>
                <svg>
                  <path />
                </svg>
              </div>

              <div>
                <h4>Deploy with natural language</h4>
                <p>Ask Claude to deploy your app, create environments, or scale resources</p>
              </div>
            </div>

            <div>
              <div>
                <svg>
                  <path />
                </svg>
              </div>

              <div>
                <h4>Manage infrastructure</h4>
                <p>Query logs, check metrics, and troubleshoot issues conversationally</p>
              </div>
            </div>

            <div>
              <div>
                <svg>
                  <path />
                </svg>
              </div>

              <div>
                <h4>Works with Claude Desktop</h4>
                <p>Seamless integration with your existing AI assistant workflow</p>
              </div>
            </div>
          </div>

          <div>
            <a href="/docs/get-started/ai/using-the-mcp">
              Get Started with MCP

              <svg>
                <path />
              </svg>
            </a>

            <a href="https://github.com/upsun/upsun-mcp-server#installation-instructions">
              All install options

              <svg>
                <path />
              </svg>
            </a>
          </div>
        </div>

        <div>
          <div>
            <div>
              <div />

              <div />

              <div />
            </div>

            <span>terminal</span>
          </div>

          <div>
            <div># Add the Upsun MCP Server</div>

            <div>
              <span>\$</span> claude mcp add --transport http upsun [https://mcp.upsun.com/mcp](https://mcp.upsun.com/mcp)
            </div>

            <div># Now ask Claude to deploy</div>
            <div>You: "Deploy my Next.js app to production"</div>

            <div>
              ✓ MCP Server connected<br />
              ✓ Found project: my-nextjs-app<br />
              ✓ Creating environment: main<br />
              ✓ Deploying application...<br />
              <span>✓ Deployment complete!</span>
            </div>
          </div>
        </div>
      </div>
    </div>

    <div>
      <div>
        <div>
          <div>
            <div>
              <div />

              <div />

              <div />
            </div>

            <span>Claude Code CLI</span>
          </div>

          <div>
            <div># Deploy with slash commands</div>

            <div>
              <span>claude></span> /upsun deploy --environment=main
            </div>

            <div>
              Building application 'myapp'...<br />
              Provisioning services...<br />
              <span>✓ Deployed to main</span>
            </div>

            <div># Check environment status</div>

            <div>
              <span>claude></span> /upsun status
            </div>
          </div>
        </div>

        <div>
          <div>
            <svg>
              <path />
            </svg>

            Claude Code Integration
          </div>

          ## Upsun Skill for Claude Code

          <p>
            Deploy directly from your terminal with Claude Code CLI. Manage your entire Upsun infrastructure without leaving your development environment.
          </p>

          <div>
            <div>
              <div>
                <svg>
                  <path />
                </svg>
              </div>

              <div>
                <h4>Slash command interface</h4>
                <p>Simple commands like /upsun deploy for instant deployment</p>
              </div>
            </div>

            <div>
              <div>
                <svg>
                  <path />
                </svg>
              </div>

              <div>
                <h4>Integrated workflow</h4>
                <p>Code, test, and deploy without context switching</p>
              </div>
            </div>

            <div>
              <div>
                <svg>
                  <path />
                </svg>
              </div>

              <div>
                <h4>Full environment control</h4>
                <p>Create, merge, and manage environments from the command line</p>
              </div>
            </div>
          </div>

          <a href="https://github.com/upsun/ai">
            View on GitHub

            <svg>
              <path />
            </svg>
          </a>
        </div>
      </div>
    </div>

    <div>
      <div>
        Apps
      </div>

      <div />
    </div>

    <div>
      <div>
        <div>
          <div>
            <div />

            <div />

            <div />
          </div>

          <span>terminal — bash</span>
        </div>

        <h2>Quick Start: Deploy an AI Agent</h2>

        <p>
          Get started with a simple Python AI agent that integrates with the Anthropic API.
        </p>

        <div>
          <div>
            <div>.upsun/config.yaml</div>

            <div>
              <div>applications:</div>
              <div>ai-agent:</div>
              <div>type: <span>"python:3.12"</span></div>
              <div>relationships:</div>
              <div>database: <span>"db:postgresql"</span></div>
              <div>hooks:</div>
              <div>build: |</div>
              <div>pip install anthropic flask</div>
              <div>web:</div>
              <div>commands:</div>
              <div>start: <span>"python app.py"</span></div>

              <div />

              <div>services:</div>
              <div>db:</div>
              <div>type: <span>postgresql:16</span></div>
            </div>
          </div>

          <div>
            <div>app.py</div>

            <div>
              <div>import <span>anthropic</span></div>
              <div>import <span>os</span></div>

              <div />

              <div>client = anthropic.Anthropic(</div>
              <div>api\_key=os.environ\[<span>"ANTHROPIC\_API\_KEY"</span>]</div>
              <div>)</div>

              <div />

              <div>message = client.messages.create(</div>
              <div>model=<span>"claude-3-5-sonnet-20241022"</span>,</div>
              <div>max\_tokens=<span>1024</span>,</div>
              <div>messages=\[</div>

              <div>]</div>
              <div>)</div>
            </div>
          </div>
        </div>

        <div>
          <div># Set your API key as an environment variable</div>

          <div>
            <span>\$</span>
            <span>upsun variable:create --level environment --name ANTHROPIC\_API\_KEY --value "your-key"</span>
          </div>

          <div># Deploy to Upsun</div>

          <div>
            <span>\$</span>
            <span>git push upsun main</span>
          </div>

          <div>
            Building application 'ai-agent'...
          </div>

          <div>
            Provisioning PostgreSQL database...
          </div>

          <div>
            ✓ Deployment complete
          </div>

          <div>
            [https://main-abc123.us-5.platformsh.site/](https://main-abc123.us-5.platformsh.site/)
          </div>
        </div>

        <a href="/docs/get-started/ai/aiagent">
          Full AI Agent Tutorial

          <svg>
            <path />
          </svg>
        </a>
      </div>
    </div>

    <div>
      <div>
        <svg>
          <path />
        </svg>

        Use Cases
      </div>

      ## What You Can Build

      <p>
        Deploy any AI application that integrates with LLM APIs. Upsun provides the infrastructure, databases, and networking you need.
      </p>

      <CardGroup>
        <Card title="AI Agents & Chatbots" href="/docs/get-started/ai/aiagent" icon="message-square">
          Deploy conversational AI powered by Claude, GPT, or Gemini with persistent chat history and context management.
        </Card>

        <Card title="MCP Servers" href="/docs/get-started/ai/deploy-mcp" icon="server">
          Host Model Context Protocol servers that extend Claude Desktop and other AI tools with custom capabilities.
        </Card>

        <Card title="RAG Applications" href="https://devcenter.upsun.com/posts/building-internal-ai-agents-for-our-teams-on-upsun/" icon="file-text">
          Build retrieval-augmented generation apps with vector databases like Chroma and Qdrant for context-aware AI responses.
        </Card>
      </CardGroup>
    </div>

    <div>
      <div>
        ## Supported Technologies

        <p>
          Build with your preferred stack. Any language, any LLM, any database.
        </p>

        <div>
          <div>
            <div>
              <svg>
                <path />
              </svg>
            </div>

            <h4>Runtimes</h4>

            <div>
              <span>Python</span>
              <span>Node.js</span>
              <span>PHP</span>
              <span>Go</span>
              <span>Ruby</span>
              <span>Java</span>
            </div>
          </div>

          <div>
            <div>
              <svg>
                <path />
              </svg>
            </div>

            <h4>LLM Providers</h4>

            <div>
              <span>Claude</span>
              <span>GPT-4</span>
              <span>Gemini</span>
              <span>Azure OpenAI</span>
              <span>Bedrock</span>
            </div>
          </div>

          <div>
            <div>
              <svg>
                <path />
              </svg>
            </div>

            <h4>AI Frameworks</h4>

            <div>
              <span>LangChain</span>
              <span>LlamaIndex</span>
              <span>Haystack</span>
              <span>Semantic Kernel</span>
            </div>
          </div>

          <div>
            <div>
              <svg>
                <path />
              </svg>
            </div>

            <h4>Vector Databases</h4>

            <div>
              <span>pgvector</span>
              <span>Chroma</span>
              <span>Qdrant</span>
              <span>Redis</span>
              <span>MongoDB</span>
            </div>
          </div>
        </div>

        <div>
          <div>
            <svg>
              <path />
            </svg>
          </div>

          <p>
            <span>CPU-optimized for AI orchestration.</span> Call external LLM APIs for GPU-intensive inference. Your app handles business logic, data processing, and UX — cost-effective and easy to scale.
          </p>
        </div>
      </div>
    </div>

    <div>
      <div>
        <svg>
          <path />
        </svg>

        Learn More
      </div>

      ## Resources & Tutorials

      <CardGroup>
        <Card title="AI Agent Guide" href="/docs/get-started/ai/aiagent" icon="bot">
          Complete guide to deploying conversational AI agents with persistent memory
        </Card>

        <Card title="Deploy MCP Servers" href="/docs/get-started/ai/deploy-mcp" icon="server">
          Host Model Context Protocol servers for Claude Desktop and other tools
        </Card>

        <Card title="Building AI Agents Tutorial" href="https://devcenter.upsun.com/posts/building-internal-ai-agents-for-our-teams-on-upsun/" icon="graduation-cap">
          Production RAG application with vector search and intelligent context
        </Card>

        <Card title="Vector Databases" href="/docs/add-services" icon="database">
          Set up Chroma, Qdrant, or pgvector for embeddings storage
        </Card>

        <Card title="AI Blog Posts" href="https://devcenter.upsun.com/posts/?tag=ai" icon="newspaper">
          Latest AI tutorials, best practices, and case studies
        </Card>

        <Card title="Community Forum" href="https://community.upsun.com" icon="messages-square">
          Get help and share your AI projects with the community
        </Card>
      </CardGroup>
    </div>

    <div>
      <h2>Ready to Deploy Your AI Application?</h2>

      <p>
        Start building AI agents, MCP servers, and intelligent applications on Upsun today.
      </p>

      <div>
        <a href="/docs/get-started/ai/aiagent">
          Start Tutorial →
        </a>

        <a href="https://github.com/orgs/upsun/repositories?q=topic%3Aai">
          Browse Examples
        </a>
      </div>
    </div>
  </div>
</div>


# Upsun MCP on your Agent
Source: https://developer.upsun.com/ai/mcp/integrations/all

How to integrate Upsun MCP into an agent

<Danger>TO-DO: Create this content!</Danger>


# Upsun MCP on Cursor
Source: https://developer.upsun.com/ai/mcp/integrations/cursor

How to integrate Upsun MCP into Cursor

<Danger>TO-DO: Create this content!</Danger>


# Upsun MCP on VSCode
Source: https://developer.upsun.com/ai/mcp/integrations/vscode

How to integrate Upsun MCP into VSCode

<Danger>TO-DO: Create this content!</Danger>


# Overview
Source: https://developer.upsun.com/ai/mcp/overview

Why use MCP

<Danger>TO-DO: Create this content!</Danger>


# Best Practices
Source: https://developer.upsun.com/ai/onboarding/best-practices

Best practices for onboarding with Upsun AI Tools

<Danger>TO-DO: Create this content!</Danger>


# Overview
Source: https://developer.upsun.com/ai/onboarding/overview

Help onboard new users with Upsun AI Tools

<Danger>TO-DO: Create this content!</Danger>


# Setup
Source: https://developer.upsun.com/ai/onboarding/setup

Set up onboarding with Upsun AI Tools

<Danger>TO-DO: Create this content!</Danger>


# Get add-ons
Source: https://developer.upsun.com/api-reference/add-ons/get-add-ons

https://meta.upsun.com/openapi-spec get /organizations/{organization_id}/addons
Retrieves information about the add-ons for an organization.



# Get usage alerts for a subscription
Source: https://developer.upsun.com/api-reference/alerts/get-usage-alerts-for-a-subscription

https://meta.upsun.com/openapi-spec get /alerts/subscriptions/{subscriptionId}/usage



# Update usage alerts.
Source: https://developer.upsun.com/api-reference/alerts/update-usage-alerts

https://meta.upsun.com/openapi-spec patch /alerts/subscriptions/{subscriptionId}/usage



# Create an API token
Source: https://developer.upsun.com/api-reference/api-tokens/create-an-api-token

https://meta.upsun.com/openapi-spec post /users/{user_id}/api-tokens
Creates an API token



# Delete an API token
Source: https://developer.upsun.com/api-reference/api-tokens/delete-an-api-token

https://meta.upsun.com/openapi-spec delete /users/{user_id}/api-tokens/{token_id}
Deletes an API token



# Get an API token
Source: https://developer.upsun.com/api-reference/api-tokens/get-an-api-token

https://meta.upsun.com/openapi-spec get /users/{user_id}/api-tokens/{token_id}
Retrieves the specified API token.



# List a user's API tokens
Source: https://developer.upsun.com/api-reference/api-tokens/list-a-users-api-tokens

https://meta.upsun.com/openapi-spec get /users/{user_id}/api-tokens
Retrieves a list of API tokens associated with a single user.



# Modifies Autoscaler settings
Source: https://developer.upsun.com/api-reference/autoscaling/modifies-autoscaler-settings

https://meta.upsun.com/openapi-spec patch /projects/{projectId}/environments/{environmentId}/autoscaling/settings
Modifies Autoscaler settings



# Retrieves Autoscaler settings
Source: https://developer.upsun.com/api-reference/autoscaling/retrieves-autoscaler-settings

https://meta.upsun.com/openapi-spec get /projects/{projectId}/environments/{environmentId}/autoscaling/settings
Retrieves Autoscaler settings



# Updates Autoscaler settings
Source: https://developer.upsun.com/api-reference/autoscaling/updates-autoscaler-settings

https://meta.upsun.com/openapi-spec post /projects/{projectId}/environments/{environmentId}/autoscaling/settings
Updates Autoscaler settings



# Get server cache metrics
Source: https://developer.upsun.com/api-reference/blackfire-monitoring/get-server-cache-metrics

https://meta.upsun.com/openapi-spec get /projects/{projectId}/environments/{environmentId}/observability/server/caches
Returns time-series PHP cache usage ratios (0.0-1.0) for OPcache memory, OPcache interned strings buffer (ISB), APCu memory, realpath cache, and PCRE cache. Includes hit rate ratios (0.0-1.0) for APCu and OPcache. Each data point contains `timestamp` and optional data fields. Fields are omitted for timestamps with no data - this indicates no data was received. Filtered by agent ID and execution contexts (web, cli, etc.).



# Get server monitoring overview
Source: https://developer.upsun.com/api-reference/blackfire-monitoring/get-server-monitoring-overview

https://meta.upsun.com/openapi-spec get /projects/{projectId}/environments/{environmentId}/observability/server
Returns time-series server monitoring data for the specified metrics (wall time, memory usage, peak memory usage, CPU load, stdout, requests per minute). Includes alert evaluations and APM quota usage. Data points contain metric values aggregated at the requested granularity.



# Get server transaction breakdown
Source: https://developer.upsun.com/api-reference/blackfire-monitoring/get-server-transaction-breakdown

https://meta.upsun.com/openapi-spec get /projects/{projectId}/environments/{environmentId}/observability/server/transactions-break-down
Returns transaction breakdown with impact scores, showing how each transaction contributes to overall resource consumption. Includes time-series data for top-hit transactions and aggregated metrics per transaction. Use breakdown_dimension to analyze by wall time (wt), memory (pmu), or stdout. Supports extensive filtering by context, transaction, host, framework, runtime, HTTP method, status code, and more.



# Get top spans
Source: https://developer.upsun.com/api-reference/blackfire-monitoring/get-top-spans

https://meta.upsun.com/openapi-spec get /projects/{projectId}/environments/{environmentId}/observability/server/top-spans
Returns the top spans aggregated across traces, sorted by impact or other metrics. Each span includes wall time, P96, call count, percentage of traces containing the span, and impact score. Supports filtering by context, transaction, host, framework, runtime, HTTP method/status, and service layer.



# Get profile call graph
Source: https://developer.upsun.com/api-reference/blackfire-profiling/get-profile-call-graph

https://meta.upsun.com/openapi-spec get /projects/{projectId}/environments/{environmentId}/observability/profiles/{uuid}/graph
Returns the call graph data for a Blackfire profile, showing function calls and their performance metrics.



# Get profile details
Source: https://developer.upsun.com/api-reference/blackfire-profiling/get-profile-details

https://meta.upsun.com/openapi-spec get /projects/{projectId}/environments/{environmentId}/observability/profiles/{uuid}/profile
Returns full profile data including metrics, metadata, and recommendations.



# Get profile subprofiles
Source: https://developer.upsun.com/api-reference/blackfire-profiling/get-profile-subprofiles

https://meta.upsun.com/openapi-spec get /projects/{projectId}/environments/{environmentId}/observability/profiles/{uuid}/subprofiles
Returns subprofiles (child profiles) associated with a Blackfire profile.



# Get profile timeline data
Source: https://developer.upsun.com/api-reference/blackfire-profiling/get-profile-timeline-data

https://meta.upsun.com/openapi-spec get /projects/{projectId}/environments/{environmentId}/observability/profiles/{uuid}/timeline
Returns timeline visualization data for a Blackfire profile, showing the execution flow over time.



# Get recommendation statistics
Source: https://developer.upsun.com/api-reference/blackfire-profiling/get-recommendation-statistics

https://meta.upsun.com/openapi-spec get /projects/{projectId}/environments/{environmentId}/observability/profiles/recommendations
Returns recommendation statistics for the environment, optionally filtered by transaction. Proxied from the Blackfire API. Each recommendation includes the constraint details, occurrence count, and links to the latest profile and documentation.



# List profiling results
Source: https://developer.upsun.com/api-reference/blackfire-profiling/list-profiling-results

https://meta.upsun.com/openapi-spec get /projects/{projectId}/environments/{environmentId}/observability/profiles
Returns a paginated list of profiles for the environment, optionally filtered by transaction name. Proxied from the Blackfire API.



# Add an SSL certificate
Source: https://developer.upsun.com/api-reference/cert-management/add-an-ssl-certificate

https://meta.upsun.com/openapi-spec post /projects/{projectId}/certificates
Add a single SSL certificate to a project.




# Delete an SSL certificate
Source: https://developer.upsun.com/api-reference/cert-management/delete-an-ssl-certificate

https://meta.upsun.com/openapi-spec delete /projects/{projectId}/certificates/{certificateId}
Delete a single SSL certificate associated with a project.




# Get an SSL certificate
Source: https://developer.upsun.com/api-reference/cert-management/get-an-ssl-certificate

https://meta.upsun.com/openapi-spec get /projects/{projectId}/certificates/{certificateId}
Retrieve information about a single SSL certificate
associated with a project.




# Get list of SSL certificates
Source: https://developer.upsun.com/api-reference/cert-management/get-list-of-ssl-certificates

https://meta.upsun.com/openapi-spec get /projects/{projectId}/certificates
Retrieve a list of objects representing the SSL certificates
associated with a project.




# Get projects provisioners
Source: https://developer.upsun.com/api-reference/cert-management/get-projects-provisioners

https://meta.upsun.com/openapi-spec get /projects/{projectId}/provisioners



# Get projects provisioners 1
Source: https://developer.upsun.com/api-reference/cert-management/get-projects-provisioners-1

https://meta.upsun.com/openapi-spec get /projects/{projectId}/provisioners/{certificateProvisionerDocumentId}



# Patch projects provisioners
Source: https://developer.upsun.com/api-reference/cert-management/patch-projects-provisioners

https://meta.upsun.com/openapi-spec patch /projects/{projectId}/provisioners/{certificateProvisionerDocumentId}



# Update an SSL certificate
Source: https://developer.upsun.com/api-reference/cert-management/update-an-ssl-certificate

https://meta.upsun.com/openapi-spec patch /projects/{projectId}/certificates/{certificateId}
Update a single SSL certificate associated with a project.




# Delete a federated login connection
Source: https://developer.upsun.com/api-reference/connections/delete-a-federated-login-connection

https://meta.upsun.com/openapi-spec delete /users/{user_id}/connections/{provider}
Deletes the specified connection.



# Get a federated login connection
Source: https://developer.upsun.com/api-reference/connections/get-a-federated-login-connection

https://meta.upsun.com/openapi-spec get /users/{user_id}/connections/{provider}
Retrieves the specified connection.



# List federated login connections
Source: https://developer.upsun.com/api-reference/connections/list-federated-login-connections

https://meta.upsun.com/openapi-spec get /users/{user_id}/connections
Retrieves a list of connections associated with a single user.



# Get application filter values
Source: https://developer.upsun.com/api-reference/continuous-profiling/get-application-filter-values

https://meta.upsun.com/openapi-spec get /projects/{projectId}/environments/{envId}/continuous-profiling/app/{app}/filter
Returns available label filter fields and their distinct values for the given application. Use these values to build filter parameters (`runtime[]`, `runtime_version[]`, etc.) on the timeline and merge endpoints



# Get application timeline
Source: https://developer.upsun.com/api-reference/continuous-profiling/get-application-timeline

https://meta.upsun.com/openapi-spec get /projects/{projectId}/environments/{envId}/continuous-profiling/app/{app}
Returns timeline data points for the given application and profile type, scoped to the authenticated agent. Points are aggregated at a computed grain (60s to 1h) based on the time range. The response includes the bounded time range, aggregation metadata, and the agent retention period



# Get merged profile
Source: https://developer.upsun.com/api-reference/continuous-profiling/get-merged-profile

https://meta.upsun.com/openapi-spec get /projects/{projectId}/environments/{envId}/continuous-profiling/app/{app}/merge
Returns a merged profile for the given application over the specified time range. The output format is controlled by the `out` query parameter: `pprof` returns a gzipped protobuf with Content-Disposition header, `dot` returns a GraphViz DOT graph, `flamebearerv2` returns JSON flame graph data



# List profiled applications
Source: https://developer.upsun.com/api-reference/continuous-profiling/list-profiled-applications

https://meta.upsun.com/openapi-spec get /projects/{projectId}/environments/{envId}/continuous-profiling
Returns all applications reporting continuous profiling data for the authenticated agent, scoped to the given time range. Each application includes its available profile types (with unit and aggregation metadata) and detected languages



# Create a project deployment target
Source: https://developer.upsun.com/api-reference/deployment-target/create-a-project-deployment-target

https://meta.upsun.com/openapi-spec post /projects/{projectId}/deployments
Set the deployment target information for a project.




# Delete a single project deployment target
Source: https://developer.upsun.com/api-reference/deployment-target/delete-a-single-project-deployment-target

https://meta.upsun.com/openapi-spec delete /projects/{projectId}/deployments/{deploymentTargetConfigurationId}
Delete a single deployment target configuration associated with a specific project.




# Get a single project deployment target
Source: https://developer.upsun.com/api-reference/deployment-target/get-a-single-project-deployment-target

https://meta.upsun.com/openapi-spec get /projects/{projectId}/deployments/{deploymentTargetConfigurationId}
Get a single deployment target configuration of a project.




# Get project deployment target info
Source: https://developer.upsun.com/api-reference/deployment-target/get-project-deployment-target-info

https://meta.upsun.com/openapi-spec get /projects/{projectId}/deployments
The deployment target information for the project.




# Update a project deployment
Source: https://developer.upsun.com/api-reference/deployment-target/update-a-project-deployment

https://meta.upsun.com/openapi-spec patch /projects/{projectId}/deployments/{deploymentTargetConfigurationId}



# Get a single environment deployment
Source: https://developer.upsun.com/api-reference/deployment/get-a-single-environment-deployment

https://meta.upsun.com/openapi-spec get /projects/{projectId}/environments/{environmentId}/deployments/{deploymentId}
Retrieve a single deployment configuration with an id of `current`. This may be subject to change in the future.
Only `current` can be queried.




# Get an environment's deployment information
Source: https://developer.upsun.com/api-reference/deployment/get-an-environments-deployment-information

https://meta.upsun.com/openapi-spec get /projects/{projectId}/environments/{environmentId}/deployments
Retrieve the read-only configuration of an environment's deployment.
The returned information is everything required to
recreate a project's current deployment.

More specifically, the objects
returned by this endpoint contain the configuration derived from the
repository's YAML configuration file: `.upsun/config.yaml`.

Additionally, any values deriving from environment variables, the
domains attached to a project, project access settings, etc. are
included here.

This endpoint currently returns a list containing a single deployment
configuration with an `id` of `current`. This may be subject to change
in the future.




# Get projects gitdiffs 
Source: https://developer.upsun.com/api-reference/diff/get-projects-gitdiffs-

https://meta.upsun.com/openapi-spec get /projects/{projectId}/git/diffs/{diffBaseId}/{diffTargetId}



# Get an organization discount
Source: https://developer.upsun.com/api-reference/discounts/get-an-organization-discount

https://meta.upsun.com/openapi-spec get /discounts/{id}



# Get the value of the First Project Incentive discount
Source: https://developer.upsun.com/api-reference/discounts/get-the-value-of-the-first-project-incentive-discount

https://meta.upsun.com/openapi-spec get /discounts/types/allowance



# List organization discounts
Source: https://developer.upsun.com/api-reference/discounts/list-organization-discounts

https://meta.upsun.com/openapi-spec get /organizations/{organization_id}/discounts
Retrieves all applicable discounts granted to the specified organization.



# Delete projects domain claims
Source: https://developer.upsun.com/api-reference/domain-claim/delete-projects-domain-claims

https://meta.upsun.com/openapi-spec delete /projects/{projectId}/domain-claims/{domainClaimId}



# Get projects domain claims
Source: https://developer.upsun.com/api-reference/domain-claim/get-projects-domain-claims

https://meta.upsun.com/openapi-spec get /projects/{projectId}/domain-claims



# Get projects domain claims 1
Source: https://developer.upsun.com/api-reference/domain-claim/get-projects-domain-claims-1

https://meta.upsun.com/openapi-spec get /projects/{projectId}/domain-claims/{domainClaimId}



# Patch projects domain claims
Source: https://developer.upsun.com/api-reference/domain-claim/patch-projects-domain-claims

https://meta.upsun.com/openapi-spec patch /projects/{projectId}/domain-claims/{domainClaimId}



# Post projects domain claims
Source: https://developer.upsun.com/api-reference/domain-claim/post-projects-domain-claims

https://meta.upsun.com/openapi-spec post /projects/{projectId}/domain-claims



# Add a project domain
Source: https://developer.upsun.com/api-reference/domain-management/add-a-project-domain

https://meta.upsun.com/openapi-spec post /projects/{projectId}/domains
Add a single domain to a project.
If the `ssl` field is left blank without an object containing
a PEM-encoded SSL certificate, a certificate will
[be provisioned for you via Let's Encrypt.](https://docs.upsun.com/anchors/routes/https/certificates/)




# Add an environment domain
Source: https://developer.upsun.com/api-reference/domain-management/add-an-environment-domain

https://meta.upsun.com/openapi-spec post /projects/{projectId}/environments/{environmentId}/domains
Add a single domain to an environment.
If the environment is not production, the `replacement_for` field
is required, which binds a new domain to an existing one from a
production environment.
If the `ssl` field is left blank without an object containing
a PEM-encoded SSL certificate, a certificate will
[be provisioned for you via Let's Encrypt](https://docs.upsun.com/anchors/routes/https/certificates/).




# Delete a project domain
Source: https://developer.upsun.com/api-reference/domain-management/delete-a-project-domain

https://meta.upsun.com/openapi-spec delete /projects/{projectId}/domains/{domainId}
Delete a single user-specified domain associated with a project.




# Delete an environment domain
Source: https://developer.upsun.com/api-reference/domain-management/delete-an-environment-domain

https://meta.upsun.com/openapi-spec delete /projects/{projectId}/environments/{environmentId}/domains/{domainId}
Delete a single user-specified domain associated with an environment.




# Get a list of environment domains
Source: https://developer.upsun.com/api-reference/domain-management/get-a-list-of-environment-domains

https://meta.upsun.com/openapi-spec get /projects/{projectId}/environments/{environmentId}/domains
Retrieve a list of objects representing the user-specified domains
associated with an environment. Note that this does *not* return the
`.platformsh.site` subdomains, which are automatically assigned to
the environment.




# Get a project domain
Source: https://developer.upsun.com/api-reference/domain-management/get-a-project-domain

https://meta.upsun.com/openapi-spec get /projects/{projectId}/domains/{domainId}
Retrieve information about a single user-specified domain
associated with a project.




# Get an environment domain
Source: https://developer.upsun.com/api-reference/domain-management/get-an-environment-domain

https://meta.upsun.com/openapi-spec get /projects/{projectId}/environments/{environmentId}/domains/{domainId}
Retrieve information about a single user-specified domain
associated with an environment.




# Get list of project domains
Source: https://developer.upsun.com/api-reference/domain-management/get-list-of-project-domains

https://meta.upsun.com/openapi-spec get /projects/{projectId}/domains
Retrieve a list of objects representing the user-specified domains
associated with a project. Note that this does *not* return the
domains automatically assigned to a project that appear under
"Access site" on the user interface.




# Update a project domain
Source: https://developer.upsun.com/api-reference/domain-management/update-a-project-domain

https://meta.upsun.com/openapi-spec patch /projects/{projectId}/domains/{domainId}
Update the information associated with a single user-specified
domain associated with a project.




# Update an environment domain
Source: https://developer.upsun.com/api-reference/domain-management/update-an-environment-domain

https://meta.upsun.com/openapi-spec patch /projects/{projectId}/environments/{environmentId}/domains/{domainId}
Update the information associated with a single user-specified
domain associated with an environment.




# Get observability entrypoint
Source: https://developer.upsun.com/api-reference/entrypoint/get-observability-entrypoint

https://meta.upsun.com/openapi-spec get /projects/{projectId}/environments/{environmentId}/observability
Returns API entrypoint with hypermedia links to all observability endpoints (resources, logs, HTTP traffic, continuous profiling, server metrics) following HATEOAS principles. Includes data retention policies per metric type (retention_period, max_range, recommended_default_range in minutes), environment metadata (project_id, environment_id, environment_type, vendor), and per-service resource links. Use _links for API navigation.



# Cancel an environment activity
Source: https://developer.upsun.com/api-reference/environment-activity/cancel-an-environment-activity

https://meta.upsun.com/openapi-spec post /projects/{projectId}/environments/{environmentId}/activities/{activityId}/cancel
Cancel a single activity as specified by an `id` returned by the
[Get environment activities list](#tag/Environment-Activity%2Fpaths%2F~1projects~1%7BprojectId%7D~1environments~1%7BenvironmentId%7D~1activities%2Fget)
endpoint.

Please note that not all activities are cancelable.




# Get an environment activity log entry
Source: https://developer.upsun.com/api-reference/environment-activity/get-an-environment-activity-log-entry

https://meta.upsun.com/openapi-spec get /projects/{projectId}/environments/{environmentId}/activities/{activityId}
Retrieve a single environment activity entry as specified by an
`id` returned by the
[Get environment activities list](#tag/Environment-Activity%2Fpaths%2F~1projects~1%7BprojectId%7D~1environments~1%7BenvironmentId%7D~1activities%2Fget)
endpoint. See the documentation on that endpoint for details about
the information this endpoint can return.




# Get environment activity log
Source: https://developer.upsun.com/api-reference/environment-activity/get-environment-activity-log

https://meta.upsun.com/openapi-spec get /projects/{projectId}/environments/{environmentId}/activities
Retrieve an environment's activity log. This returns a list of object
with records of actions such as:

- Commits being pushed to the repository
- A new environment being branched out from the specified environment
- A snapshot being created of the specified environment

The object includes a timestamp of when the action occurred
(`created_at`), when the action concluded (`updated_at`),
the current `state` of the action, the action's completion
percentage (`completion_percent`), and other related information in
the `payload`.

The contents of the `payload` varies based on the `type` of the
activity. For example:

- An `environment.branch` action's `payload` can contain objects
representing the `parent` environment and the branching action's
`outcome`.

- An `environment.push` action's `payload` can contain objects
representing the `environment`, the specific `commits` included in
the push, and the `user` who pushed.




# Create backup of environment
Source: https://developer.upsun.com/api-reference/environment-backups/create-backup-of-environment

https://meta.upsun.com/openapi-spec post /projects/{projectId}/environments/{environmentId}/backup
Trigger a new backup of an environment to be created. See the
[Backups](https://docs.upsun.com/anchors/environments/backup/)
section of the documentation for more information.




# Delete an environment backup
Source: https://developer.upsun.com/api-reference/environment-backups/delete-an-environment-backup

https://meta.upsun.com/openapi-spec delete /projects/{projectId}/environments/{environmentId}/backups/{backupId}
Delete a specific backup from an environment using the `id`
of the entry retrieved by the
[Get backups list](#tag/Environment-Backups%2Fpaths%2F~1projects~1%7BprojectId%7D~1environments~1%7BenvironmentId%7D~1backups%2Fget)
endpoint.




# Get an environment backup's info
Source: https://developer.upsun.com/api-reference/environment-backups/get-an-environment-backups-info

https://meta.upsun.com/openapi-spec get /projects/{projectId}/environments/{environmentId}/backups/{backupId}
Get the details of a specific backup from an environment using the `id`
of the entry retrieved by the
[Get backups list](#tag/Environment-Backups%2Fpaths%2F~1projects~1%7BprojectId%7D~1environments~1%7BenvironmentId%7D~1backups%2Fget)
endpoint.




# Get an environment's backup list
Source: https://developer.upsun.com/api-reference/environment-backups/get-an-environments-backup-list

https://meta.upsun.com/openapi-spec get /projects/{projectId}/environments/{environmentId}/backups
Retrieve a list of objects representing backups of this environment.




# Restore an environment snapshot
Source: https://developer.upsun.com/api-reference/environment-backups/restore-an-environment-snapshot

https://meta.upsun.com/openapi-spec post /projects/{projectId}/environments/{environmentId}/backups/{backupId}/restore
Restore a specific backup from an environment using the `id`
of the entry retrieved by the
[Get backups list](#tag/Environment-Backups%2Fpaths%2F~1projects~1%7BprojectId%7D~1environments~1%7BenvironmentId%7D~1backups%2Fget)
endpoint.




# Get environment type links
Source: https://developer.upsun.com/api-reference/environment-type/get-environment-type-links

https://meta.upsun.com/openapi-spec get /projects/{projectId}/environment-types/{environmentTypeId}
Lists the endpoints used to retrieve info about the environment type.



# Get environment types
Source: https://developer.upsun.com/api-reference/environment-type/get-environment-types

https://meta.upsun.com/openapi-spec get /projects/{projectId}/environment-types
List all available environment types



# Add an environment variable
Source: https://developer.upsun.com/api-reference/environment-variables/add-an-environment-variable

https://meta.upsun.com/openapi-spec post /projects/{projectId}/environments/{environmentId}/variables
Add a variable to an environment. The `value` can be either a string or a JSON
object (default: string), as specified by the `is_json` boolean flag.
Additionally, the inheritability of an environment variable can be
determined through the `is_inheritable` flag (default: true).
See the [Environment Variables](https://docs.upsun.com/anchors/variables/set/environment/create/)
section in our documentation for more information.




# Delete an environment variable
Source: https://developer.upsun.com/api-reference/environment-variables/delete-an-environment-variable

https://meta.upsun.com/openapi-spec delete /projects/{projectId}/environments/{environmentId}/variables/{variableId}
Delete a single user-defined environment variable.



# Get an environment variable
Source: https://developer.upsun.com/api-reference/environment-variables/get-an-environment-variable

https://meta.upsun.com/openapi-spec get /projects/{projectId}/environments/{environmentId}/variables/{variableId}
Retrieve a single user-defined environment variable.



# Get list of environment variables
Source: https://developer.upsun.com/api-reference/environment-variables/get-list-of-environment-variables

https://meta.upsun.com/openapi-spec get /projects/{projectId}/environments/{environmentId}/variables
Retrieve a list of objects representing the user-defined variables
within an environment.




# Update an environment variable
Source: https://developer.upsun.com/api-reference/environment-variables/update-an-environment-variable

https://meta.upsun.com/openapi-spec patch /projects/{projectId}/environments/{environmentId}/variables/{variableId}
Update a single user-defined environment variable.
The `value` can be either a string or a JSON
object (default: string), as specified by the `is_json` boolean flag.
Additionally, the inheritability of an environment variable can be
determined through the `is_inheritable` flag (default: true).
See the [Variables](https://docs.upsun.com/anchors/variables/)
section in our documentation for more information.




# Activate an environment
Source: https://developer.upsun.com/api-reference/environment/activate-an-environment

https://meta.upsun.com/openapi-spec post /projects/{projectId}/environments/{environmentId}/activate
Set the specified environment's status to active



# Branch an environment
Source: https://developer.upsun.com/api-reference/environment/branch-an-environment

https://meta.upsun.com/openapi-spec post /projects/{projectId}/environments/{environmentId}/branch
Create a new environment as a branch of the current environment.




# Deactivate an environment
Source: https://developer.upsun.com/api-reference/environment/deactivate-an-environment

https://meta.upsun.com/openapi-spec post /projects/{projectId}/environments/{environmentId}/deactivate
Destroy all services and data running on this environment so that
only the Git branch remains. The environment can be reactivated
later at any time; reactivating an environment will sync data
from the parent environment and redeploy.

**NOTE: ALL DATA IN THIS ENVIRONMENT WILL BE IRREVOCABLY LOST**




# Delete an environment
Source: https://developer.upsun.com/api-reference/environment/delete-an-environment

https://meta.upsun.com/openapi-spec delete /projects/{projectId}/environments/{environmentId}
Delete a specified environment.



# Deploy an environment
Source: https://developer.upsun.com/api-reference/environment/deploy-an-environment

https://meta.upsun.com/openapi-spec post /projects/{projectId}/environments/{environmentId}/deploy
Trigger a controlled [manual deployment](https://docs.upsun.com/learn/overview/build-deploy.html#manual-deployment)
to release all the staged changes




# Get an environment
Source: https://developer.upsun.com/api-reference/environment/get-an-environment

https://meta.upsun.com/openapi-spec get /projects/{projectId}/environments/{environmentId}
Retrieve the details of a single existing environment.



# Get list of project environments
Source: https://developer.upsun.com/api-reference/environment/get-list-of-project-environments

https://meta.upsun.com/openapi-spec get /projects/{projectId}/environments
Retrieve a list of a project's existing environments and the
information associated with each environment.




# Initialize a new environment
Source: https://developer.upsun.com/api-reference/environment/initialize-a-new-environment

https://meta.upsun.com/openapi-spec post /projects/{projectId}/environments/{environmentId}/initialize
Initialize and configure a new environment with an existing repository.
The payload is the url of a git repository with a profile name:

```
{
    "repository": "git@github.com:platformsh/a-project-template.git@master",
    "profile": "Example Project",
    "files": [
      {
        "mode": 0600,
        "path": "config.json",
        "contents": "XXXXXXXX"
      }
    ]
}
```
It can optionally carry additional files that will be committed to the
repository, the POSIX file mode to set on each file, and the base64-encoded
contents of each file.

This endpoint can also add a second repository
URL in the `config` parameter that will be added to the contents of the first.
This allows you to put your application in one repository and the Upsun
YAML configuration files in another.




# Merge an environment
Source: https://developer.upsun.com/api-reference/environment/merge-an-environment

https://meta.upsun.com/openapi-spec post /projects/{projectId}/environments/{environmentId}/merge
Merge an environment into its parent. This means that code changes
from the branch environment will be merged into the parent branch, and
the parent branch will be rebuilt and deployed with the new code changes,
retaining the existing data in the parent environment.




# Pause an environment
Source: https://developer.upsun.com/api-reference/environment/pause-an-environment

https://meta.upsun.com/openapi-spec post /projects/{projectId}/environments/{environmentId}/pause
Pause an environment, stopping all services and applications (except the router).

Development environments are often used for a limited time and then abandoned.
To prevent unnecessary consumption of resources, development environments that
haven't been redeployed in 14 days are automatically paused.

You can pause an environment manually at any time using this endpoint. Further
information is available in our [public documentation](https://docs.upsun.com/anchors/environments/paused/).




# Post projects environments maintenance redeploy
Source: https://developer.upsun.com/api-reference/environment/post-projects-environments-maintenance-redeploy

https://meta.upsun.com/openapi-spec post /projects/{projectId}/environments/{environmentId}/maintenance-redeploy



# Redeploy an environment
Source: https://developer.upsun.com/api-reference/environment/redeploy-an-environment

https://meta.upsun.com/openapi-spec post /projects/{projectId}/environments/{environmentId}/redeploy
Trigger the redeployment sequence of an environment.



# Resume a paused environment
Source: https://developer.upsun.com/api-reference/environment/resume-a-paused-environment

https://meta.upsun.com/openapi-spec post /projects/{projectId}/environments/{environmentId}/resume
Resume a paused environment, restarting all services and applications.

Development environments that haven't been used for 14 days will be paused
automatically. They can be resumed via a redeployment or manually using this
endpoint or the CLI as described in the [public documentation](https://docs.upsun.com/anchors/environments/paused/).




# Synchronize a child environment with its parent
Source: https://developer.upsun.com/api-reference/environment/synchronize-a-child-environment-with-its-parent

https://meta.upsun.com/openapi-spec post /projects/{projectId}/environments/{environmentId}/synchronize
This synchronizes the code and/or data of an environment with that of
its parent, then redeploys the environment. Synchronization is only
possible if a branch has no unmerged commits and it can be fast-forwarded.

If data synchronization is specified, the data in the environment will
be overwritten with that of its parent.




# Update an environment
Source: https://developer.upsun.com/api-reference/environment/update-an-environment

https://meta.upsun.com/openapi-spec patch /projects/{projectId}/environments/{environmentId}
Update the details of a single existing environment.



# Get access document by access ID
Source: https://developer.upsun.com/api-reference/grants/get-access-document-by-access-id

https://meta.upsun.com/openapi-spec get /access/{access_id}
Returns the full access document referenced by token claim `access_id`.



# List extended access of a user
Source: https://developer.upsun.com/api-reference/grants/list-extended-access-of-a-user

https://meta.upsun.com/openapi-spec get /users/{user_id}/extended-access
List extended access of the given user, which includes both individual and team access to project and organization.



# Get HTTP traffic timeline by IP
Source: https://developer.upsun.com/api-reference/http-traffic/get-http-traffic-timeline-by-ip

https://meta.upsun.com/openapi-spec get /projects/{projectId}/environments/{environmentId}/observability/http/breakdown/ips
Returns HTTP traffic analytics grouped by IP address with IPs ranked by impact (response time × request count). Use limit parameter to control total items returned (default: 200, max: 300) and top_hits_count to control how many items are flagged as top hits and tracked in the timeline (default: 10, max: 15). Items with index < top_hits_count are flagged with top_hit: true and tracked in top_hits_timeline; the remainder (up to limit) are returned with top_hit: false.



# Get HTTP traffic timeline by URL
Source: https://developer.upsun.com/api-reference/http-traffic/get-http-traffic-timeline-by-url

https://meta.upsun.com/openapi-spec get /projects/{projectId}/environments/{environmentId}/observability/http/breakdown/urls
Returns HTTP traffic analytics with URLs ranked by impact (response time × request count), aggregated metrics (average, median, p96 response times in milliseconds), status code distributions, and time-series data. Use limit parameter to control total items returned (default: 200, max: 300) and top_hits_count to control how many items are flagged as top hits and tracked in the timeline (default: 10, max: 15). Items with index < top_hits_count are flagged with top_hit: true and tracked in top_hits_timeline; the remainder (up to limit) are returned with top_hit: false.



# Get HTTP traffic timeline by user agent
Source: https://developer.upsun.com/api-reference/http-traffic/get-http-traffic-timeline-by-user-agent

https://meta.upsun.com/openapi-spec get /projects/{projectId}/environments/{environmentId}/observability/http/breakdown/user-agents
Returns HTTP traffic analytics grouped by User Agent with User Agents ranked by impact (response time × request count). Use limit parameter to control total items returned (default: 200, max: 300) and top_hits_count to control how many items are flagged as top hits and tracked in the timeline (default: 10, max: 15). Items with index < top_hits_count are flagged with top_hit: true and tracked in top_hits_timeline; the remainder (up to limit) are returned with top_hit: false.



# Get invoice
Source: https://developer.upsun.com/api-reference/invoices/get-invoice

https://meta.upsun.com/openapi-spec get /organizations/{organization_id}/invoices/{invoice_id}
Retrieves an invoice for the specified organization.



# List invoices
Source: https://developer.upsun.com/api-reference/invoices/list-invoices

https://meta.upsun.com/openapi-spec get /organizations/{organization_id}/invoices
Retrieves a list of invoices for the specified organization.



# List support tickets
Source: https://developer.upsun.com/api-reference/list-support-tickets

https://meta.upsun.com/openapi-spec get /tickets



# Confirm TOTP enrollment
Source: https://developer.upsun.com/api-reference/mfa/confirm-totp-enrollment

https://meta.upsun.com/openapi-spec post /users/{user_id}/totp
Confirms the given TOTP enrollment.



# Disable organization MFA enforcement
Source: https://developer.upsun.com/api-reference/mfa/disable-organization-mfa-enforcement

https://meta.upsun.com/openapi-spec post /organizations/{organization_id}/mfa-enforcement/disable
Disables MFA enforcement for the specified organization.



# Enable organization MFA enforcement
Source: https://developer.upsun.com/api-reference/mfa/enable-organization-mfa-enforcement

https://meta.upsun.com/openapi-spec post /organizations/{organization_id}/mfa-enforcement/enable
Enables MFA enforcement for the specified organization.



# Get information about TOTP enrollment
Source: https://developer.upsun.com/api-reference/mfa/get-information-about-totp-enrollment

https://meta.upsun.com/openapi-spec get /users/{user_id}/totp
Retrieves TOTP enrollment information.



# Get organization MFA settings
Source: https://developer.upsun.com/api-reference/mfa/get-organization-mfa-settings

https://meta.upsun.com/openapi-spec get /organizations/{organization_id}/mfa-enforcement
Retrieves MFA settings for the specified organization.



# Re-create recovery codes
Source: https://developer.upsun.com/api-reference/mfa/re-create-recovery-codes

https://meta.upsun.com/openapi-spec post /users/{user_id}/codes
Re-creates recovery codes for the MFA enrollment.



# Send MFA reminders to organization members
Source: https://developer.upsun.com/api-reference/mfa/send-mfa-reminders-to-organization-members

https://meta.upsun.com/openapi-spec post /organizations/{organization_id}/mfa/remind
Sends a reminder about setting up MFA to the specified organization members.



# Withdraw TOTP enrollment
Source: https://developer.upsun.com/api-reference/mfa/withdraw-totp-enrollment

https://meta.upsun.com/openapi-spec delete /users/{user_id}/totp
Withdraws from the TOTP enrollment.



# Create confirmation credentials for for 3D-Secure
Source: https://developer.upsun.com/api-reference/orders/create-confirmation-credentials-for-for-3d-secure

https://meta.upsun.com/openapi-spec post /organizations/{organization_id}/orders/{order_id}/authorize
Creates confirmation credentials for payments that require online authorization



# Download an invoice.
Source: https://developer.upsun.com/api-reference/orders/download-an-invoice

https://meta.upsun.com/openapi-spec get /orders/download



# Get order
Source: https://developer.upsun.com/api-reference/orders/get-order

https://meta.upsun.com/openapi-spec get /organizations/{organization_id}/orders/{order_id}
Retrieves an order for the specified organization.



# List orders
Source: https://developer.upsun.com/api-reference/orders/list-orders

https://meta.upsun.com/openapi-spec get /organizations/{organization_id}/orders
Retrieves orders for the specified organization.



# Cancel a pending invitation to an organization
Source: https://developer.upsun.com/api-reference/organization-invitations/cancel-a-pending-invitation-to-an-organization

https://meta.upsun.com/openapi-spec delete /organizations/{organization_id}/invitations/{invitation_id}
Cancels the specified invitation.



# Invite user to an organization by email
Source: https://developer.upsun.com/api-reference/organization-invitations/invite-user-to-an-organization-by-email

https://meta.upsun.com/openapi-spec post /organizations/{organization_id}/invitations
Creates an invitation to an organization for a user with the specified email address.



# List invitations to an organization
Source: https://developer.upsun.com/api-reference/organization-invitations/list-invitations-to-an-organization

https://meta.upsun.com/openapi-spec get /organizations/{organization_id}/invitations
Returns a list of invitations to an organization.



# Estimate total spend
Source: https://developer.upsun.com/api-reference/organization-management/estimate-total-spend

https://meta.upsun.com/openapi-spec get /organizations/{organization_id}/estimate
Estimates the total spend for the specified organization.



# Get billing alert configuration
Source: https://developer.upsun.com/api-reference/organization-management/get-billing-alert-configuration

https://meta.upsun.com/openapi-spec get /organizations/{organization_id}/alerts/billing
Retrieves billing alert configuration for the specified organization.



# Get organization prepayment information
Source: https://developer.upsun.com/api-reference/organization-management/get-organization-prepayment-information

https://meta.upsun.com/openapi-spec get /organizations/{organization_id}/prepayment
Retrieves prepayment information for the specified organization, if applicable.



# List organization prepayment transactions
Source: https://developer.upsun.com/api-reference/organization-management/list-organization-prepayment-transactions

https://meta.upsun.com/openapi-spec get /organizations/{organization_id}/prepayment/transactions
Retrieves a list of prepayment transactions for the specified organization, if applicable.



# Update billing alert configuration
Source: https://developer.upsun.com/api-reference/organization-management/update-billing-alert-configuration

https://meta.upsun.com/openapi-spec patch /organizations/{organization_id}/alerts/billing
Updates billing alert configuration for the specified organization.



# Create organization member
Source: https://developer.upsun.com/api-reference/organization-members/create-organization-member

https://meta.upsun.com/openapi-spec post /organizations/{organization_id}/members
Creates a new organization member.



# Delete organization member
Source: https://developer.upsun.com/api-reference/organization-members/delete-organization-member

https://meta.upsun.com/openapi-spec delete /organizations/{organization_id}/members/{user_id}
Deletes the specified organization member.



# Get organization member
Source: https://developer.upsun.com/api-reference/organization-members/get-organization-member

https://meta.upsun.com/openapi-spec get /organizations/{organization_id}/members/{user_id}
Retrieves the specified organization member.



# List organization members
Source: https://developer.upsun.com/api-reference/organization-members/list-organization-members

https://meta.upsun.com/openapi-spec get /organizations/{organization_id}/members
Accessible to organization owners and members with the "manage members" permission.



# Update organization member
Source: https://developer.upsun.com/api-reference/organization-members/update-organization-member

https://meta.upsun.com/openapi-spec patch /organizations/{organization_id}/members/{user_id}
Updates the specified organization member.



# Create project
Source: https://developer.upsun.com/api-reference/organization-projects/create-project

https://meta.upsun.com/openapi-spec post /organizations/{organization_id}/projects
Creates a new project in the specified organization.



# Delete project
Source: https://developer.upsun.com/api-reference/organization-projects/delete-project

https://meta.upsun.com/openapi-spec delete /organizations/{organization_id}/projects/{project_id}
Deletes the specified project.



# Get project
Source: https://developer.upsun.com/api-reference/organization-projects/get-project

https://meta.upsun.com/openapi-spec get /organizations/{organization_id}/projects/{project_id}
Retrieves the specified project.



# List projects
Source: https://developer.upsun.com/api-reference/organization-projects/list-projects

https://meta.upsun.com/openapi-spec get /organizations/{organization_id}/projects
Retrieves a list of projects for the specified organization.



# Query project carbon emissions metrics
Source: https://developer.upsun.com/api-reference/organization-projects/query-project-carbon-emissions-metrics

https://meta.upsun.com/openapi-spec get /organizations/{organization_id}/projects/{project_id}/metrics/carbon
Queries the carbon emission data for the specified project using the supplied parameters.



# Stream provisioning progress
Source: https://developer.upsun.com/api-reference/organization-projects/stream-provisioning-progress

https://meta.upsun.com/openapi-spec get /organizations/{organization_id}/projects/provisioning
Streams real-time provisioning progress for projects being created in the
specified organization. The response is an NDJSON stream where each line
is a JSON object representing a provisioning event.

The stream emits events as provisioning stages complete and terminates
automatically when all in-flight projects finish (or fail). A keep-alive
event is sent periodically to prevent connection timeouts.

The body is a newline-delimited stream of JSON objects.
Each line is a single `ProvisionEvent`.

The `data`, `done`, and `error` events include a `steps` array listing the ordered provisioning steps.

Event types:
- `data` — a provisioning stage completed
- `done` — provisioning finished successfully
- `error` — provisioning failed
- `keep_alive` — connection keep-alive




# Update project
Source: https://developer.upsun.com/api-reference/organization-projects/update-project

https://meta.upsun.com/openapi-spec patch /organizations/{organization_id}/projects/{project_id}
Updates the specified project.



# Create organization
Source: https://developer.upsun.com/api-reference/organizations/create-organization

https://meta.upsun.com/openapi-spec post /organizations
Creates a new organization.



# Delete organization
Source: https://developer.upsun.com/api-reference/organizations/delete-organization

https://meta.upsun.com/openapi-spec delete /organizations/{organization_id}
Deletes the specified organization.



# Get organization
Source: https://developer.upsun.com/api-reference/organizations/get-organization

https://meta.upsun.com/openapi-spec get /organizations/{organization_id}
Retrieves the specified organization.



# List organizations
Source: https://developer.upsun.com/api-reference/organizations/list-organizations

https://meta.upsun.com/openapi-spec get /organizations
Non-admin users will only see organizations they are members of.



# Update organization
Source: https://developer.upsun.com/api-reference/organizations/update-organization

https://meta.upsun.com/openapi-spec patch /organizations/{organization_id}
Updates the specified organization.



# User organizations
Source: https://developer.upsun.com/api-reference/organizations/user-organizations

https://meta.upsun.com/openapi-spec get /users/{user_id}/organizations
Retrieves organizations that the specified user is a member of.



# Confirm phone number
Source: https://developer.upsun.com/api-reference/phonenumber/confirm-phone-number

https://meta.upsun.com/openapi-spec post /users/{user_id}/phonenumber/{sid}
Confirms phone number using a verification code.



# Verify phone number
Source: https://developer.upsun.com/api-reference/phonenumber/verify-phone-number

https://meta.upsun.com/openapi-spec post /users/{user_id}/phonenumber
Starts a phone number verification session.



# Get address
Source: https://developer.upsun.com/api-reference/profiles/get-address

https://meta.upsun.com/openapi-spec get /organizations/{organization_id}/address
Retrieves the address for the specified organization.



# Get profile
Source: https://developer.upsun.com/api-reference/profiles/get-profile

https://meta.upsun.com/openapi-spec get /organizations/{organization_id}/profile
Retrieves the profile for the specified organization.



# Update address
Source: https://developer.upsun.com/api-reference/profiles/update-address

https://meta.upsun.com/openapi-spec patch /organizations/{organization_id}/address
Updates the address for the specified organization.



# Update profile
Source: https://developer.upsun.com/api-reference/profiles/update-profile

https://meta.upsun.com/openapi-spec patch /organizations/{organization_id}/profile
Updates the profile for the specified organization.



# Cancel a project activity
Source: https://developer.upsun.com/api-reference/project-activity/cancel-a-project-activity

https://meta.upsun.com/openapi-spec post /projects/{projectId}/activities/{activityId}/cancel
Cancel a single activity as specified by an `id` returned by the
[Get project activity log](#tag/Project-Activity%2Fpaths%2F~1projects~1%7BprojectId%7D~1activities%2Fget)
endpoint.

Please note that not all activities are cancelable.




# Get a project activity log entry
Source: https://developer.upsun.com/api-reference/project-activity/get-a-project-activity-log-entry

https://meta.upsun.com/openapi-spec get /projects/{projectId}/activities/{activityId}
Retrieve a single activity log entry as specified by an
`id` returned by the
[Get project activity log](#tag/Project-Activity%2Fpaths%2F~1projects~1%7BprojectId%7D~1activities%2Fget)
endpoint. See the documentation on that endpoint for details about
the information this endpoint can return.




# Get project activity log
Source: https://developer.upsun.com/api-reference/project-activity/get-project-activity-log

https://meta.upsun.com/openapi-spec get /projects/{projectId}/activities
Retrieve a project's activity log including logging actions in all
environments within a project. This returns a list of objects
with records of actions such as:

- Commits being pushed to the repository
- A new environment being branched out from the specified environment
- A snapshot being created of the specified environment

The object includes a timestamp of when the action occurred
(`created_at`), when the action concluded (`updated_at`),
the current `state` of the action, the action's completion
percentage (`completion_percent`), the `environments` it
applies to and when the activity expires (`expires_at`).

There are other related information in the `payload`.
The contents of the `payload` varies based on the `type` of the
activity. For example:

- An `environment.branch` action's `payload` can contain objects
representing the environment's `parent` environment and the
branching action's `outcome`.

- An `environment.push` action's `payload` can contain objects
representing the `environment`, the specific `commits` included in
the push, and the `user` who pushed.

Expired activities are removed from the project activity log, except
the last 100 expired objects provided they are not of type `environment.cron`
or `environment.backup`.




# Cancel a pending invitation to a project
Source: https://developer.upsun.com/api-reference/project-invitations/cancel-a-pending-invitation-to-a-project

https://meta.upsun.com/openapi-spec delete /projects/{project_id}/invitations/{invitation_id}
Cancels the specified invitation.



# Invite user to a project by email
Source: https://developer.upsun.com/api-reference/project-invitations/invite-user-to-a-project-by-email

https://meta.upsun.com/openapi-spec post /projects/{project_id}/invitations
Creates an invitation to a project for a user with the specified email address.



# List invitations to a project
Source: https://developer.upsun.com/api-reference/project-invitations/list-invitations-to-a-project

https://meta.upsun.com/openapi-spec get /projects/{project_id}/invitations
Returns a list of invitations to a project.



# Get list of project settings
Source: https://developer.upsun.com/api-reference/project-settings/get-list-of-project-settings

https://meta.upsun.com/openapi-spec get /projects/{projectId}/settings
Retrieve the global settings for a project.



# Update a project setting
Source: https://developer.upsun.com/api-reference/project-settings/update-a-project-setting

https://meta.upsun.com/openapi-spec patch /projects/{projectId}/settings
Update one or more project-level settings.



# Add a project variable
Source: https://developer.upsun.com/api-reference/project-variables/add-a-project-variable

https://meta.upsun.com/openapi-spec post /projects/{projectId}/variables
Add a variable to a project. The `value` can be either a string or a JSON
object (default: string), as specified by the `is_json` boolean flag.
See the [Variables](https://docs.upsun.com/anchors/variables/set/project/create/)
section in our documentation for more information.




# Delete a project variable
Source: https://developer.upsun.com/api-reference/project-variables/delete-a-project-variable

https://meta.upsun.com/openapi-spec delete /projects/{projectId}/variables/{projectVariableId}
Delete a single user-defined project variable.



# Get a project variable
Source: https://developer.upsun.com/api-reference/project-variables/get-a-project-variable

https://meta.upsun.com/openapi-spec get /projects/{projectId}/variables/{projectVariableId}
Retrieve a single user-defined project variable.



# Get list of project variables
Source: https://developer.upsun.com/api-reference/project-variables/get-list-of-project-variables

https://meta.upsun.com/openapi-spec get /projects/{projectId}/variables
Retrieve a list of objects representing the user-defined variables
within a project.




# Update a project variable
Source: https://developer.upsun.com/api-reference/project-variables/update-a-project-variable

https://meta.upsun.com/openapi-spec patch /projects/{projectId}/variables/{projectVariableId}
Update a single user-defined project variable.
The `value` can be either a string or a JSON
object (default: string), as specified by the `is_json` boolean flag.
See the [Variables](https://docs.upsun.com/anchors/variables/set/project/create/)
section in our documentation for more information.




# Clear project build cache
Source: https://developer.upsun.com/api-reference/project/clear-project-build-cache

https://meta.upsun.com/openapi-spec post /projects/{projectId}/clear_build_cache
On rare occasions, a project's build cache can become corrupted. This
endpoint will entirely flush the project's build cache. More information
on [clearing the build cache can be found in our user documentation.](https://docs.upsun.com/anchors/troubleshoot/clear-build-cache/)




# Get a project
Source: https://developer.upsun.com/api-reference/project/get-a-project

https://meta.upsun.com/openapi-spec get /projects/{projectId}
Retrieve the details of a single project.



# Get a project's capabilities
Source: https://developer.upsun.com/api-reference/project/get-a-projects-capabilities

https://meta.upsun.com/openapi-spec get /projects/{projectId}/capabilities
Get a list of capabilities on a project, as defined by the billing system.
For instance, one special capability that could be defined on a project is
large development environments.




# Post projects maintenance redeploy
Source: https://developer.upsun.com/api-reference/project/post-projects-maintenance-redeploy

https://meta.upsun.com/openapi-spec post /projects/{projectId}/maintenance-redeploy



# List project history
Source: https://developer.upsun.com/api-reference/projects/list-project-history

https://meta.upsun.com/openapi-spec get /organizations/{organization_id}/projects/{project_id}/history
Retrieves history records for the specified project, oldest first.



# Query project carbon emissions metrics for an entire organization
Source: https://developer.upsun.com/api-reference/query-project-carbon-emissions-metrics-for-an-entire-organization

https://meta.upsun.com/openapi-spec get /organizations/{organization_id}/metrics/carbon
Queries the carbon emission data for all projects owned by the specified organiation.



# List plan records
Source: https://developer.upsun.com/api-reference/records/list-plan-records

https://meta.upsun.com/openapi-spec get /organizations/{organization_id}/records/plan
Retrieves plan records for the specified organization.



# List usage records
Source: https://developer.upsun.com/api-reference/records/list-usage-records

https://meta.upsun.com/openapi-spec get /organizations/{organization_id}/records/usage
Retrieves usage records for the specified organization.



# List referenced organizations
Source: https://developer.upsun.com/api-reference/references/list-referenced-organizations

https://meta.upsun.com/openapi-spec get /ref/organizations
Retrieves a list of organizations referenced by a trusted service. Clients cannot construct the URL themselves. The correct URL will be provided in the HAL links of another API response, in the <code>_links</code> object with a key like <code>ref:organizations:0</code>.



# List referenced projects
Source: https://developer.upsun.com/api-reference/references/list-referenced-projects

https://meta.upsun.com/openapi-spec get /ref/projects
Retrieves a list of projects referenced by a trusted service. Clients cannot construct the URL themselves. The correct URL will be provided in the HAL links of another API response, in the <code>_links</code> object with a key like <code>ref:projects:0</code>.



# List referenced regions
Source: https://developer.upsun.com/api-reference/references/list-referenced-regions

https://meta.upsun.com/openapi-spec get /ref/regions
Retrieves a list of regions referenced by a trusted service. Clients cannot construct the URL themselves. The correct URL will be provided in the HAL links of another API response, in the <code>_links</code> object with a key like <code>ref:regions:0</code>.



# List referenced teams
Source: https://developer.upsun.com/api-reference/references/list-referenced-teams

https://meta.upsun.com/openapi-spec get /ref/teams
Retrieves a list of teams referenced by a trusted service. Clients cannot construct the URL themselves. The correct URL will be provided in the HAL links of another API response, in the <code>_links</code> object with a key like <code>ref:teams:0</code>.



# List referenced users
Source: https://developer.upsun.com/api-reference/references/list-referenced-users

https://meta.upsun.com/openapi-spec get /ref/users
Retrieves a list of users referenced by a trusted service. Clients cannot construct the URL themselves. The correct URL will be provided in the HAL links of another API response, in the <code>_links</code> object with a key like <code>ref:users:0</code>.



# Get region
Source: https://developer.upsun.com/api-reference/regions/get-region

https://meta.upsun.com/openapi-spec get /regions/{region_id}
Retrieves the specified region.



# List regions
Source: https://developer.upsun.com/api-reference/regions/list-regions

https://meta.upsun.com/openapi-spec get /regions
Retrieves a list of available regions.



# Get a blob object
Source: https://developer.upsun.com/api-reference/repository/get-a-blob-object

https://meta.upsun.com/openapi-spec get /projects/{projectId}/git/blobs/{repositoryBlobId}
Retrieve, by hash, an object representing a blob in the repository
backing a project. This endpoint allows direct read-only access
to the contents of files in a repo. It returns the file in the
`content` field of the response object, encoded according to the
format in the `encoding` field, e.g. `base64`.




# Get a commit object
Source: https://developer.upsun.com/api-reference/repository/get-a-commit-object

https://meta.upsun.com/openapi-spec get /projects/{projectId}/git/commits/{repositoryCommitId}
Retrieve, by hash, an object representing a commit in the repository backing
a project. This endpoint functions similarly to `git cat-file -p <commit-id>`.
The returned object contains the hash of the Git tree that it
belongs to, as well as the ID of parent commits.

The commit represented by a parent ID can be retrieved using this
endpoint, while the tree state represented by this commit can
be retrieved using the
[Get a tree object](#tag/Git-Repo%2Fpaths%2F~1projects~1%7BprojectId%7D~1git~1trees~1%7BrepositoryTreeId%7D%2Fget)
endpoint.




# Get a ref object
Source: https://developer.upsun.com/api-reference/repository/get-a-ref-object

https://meta.upsun.com/openapi-spec get /projects/{projectId}/git/refs/{repositoryRefId}
Retrieve the details of a single `refs` object in the repository
backing a project. This endpoint functions similarly to
`git show-ref <pattern>`, although the pattern must be a full ref `id`,
rather than a matching pattern.

*NOTE: The `{repositoryRefId}` must be properly escaped.*
That is, the ref `refs/heads/master` is accessible via
`/projects/{projectId}/git/refs/heads%2Fmaster`.




# Get a tree object
Source: https://developer.upsun.com/api-reference/repository/get-a-tree-object

https://meta.upsun.com/openapi-spec get /projects/{projectId}/git/trees/{repositoryTreeId}
Retrieve, by hash, the tree state represented by a commit.
The returned object's `tree` field contains a list of files and
directories present in the tree.

Directories in the tree can be recursively retrieved by this endpoint
through their hashes. Files in the tree can be retrieved by the
[Get a blob object](#tag/Git-Repo%2Fpaths%2F~1projects~1%7BprojectId%7D~1git~1blobs~1%7BrepositoryBlobId%7D%2Fget)
endpoint.




# Get list of repository refs
Source: https://developer.upsun.com/api-reference/repository/get-list-of-repository-refs

https://meta.upsun.com/openapi-spec get /projects/{projectId}/git/refs
Retrieve a list of `refs/*` in the repository backing a project.
This endpoint functions similarly to `git show-ref`, with each
returned object containing a `ref` field with the ref's name,
and an object containing the associated commit ID.

The returned commit ID can be used with the
[Get a commit object](#tag/Git-Repo%2Fpaths%2F~1projects~1%7BprojectId%7D~1git~1commits~1%7BrepositoryCommitId%7D%2Fget)
endpoint to retrieve information about that specific commit.




# Get resource metrics by service
Source: https://developer.upsun.com/api-reference/resources/get-resource-metrics-by-service

https://meta.upsun.com/openapi-spec get /projects/{projectId}/environments/{environmentId}/observability/resources/service/{service}
Returns time-series resource data for one service. Each timestamp contains per-instance metrics. Filter results using aggs[] (min, max, avg, stddev, p50, p95-p99) and types[] (cpu, memory, swap, disk, inodes, pressure metrics). Response grouped by timestamp then instance ID (e.g., "app.0"). All aggregations nullable when insufficient data exists.



# Get resource metrics overview
Source: https://developer.upsun.com/api-reference/resources/get-resource-metrics-overview

https://meta.upsun.com/openapi-spec get /projects/{projectId}/environments/{environmentId}/observability/resources/overview
Returns time-series resource utilization data for all services. Each timestamp includes per-service metrics: CPU (cores), memory (bytes), swap (bytes), pressure indicators (0.0-1.0), and per-mountpoint disk/inode usage. All metrics include statistical aggregations: min, max, avg, stddev, and percentiles (p50, p95-p99). Service names and mountpoint paths are dynamic. Aggregation values are nullable when insufficient data exists.



# Get resource metrics summary
Source: https://developer.upsun.com/api-reference/resources/get-resource-metrics-summary

https://meta.upsun.com/openapi-spec get /projects/{projectId}/environments/{environmentId}/observability/resources/summary
Returns per-instance resource statistics aggregated over the time range. Filter results using aggs[] (min, max, avg, stddev, p50, p95-p99) and types[] (cpu, memory, swap, disk, inodes, pressure metrics). Response grouped by service name then instance ID (e.g., "app.0", "database.1"). All aggregations nullable when insufficient data exists.



# Get a route's info
Source: https://developer.upsun.com/api-reference/routing/get-a-routes-info

https://meta.upsun.com/openapi-spec get /projects/{projectId}/environments/{environmentId}/routes/{routeId}
Get details of a route from an environment using the `id` of the entry
retrieved by the [Get environment routes list](#tag/Environment-Routes%2Fpaths%2F~1projects~1%7BprojectId%7D~1environments~1%7BenvironmentId%7D~1routes%2Fget)
endpoint.




# Get list of routes
Source: https://developer.upsun.com/api-reference/routing/get-list-of-routes

https://meta.upsun.com/openapi-spec get /projects/{projectId}/environments/{environmentId}/routes
Retrieve a list of objects containing route definitions for
a specific environment. The definitions returned by this endpoint
are those present in an environment's `.upsun/config.yaml` file.




# Execute a runtime operation
Source: https://developer.upsun.com/api-reference/runtime-operations/execute-a-runtime-operation

https://meta.upsun.com/openapi-spec post /projects/{projectId}/environments/{environmentId}/deployments/{deploymentId}/operations
Execute a runtime operation on a currently deployed environment. This allows you to run one-off commands, such as rebuilding static assets on demand, by defining an `operations` key in a project's `.upsun/config.yaml` configuration. More information on runtime operations is [available in our user documentation](https://docs.upsun.com/anchors/app/runtime-operations/).



# List source operations
Source: https://developer.upsun.com/api-reference/source-operations/list-source-operations

https://meta.upsun.com/openapi-spec get /projects/{projectId}/environments/{environmentId}/source-operations
Lists all the source operations, defined in `.upsun/config.yaml`, that are available in an environment.
More information on source code operations is
[available in our user documentation](https://docs.upsun.com/anchors/app/reference/source/operations/).




# Trigger a source operation
Source: https://developer.upsun.com/api-reference/source-operations/trigger-a-source-operation

https://meta.upsun.com/openapi-spec post /projects/{projectId}/environments/{environmentId}/source-operation
This endpoint triggers a source code operation as defined in the `source.operations`
key in a project's `.upsun/config.yaml` configuration. More information
on source code operations is
[available in our user documentation](https://docs.upsun.com/anchors/app/reference/source/operations/).




# Add a new public SSH key to a user
Source: https://developer.upsun.com/api-reference/ssh-keys/add-a-new-public-ssh-key-to-a-user

https://meta.upsun.com/openapi-spec post /ssh_keys



# Delete an SSH key
Source: https://developer.upsun.com/api-reference/ssh-keys/delete-an-ssh-key

https://meta.upsun.com/openapi-spec delete /ssh_keys/{key_id}



# Get an SSH key
Source: https://developer.upsun.com/api-reference/ssh-keys/get-an-ssh-key

https://meta.upsun.com/openapi-spec get /ssh_keys/{key_id}



# Checks if the user can afford the requested resources.
Source: https://developer.upsun.com/api-reference/subscriptions/checks-if-the-user-can-afford-the-requested-resources

https://meta.upsun.com/openapi-spec post /subscriptions/{subscriptionId}/can-afford



# Checks if the user is able to create a new project.
Source: https://developer.upsun.com/api-reference/subscriptions/checks-if-the-user-is-able-to-create-a-new-project

https://meta.upsun.com/openapi-spec get /organizations/{organization_id}/subscriptions/can-create



# Checks if the user is able to update a project.
Source: https://developer.upsun.com/api-reference/subscriptions/checks-if-the-user-is-able-to-update-a-project

https://meta.upsun.com/openapi-spec get /subscriptions/{subscriptionId}/can-update



# Create subscription
Source: https://developer.upsun.com/api-reference/subscriptions/create-subscription

https://meta.upsun.com/openapi-spec post /organizations/{organization_id}/subscriptions
Creates a subscription for the specified organization.



# Delete subscription
Source: https://developer.upsun.com/api-reference/subscriptions/delete-subscription

https://meta.upsun.com/openapi-spec delete /organizations/{organization_id}/subscriptions/{subscription_id}
Deletes a subscription for the specified organization.



# Estimate the price of a new subscription
Source: https://developer.upsun.com/api-reference/subscriptions/estimate-the-price-of-a-new-subscription

https://meta.upsun.com/openapi-spec get /organizations/{organization_id}/subscriptions/estimate



# Estimate the price of a subscription
Source: https://developer.upsun.com/api-reference/subscriptions/estimate-the-price-of-a-subscription

https://meta.upsun.com/openapi-spec get /organizations/{organization_id}/subscriptions/{subscription_id}/estimate



# Get current usage for a subscription
Source: https://developer.upsun.com/api-reference/subscriptions/get-current-usage-for-a-subscription

https://meta.upsun.com/openapi-spec get /organizations/{organization_id}/subscriptions/{subscription_id}/current_usage



# Get subscription
Source: https://developer.upsun.com/api-reference/subscriptions/get-subscription

https://meta.upsun.com/openapi-spec get /organizations/{organization_id}/subscriptions/{subscription_id}
Retrieves a subscription for the specified organization.



# Get usage alerts
Source: https://developer.upsun.com/api-reference/subscriptions/get-usage-alerts

https://meta.upsun.com/openapi-spec get /organizations/{organization_id}/alerts/subscriptions/{subscription_id}/usage
Retrieves current and available usage alerts.



# List addons for a subscription
Source: https://developer.upsun.com/api-reference/subscriptions/list-addons-for-a-subscription

https://meta.upsun.com/openapi-spec get /organizations/{organization_id}/subscriptions/{subscription_id}/addons



# List subscriptions
Source: https://developer.upsun.com/api-reference/subscriptions/list-subscriptions

https://meta.upsun.com/openapi-spec get /organizations/{organization_id}/subscriptions
Retrieves subscriptions for the specified organization.



# Update subscription
Source: https://developer.upsun.com/api-reference/subscriptions/update-subscription

https://meta.upsun.com/openapi-spec patch /organizations/{organization_id}/subscriptions/{subscription_id}
Updates a subscription for the specified organization.



# Update usage alerts.
Source: https://developer.upsun.com/api-reference/subscriptions/update-usage-alerts

https://meta.upsun.com/openapi-spec patch /organizations/{organization_id}/alerts/subscriptions/{subscription_id}/usage
Updates usage alerts for a subscription.



# Create a new support ticket
Source: https://developer.upsun.com/api-reference/support/create-a-new-support-ticket

https://meta.upsun.com/openapi-spec post /tickets



# List support ticket categories
Source: https://developer.upsun.com/api-reference/support/list-support-ticket-categories

https://meta.upsun.com/openapi-spec get /tickets/category



# List support ticket priorities
Source: https://developer.upsun.com/api-reference/support/list-support-ticket-priorities

https://meta.upsun.com/openapi-spec get /tickets/priority



# Update a ticket
Source: https://developer.upsun.com/api-reference/support/update-a-ticket

https://meta.upsun.com/openapi-spec patch /tickets/{ticket_id}



# Get information about the Git server.
Source: https://developer.upsun.com/api-reference/system-information/get-information-about-the-git-server

https://meta.upsun.com/openapi-spec get /projects/{projectId}/system
Output information for the project.



# Restart the Git server
Source: https://developer.upsun.com/api-reference/system-information/restart-the-git-server

https://meta.upsun.com/openapi-spec post /projects/{projectId}/system/restart
Force the Git server to restart.



# Get projects environments tasks
Source: https://developer.upsun.com/api-reference/task/get-projects-environments-tasks

https://meta.upsun.com/openapi-spec get /projects/{projectId}/environments/{environmentId}/tasks



# Get projects environments tasks 1
Source: https://developer.upsun.com/api-reference/task/get-projects-environments-tasks-1

https://meta.upsun.com/openapi-spec get /projects/{projectId}/environments/{environmentId}/tasks/{taskId}



# Post projects environments tasks run
Source: https://developer.upsun.com/api-reference/task/post-projects-environments-tasks-run

https://meta.upsun.com/openapi-spec post /projects/{projectId}/environments/{environmentId}/tasks/{taskId}/run



# Get project access for a team
Source: https://developer.upsun.com/api-reference/team-access/get-project-access-for-a-team

https://meta.upsun.com/openapi-spec get /teams/{team_id}/project-access/{project_id}
Retrieves the team's permissions for the current project.



# Get team access for a project
Source: https://developer.upsun.com/api-reference/team-access/get-team-access-for-a-project

https://meta.upsun.com/openapi-spec get /projects/{project_id}/team-access/{team_id}
Retrieves the team's permissions for the current project.



# Grant project access to a team
Source: https://developer.upsun.com/api-reference/team-access/grant-project-access-to-a-team

https://meta.upsun.com/openapi-spec post /teams/{team_id}/project-access
Adds the team to one or more specified projects.



# Grant team access to a project
Source: https://developer.upsun.com/api-reference/team-access/grant-team-access-to-a-project

https://meta.upsun.com/openapi-spec post /projects/{project_id}/team-access
Grants one or more team access to a specific project.



# List project access for a team
Source: https://developer.upsun.com/api-reference/team-access/list-project-access-for-a-team

https://meta.upsun.com/openapi-spec get /teams/{team_id}/project-access
Returns a list of items representing the team's project access.



# List team access for a project
Source: https://developer.upsun.com/api-reference/team-access/list-team-access-for-a-project

https://meta.upsun.com/openapi-spec get /projects/{project_id}/team-access
Returns a list of items representing the project access.



# Remove project access for a team
Source: https://developer.upsun.com/api-reference/team-access/remove-project-access-for-a-team

https://meta.upsun.com/openapi-spec delete /teams/{team_id}/project-access/{project_id}
Removes the team from the current project.



# Remove team access for a project
Source: https://developer.upsun.com/api-reference/team-access/remove-team-access-for-a-project

https://meta.upsun.com/openapi-spec delete /projects/{project_id}/team-access/{team_id}
Removes the team from the current project.



# Create team
Source: https://developer.upsun.com/api-reference/teams/create-team

https://meta.upsun.com/openapi-spec post /teams
Creates a new team.



# Create team member
Source: https://developer.upsun.com/api-reference/teams/create-team-member

https://meta.upsun.com/openapi-spec post /teams/{team_id}/members
Creates a new team member.



# Delete team
Source: https://developer.upsun.com/api-reference/teams/delete-team

https://meta.upsun.com/openapi-spec delete /teams/{team_id}
Deletes the specified team.



# Delete team member
Source: https://developer.upsun.com/api-reference/teams/delete-team-member

https://meta.upsun.com/openapi-spec delete /teams/{team_id}/members/{user_id}
Deletes the specified team member.



# Get team
Source: https://developer.upsun.com/api-reference/teams/get-team

https://meta.upsun.com/openapi-spec get /teams/{team_id}
Retrieves the specified team.



# Get team member
Source: https://developer.upsun.com/api-reference/teams/get-team-member

https://meta.upsun.com/openapi-spec get /teams/{team_id}/members/{user_id}
Retrieves the specified team member.



# List team members
Source: https://developer.upsun.com/api-reference/teams/list-team-members

https://meta.upsun.com/openapi-spec get /teams/{team_id}/members
Retrieves a list of users associated with a single team.



# List teams
Source: https://developer.upsun.com/api-reference/teams/list-teams

https://meta.upsun.com/openapi-spec get /teams
Retrieves a list of teams.



# Update team
Source: https://developer.upsun.com/api-reference/teams/update-team

https://meta.upsun.com/openapi-spec patch /teams/{team_id}
Updates the specified team.



# User teams
Source: https://developer.upsun.com/api-reference/teams/user-teams

https://meta.upsun.com/openapi-spec get /users/{user_id}/teams
Retrieves teams that the specified user is a member of.



# Delete an existing third-party integration
Source: https://developer.upsun.com/api-reference/third-party-integrations/delete-an-existing-third-party-integration

https://meta.upsun.com/openapi-spec delete /projects/{projectId}/integrations/{integrationId}



# Get information about an existing third-party integration
Source: https://developer.upsun.com/api-reference/third-party-integrations/get-information-about-an-existing-third-party-integration

https://meta.upsun.com/openapi-spec get /projects/{projectId}/integrations/{integrationId}



# Get list of existing integrations for a project
Source: https://developer.upsun.com/api-reference/third-party-integrations/get-list-of-existing-integrations-for-a-project

https://meta.upsun.com/openapi-spec get /projects/{projectId}/integrations



# Integrate project with a third-party service
Source: https://developer.upsun.com/api-reference/third-party-integrations/integrate-project-with-a-third-party-service

https://meta.upsun.com/openapi-spec post /projects/{projectId}/integrations



# Update an existing third-party integration
Source: https://developer.upsun.com/api-reference/third-party-integrations/update-an-existing-third-party-integration

https://meta.upsun.com/openapi-spec patch /projects/{projectId}/integrations/{integrationId}



# Get project access for a user
Source: https://developer.upsun.com/api-reference/user-access/get-project-access-for-a-user

https://meta.upsun.com/openapi-spec get /users/{user_id}/project-access/{project_id}
Retrieves the user's permissions for the current project.



# Get user access for a project
Source: https://developer.upsun.com/api-reference/user-access/get-user-access-for-a-project

https://meta.upsun.com/openapi-spec get /projects/{project_id}/user-access/{user_id}
Retrieves the user's permissions for the current project.



# Grant project access to a user
Source: https://developer.upsun.com/api-reference/user-access/grant-project-access-to-a-user

https://meta.upsun.com/openapi-spec post /users/{user_id}/project-access
Adds the user to one or more specified projects.



# Grant user access to a project
Source: https://developer.upsun.com/api-reference/user-access/grant-user-access-to-a-project

https://meta.upsun.com/openapi-spec post /projects/{project_id}/user-access
Grants one or more users access to a specific project.



# List project access for a user
Source: https://developer.upsun.com/api-reference/user-access/list-project-access-for-a-user

https://meta.upsun.com/openapi-spec get /users/{user_id}/project-access
Returns a list of items representing the user's project access.



# List user access for a project
Source: https://developer.upsun.com/api-reference/user-access/list-user-access-for-a-project

https://meta.upsun.com/openapi-spec get /projects/{project_id}/user-access
Returns a list of items representing the project access.



# Remove project access for a user
Source: https://developer.upsun.com/api-reference/user-access/remove-project-access-for-a-user

https://meta.upsun.com/openapi-spec delete /users/{user_id}/project-access/{project_id}
Removes the user from the current project.



# Remove user access for a project
Source: https://developer.upsun.com/api-reference/user-access/remove-user-access-for-a-project

https://meta.upsun.com/openapi-spec delete /projects/{project_id}/user-access/{user_id}
Removes the user from the current project.



# Update project access for a user
Source: https://developer.upsun.com/api-reference/user-access/update-project-access-for-a-user

https://meta.upsun.com/openapi-spec patch /users/{user_id}/project-access/{project_id}
Updates the user's permissions for the current project.



# Update user access for a project
Source: https://developer.upsun.com/api-reference/user-access/update-user-access-for-a-project

https://meta.upsun.com/openapi-spec patch /projects/{project_id}/user-access/{user_id}
Updates the user's permissions for the current project.



# Create a user profile picture
Source: https://developer.upsun.com/api-reference/user-profiles/create-a-user-profile-picture

https://meta.upsun.com/openapi-spec post /profile/{uuid}/picture



# Delete a user profile picture
Source: https://developer.upsun.com/api-reference/user-profiles/delete-a-user-profile-picture

https://meta.upsun.com/openapi-spec delete /profile/{uuid}/picture



# Get a single user profile
Source: https://developer.upsun.com/api-reference/user-profiles/get-a-single-user-profile

https://meta.upsun.com/openapi-spec get /profiles/{userId}



# Get a user address
Source: https://developer.upsun.com/api-reference/user-profiles/get-a-user-address

https://meta.upsun.com/openapi-spec get /profiles/{userId}/address



# List user profiles
Source: https://developer.upsun.com/api-reference/user-profiles/list-user-profiles

https://meta.upsun.com/openapi-spec get /profiles



# Update a user address
Source: https://developer.upsun.com/api-reference/user-profiles/update-a-user-address

https://meta.upsun.com/openapi-spec patch /profiles/{userId}/address
Update a user address, supplying one or more key/value pairs to to change.



# Update a user profile
Source: https://developer.upsun.com/api-reference/user-profiles/update-a-user-profile

https://meta.upsun.com/openapi-spec patch /profiles/{userId}
Update a user profile, supplying one or more key/value pairs to to change.



# Check if phone verification is required
Source: https://developer.upsun.com/api-reference/users/check-if-phone-verification-is-required

https://meta.upsun.com/openapi-spec post /me/phone
Find out if the current logged in user requires phone verification to create projects.



# Check if verification is required
Source: https://developer.upsun.com/api-reference/users/check-if-verification-is-required

https://meta.upsun.com/openapi-spec post /me/verification
Find out if the current logged in user requires verification (phone or staff) to create projects.



# Get a user
Source: https://developer.upsun.com/api-reference/users/get-a-user

https://meta.upsun.com/openapi-spec get /users/{user_id}
Retrieves the specified user.



# Get a user by email
Source: https://developer.upsun.com/api-reference/users/get-a-user-by-email

https://meta.upsun.com/openapi-spec get /users/email={email}
Retrieves a user matching the specified email address.



# Get a user by username
Source: https://developer.upsun.com/api-reference/users/get-a-user-by-username

https://meta.upsun.com/openapi-spec get /users/username={username}
Retrieves a user matching the specified username.



# Get current logged-in user info
Source: https://developer.upsun.com/api-reference/users/get-current-logged-in-user-info

https://meta.upsun.com/openapi-spec get /me
Retrieve information about the currently logged-in user (the user associated with the access token).



# Get the current user
Source: https://developer.upsun.com/api-reference/users/get-the-current-user

https://meta.upsun.com/openapi-spec get /users/me
Retrieves the current user, determined from the used access token.



# Reset email address
Source: https://developer.upsun.com/api-reference/users/reset-email-address

https://meta.upsun.com/openapi-spec post /users/{user_id}/emailaddress
Requests a reset of the user's email address. A confirmation email will be sent to the new address when the request is accepted.



# Reset user password
Source: https://developer.upsun.com/api-reference/users/reset-user-password

https://meta.upsun.com/openapi-spec post /users/{user_id}/resetpassword
Requests a reset of the user's password. A password reset email will be sent to the user when the request is accepted.



# Update a user
Source: https://developer.upsun.com/api-reference/users/update-a-user

https://meta.upsun.com/openapi-spec patch /users/{user_id}
Updates the specified user.



# Apply voucher
Source: https://developer.upsun.com/api-reference/vouchers/apply-voucher

https://meta.upsun.com/openapi-spec post /organizations/{organization_id}/vouchers/apply
Applies a voucher for the specified organization, and refreshes the currently open order.



# List vouchers
Source: https://developer.upsun.com/api-reference/vouchers/list-vouchers

https://meta.upsun.com/openapi-spec get /organizations/{organization_id}/vouchers
Retrieves vouchers for the specified organization.



# Upsun Cloud API
Source: https://developer.upsun.com/api/index

Interact with the Upsun Cloud platform programmatically through the REST API or language-specific SDKs.

Manage projects, environments, and resources programmatically. Automate deployments, configure infrastructure, and integrate Upsun Cloud into your toolchain.

## SDKs

Official client libraries with typed methods and built-in authentication.

<CardGroup>
  <Card title="PHP SDK" icon="php" href="/api/sdk/php">
    Install with Composer and manage your Upsun Cloud projects from PHP applications and scripts.
  </Card>

  <Card title="Node.js SDK" icon="js" href="/api/sdk/js">
    Install with `npm` and integrate Upsun Cloud into your Node.js applications, serverless functions, or build pipelines.
  </Card>
</CardGroup>

## REST API

Full access to the Upsun Cloud platform over HTTP. Authenticate with API tokens and interact with any resource.

<CardGroup>
  <Card title="Authentication" icon="lock" href="/api/rest/authentication">
    API tokens and OAuth
  </Card>

  <Card title="Errors" icon="shield" href="/api/rest/errors">
    Error codes and best practices
  </Card>
</CardGroup>

## OpenAPI Reference

Interactive documentation for every endpoint, generated from the Upsun Cloud OpenAPI spec. Try requests directly from the browser.

<CardGroup>
  <Card title="Explore the API" icon="book-open" href="/api/rest/overview">
    Browse all available endpoints with request and response schemas, parameters, and example payloads.
  </Card>
</CardGroup>


# Introduction
Source: https://developer.upsun.com/api/introduction

Example section for showcasing API endpoints

<Note>
  If you're not looking to build API reference documentation, you can delete this section by removing the api-reference
  folder.
</Note>

## Welcome

There are two ways to build API documentation: [OpenAPI](https://mintlify.com/docs/api-playground/openapi/setup) and [MDX components](https://mintlify.com/docs/api-playground/mdx/configuration). For the starter kit, we are using the following OpenAPI specification.

<Card title="Plant Store Endpoints" icon="leaf" href="https://github.com/mintlify/starter/blob/main/api-reference/openapi.json">
  View the OpenAPI specification file
</Card>

## Authentication

All API endpoints are authenticated using Bearer tokens and picked up from the specification file.

```json theme={null}
"security": [
  {
    "bearerAuth": []
  }
]
```


# Metadata Registry Explorer
Source: https://developer.upsun.com/api/resources/meta/explorer

Explore all versions of all components registered in the Upsun Trust Registry.

<iframe title="Embedded content" />


# Trust Registry
Source: https://developer.upsun.com/api/resources/meta/overview

Meta is the Upsun Trust Registry, a decentralized registry.

Available at: [https://meta.upsun.com](https://meta.upsun.com)

<iframe title="Embedded content" />


# Authentication
Source: https://developer.upsun.com/api/rest/authentication

Authenticate with the Upsun Cloud REST API using OAuth2 API tokens.

The Upsun Cloud REST API uses OAuth2 bearer tokens for authentication. You exchange an API token for a short-lived access token, then include it in the `Authorization` header of every request.

## Create an API token

You will first need to have an <a href="https://auth.upsun.com/register/">Upsun account</a> and [create an API Token](/cli/api-tokens) via the Console.

## Exchange for an access token

Use the token exchange endpoint to get a short-lived access token:

```bash theme={null}
curl -u platform-api-user: \
  -d 'grant_type=api_token&api_token=YOUR_API_TOKEN' \
  https://auth.upsun.com/oauth2/token
```

The response contains a bearer token valid for **900 seconds** (15 minutes):

```json theme={null}
{
  "access_token": "YOUR_ACCESS_TOKEN",
  "expires_in": 900,
  "token_type": "bearer"
}
```

## Make authenticated requests

Include the access token in the `Authorization` header:

```bash theme={null}
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  https://api.upsun.com/projects
```

<Info>
  **Base URL:** All API requests go to `https://api.upsun.com`.
</Info>

## Token lifecycle

| Property | Value |
| - | - |
| Token type | Bearer |
| Expires in | 900 seconds (15 minutes) |
| Exchange endpoint | `https://auth.upsun.com/oauth2/token` |
| Grant type | `api_token` |

Access tokens expire after 15 minutes. Your application should handle re-authentication by exchanging the API token again when a request returns `401 Unauthorized`.


# Endpoints
Source: https://developer.upsun.com/api/rest/endpoints

Key API endpoints and resource overview for the Upsun Cloud REST API.

All API requests are made to the base URL:

```
https://api.upsun.com
```

The API follows the OpenAPI (Swagger) specification and returns [HAL-style JSON](/api/rest/errors#hal-response-structure) over HTTPS.

## Resource overview

The API is organized around these primary resources:

| Resource | Base path | Description |
| - | - | - |
| **Organizations** | `/organizations` | Create, list, update, and delete organizations |
| **Projects** | `/projects` | Manage projects and their settings |
| **Environments** | `/projects/{id}/environments` | Branch, merge, activate, and deactivate environments |
| **Subscriptions** | `/subscriptions` | Manage project subscriptions and plans |
| **Users** | `/users` | User profiles and account management |
| **Members** | `/organizations/{id}/members` | Organization membership and permissions |
| **Invitations** | `/organizations/{id}/invitations` | Invite users to organizations |

## Common patterns

### Pagination

List endpoints support pagination with query parameters:

| Parameter | Description |
| - | - |
| `page[size]` | Number of results per page (1–100) |
| `page[before]` | Cursor for previous page |
| `page[after]` | Cursor for next page |

### Sorting

Use the `sort` parameter on list endpoints. Prefix with `-` for descending order:

```bash theme={null}
# Sort by creation date, newest first
curl -H "Authorization: Bearer $TOKEN" \
  "https://api.upsun.com/organizations?sort=-created_at"
```

### Filtering

Most list endpoints accept filter parameters specific to the resource:

```bash theme={null}
# Filter organizations by status
curl -H "Authorization: Bearer $TOKEN" \
  "https://api.upsun.com/organizations?filter[status]=active"
```

## Quick reference

<CardGroup>
  <Card title="OpenAPI Reference" icon="book-open" href="/api/rest/overview">
    Browse the full interactive API reference with schemas and example payloads.
  </Card>

  <Card title="Authentication" icon="lock" href="/api/rest/authentication">
    Set up API tokens and authenticate your requests.
  </Card>
</CardGroup>


# Errors
Source: https://developer.upsun.com/api/rest/errors

HTTP status codes and error handling for the Upsun Cloud REST API.

The Upsun Cloud REST API uses standard HTTP status codes to indicate the success or failure of a request.

## Status codes

| Code | Status | Description |
| - | - | - |
| `200` | OK | Request succeeded. Response body contains the requested resource. |
| `201` | Created | Resource created successfully. Response body contains the new resource. |
| `204` | No Content | Request succeeded with no response body (typically for deletions). |
| `400` | Bad Request | Invalid request parameters or body. Check the error message for details. |
| `401` | Unauthorized | Missing or expired access token. Re-authenticate and retry. |
| `403` | Forbidden | Valid token but insufficient permissions for the requested action. |
| `404` | Not Found | The requested resource does not exist. |
| `409` | Conflict | Resource already exists or a state conflict prevents the action. |

## HAL response structure

Successful responses use the [HAL](https://stateless.group/hal_specification.html) (Hypertext Application Language) format. Most responses include:

### `_links`

Most GET endpoints return a `_links` object defining available actions on the resource. The `self` key contains a fully qualified URL and an OpenAPI schema reference. Additional keys use fragment identifiers (e.g., `#edit`, `#delete`) to describe available operations:

```json theme={null}
{
  "_links": {
    "self": {
      "href": "/api/projects/abcdefghij1234567890",
      "meta": { ... }
    },
    "#delete": {
      "href": "/api/projects/abcdefghij1234567890",
      "meta": {
        "delete": {
          "responses": { ... },
          "parameters": []
        }
      }
    }
  }
}
```

### `_embedded`

Requests to endpoints which create or modify objects, such as POST, PATCH, or DELETE requests, include an `_embedded` key in their response. It contains the created or modified object, identical to what would be returned by a subsequent GET request for that resource.


# Overview
Source: https://developer.upsun.com/api/rest/overview

This section provides an overview of the Upsun Cloud REST API.

Upsun, formerly Platform.sh, is a container-based Cloud Application Platform. Our main API is simply Git. With a single `git push` and a couple of YAML files in your repository you can deploy an arbitrarily complex cluster. Every Project can have multiple applications (PHP, Node.js, Python, Ruby, Go, etc.) and managed, automatically provisioned services (databases, message queues, etc.).

Each project also comes with multiple concurrent live staging/development Environments. These ephemeral development environments are automatically created every time you push a new branch or create a pull request, and each has a full copy of the data of its parent branch, which is created on-the-fly in seconds.

Our Git implementation supports integrations with third party Git providers such as GitHub, Bitbucket, or GitLab, allowing you to simply integrate Upsun Cloud into your existing workflow.

## Using the REST API

In addition to the Git API, we also offer a REST API that allows you to manage every aspect of the platform, from managing projects and environments, to accessing accounts and subscriptions, to creating robust workflows and integrations with your CI systems and internal services.

These API docs are generated from a standard **OpenAPI (Swagger)** Specification document which you can find here in [JSON](https://meta.upsun.com/openapi-spec) format.

This RESTful API consumes and produces HAL-style JSON over HTTPS, and any REST library can be used to access it.

In order to use the API you will first need to have an <a href="https://auth.upsun.com/register/">Upsun account</a> and [create an API Token](/api/rest/authentication).

<OpenApiIntroduction />


# Upsun Cloud SDK for Go
Source: https://developer.upsun.com/api/sdk/go

This section describe how to use Upsun Cloud SDK for Go.

Upsun SDK for Go.\
This SDK maps the Upsun CLI commands. For more information, read [the documentation](https://docs.upsun.com).

## Install

```bash theme={null}
go get upsun-sdk-go
```

## Usage

```Go theme={null}

import "github.com/upsun/upsun-sdk-go";

config := NewUpsunConfig(nil)
upsun := NewUpsunClient(*config)

orgs := upsun.organization.List()
prjs := upsun.project.list("name=MyOrganizationName");
result := upsun.environment.redeploy("MyProjectId", "main");
```

## Devel

Clone repository:

```bash theme={null}
git clone git@github.com:upsun/upsun-sdk-go.git
```

Install Dep:

```bash theme={null}
go install
```

Generate API Client (Low-level) base on OpenAPI spec.

```bash theme={null}
./scripts/gen_golang.sh
```

Build the stack:

```bash theme={null}
go build .
```


# Upsun Cloud SDK for NodeJs
Source: https://developer.upsun.com/api/sdk/js

This section describe how to use Upsun Cloud SDK for NodeJs.

The official **Upsun SDK for Node.js** on TypeScript.
This SDK provides a Node.js interface that maps to the Upsun CLI commands.

For more information, read [the documentation](https://docs.upsun.com/api).

> **CAUTION**:
> This project is currently in **Beta**, meaning features and APIs may evolve over time.
>
> Please report bugs or request new features by creating a GitHub issue.

## Installation

Install the SDK via npm:

```bash theme={null}
npm install upsun-sdk-node
```

## Authentication

You will need an [Upsun API token](https://docs.upsun.com/administration/cli/api-tokens.html) to use this SDK.\
Store it securely, preferably in an environment variable.

```ts theme={null}
import { UpsunClient, UpsunConfig } from 'upsun-sdk-node';

const config: UpsunConfig = {
  apiKey: process.env.UPSUN_CLI_TOKEN || '',
};

const upsunClient = new UpsunClient(config);
```

## Usage

### Example: List organizations

```ts theme={null}
const organizations = await upsunClient.organizations.list();
```

### Example: List projects

```ts theme={null}
const projects = await upsunClient.projects.list('<organizationId>');
```

### Example: Redeploy an environment

```ts theme={null}
const result = await upsunClient.environments.redeploy('<projectId>', '<environmentId>');
```

***

## Development

Clone the repository and install dependencies:

```bash theme={null}
git clone git@github.com:upsun/upsun-sdk-node.git
npm install
```

## Architecture of this SDK

The SDK is built as follows:

* From the [JSON specs of our API](https://docs.upsun.com/api/openapispec-upsun.json)
* Using [`@openapitools/openapi-generator-cli`](https://www.npmjs.com/package/%40openapitools/openapi-generator-cli)
* Which generates a low-level API client
* On top of that, the SDK exposes higher-level task-oriented methods

### Regenerating API client code

API classes are generated from the [Upsun OpenAPI spec](https://docs.upsun.com/api/openapispec-upsun.json).

```bash theme={null}
npm run spec:generate:install
npm run spec:full
```

## Publishing

To generate a new version of the Upsun SDK Node and automatically publish it on [https://npmjs.org](https://npmjs.org)

1. update your local

```bash theme={null}
git fetch
git checkout main
git pull
```

2. check existing tags on [https://github.com/upsun/upsun-sdk-node/tags](https://github.com/upsun/upsun-sdk-node/tags)
3. Update `package.json` version to the new release version (highest version + 1)
4. update `package-lock.json` using:

```bash theme={null}
npm install
git add package.json package-lock.json
git commit -m "bump release version to v<x.y.z>"
git push
```

5. create a new tag from your local

```bash theme={null}
git tag v<x.y.z>
git push --tag
```

6. Go on release page: [https://github.com/upsun/upsun-sdk-node/releases](https://github.com/upsun/upsun-sdk-node/releases)
7. create a new release based on the previously created tag (Do not forget to autogenerate description in the form)
8. check publishing action status: [https://github.com/upsun/upsun-sdk-node/actions](https://github.com/upsun/upsun-sdk-node/actions)
9. check new release version on [https://www.npmjs.com/package/upsun-sdk-node](https://www.npmjs.com/package/upsun-sdk-node)

## Contributing

Contributions are welcome!\
Please open a [pull request](https://github.com/upsun/upsun-sdk-node/compare) or an [issue](https://github.com/upsun/upsun-sdk-node/issues/new)
for any improvements, bug fixes, or new features.

## Tests

To run the tests, use:

```bash theme={null}
npm run test
```

## License

This project is licensed under the Apache License 2.0. See the [LICENSE](https://github.com/upsun/upsun-sdk-node/blob/main/LICENSE) and [NOTICE](https://github.com/upsun/upsun-sdk-node/blob/main/NOTICE) files for details.


# Overview
Source: https://developer.upsun.com/api/sdk/overview

Official Upsun Cloud SDKs for PHP and Node.js.

The Upsun Cloud SDKs provide typed client libraries that map to the Upsun Cloud CLI commands, letting you manage the platform programmatically from your applications. Both SDKs are currently in **Beta** — features and APIs may evolve over time.

<CardGroup>
  <Card title="PHP SDK" icon="php" href="/api/sdk/php">
    Install with Composer
  </Card>

  <Card title="Node.js SDK" icon="js" href="/api/sdk/js">
    Install with npm
  </Card>
</CardGroup>

## Quick comparison

| | PHP | Node.js |
| - | - | - |
| **Package** | `upsun/upsun-sdk-php` | `upsun-sdk-node` |
| **Install** | `composer require upsun/upsun-sdk-php` | `npm install upsun-sdk-node` |
| **Language** | PHP | TypeScript |
| **License** | Apache 2.0 | Apache 2.0 |
| **Source** | [GitHub](https://github.com/upsun/upsun-sdk-php) | [GitHub](https://github.com/upsun/upsun-sdk-node) |

## Authentication

Both SDKs authenticate with an Upsun Cloud API token. Store it in an environment variable and pass it when initializing the client. See each SDK's README for usage examples.


# Upsun Cloud SDK for PHP
Source: https://developer.upsun.com/api/sdk/php

This section describes how to use Upsun Cloud SDK for PHP.

The official **Upsun SDK for PHP**. This SDK provides a PHP interface that maps to the Upsun CLI commands.

For more information, read [the documentation](https://docs.upsun.com/api).

> **CAUTION**:
> This project is currently in **Beta**, meaning features and APIs may evolve over time.
>
> Please report bugs or request new features by creating a GitHub issue.

## Installation

Install the SDK via Composer:

```bash theme={null}
composer require upsun/upsun-sdk-php
```

Then include Composer's autoloader in your PHP application:

```php theme={null}
require __DIR__ . '/vendor/autoload.php';
```

## Authentication

You will need an [Upsun API token](https://docs.upsun.com/administration/cli/api-tokens.html) to use this SDK.
Store it securely, preferably in an environment variable.

```php theme={null}
use Upsun\UpsunConfig;
use Upsun\UpsunClient;

$config = new UpsunConfig(apiToken: getenv('UPSUN_API_TOKEN'));
$upsunClient = new UpsunClient($config);
```

## Usage

### Example: List organizations

```php theme={null}
$organizations = $upsunClient->organizations->list();
```

### Example: List projects in an organization

```php theme={null}
$projects = $upsunClient->projects->list('<organizationId>');
```

### Example: Redeploy an environment

```php theme={null}
$response = $upsunClient->environments->redeploy('<projectId>', '<environmentId>');
```

***

## Development

Clone the repository and install dependencies:

```bash theme={null}
git clone git@github.com:upsun/upsun-sdk-php.git
composer install
```

## Architecture of this SDK

The SDK is built as follows:

* From the [JSON specs of our API](https://docs.upsun.com/api/openapispec-upsun.json)
* Using [`@openapitools/openapi-generator-cli`](https://www.npmjs.com/package/%40openapitools/openapi-generator-cli)
* Which generates:
  * PHP **Models** (in `src/Model/`)
  * PHP **APIs** (in `src/Api/`)
* Higher-level PHP (Facade) oriented **Tasks** (in `src/Core/Tasks/`)

### Regenerating API & Model classes

API and Model classes are generated using [openapi-generator-cli](https://openapi-generator.tech)
from the [Upsun OpenAPI spec](https://docs.upsun.com/api/openapispec-upsun.json).

```bash theme={null}
composer run spec:install
composer run spec:full
```

## Contributing

Contributions are welcome!<br />
Please open a [pull request](https://github.com/upsun/upsun-sdk-php/compare) or an [issue](https://github.com/upsun/upsun-sdk-php/issues/new)
for any improvements, bug fixes, or new features.

## Publishing

To generate a new version of the Upsun SDK PHP and automatically publish it on [https://packagist.org](https://packagist.org)

1. update your local

```bash theme={null}
git fetch
git checkout main
git pull
```

2. check existing tags on [https://github.com/upsun/upsun-sdk-php/tags](https://github.com/upsun/upsun-sdk-php/tags)
3. create a new tag from your local

```bash theme={null}
git tag v<x.y.z>
git push --tag
```

4. Go on release page: [https://github.com/upsun/upsun-sdk-php/releases](https://github.com/upsun/upsun-sdk-php/releases)
5. create a new release based on the previously created tag (Do not forget to autogenerate description in the form)
6. check publishing action status: [https://github.com/upsun/upsun-sdk-php/actions](https://github.com/upsun/upsun-sdk-php/actions)
7. check new release version on [https://packagist.org/packages/upsun/upsun-sdk-php](https://packagist.org/packages/upsun/upsun-sdk-php)

## Tests

To run the tests, use:

```bash theme={null}
composer install
composer run test
```

## License

This project is licensed under the Apache License 2.0. See the [LICENSE](https://github.com/upsun/upsun-sdk-php/blob/main/LICENSE) and [NOTICE](https://github.com/upsun/upsun-sdk-php/blob/main/NOTICE) files for details.


# Upsun Cloud SDK for Python
Source: https://developer.upsun.com/api/sdk/python

This section describe how to use Upsun Cloud SDK for Python.



# Api
Source: https://developer.upsun.com/blackfire/api/index



## --

Hello Blackfire API


# Docs
Source: https://developer.upsun.com/blackfire/docs/index



## --

Hello Blackfire Docs


# Upsun Blackfire
Source: https://developer.upsun.com/blackfire/index



<div>
  <div>
    # Monitor with <span>Upsun Blackfire</span>

    <p>
      Docs, guides, and references for deploying and monitor applications on the Upsun platform.
    </p>
  </div>
</div>


# Changelog
Source: https://developer.upsun.com/changelog

Keep up with the latest updates and enhancements to Upsun.

We're always open to new and fresh ideas that can help improve our product. Learn how to make a feature request and engage with the [Upsun community](https://community.upsun.com/).

<Update label="September 29, 2026">
  <Badge>Feature</Badge>

  ### Choose when your services get updated

  <p>Set a maintenance window per project, and updates that need a restart wait for your chosen slot.</p>

  <img alt="Choose when your services get updated" />

  Project admins can now set a **maintenance window** in Console: a weekday, a time, and a 2- or 4-week recurrence. Service updates that need a restart wait for it. If nothing is pending, nothing runs.

  Production is updated first, other environments follow. Need to move a run? Reschedule it from the activity feed.

  A maintenance window is required for zero-downtime deployments and can’t be turned off once set. See the [maintenance window docs](https://developer.upsun.com/docs/core-concepts/build-deploy#maintenance-window).
</Update>

<Update label="September 23, 2026">
  <Badge>Feature</Badge>

  ### Built-in S3-compatible object storage

  <p>Store large asset volumes directly on Upsun - fully managed and billed on your existing invoice.</p>

  <img alt="Built-in S3-compatible object storage" />

  Run asset-heavy applications on Upsun without an external storage provider. Add object storage like disk storage - from the Console or CLI.

  **Object storage is now part of your Upsun platform:**

  * No separate vendor - nothing external to set up or manage
  * No rework - your existing S3 tools and SDKs work as-is
  * No separate bill - it appears on your existing Upsun invoice
  * Production-proven - already powering enterprise workloads, including ALDI

  Lower-cost than disk storage for large volumes: €0.083/GB/month on allocated capacity (512 GB minimum). Available on Flex projects. \[[Read the docs →](https://developer.upsun.com/docs/manage-resources/object-storage)]
</Update>

<Update label="September 17, 2026">
  <Badge>Feature</Badge>

  ### Upsun Dispatch is here!

  <p>Agentic software workflows with human approval built in - now live.</p>

  <img alt="Upsun Dispatch is here!" />

  We've launched Upsun Dispatch, a new way to run agentic software workflows with humans in control. Connect a GitHub or GitLab repository and let agents review code and turn issues into draft pull requests - with approval gates when your workflows require a human decision, with every run recorded.\
  [Learn more →](https://dispatch.upsun.com/)
</Update>

<Update label="September 9, 2026">
  <Badge>Feature</Badge>

  ### Keeping your projects up to date just got easier

  <p>Upsun now flags runtimes and services that need upgrading, in the Console and deploy logs.</p>

  <img alt="Keeping your projects up to date just got easier" />

  Upsun now helps you keep your projects up to date. When a runtime or service you use is no longer fully maintained, a warning appears in the Console, on your project's Overview page, and in your deploy logs, so you see it in the browser and from your terminal.

  Each warning tells you what the status means, how long you have, which version to move to, and links to the upgrade steps. We are rolling this out gradually, starting with Redis. See [Upgrade to a maintained version](https://developer.upsun.com/docs/core-concepts/upgrade-runtimes-services#image-statuses).
</Update>

<Update label="August 31, 2026">
  <Badge>Feature</Badge>

  ### Dynamic response compression

  <p>Compress your app's dynamic responses without writing any code, per location. Off by default.</p>

  <img alt="Dynamic response compression" />

  Static files were already compressed, dynamic responses were not, so that work fell to your app runtime. The new `dynamic_compression` boolean under `web.locations` takes it off your hands.

  Off by default. Turn it on per location, then opt out per rule on authenticated paths. Brotli or gzip is picked from `Accept-Encoding`.

  It reintroduces the theoretical BREACH surface, so enable it only where your framework mitigates it. [Read the docs](https://developer.upsun.com/docs/configure-apps/image-properties/web#dynamic-response-compression).
</Update>

<Update label="August 20, 2026">
  <Badge>Feature</Badge>

  ### Find performance bottlenecks faster

  <p>Automatically analyze your profiling data and code to pinpoint root causes and rank issues by user impact.</p>

  <img alt="Find performance bottlenecks faster" />

  An AI agent that correlates your application profiling, traffic, and source code, then tells you what to fix.\
  The data to explain a slow endpoint is already there. Correlating a profile, your traffic, and the code to find the cause is the part that takes an afternoon.\
  The Performance Agent reads Upsun Blackfire profiles, continuous profiling data, traffic, and your application source from a deployed environment. The report explains the root cause in plain language, ranks findings by impact on user experience, and includes a code diff.\
  Read the [documentation](https://developer.upsun.com/docs/get-started/ai/upsun-performance-agent) to get started.
</Update>

<Update label="August 12, 2026">
  <Badge>Feature</Badge>

  ### Task containers are now available to all

  <p>Spin up ephemeral, API-triggered containers for run-once workloads, from batch jobs to AI agents.</p>

  <img alt="Task containers are now available to all" />

  Run-to-completion work, on demand.

  Task containers bring a new way to run work on Upsun: ephemeral containers that spin up on an API trigger, run a command with full access to your environment's services, then shut down when the job is done. They handle any run-to-completion workload, from data migrations and report generation to batch processing, and they give background AI agents the isolated, on-demand compute they need.

  Billed only while a task runs, with CLI and Console support. [Read the documentation to get started](https://developer.upsun.com/docs/configure-apps/tasks).
</Update>

<Update label="July 27, 2026">
  <Badge>Feature</Badge>

  ### Self-host Meilisearch on Upsun

  <p>Run Meilisearch on Upsun using its official public Docker image.</p>

  <img alt="Self-host Meilisearch on Upsun" />

  You can now deploy Meilisearch on Upsun using its official public Docker image.

  [This is the first verified example](https://developer.upsun.com/docs/add-services/docker-images/docker-meilisearch) for self-hosted services from public Docker images. Upsun pulls the image from a public registry and runs it as-is, without requiring you to write a Dockerfile or maintain a build process.

  You can run any public Docker image as a self-hosted service, making it easy to experiment with other tools and services beyond Meilisearch.

  You remain responsible for the image version, maintenance, and security updates.
</Update>

<Update label="July 21, 2026">
  <Badge>UI</Badge>

  ### See config changes in the activity log

  <p>Quickly see when deployment configuration changed.</p>

  <img alt="See config changes in the activity log" />

  You can now view configuration changes directly in the activity log. Open a commit activity and select **Config changes** to see the exact changes to your Upsun configuration files.

  Compare added and removed lines without leaving the Console or digging through Git, making it easier to understand what changed between deployments and troubleshoot issues faster.
</Update>

<Update label="June 8, 2026">
  <Badge>Feature</Badge>

  ### Task containers, now in prerelease access

  <p>Run on-demand workloads in ephemeral, API-triggered containers. From batch jobs to AI agents.</p>

  <img alt="Task containers, now in prerelease access" />

  Task containers are a new infrastructure primitive: ephemeral containers that spin up on an API trigger, run a command with full access to your environment's services, and shut down when done. They're built for any run-to-completion workload, from data migrations and report generation to batch processing.

  Running isolated, on-demand code with scoped environment access, they're also a natural fit for background AI agents.

  Available on Upsun Flex as a prerelease. Read [the documentation](https://developer.upsun.com/docs/configure-apps/tasks) to learn more and request access.
</Update>

<Update label="May 26, 2026">
  <Badge>Image</Badge>

  ### RabbitMQ 4.2 is now available

  <p>Improved quorum queues, better stream performance, and enhanced observability.</p>

  <img alt="RabbitMQ 4.2 is now available" />

  Upgrade to RabbitMQ 4.2 for more efficient messaging and better operational visibility:

  Quorum queues now support single active consumer, improving message ordering and simplifying consumer coordination.

  Stream performance and stability improvements help handle high-throughput workloads more reliably.

  Enhanced observability with additional metrics and monitoring capabilities makes it easier to understand system behavior in production.

  With RabbitMQ 4.2, you can process messages more reliably while gaining better insight into your system’s performance.
</Update>

<Update label="May 13, 2026">
  <Badge>Image</Badge>

  ### Solr 10.0 is now available

  <p>Expanded vector search, Java 21 support, and major platform upgrades.</p>

  <img alt="Solr 10.0 is now available" />

  Upgrade to Solr 10.0 for improved search performance, scalability, and modern platform support:

  Expanded vector search capabilities, including scalar and binary quantized dense vectors, improve performance and reduce memory usage.

  Optional GPU acceleration via cuVS-Lucene enables faster vector operations for advanced workloads.

  New indexing and query improvements, including enhanced KNN tuning and optimized merge policies, increase throughput and search efficiency.

  Modernized platform with Java 21 support, Jetty 12 upgrade, and full migration to OpenTelemetry for observability.

  Stability improvements with Apache Curator managing ZooKeeper interactions.

  This is a major release with breaking changes and removed legacy components, so review upgrade notes before migrating.
</Update>

<Update label="April 24, 2026">
  <Badge>System</Badge>

  ### New status page is live

  <p>We’ve updated our status page, now live at status.upsun.com. Resubscribe to stay up to date.</p>

  <img alt="New status page is live" />

  We’ve upgraded our status page to make it even easier for you to stay informed. Not only does the Upsun status page have a new look, but it also has a new home at status.upsun.com. Resubscribe now to continue receiving status notifications for region and system health, as well as upcoming maintenance events.

  Visit [status.upsun.com](http://status.upsun.com) to resubscribe, grab the new RSS feed, or see the status of your region or upcoming maintenance you need to be aware of.
</Update>

<Update label="March 17, 2026">
  <Badge>Feature</Badge>

  ### CPU & RAM autoscaling for workers

  <p>Automatically scale worker instances based on CPU and RAM usage.</p>

  <img alt="CPU & RAM autoscaling for workers" />

  Managing worker instances manually often leads to a trade-off between over-provisioning for peak loads or risking performance bottlenecks. To simplify this, we are introducing **horizontal autoscaling for workers** on Upsun Flex.

  You can now configure your worker instances to scale automatically based on **CPU and RAM utilization**. This initial release provides a critical foundation for developers who need to handle resource-intensive processing without manual intervention.

  This feature is available immediately via the **Console, CLI, and API** for all projects on Upsun Flex.
</Update>

<Update label="March 6, 2026">
  <Badge>Image</Badge>

  ### Elasticsearch Enterprise 8.19

  <p>Unlock ES|QL for pipe-based querying, ELSER for semantic search, and up to 65% storage reduction for logs.</p>

  <img alt="Elasticsearch Enterprise 8.19" />

  Upgrade to the latest Enterprise release to leverage advanced search capabilities and significant resource optimizations:

  * **ES|QL:** A pipe-based query language to transform, enrich, and simplify data investigation in a single request.
  * **Semantic Search:** Use ELSER (Elastic Learned Sparse Encoder) for out-of-the-box relevance without model training.
  * **Efficiency at Scale:** Reduce memory usage for vectors by up to 96% with BBQ and cut log storage costs by 65% using `logsdb` mode.
  * **Universal Profiling:** Gain whole-system visibility with zero-instrumentation monitoring.
  * **Learning to Rank:** Optimize search relevance using machine learning models.

  *This version is available as a Premium Service.*
</Update>


# AI coding agents
Source: https://developer.upsun.com/cli/ai-coding-agents

Teach your AI coding agent to manage Upsun Cloud projects using the CLI.

[Upsun Skills](https://github.com/upsun/skills) is an open-source skill that gives AI coding agents like [Claude Code](https://claude.ai/download) full access to 130+ Upsun Cloud CLI commands across 30 namespaces -- deployments, environments, backups, databases, scaling, and more.

## Install

**As a Claude Code plugin:**

```bash theme={null}
  claude plugin add upsun/skills
```

**Or add manually to your project:**

```bash theme={null}
  git clone https://github.com/upsun/skills.git ~/.claude/skills/upsun-skills
```

## What your agent can do

<CardGroup>
  <Card title="Deploy & manage environments" icon="git-branch">
    Push, branch, merge, and sync with production safety patterns
  </Card>

  <Card title="Backup & restore" icon="hard-drive">
    Create backups, verify integrity, and restore with confirmation checks
  </Card>

  <Card title="Database operations" icon="database">
    Manage PostgreSQL, MongoDB, Redis, and Valkey services
  </Card>

  <Card title="Scale & configure" icon="scaling">
    Adjust resources, manage domains, and configure autoscaling
  </Card>
</CardGroup>

<Card title="View on GitHub" href="https://github.com/upsun/skills" icon="github">
  Browse the source, report issues, and contribute to Upsun Skills
</Card>


# Authenticate the Upsun Cloud CLI using an API token
Source: https://developer.upsun.com/cli/api-tokens



You need to set up an API token to authenticate the Upsun Cloud CLI for any of the following tasks:

* Running automated tasks on a CI system
* Running automated tasks directly on app container, for example in a cron job

## Before you begin

You might need the [Upsun Cloud CLI](/cli) to perform certain tasks.
For example, you need the CLI to do the following:

* [Check the validity of an API token](#optional-check-the-validity-of-your-api-token).
* [Load the CLI SSH certificate for non-CLI commands](#use-the-cli-ssh-certificate-for-non-cli-commands).

## 1. Create a machine user

To safely run automated tasks, first create machine users.
Each machine user has its own Upsun account associated with a unique email address.
You can grant them restrictive [access permissions](/docs/administration/users) to handle specific automated tasks.
For security purposes, create a machine user for each type of task you want to automate.

To create a machine user, follow these steps:

<Tabs>
  <Tab title="Using the CLI">
    1. Run the following command using your machine user's email address.
       ```bash theme={null}
       upsun user:add  EMAIL_ADDRESS --role viewer --role development:contributor
       ```
       This sets your machine user as a viewer on your project and a contributor on development environments,
       with no access to other environment types.
       Note that you can further [adjust user roles](/docs/administration/users#environment-type-roles) depending on your needs and each environment type.

    2. In the email invitation, click **Create account**.

    3. To create an Upsun Cloud account for the machine user, click **Sign up** and follow the instructions.
  </Tab>

  <Tab title="In the Console">
    1. Go to your project and click <Icon icon="settings" /> **Settings**.
    2. In the **Project Settings** menu, click **Access**.
    3. Click **Add**.
    4. Enter your machine user's email address.
    5. For each [environment type](/docs/administration/users#environment-type-roles), assign a role to your machine user and click **Save**.
  </Tab>
</Tabs>

<Info>
  Machine users with an email address under your single sign-on (SSO) domain can be excluded from the SSO enforcement rule so they aren’t required to authenticate through your identity provider. See the [SSO documentation](/docs/administration/security/sso#service-users) for more information.
</Info>

## 2. Create an API token

1. Log in to the Console as your machine user.
2. Open the user menu (your name or profile picture).
3. Click **My profile**.
4. Go to the **API tokens** tab and click **Create API token**.
5. Enter a name for your API token and click **Create API token**.
6. To copy the API token to your clipboard, click **<Icon icon="copy" /> Copy**.
   Note that after you close the **API tokens** tab, you can't display the API token again.
7. Store the API token somewhere secure on your computer.

### Optional: check the validity of your API token

To check that your API token is valid, run the following command:

```bash theme={null}
upsun auth:api-token-login
```

When prompted, enter your API token.
You get output similar to this:

```bash theme={null}
The API token is valid.
You are logged in.
```

For security reasons, rotate your API tokens regularly.
When an API token is compromised, revoke it immediately.

## 3. Authenticate the CLI using your API token

After you create your API token, you can use it to do the following:

* Allow a CI system to run automated tasks using the Upsun Cloud CLI.
* Run automated tasks on an app container using the Upsun Cloud CLI,
  for example in a cron job.

Note that when running CLI commands in these cases,
some operations might take time to complete.
To avoid waiting for an operation to complete before moving on to the next one,
use the `--no-wait` flag.

### Authenticate in a CI system

You can allow your CI system to run automated tasks using the Upsun Cloud CLI.
To do so, create an environment variable named `UPSUN_CLI_TOKEN` with your API token as its value.
For more information, see your CI system's official documentation.

To run SSH-based commands that aren't specific to the Upsun Cloud CLI,
see how to [load the proper SSH certificate](#use-the-cli-ssh-certificate-for-non-cli-commands).

### Authenticate in an environment

You can run automated tasks on an app container using the Upsun Cloud CLI.
To do so, set your API token as a [top-level environment variable](/docs/development/variables#top-level-environment-variables).

<Warning>
  Once you add the token as an environment variable,
  anyone with [SSH access](/docs/development/ssh) can read its value.
  Make sure your [machine user has only the necessary permissions](#1-create-a-machine-user).
</Warning>

<Tabs>
  <Tab title="Using the CLI">
    Run the following command:

    ```bash theme={null}
    upsun variable:create \
       -e ENVIRONMENT_NAME \
       --level environment \
       --prefix 'env' \
       --name UPSUN_CLI_TOKEN \
       --sensitive true \
       --value 'API_TOKEN' \
       --inheritable false \
       --visible-build true \
       --no-interaction
    ```
  </Tab>

  <Tab title="In the Console">
    1. Open the environment where you want to add the variable.
    2. Click <Icon icon="settings" /> **Settings**.
    3. Click **Variables**.
    4. Click **+ Add variable**.
    5. In the **Variable name** field, enter `env:UPSUN_CLI_TOKEN`.
    6. In the **Value** field, enter your API token.
    7. Make sure the **Available at runtime** and **Sensitive variable** options are selected.
    8. Click **Add variable**.
  </Tab>
</Tabs>

Then add a build hook to your app configuration to install the CLI as part of the build process.

```yaml .upsun/config.yaml theme={null}
hooks:
  build: |
    set -e
    echo "Installing Upsun Cloud CLI"
    curl -fsSL https://raw.githubusercontent.com/upsun/cli/main/installer.sh | bash

    echo "Testing Upsun Cloud CLI"
    upsun
```

You can now call the CLI from within the shell on the app container or in a cron job.

To run SSH-based commands that aren't specific to the Upsun Cloud CLI,
see how to [load the proper SSH certificate](#use-the-cli-ssh-certificate-for-non-cli-commands).

You can set up a cron job on a specific type of environment.
For example, to run the `update` source operation on your production environment,
use the following cron job:

```yaml theme={null}
crons:
  update:
    spec: '0 0 * * *'
    commands:
      start: |
        if [ "$PLATFORM_ENVIRONMENT_TYPE" = production ]; then
          upsun backup:create --yes --no-wait
          upsun source-operation:run update --no-wait --yes
        fi
```

## Use the CLI SSH certificate for non-CLI commands

When you set a `UPSUN_CLI_TOKEN` environment variable,
the CLI authentication isn't complete until your run a CLI command
or load the CLI SSH certificate.

For example, after setting a `UPSUN_CLI_TOKEN` environment variable,
you might need to run `ssh`, `git`, `rsync`, or `scp` commands before you run any CLI commands.

In this case, to ensure all your commands work, load the CLI SSH certificate first.
To do so, run the following command:

```bash theme={null}
upsun ssh-cert:load --no-interaction
```


# Upsun Cloud CLI
Source: https://developer.upsun.com/cli/index

Install and use the Upsun Cloud CLI to manage your projects directly from the terminal

<div>
  <div>
    <div>
      <div />

      <div>
        <div>
          <div>
            <span />

            <CliVersion />
          </div>

          # Upsun Cloud CLI

          <p>
            The full power of Upsun Cloud in your terminal. Manage projects, push code, SSH into environments, and automate workflows.
          </p>

          <div>
            <a href="/cli/install">
              Install

              <svg>
                <path />
              </svg>
            </a>

            <a href="/cli/reference">
              Command Reference
            </a>
          </div>
        </div>

        <div>
          <div>
            <div>
              <div>
                <div />

                <div />

                <div />
              </div>

              <span>\~/my-project</span>
            </div>

            <div>
              <div>
                <span>\$</span><span>upsun</span>
                <div>Welcome to Upsun Cloud!</div>
              </div>

              <div>
                <span>\$</span><span>upsun push</span>

                <div>
                  Pushing HEAD to branch feature-login...<br />
                  Building application 'myapp'...<br />
                  <span>✓ Environment deployed:</span> [https://feature-login-abc123.upsun.app](https://feature-login-abc123.upsun.app)
                </div>
              </div>

              <div>
                <span>\$</span><span>upsun ssh</span>

                <div>
                  Connected to myapp\@feature-login (us-5)<br />
                  <span>app\@feature-login:\~\$</span> \_
                </div>
              </div>
            </div>
          </div>
        </div>
      </div>
    </div>

    <h2>CLI Documentation</h2>
    <p>Learn how to install, configure, and use the Upsun Cloud CLI.</p>

    <CardGroup>
      <Card title="Install" href="/cli/install" icon="download">
        Install and authenticate the CLI
      </Card>

      <Card title="Use" href="/cli/use" icon="square-terminal">
        Run commands and customize the CLI
      </Card>

      <Card title="API Tokens" href="/cli/api-tokens" icon="key">
        Authenticate for CI/CD and automation
      </Card>

      <Card title="Init" href="/cli/init" icon="rocket">
        Set up a project from a repository
      </Card>

      <Card title="Reference" href="/cli/reference" icon="terminal">
        All CLI commands and options
      </Card>

      <Card title="AI Agents" href="/cli/ai-coding-agents" icon="sparkles">
        Manage projects with AI coding agents
      </Card>
    </CardGroup>

    <div />

    <div>
      <div>
        <div>
          <span>1</span>
        </div>

        <div>
          <h2>Install</h2>
          <p>Choose your platform</p>
        </div>
      </div>

      <CodeGroup>
        ```bash macOS (Homebrew) theme={null}
          brew install upsun/tap/upsun-cli
        ```

        ```bash Linux theme={null}
          curl -fsSL https://raw.githubusercontent.com/upsun/cli/main/installer.sh | bash
        ```

        ```bash Windows (Scoop) theme={null}
          scoop bucket add upsun https://github.com/upsun/homebrew-tap.git
          scoop install upsun
        ```
      </CodeGroup>

      <p>Windows (Scoop) requires the <a href="https://github.com/ScoopInstaller/Extras">Extras bucket</a></p>
    </div>

    <div>
      <div>
        <div>
          <span>2</span>
        </div>

        <div>
          <h2>Authenticate</h2>
          <p>Log in via your browser</p>
        </div>
      </div>

      <div>
        <div>
          <div>
            <div>
              <div />

              <div />

              <div />
            </div>
          </div>
        </div>

        <div>
          <p>
            Running <code>upsun</code> opens a browser login flow and generates SSH certificates for secure access.
          </p>

          <p>
            Use <code>upsun login</code> to force a re-authentication.
          </p>

          <p>
            For CI/CD pipelines and automation, use <a href="/cli/api-tokens">API tokens</a> instead.
          </p>
        </div>
      </div>
    </div>

    <div>
      <div>
        <div>
          <span>3</span>
        </div>

        <div>
          <h2>Use</h2>
          <p>Common commands</p>
        </div>
      </div>
    </div>

    <div>
      <div>
        <div>
          <svg>
            <path />
          </svg>
        </div>

        <h2>AI Coding Agents</h2>
      </div>

      <p>Teach your AI coding agent to manage Upsun Cloud projects using the CLI.</p>

      <div>
        <div>
          <div>
            <h3>Upsun Skills</h3>

            <p>
              <a href="https://github.com/upsun/skills">Upsun Skills</a> is an open-source skill that gives AI coding agents like <a href="https://claude.ai/download">Claude Code</a> full access to 130+ Upsun Cloud CLI commands across 30 namespaces — deployments, environments, backups, databases, scaling, and more.
            </p>

            <p>Install as a Claude Code plugin</p>

            <p>Or add manually to your project</p>
          </div>
        </div>

        <div>
          <p>What your agent can do</p>

          <div>
            <svg>
              <path />
            </svg>

            <div>
              <p>Deploy & manage environments</p>
              <p>Push, branch, merge, and sync with production safety patterns</p>
            </div>
          </div>

          <div>
            <svg>
              <path />
            </svg>

            <div>
              <p>Backup & restore</p>
              <p>Create backups, verify integrity, and restore with confirmation checks</p>
            </div>
          </div>

          <div>
            <svg>
              <path />
            </svg>

            <div>
              <p>Database operations</p>
              <p>Manage PostgreSQL, MongoDB, Redis, and Valkey services</p>
            </div>
          </div>

          <div>
            <svg>
              <path />
            </svg>

            <div>
              <p>Scale & configure</p>
              <p>Adjust resources, manage domains, and configure autoscaling</p>
            </div>
          </div>

          <a href="https://github.com/upsun/skills">
            View on GitHub

            <svg>
              <path />
            </svg>
          </a>
        </div>
      </div>
    </div>

    <div>
      <div>
        <h2>Features</h2>
        <p>Everything you need to manage projects, environments, and deployments from the terminal.</p>

        <div>
          <div>
            <div>
              <svg>
                <path />
              </svg>
            </div>

            <div>
              <h3>Auto-detection</h3>
              <p>Detects project and environment from your local checkout. Override with <code>--project</code> and <code>--environment</code>.</p>
            </div>
          </div>

          <div>
            <div>
              <svg>
                <path />
              </svg>
            </div>

            <div>
              <h3>More than Git</h3>
              <p>Commands like <code>upsun push</code> add options like <code>--activate</code> and <code>--no-wait</code>.</p>
            </div>
          </div>

          <div>
            <div>
              <svg>
                <path />

                <path />
              </svg>
            </div>

            <div>
              <h3>Customizable</h3>
              <p>Configure via <code>\~/.upsun-cli/config.yaml</code>. See <a href="https://github.com/upsun/cli/blob/main/legacy/README.md#customization">GitHub</a>.</p>
            </div>
          </div>

          <div>
            <div>
              <svg>
                <path />
              </svg>
            </div>

            <div>
              <h3>Automation-ready</h3>
              <p>Set <code>UPSUN\_CLI\_NO\_INTERACTION=1</code> to bypass prompts in CI/CD.</p>
            </div>
          </div>

          <div>
            <div>
              <svg>
                <path />
              </svg>
            </div>

            <div>
              <h3>Autocompletion</h3>
              <p>Enable tab completion with  or via <a href="https://docs.brew.sh/Shell-Completion">Homebrew</a>.</p>
            </div>
          </div>

          <div>
            <div>
              <svg>
                <path />
              </svg>
            </div>

            <div>
              <h3>SSH built-in</h3>
              <p>Creates SSH certificates automatically on login. Access environments with <code>upsun ssh</code>.</p>
            </div>
          </div>
        </div>
      </div>
    </div>

    <div>
      <h2>Maintenance</h2>
      <p>Keep your CLI up to date and resolve common issues.</p>

      <div>
        <div>
          <h3>Update</h3>
        </div>

        <div>
          <h3>Troubleshooting</h3>

          <div>
            <p>RootNotFoundException</p>
            <p>If you cloned via Git directly, run:</p>
          </div>

          <p>
            <span>Upgrading from legacy CLI?</span> Follow the <a href="/cli/install">installation steps</a> — the new CLI guides you through removal.
          </p>
        </div>
      </div>
    </div>

    <div>
      <h2>Ready to get started?</h2>

      <p>
        Install the CLI and start managing your projects from the terminal.
      </p>

      <div>
        <a href="/cli/install">
          Install the CLI
        </a>

        <a href="/cli/reference">
          View Reference
        </a>
      </div>
    </div>
  </div>
</div>


# Initialize a project
Source: https://developer.upsun.com/cli/init

Generate starter configuration files for your Upsun Cloud project by using AI or guided setup.


The `init` command generates starter configuration files for your Upsun Cloud project.

## Usage

```bash theme={null}
upsun init
```

When you run `upsun init`, you can choose how to generate your starter configuration files. You can either:

* Use AI to analyze your project and generate a configuration automatically.
* Follow a guided setup, which does not use AI.

## AI configuration

The AI option analyzes the repository locally and sends a sanitized "digest" to the Upsun Cloud API, which then contacts our AI provider.

You can view the repository digest by running `upsun init --digest`. The digest contains:

* `tree`: a concise list of the files in the repository
* `reports`: a list of findings for each directory in the repository, including identified frameworks or build tools
* `selected_files`: the contents of a few files that look particularly relevant for configuration, including `README.md` and `Dockerfile`

At this time, OpenAI is the provider used for all configuration generation.

## Privacy

<Info>
  **Neither Upsun nor our AI providers will use your data for AI model training.**
</Info>

The selected files whose contents are included in the repository digest are chosen to be unlikely to include sensitive information.

The file contents are sanitized locally before being sent to the Upsun Cloud API. Upsun Cloud redacts email addresses and common secrets identified by using [`gitleaks`](https://github.com/gitleaks/gitleaks).

## Output

For both the AI and non-AI processes, the expected result is valid YAML. In many cases, the result is an acceptable starter configuration for the project.

<Info>
  AI can make convincing-looking mistakes, and projects can be very diverse in layout.

  Be sure to review and edit your configuration to suit your needs.
</Info>

Both the AI and non-AI processes create an `.upsun/config.yaml` file in your project root. This config file contains:

* Application configuration (see the [App reference](/docs/configure-apps/app-reference))
* Service definitions (see [Add services](/docs/add-services))
* Route configurations (see [Define routes](/docs/routes))

After running `upsun init`, you can deploy your project as follows:

```bash theme={null}
git add .upsun/config.yaml
git commit -m 'Add Upsun Cloud configuration'
upsun project:set-remote
upsun push
```

## `init` command options

| Option | Description |
| - | - |
| `--ai` | Use AI configuration (use `--ai=false` to disable) |
| `--digest` | Only show the repository digest (AI input) without sending it |
| `--yes` (`-y`) | Answer "yes" to confirmation questions and accept defaults (including overwriting existing configuration, if it exists). Implies `--no-interaction`. |
| `--no-interaction` | Don't ask interactive questions; accept default values |


# Install the Upsun Cloud CLI
Source: https://developer.upsun.com/cli/install

Install the Upsun Cloud CLI on macOS, Linux, or Windows to manage your projects from the terminal. Includes authentication, updates, and legacy CLI upgrade steps.

## Install

<Tabs>
  <Tab title="macOS (Homebrew)">
    Trust the Upsun tap, then install:

    ```bash theme={null}
      brew install upsun/tap/upsun-cli
    ```
  </Tab>

  <Tab title="Linux">
    ```bash theme={null}
      curl -fsSL https://raw.githubusercontent.com/upsun/cli/main/installer.sh | bash
    ```
  </Tab>

  <Tab title="Windows (Scoop)">
    Install the [Scoop Extras bucket](https://github.com/ScoopInstaller/Extras) before proceeding:

    ```bash theme={null}
      scoop bucket add extras
    ```

    Then add the Upsun bucket and install the CLI:

    ```bash theme={null}
      scoop bucket add upsun https://github.com/upsun/homebrew-tap.git
      scoop install upsun
    ```
  </Tab>
</Tabs>

To verify the installation, run:

```bash theme={null}
upsun --version
```

## Authenticate

Run the following command to authenticate and to manage your projects:

```bash theme={null}
upsun
```

This command opens a browser tab for you to log in.
It also creates certificates on your computer for [SSH](/docs/development/ssh).

After logging in, you see a list of your projects and tips for getting started.
If you experience authentication issues or want to force a login, run `upsun login`.

To install and authenticate the CLI in a CI system or app container using a build hook, see [Authenticate using an API token](/cli/api-tokens).

## Update the CLI

To update the CLI, run the appropriate command for your platform:

<Tabs>
  <Tab title="Homebrew">
    ```bash theme={null}
      brew upgrade upsun-cli
    ```
  </Tab>

  <Tab title="Linux">
    ```bash theme={null}
      curl -fsSL https://raw.githubusercontent.com/upsun/cli/main/installer.sh | bash
    ```
  </Tab>

  <Tab title="Scoop">
    ```bash theme={null}
      scoop update upsun
    ```
  </Tab>
</Tabs>

## Upgrade from the legacy CLI

Follow the [installation instructions above](#install).
Once installed, the CLI guides you through removing the legacy CLI.


# CLI Command reference
Source: https://developer.upsun.com/cli/reference



# Upsun Cloud CLI 5.11.0

* [Installation](/cli/install)
* [Open an issue](https://github.com/upsun/cli/issues)

- [`clear-cache`](#clear-cache)
- [`completion`](#completion)
- [`console`](#console)
- [`decode`](#decode)
- [`docs`](#docs)
- [`help`](#help)
- [`list`](#list)
- [`multi`](#multi)

**activity**

* [`activity:cancel`](#activitycancel)
* [`activity:get`](#activityget)
* [`activity:list`](#activitylist)
* [`activity:log`](#activitylog)

**app**

* [`app:config-get`](#appconfig-get)
* [`app:config-validate`](#appconfig-validate)
* [`app:list`](#applist)

**auth**

* [`auth:api-token-login`](#authapi-token-login)
* [`auth:browser-login`](#authbrowser-login)
* [`auth:info`](#authinfo)
* [`auth:logout`](#authlogout)
* [`auth:verify-phone-number`](#authverify-phone-number)

**autoscaling**

* [`autoscaling:get`](#autoscalingget)
* [`autoscaling:set`](#autoscalingset)

**backup**

* [`backup:create`](#backupcreate)
* [`backup:delete`](#backupdelete)
* [`backup:get`](#backupget)
* [`backup:list`](#backuplist)
* [`backup:restore`](#backuprestore)

**certificate**

* [`certificate:add`](#certificateadd)
* [`certificate:delete`](#certificatedelete)
* [`certificate:get`](#certificateget)
* [`certificate:list`](#certificatelist)

**commit**

* [`commit:get`](#commitget)
* [`commit:list`](#commitlist)

**db**

* [`db:dump`](#dbdump)
* [`db:sql`](#dbsql)

**domain**

* [`domain:add`](#domainadd)
* [`domain:delete`](#domaindelete)
* [`domain:get`](#domainget)
* [`domain:list`](#domainlist)
* [`domain:update`](#domainupdate)

**environment**

* [`environment:activate`](#environmentactivate)
* [`environment:branch`](#environmentbranch)
* [`environment:checkout`](#environmentcheckout)
* [`environment:delete`](#environmentdelete)
* [`environment:deploy`](#environmentdeploy)
* [`environment:deploy:type`](#environmentdeploytype)
* [`environment:drush`](#environmentdrush)
* [`environment:http-access`](#environmenthttp-access)
* [`environment:info`](#environmentinfo)
* [`environment:init`](#environmentinit)
* [`environment:list`](#environmentlist)
* [`environment:logs`](#environmentlogs)
* [`environment:merge`](#environmentmerge)
* [`environment:pause`](#environmentpause)
* [`environment:push`](#environmentpush)
* [`environment:redeploy`](#environmentredeploy)
* [`environment:relationships`](#environmentrelationships)
* [`environment:resume`](#environmentresume)
* [`environment:scp`](#environmentscp)
* [`environment:ssh`](#environmentssh)
* [`environment:synchronize`](#environmentsynchronize)
* [`environment:url`](#environmenturl)
* [`environment:xdebug`](#environmentxdebug)

**integration**

* [`integration:activity:get`](#integrationactivityget)
* [`integration:activity:list`](#integrationactivitylist)
* [`integration:activity:log`](#integrationactivitylog)
* [`integration:add`](#integrationadd)
* [`integration:delete`](#integrationdelete)
* [`integration:get`](#integrationget)
* [`integration:list`](#integrationlist)
* [`integration:update`](#integrationupdate)
* [`integration:validate`](#integrationvalidate)

**local**

* [`local:dir`](#localdir)

**metrics**

* [`metrics:all`](#metricsall)
* [`metrics:cpu`](#metricscpu)
* [`metrics:disk-usage`](#metricsdisk-usage)
* [`metrics:memory`](#metricsmemory)

**mount**

* [`mount:download`](#mountdownload)
* [`mount:list`](#mountlist)
* [`mount:upload`](#mountupload)

**operation**

* [`operation:list`](#operationlist)
* [`operation:run`](#operationrun)

**organization**

* [`organization:billing:address`](#organizationbillingaddress)
* [`organization:billing:profile`](#organizationbillingprofile)
* [`organization:create`](#organizationcreate)
* [`organization:delete`](#organizationdelete)
* [`organization:info`](#organizationinfo)
* [`organization:list`](#organizationlist)
* [`organization:subscription:list`](#organizationsubscriptionlist)
* [`organization:user:add`](#organizationuseradd)
* [`organization:user:delete`](#organizationuserdelete)
* [`organization:user:get`](#organizationuserget)
* [`organization:user:list`](#organizationuserlist)
* [`organization:user:projects`](#organizationuserprojects)
* [`organization:user:update`](#organizationuserupdate)

**project**

* [`project:clear-build-cache`](#projectclear-build-cache)
* [`project:convert`](#projectconvert)
* [`project:create`](#projectcreate)
* [`project:delete`](#projectdelete)
* [`project:get`](#projectget)
* [`project:info`](#projectinfo)
* [`project:init`](#projectinit)
* [`project:list`](#projectlist)
* [`project:set-remote`](#projectset-remote)

**repo**

* [`repo:cat`](#repocat)
* [`repo:ls`](#repols)
* [`repo:read`](#reporead)

**resources**

* [`resources:build:get`](#resourcesbuildget)
* [`resources:build:set`](#resourcesbuildset)
* [`resources:get`](#resourcesget)
* [`resources:set`](#resourcesset)
* [`resources:size:list`](#resourcessizelist)

**route**

* [`route:get`](#routeget)
* [`route:list`](#routelist)

**service**

* [`service:list`](#servicelist)
* [`service:mongo:dump`](#servicemongodump)
* [`service:mongo:export`](#servicemongoexport)
* [`service:mongo:restore`](#servicemongorestore)
* [`service:mongo:shell`](#servicemongoshell)
* [`service:redis-cli`](#serviceredis-cli)
* [`service:valkey-cli`](#servicevalkey-cli)

**source-operation**

* [`source-operation:list`](#source-operationlist)
* [`source-operation:run`](#source-operationrun)

**ssh-cert**

* [`ssh-cert:load`](#ssh-certload)

**ssh-key**

* [`ssh-key:add`](#ssh-keyadd)
* [`ssh-key:delete`](#ssh-keydelete)
* [`ssh-key:list`](#ssh-keylist)

**subscription**

* [`subscription:info`](#subscriptioninfo)

**task**

* [`task:list`](#tasklist)
* [`task:run`](#taskrun)

**team**

* [`team:create`](#teamcreate)
* [`team:delete`](#teamdelete)
* [`team:get`](#teamget)
* [`team:list`](#teamlist)
* [`team:project:add`](#teamprojectadd)
* [`team:project:delete`](#teamprojectdelete)
* [`team:project:list`](#teamprojectlist)
* [`team:update`](#teamupdate)
* [`team:user:add`](#teamuseradd)
* [`team:user:delete`](#teamuserdelete)
* [`team:user:list`](#teamuserlist)

**tunnel**

* [`tunnel:close`](#tunnelclose)
* [`tunnel:info`](#tunnelinfo)
* [`tunnel:list`](#tunnellist)
* [`tunnel:open`](#tunnelopen)
* [`tunnel:single`](#tunnelsingle)

**user**

* [`user:add`](#useradd)
* [`user:delete`](#userdelete)
* [`user:get`](#userget)
* [`user:list`](#userlist)
* [`user:update`](#userupdate)

**variable**

* [`variable:create`](#variablecreate)
* [`variable:delete`](#variabledelete)
* [`variable:get`](#variableget)
* [`variable:list`](#variablelist)
* [`variable:update`](#variableupdate)

**worker**

* [`worker:list`](#workerlist)

## `clear-cache`

Clear the CLI cache

Aliases: `cc`

### Usage

```
upsun cc
```

## `completion`

Dump the shell completion script

### Usage

```
completion [--debug] [--] [<shell>]
```

The completion command dumps the shell completion script required
to use shell autocompletion (currently, bash, fish, zsh completion are supported).

## Static installation

Dump the script to a global completion file and restart your shell:

upsun completion zsh | sudo tee \$fpath\[1]/\_upsun.phar

Or dump the script to a local file and source it:

upsun completion zsh > completion.sh

# source the file whenever you use the project

source completion.sh

# or add this line at the end of your "\~/.zshrc" file:

source /path/to/completion.sh

## Dynamic installation

Add this to the end of your shell configuration file (e.g. "\~/.zshrc"):

eval "\$(upsun completion zsh)"

#### Arguments

* `shell`(optional)
  The shell type (e.g. "bash"), the value of the "\$SHELL" env var will be used if this is not given

#### Options

* `--debug`
  Tail the completion debug log

## `console`

Open the project in the Console

Aliases: `web`

### Usage

```
upsun web [--browser BROWSER] [--pipe] [-p|--project PROJECT] [-e|--environment ENVIRONMENT]
```

#### Options

* `--browser` (expects a value)
  The browser to use to open the URL. Set 0 for none.

* `--pipe`
  Output the URL to stdout.

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

## `decode`

Decode a string that was encoded with JSON and Base64

### Usage

```
upsun decode [-P|--property PROPERTY] [--] <value>
```

#### Arguments

* `value`(required)
  The value to decode

#### Options

* `--property` (`-P`) (expects a value)
  The property to view within the value

### Examples

* View "foo" in PLATFORM\_VARIABLES:

```
upsun decode "$PLATFORM_VARIABLES" -P foo
```

## `docs`

Open the online documentation

### Usage

```
upsun docs [--browser BROWSER] [--pipe] [--] [<search>...]
```

#### Arguments

* `search`(optional; multiple values allowed)
  Search term(s)

#### Options

* `--browser` (expects a value)
  The browser to use to open the URL. Set 0 for none.

* `--pipe`
  Output the URL to stdout.

### Examples

* Search for information about the CLI:

```
upsun docs CLI
```

## `help`

Displays help for a command

### Usage

```
upsun help [--format FORMAT] [--raw] [--] [<command_name>]
```

The help command displays help for a given command:

upsun help list

You can also output the help in other formats by using the --format option:

upsun help --format=json list

To display the list of available commands, please use the list command.

#### Arguments

* `command_name`(optional)
  The command name

#### Options

* `--format` (expects a value)
  The output format (txt, json, or md)

* `--raw`
  To output raw command help

## `list`

List commands

### Usage

```
upsun list [--raw] [--format FORMAT] [--all] [-h|--help] [-V|--version] [-v|vv|vvv|--verbose] [-q|--quiet] [-y|--yes] [--no-interaction] [--] <command> [<namespace>]
```

The list command lists all commands:

upsun list

You can also display the commands for a specific namespace:

upsun list project

You can also output the information in other formats by using the --format option:

upsun list --format=xml

It's also possible to get raw list of commands (useful for embedding command runner):

upsun list --raw

#### Arguments

* `namespace`(optional)
  The namespace name

#### Options

* `--raw`
  To output raw command list

* `--format` (expects a value)
  The output format (txt, xml, json, or md)

* `--all`
  Show all commands, including hidden ones

## `multi`

Execute a command on multiple projects

### Usage

```
upsun multi [-p|--projects PROJECTS] [--continue] [--sort SORT] [--reverse] [--] <cmd>...
```

#### Arguments

* `cmd`(required; multiple values allowed)
  The command to execute

#### Options

* `--projects` (`-p`) (expects a value)
  A list of project IDs. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--continue`
  Continue running commands even if an exception is encountered

* `--sort` (expects a value)
  A property by which to sort the list of project options

* `--reverse`
  Reverse the order of project options

### Examples

* List variables on the "main" environment for multiple projects:

```
upsun multi -p l7ywemwizmmgb,o43m25zns6k2d,3nyujoslhydhx -- var -e main
```

## `activity:cancel`

Cancel an activity

### Usage

```
upsun activity:cancel [-t|--type TYPE] [-x|--exclude-type EXCLUDE-TYPE] [-a|--all] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [--] [<id>]
```

#### Arguments

* `id`(optional)
  The activity ID. Defaults to the most recent cancellable activity.

#### Options

* `--type` (`-t`) (expects a value)
  Filter by type (when selecting a default activity). Values may be split by commas (e.g. "a,b,c") and/or whitespace. The % or \* characters can be used as a wildcard for the type, e.g. '%var%' to select variable-related activities.

* `--exclude-type` (`-x`) (expects a value)
  Exclude by type (when selecting a default activity). Values may be split by commas (e.g. "a,b,c") and/or whitespace. The % or \* characters can be used as a wildcard to exclude types.

* `--all` (`-a`)
  Check recent activities on all environments (when selecting a default activity)

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

## `activity:get`

View detailed information on a single activity

### Usage

```
upsun activity:get [-P|--property PROPERTY] [-t|--type TYPE] [-x|--exclude-type EXCLUDE-TYPE] [--state STATE] [--result RESULT] [-i|--incomplete] [-a|--all] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [--format FORMAT] [-c|--columns COLUMNS] [--no-header] [--date-fmt DATE-FMT] [--] [<id>]
```

#### Arguments

* `id`(optional)
  The activity ID. Defaults to the most recent activity.

#### Options

* `--property` (`-P`) (expects a value)
  The property to view

* `--type` (`-t`) (expects a value)
  Filter by type (when selecting a default activity). Values may be split by commas (e.g. "a,b,c") and/or whitespace. The % or \* characters can be used as a wildcard for the type, e.g. '%var%' to select variable-related activities.

* `--exclude-type` (`-x`) (expects a value)
  Exclude by type (when selecting a default activity). Values may be split by commas (e.g. "a,b,c") and/or whitespace. The % or \* characters can be used as a wildcard to exclude types.

* `--state` (expects a value)
  Filter by state (when selecting a default activity): in\_progress, pending, complete, or cancelled. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--result` (expects a value)
  Filter by result (when selecting a default activity): success or failure

* `--incomplete` (`-i`)
  Include only incomplete activities (when selecting a default activity). This is a shorthand for --state=in\_progress,pending

* `--all` (`-a`)
  Check recent activities on all environments (when selecting a default activity)

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--format` (expects a value)
  The output format: table, csv, tsv, or plain

* `--columns` (`-c`) (expects a value)
  Columns to display. The % or \* characters may be used as a wildcard. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--no-header`
  Do not output the table header

* `--date-fmt` (expects a value)
  The date format (as a PHP date format string)

### Examples

* Find the time a project was created:

```
upsun activity:get --all --type project.create -P completed_at
```

* Find the duration (in seconds) of the last activity:

```
upsun activity:get -P duration
```

## `activity:list`

Get a list of activities for an environment or project

Aliases: `activities`, `act`

### Usage

```
upsun activities [-t|--type TYPE] [-x|--exclude-type EXCLUDE-TYPE] [--limit LIMIT] [--start START] [--state STATE] [--result RESULT] [-i|--incomplete] [-a|--all] [--format FORMAT] [-c|--columns COLUMNS] [--no-header] [--date-fmt DATE-FMT] [-p|--project PROJECT] [-e|--environment ENVIRONMENT]
```

#### Options

* `--type` (`-t`) (expects a value)
  Filter activities by type For a list of types see: [https://docs.upsun.com/anchors/integrations/activity-scripts/type/](https://docs.upsun.com/anchors/integrations/activity-scripts/type/) Values may be split by commas (e.g. "a,b,c") and/or whitespace. The first part of the activity name can be omitted, e.g. 'cron' can select 'environment.cron' activities. The % or \* characters can be used as a wildcard, e.g. '%var%' to select variable-related activities.

* `--exclude-type` (`-x`) (expects a value)
  Exclude activities by type. Values may be split by commas (e.g. "a,b,c") and/or whitespace. The first part of the activity name can be omitted, e.g. 'cron' can exclude 'environment.cron' activities. The % or \* characters can be used as a wildcard to exclude types.

* `--limit` (expects a value)
  Limit the number of results displayed

* `--start` (expects a value)
  Only activities created before this date will be listed

* `--state` (expects a value)
  Filter activities by state: in\_progress, pending, complete, or cancelled. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--result` (expects a value)
  Filter activities by result: success or failure

* `--incomplete` (`-i`)
  Only list incomplete activities

* `--all` (`-a`)
  List activities on all environments

* `--format` (expects a value)
  The output format: table, csv, tsv, or plain

* `--columns` (`-c`) (expects a value)
  Columns to display. Available columns: id\*, created\*, description\*, progress\*, state\*, result\*, completed, environments, time\_build, time\_deploy, time\_execute, time\_wait, type (\* = default columns). The character "+" can be used as a placeholder for the default columns. The % or \* characters may be used as a wildcard. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--no-header`
  Do not output the table header

* `--date-fmt` (expects a value)
  The date format (as a PHP date format string)

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

### Examples

* List recent activities for the current environment:

```
upsun activity:list 
```

* List all recent activities for the current project:

```
upsun activity:list --all
```

* List recent pushes:

```
upsun activity:list --type push
```

* List all recent activities excluding crons and redeploys:

```
upsun activity:list --exclude-type '*.cron,*.backup*'
```

* List pushes made before 15 March:

```
upsun activity:list --type push --start 2015-03-15
```

* List up to 25 incomplete activities:

```
upsun activity:list --limit 25 -i
```

* Include the activity type in the table:

```
upsun activity:list --columns +type
```

## `activity:log`

Display the log for an activity

### Usage

```
upsun activity:log [--refresh REFRESH] [-t|--timestamps] [--type TYPE] [-x|--exclude-type EXCLUDE-TYPE] [--state STATE] [--result RESULT] [-i|--incomplete] [-a|--all] [--date-fmt DATE-FMT] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [--] [<id>]
```

#### Arguments

* `id`(optional)
  The activity ID. Defaults to the most recent activity.

#### Options

* `--refresh` (expects a value)
  Activity refresh interval (seconds). Set to 0 to disable refreshing.

* `--timestamps` (`-t`)
  Display a timestamp next to each message

* `--type` (expects a value)
  Filter by type (when selecting a default activity). Values may be split by commas (e.g. "a,b,c") and/or whitespace. The % or \* characters can be used as a wildcard for the type, e.g. '%var%' to select variable-related activities.

* `--exclude-type` (`-x`) (expects a value)
  Exclude by type (when selecting a default activity). Values may be split by commas (e.g. "a,b,c") and/or whitespace. The % or \* characters can be used as a wildcard to exclude types.

* `--state` (expects a value)
  Filter by state (when selecting a default activity): in\_progress, pending, complete, or cancelled. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--result` (expects a value)
  Filter by result (when selecting a default activity): success or failure

* `--incomplete` (`-i`)
  Include only incomplete activities (when selecting a default activity). This is a shorthand for --state=in\_progress,pending

* `--all` (`-a`)
  Check recent activities on all environments (when selecting a default activity)

* `--date-fmt` (expects a value)
  The date format (as a PHP date format string)

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

### Examples

* Display the log for the last push on the current environment:

```
upsun activity:log --type environment.push
```

* Display the log for the last activity on the current project:

```
upsun activity:log --all
```

* Display the log for the last push, with microsecond timestamps:

```
upsun activity:log -a -t --type %push --date-fmt 'Y-m-d\TH:i:s.uP'
```

## `app:config-get`

View the configuration of an app

### Usage

```
upsun app:config-get [-P|--property PROPERTY] [--refresh] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [-A|--app APP] [-i|--identity-file IDENTITY-FILE]
```

#### Options

* `--property` (`-P`) (expects a value)
  The configuration property to view

* `--refresh`
  Whether to refresh the cache

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--app` (`-A`) (expects a value)
  The remote application name

* `--identity-file` (`-i`) (expects a value)
  \[Deprecated option, no longer used]

## `app:config-validate`

Validate the config files of a project

Aliases: `validate`, `lint`

### Usage

```
upsun app:config-validate
```

#### Options

* `--help` (`-h`)
  Display this help message

* `--verbose` (`-v|vv|vvv`)
  Increase the verbosity of messages

* `--version` (`-V`)
  Display this application version

* `--yes` (`-y`)
  Answer "yes" to confirmation questions; accept the default value for other questions; disable interaction

* `--no-interaction`
  Do not ask any interactive questions; accept default values. Equivalent to using the environment variable: UPSUN\_CLI\_NO\_INTERACTION=1

### Examples

* Validate the project configuration files in your current directory:

```
upsun app:config-validate 
```

## `app:list`

List apps in the project

Aliases: `apps`

### Usage

```
upsun apps [--refresh] [--pipe] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [--format FORMAT] [-c|--columns COLUMNS] [--no-header]
```

#### Options

* `--refresh`
  Whether to refresh the cache

* `--pipe`
  Output a list of app names only

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--format` (expects a value)
  The output format: table, csv, tsv, or plain

* `--columns` (`-c`) (expects a value)
  Columns to display. Available columns: name\*, type\*, disk, path, size (\* = default columns). The character "+" can be used as a placeholder for the default columns. The % or \* characters may be used as a wildcard. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--no-header`
  Do not output the table header

## `auth:api-token-login`

Log in using an API token

### Usage

```
upsun auth:api-token-login
```

Use this command to log in to your Upsun account using an API token.

You can create an account at:
[https://auth.upsun.com/register/](https://auth.upsun.com/register/)

Alternatively, to log in to the CLI with a browser, run:
upsun auth:browser-login

## `auth:browser-login`

Log in via a browser

Aliases: `login`

### Usage

```
upsun login [-f|--force] [--method METHOD] [--max-age MAX-AGE] [--browser BROWSER] [--pipe]
```

Use this command to log in to the Upsun Cloud CLI using a web browser.

It launches a temporary local website which redirects you to log in if
necessary, and then captures the resulting authorization code.

Your system's default browser will be used. You can override this using the
\--browser option.

Alternatively, to log in using an API token (without a browser), run:
upsun auth:api-token-login

To authenticate non-interactively, configure an API token using the
UPSUN\_CLI\_TOKEN environment variable.

#### Options

* `--force` (`-f`)
  Log in again, even if already logged in

* `--method` (expects a value)
  Require specific authentication method(s)

* `--max-age` (expects a value)
  The maximum age (in seconds) of the web authentication session

* `--browser` (expects a value)
  The browser to use to open the URL. Set 0 for none.

* `--pipe`
  Output the URL to stdout.

## `auth:info`

Display your account information

### Usage

```
upsun auth:info [--no-auto-login] [-P|--property PROPERTY] [--refresh] [--format FORMAT] [-c|--columns COLUMNS] [--no-header] [--] [<property>]
```

#### Arguments

* `property`(optional)
  The account property to view

#### Options

* `--no-auto-login`
  Skips auto login. Nothing will be output if not logged in, and the exit code will be 0, assuming no other errors.

* `--property` (`-P`) (expects a value)
  The account property to view (alternate syntax)

* `--refresh`
  Whether to refresh the cache

* `--format` (expects a value)
  The output format: table, csv, tsv, or plain

* `--columns` (`-c`) (expects a value)
  Columns to display. The % or \* characters may be used as a wildcard. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--no-header`
  Do not output the table header

### Examples

* Print your user ID:

```
upsun auth:info id
```

* Print your email address:

```
upsun auth:info email
```

* Print your user ID (or nothing if not logged in):

```
upsun auth:info id --no-auto-login
```

## `auth:logout`

Log out

Aliases: `logout`

### Usage

```
upsun logout [-a|--all] [--other]
```

#### Options

* `--all` (`-a`)
  Log out from all local sessions

* `--other`
  Log out from other local sessions

## `auth:verify-phone-number`

Verify your phone number interactively

### Usage

```
upsun auth:verify-phone-number
```

## `autoscaling:get`

View the autoscaling configuration of apps, workers, and services on an environment

Aliases: `autoscaling`

### Usage

```
upsun autoscaling [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [--format FORMAT] [-c|--columns COLUMNS] [--no-header]
```

#### Options

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--format` (expects a value)
  The output format: table, csv, tsv, or plain

* `--columns` (`-c`) (expects a value)
  Columns to display. Available columns: service\*, metric\*, direction\*, threshold\*, duration\*, enabled\*, instance\_count\*, cooldown, max\_instances, min\_instances (\* = default columns). The character "+" can be used as a placeholder for the default columns. The % or \* characters may be used as a wildcard. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--no-header`
  Do not output the table header

## `autoscaling:set`

Set the autoscaling configuration of apps, workers, or services in an environment

### Usage

```
upsun autoscaling:set [-s|--service SERVICE] [-m|--metric METRIC] [--enabled ENABLED] [--threshold-up THRESHOLD-UP] [--duration-up DURATION-UP] [--cooldown-up COOLDOWN-UP] [--threshold-down THRESHOLD-DOWN] [--duration-down DURATION-DOWN] [--cooldown-down COOLDOWN-DOWN] [--instances-min INSTANCES-MIN] [--instances-max INSTANCES-MAX] [--dry-run] [-p|--project PROJECT] [-e|--environment ENVIRONMENT]
```

Configure automatic scaling for apps, workers, or services in an environment.

You can also configure resources statically by running: upsun resources:set

#### Options

* `--service` (`-s`) (expects a value)
  Name of the app, worker, or service to configure autoscaling for

* `--metric` (`-m`) (expects a value)
  Name of the metric to use for triggering autoscaling

* `--enabled` (expects a value)
  Enable autoscaling based on the given metric

* `--threshold-up` (expects a value)
  Threshold over which service will be scaled up

* `--duration-up` (expects a value)
  Duration over which metric is evaluated against threshold for scaling up

* `--cooldown-up` (expects a value)
  Duration to wait before attempting to further scale up after a scaling event

* `--threshold-down` (expects a value)
  Threshold under which service will be scaled down

* `--duration-down` (expects a value)
  Duration over which metric is evaluated against threshold for scaling down

* `--cooldown-down` (expects a value)
  Duration to wait before attempting to further scale down after a scaling event

* `--instances-min` (expects a value)
  Minimum number of instances that will be scaled down to

* `--instances-max` (expects a value)
  Maximum number of instances that will be scaled up to

* `--dry-run`
  Show the changes that would be made, without changing anything

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

### Examples

* Enable autoscaling for an application using the default configuration:

```
upsun autoscaling:set --service app --metric cpu
```

* Enable autoscaling for an application specifying a minimum of instances at all times:

```
upsun autoscaling:set --service app --metric cpu --instances-min 3
```

* Enable autoscaling for an application specifying a maximum of instances at most:

```
upsun autoscaling:set --service app --metric cpu --instances-max 5
```

* Disable autoscaling on cpu for an application:

```
upsun autoscaling:set --service app --metric cpu --enabled false
```

## `backup:create`

Make a backup of an environment

Aliases: `backup`

### Usage

```
upsun backup [--live] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [-W|--no-wait] [--wait] [--] [<environment>]
```

#### Arguments

* `environment`(optional)
  The environment

#### Options

* `--live`
  Live backup: do not stop the environment. If set, this leaves the environment running and open to connections during the backup. This reduces downtime, at the risk of backing up data in an inconsistent state.

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--no-wait` (`-W`)
  Do not wait for the operation to complete

* `--wait`
  Wait for the operation to complete (default)

### Examples

* Make a backup of the current environment:

```
upsun backup:create 
```

* Request a backup (and exit quickly):

```
upsun backup:create --no-wait
```

* Make a backup avoiding downtime (but risking inconsistency):

```
upsun backup:create --live
```

## `backup:delete`

Delete an environment backup

### Usage

```
upsun backup:delete [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [-W|--no-wait] [--wait] [--] [<backup>]
```

#### Arguments

* `backup`(optional)
  The ID of the backup. Required in non-interactive mode.

#### Options

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--no-wait` (`-W`)
  Do not wait for the operation to complete

* `--wait`
  Wait for the operation to complete (default)

## `backup:get`

View an environment backup

### Usage

```
upsun backup:get [-P|--property PROPERTY] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [--date-fmt DATE-FMT] [--] [<backup>]
```

#### Arguments

* `backup`(optional)
  The ID of the backup. Defaults to the most recent one.

#### Options

* `--property` (`-P`) (expects a value)
  The backup property to display.

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--date-fmt` (expects a value)
  The date format (as a PHP date format string)

## `backup:list`

List available backups of an environment

Aliases: `backups`

### Usage

```
upsun backups [--format FORMAT] [-c|--columns COLUMNS] [--no-header] [--date-fmt DATE-FMT] [-p|--project PROJECT] [-e|--environment ENVIRONMENT]
```

#### Options

* `--format` (expects a value)
  The output format: table, csv, tsv, or plain

* `--columns` (`-c`) (expects a value)
  Columns to display. Available columns: created\_at\*, id\*, restorable\*, automated, commit\_id, expires\_at, index, live, status, updated\_at (\* = default columns). The character "+" can be used as a placeholder for the default columns. The % or \* characters may be used as a wildcard. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--no-header`
  Do not output the table header

* `--date-fmt` (expects a value)
  The date format (as a PHP date format string)

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

### Examples

* Display backups including the "live" and "commit\_id" columns:

```
upsun backup:list -c+live,commit_id
```

## `backup:restore`

Restore an environment backup

### Usage

```
upsun backup:restore [--target TARGET] [--branch-from BRANCH-FROM] [--no-code] [--no-resources] [--resources-init RESOURCES-INIT] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [-W|--no-wait] [--wait] [--] [<backup>]
```

#### Arguments

* `backup`(optional)
  The ID of the backup. Defaults to the most recent one

#### Options

* `--target` (expects a value)
  The environment to restore to. Defaults to the backup's current environment

* `--branch-from` (expects a value)
  If the --target does not yet exist, this specifies the parent of the new environment

* `--no-code`
  Do not restore code, only data.

* `--no-resources`
  Do not override the target's existing resource settings.

* `--resources-init` (expects a value)
  Set the resources to use for new services: backup, parent, default or minimum. If not set, "backup" will be used.

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--no-wait` (`-W`)
  Do not wait for the operation to complete

* `--wait`
  Wait for the operation to complete (default)

### Examples

* Restore the most recent backup:

```
upsun backup:restore 
```

* Restore a specific backup:

```
upsun backup:restore 92c9a4b2aa75422efb3d
```

## `certificate:add`

Add an SSL certificate to the project

### Usage

```
upsun certificate:add [--cert CERT] [--key KEY] [--chain CHAIN] [-p|--project PROJECT] [-W|--no-wait] [--wait]
```

#### Options

* `--cert` (expects a value)
  The path to the certificate file

* `--key` (expects a value)
  The path to the certificate private key file

* `--chain` (expects a value)
  The path to the certificate chain file

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--no-wait` (`-W`)
  Do not wait for the operation to complete

* `--wait`
  Wait for the operation to complete (default)

## `certificate:delete`

Delete a certificate from the project

### Usage

```
upsun certificate:delete [-p|--project PROJECT] [-W|--no-wait] [--wait] [--] <id>
```

#### Arguments

* `id`(required)
  The certificate ID (or the start of it)

#### Options

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--no-wait` (`-W`)
  Do not wait for the operation to complete

* `--wait`
  Wait for the operation to complete (default)

## `certificate:get`

View a certificate

### Usage

```
upsun certificate:get [-P|--property PROPERTY] [--date-fmt DATE-FMT] [-p|--project PROJECT] [--] <id>
```

#### Arguments

* `id`(required)
  The certificate ID (or the start of it)

#### Options

* `--property` (`-P`) (expects a value)
  The certificate property to view

* `--date-fmt` (expects a value)
  The date format (as a PHP date format string)

* `--project` (`-p`) (expects a value)
  The project ID or URL

## `certificate:list`

List project certificates

Aliases: `certificates`, `certs`

### Usage

```
upsun certificates [--domain DOMAIN] [--exclude-domain EXCLUDE-DOMAIN] [--issuer ISSUER] [--only-auto] [--no-auto] [--ignore-expiry] [--only-expired] [--no-expired] [--pipe-domains] [--date-fmt DATE-FMT] [--format FORMAT] [-c|--columns COLUMNS] [--no-header] [-p|--project PROJECT]
```

#### Options

* `--domain` (expects a value)
  Filter by domain name (case-insensitive search)

* `--exclude-domain` (expects a value)
  Exclude certificates, matching by domain name (case-insensitive search)

* `--issuer` (expects a value)
  Filter by issuer

* `--only-auto`
  Show only auto-provisioned certificates

* `--no-auto`
  Show only manually added certificates

* `--ignore-expiry`
  Show both expired and non-expired certificates

* `--only-expired`
  Show only expired certificates

* `--no-expired`
  Show only non-expired certificates (default)

* `--pipe-domains`
  Only return a list of domain names covered by the certificates

* `--date-fmt` (expects a value)
  The date format (as a PHP date format string)

* `--format` (expects a value)
  The output format: table, csv, tsv, or plain

* `--columns` (`-c`) (expects a value)
  Columns to display. Available columns: created, domains, expires, id, issuer. The % or \* characters may be used as a wildcard. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--no-header`
  Do not output the table header

* `--project` (`-p`) (expects a value)
  The project ID or URL

### Examples

* Output a list of domains covered by valid certificates:

```
upsun certificate:list --pipe-domains --no-expired
```

## `commit:get`

Show commit details

### Usage

```
upsun commit:get [-P|--property PROPERTY] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [--date-fmt DATE-FMT] [--] [<commit>]
```

#### Arguments

* `commit`(optional)
  The commit SHA. This can also accept "HEAD", and caret (^) or tilde (\~) suffixes for parent commits.

#### Options

* `--property` (`-P`) (expects a value)
  The commit property to display.

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--date-fmt` (expects a value)
  The date format (as a PHP date format string)

### Examples

* Display the current commit on the environment:

```
upsun commit:get 
```

* Display the previous commit:

```
upsun commit:get HEAD~
```

* Display the 3rd commit before the current one:

```
upsun commit:get HEAD~3
```

* Display the email address of the last commit author:

```
upsun commit:get -P author.email
```

## `commit:list`

List commits

Aliases: `commits`

### Usage

```
upsun commits [--limit LIMIT] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [--format FORMAT] [-c|--columns COLUMNS] [--no-header] [--date-fmt DATE-FMT] [--] [<commit>]
```

#### Arguments

* `commit`(optional)
  The starting Git commit SHA. This can also accept "HEAD", and caret (^) or tilde (\~) suffixes for parent commits.

#### Options

* `--limit` (expects a value)
  The number of commits to display.

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--format` (expects a value)
  The output format: table, csv, tsv, or plain

* `--columns` (`-c`) (expects a value)
  Columns to display. Available columns: author, date, sha, summary. The % or \* characters may be used as a wildcard. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--no-header`
  Do not output the table header

* `--date-fmt` (expects a value)
  The date format (as a PHP date format string)

### Examples

* Display commits on an environment:

```
upsun commit:list 
```

* Display commits starting from two before the current one:

```
upsun commit:list HEAD~2
```

## `db:dump`

Create a local dump of the remote database

### Usage

```
upsun db:dump [--schema SCHEMA] [-f|--file FILE] [-d|--directory DIRECTORY] [-z|--gzip] [-t|--timestamp] [-o|--stdout] [--table TABLE] [--exclude-table EXCLUDE-TABLE] [--schema-only] [--charset CHARSET] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [-A|--app APP] [-r|--relationship RELATIONSHIP]
```

#### Options

* `--schema` (expects a value)
  The schema to dump. Omit to use the default schema (usually "main").

* `--file` (`-f`) (expects a value)
  A custom filename for the dump

* `--directory` (`-d`) (expects a value)
  A custom directory for the dump

* `--gzip` (`-z`)
  Compress the dump using gzip

* `--timestamp` (`-t`)
  Add a timestamp to the dump filename

* `--stdout` (`-o`)
  Output to STDOUT instead of a file

* `--table` (expects a value)
  Table(s) to include

* `--exclude-table` (expects a value)
  Table(s) to exclude

* `--schema-only`
  Dump only schemas, no data

* `--charset` (expects a value)
  The character set encoding for the dump

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--app` (`-A`) (expects a value)
  The remote application name

* `--relationship` (`-r`) (expects a value)
  The service relationship to use

### Examples

* Create an SQL dump file:

```
upsun db:dump 
```

* Create a gzipped SQL dump file named "dump.sql.gz":

```
upsun db:dump --gzip -f dump.sql.gz
```

## `db:sql`

Run SQL on the remote database

Aliases: `sql`

### Usage

```
upsun sql [--raw] [--schema SCHEMA] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [-A|--app APP] [-r|--relationship RELATIONSHIP] [--] [<query>]
```

#### Arguments

* `query`(optional)
  An SQL statement to execute

#### Options

* `--raw`
  Produce raw, non-tabular output

* `--schema` (expects a value)
  The schema to use. Omit to use the default schema (usually "main"). Pass an empty string to not use any schema.

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--app` (`-A`) (expects a value)
  The remote application name

* `--relationship` (`-r`) (expects a value)
  The service relationship to use

### Examples

* Open an SQL console on the remote database:

```
upsun db:sql 
```

* View tables on the remote database:

```
upsun db:sql 'SHOW TABLES'
```

* Import a dump file into the remote database:

```
upsun db:sql < dump.sql
```

## `domain:add`

Add a new domain to the project

### Usage

```
upsun domain:add [--cert CERT] [--key KEY] [--chain CHAIN] [--attach ATTACH] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [-W|--no-wait] [--wait] [--] <name>
```

#### Arguments

* `name`(required)
  The domain name

#### Options

* `--cert` (expects a value)
  The path to a custom certificate file

* `--key` (expects a value)
  The path to the private key for the custom certificate

* `--chain` (expects a value)
  The path to the chain file(s) for the custom certificate

* `--attach` (expects a value)
  The production domain that this one replaces in the environment's routes. Required for non-production environment domains.

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--no-wait` (`-W`)
  Do not wait for the operation to complete

* `--wait`
  Wait for the operation to complete (default)

### Examples

* Add the domain example.com:

```
upsun domain:add example.com
```

* Add the domain example.org with a custom SSL/TLS certificate:

```
upsun domain:add example.org --cert example-org.crt --key example-org.key
```

## `domain:delete`

Delete a domain from the project

### Usage

```
upsun domain:delete [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [-W|--no-wait] [--wait] [--] <name>
```

#### Arguments

* `name`(required)
  The domain name

#### Options

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--no-wait` (`-W`)
  Do not wait for the operation to complete

* `--wait`
  Wait for the operation to complete (default)

### Examples

* Delete the domain example.com:

```
upsun domain:delete example.com
```

## `domain:get`

Show detailed information for a domain

### Usage

```
upsun domain:get [-P|--property PROPERTY] [--format FORMAT] [-c|--columns COLUMNS] [--no-header] [--date-fmt DATE-FMT] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [--] [<name>]
```

#### Arguments

* `name`(optional)
  The domain name

#### Options

* `--property` (`-P`) (expects a value)
  The domain property to view

* `--format` (expects a value)
  The output format: table, csv, tsv, or plain

* `--columns` (`-c`) (expects a value)
  Columns to display. The % or \* characters may be used as a wildcard. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--no-header`
  Do not output the table header

* `--date-fmt` (expects a value)
  The date format (as a PHP date format string)

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

## `domain:list`

Get a list of all domains

Aliases: `domains`

### Usage

```
upsun domains [--format FORMAT] [-c|--columns COLUMNS] [--no-header] [-p|--project PROJECT] [-e|--environment ENVIRONMENT]
```

#### Options

* `--format` (expects a value)
  The output format: table, csv, tsv, or plain

* `--columns` (`-c`) (expects a value)
  Columns to display. Available columns: name\*, ssl\*, created\_at\*, registered\_name, replacement\_for, type, updated\_at (\* = default columns). The character "+" can be used as a placeholder for the default columns. The % or \* characters may be used as a wildcard. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--no-header`
  Do not output the table header

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

## `domain:update`

Update a domain

### Usage

```
upsun domain:update [--cert CERT] [--key KEY] [--chain CHAIN] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [-W|--no-wait] [--wait] [--] <name>
```

#### Arguments

* `name`(required)
  The domain name

#### Options

* `--cert` (expects a value)
  The path to a custom certificate file

* `--key` (expects a value)
  The path to the private key for the custom certificate

* `--chain` (expects a value)
  The path to the chain file(s) for the custom certificate

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--no-wait` (`-W`)
  Do not wait for the operation to complete

* `--wait`
  Wait for the operation to complete (default)

### Examples

* Update the custom certificate for the domain example.org:

```
upsun domain:update example.org --cert example-org.crt --key example-org.key
```

## `environment:activate`

Activate an environment

### Usage

```
upsun environment:activate [--parent PARENT] [--resources-init RESOURCES-INIT] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [-W|--no-wait] [--wait] [--] [<environment>...]
```

#### Arguments

* `environment`(optional; multiple values allowed)
  The environment(s) to activate

#### Options

* `--parent` (expects a value)
  Set a new environment parent before activating

* `--resources-init` (expects a value)
  Set the resources to use for new services: parent, default or minimum. If not set, "parent" will be used.

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--no-wait` (`-W`)
  Do not wait for the operation to complete

* `--wait`
  Wait for the operation to complete (default)

### Examples

* Activate the environments "develop" and "stage":

```
upsun environment:activate develop stage
```

## `environment:branch`

Branch an environment

Aliases: `branch`

### Usage

```
upsun branch [--title TITLE] [--type TYPE] [--no-clone-parent] [--no-checkout] [--resources-init RESOURCES-INIT] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [-W|--no-wait] [--wait] [--] [<id> [<parent>]]
```

#### Arguments

* `id`(optional)
  The ID (branch name) of the new environment

* `parent`(optional)
  The parent of the new environment

#### Options

* `--title` (expects a value)
  The title of the new environment

* `--type` (expects a value)
  The type of the new environment

* `--no-clone-parent`
  Do not clone the parent environment's data

* `--no-checkout`
  Do not check out the branch locally

* `--resources-init` (expects a value)
  Set the resources to use for new services: parent, default or minimum. If not set, "parent" will be used.

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--no-wait` (`-W`)
  Do not wait for the operation to complete

* `--wait`
  Wait for the operation to complete (default)

### Examples

* Create a new branch "sprint-2", based on "develop":

```
upsun environment:branch sprint-2 develop
```

## `environment:checkout`

Check out an environment

Aliases: `checkout`

### Usage

```
upsun checkout [<environment>]
```

#### Arguments

* `environment`(optional)
  The ID of the environment to check out. For example: "sprint2"

### Examples

* Check out the environment "develop":

```
upsun environment:checkout develop
```

## `environment:delete`

Delete one or more environments

### Usage

```
upsun environment:delete [--delete-branch] [--no-delete-branch] [--type TYPE] [-t|--only-type ONLY-TYPE] [--exclude EXCLUDE] [--exclude-type EXCLUDE-TYPE] [--inactive] [--status STATUS] [--only-status ONLY-STATUS] [--exclude-status EXCLUDE-STATUS] [--merged] [--allow-delete-parent] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [-W|--no-wait] [--wait] [--] [<environment>...]
```

When an Upsun Cloud environment is deleted, it will become "inactive": it will
exist only as a Git branch, containing code but no services, databases nor
files.

This command allows you to delete environments as well as their Git branches.

#### Arguments

* `environment`(optional; multiple values allowed)
  The environment(s) to delete. The % or \* characters may be used as a wildcard. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

#### Options

* `--delete-branch`
  Delete Git branch(es) for inactive environments, without confirmation

* `--no-delete-branch`
  Do not delete any Git branch(es) (inactive environments)

* `--type` (expects a value)
  Delete all environments of a type (adding to any others selected) Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--only-type` (`-t`) (expects a value)
  Only delete environments of a specific type Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--exclude` (expects a value)
  Environment(s) not to delete. The % or \* characters may be used as a wildcard. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--exclude-type` (expects a value)
  Environment type(s) of which not to delete Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--inactive`
  Delete all inactive environments (adding to any others selected)

* `--status` (expects a value)
  Delete all environments of a status (adding to any others selected) Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--only-status` (expects a value)
  Only delete environments of a specific status Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--exclude-status` (expects a value)
  Environment status(es) of which not to delete Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--merged`
  Delete all merged environments (adding to any others selected)

* `--allow-delete-parent`
  Allow environments that have children to be deleted

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--no-wait` (`-W`)
  Do not wait for the operation to complete

* `--wait`
  Wait for the operation to complete (default)

### Examples

* Delete the currently checked out environment:

```
upsun environment:delete 
```

* Delete the environments "test" and "example-1":

```
upsun environment:delete test example-1
```

* Delete all inactive environments:

```
upsun environment:delete --inactive
```

* Delete all environments merged with their parent:

```
upsun environment:delete --merged
```

## `environment:deploy`

Deploy an environment's staged changes

Aliases: `deploy`, `e:deploy`, `env:deploy`

### Usage

```
upsun deploy [-s|--strategy STRATEGY] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [-W|--no-wait] [--wait]
```

#### Options

* `--strategy` (`-s`) (expects a value)
  The deployment strategy, stopstart (default, restart with a shutdown) or rolling (zero downtime)

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--no-wait` (`-W`)
  Do not wait for the operation to complete

* `--wait`
  Wait for the operation to complete (default)

## `environment:deploy:type`

Show or set the environment deployment type

### Usage

```
upsun environment:deploy:type [--pipe] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [-W|--no-wait] [--wait] [--] [<type>]
```

Choose automatic (the default) if you want your changes to be deployed immediately as they are made.
Choose manual to have changes staged until you trigger a deployment (including changes to code, variables, domains and settings).

#### Arguments

* `type`(optional)
  The environment deployment type: automatic or manual.

#### Options

* `--pipe`
  Output the deployment type to stdout

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--no-wait` (`-W`)
  Do not wait for the operation to complete

* `--wait`
  Wait for the operation to complete (default)

### Examples

* Set the deployment type to "manual" (disable automatic deployments):

```
upsun environment:deploy:type manual
```

## `environment:drush`

Run a drush command on the remote environment

Aliases: `drush`

### Usage

```
upsun drush [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [-A|--app APP] [--] [<cmd>...]
```

#### Arguments

* `cmd`(optional; multiple values allowed)
  A command to pass to Drush

#### Options

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--app` (`-A`) (expects a value)
  The remote application name

### Examples

* Run "drush status" on the remote environment:

```
upsun environment:drush status
```

* Enable the Overlay module on the remote environment:

```
upsun environment:drush en overlay
```

* Get a one-time login link (using -- before options):

```
upsun environment:drush user-login -- --mail=name@example.com
```

* Alternative syntax (quoting the whole command):

```
upsun environment:drush 'user-login --mail=name@example.com'
```

## `environment:http-access`

Update HTTP access settings for an environment

Aliases: `httpaccess`

### Usage

```
upsun httpaccess [--access ACCESS] [--auth AUTH] [--enabled ENABLED] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [-W|--no-wait] [--wait]
```

#### Options

* `--access` (expects a value)
  Access restriction in the format "permission:address". Use 0 to clear all addresses.

* `--auth` (expects a value)
  HTTP Basic auth credentials in the format "username:password". Use 0 to clear all credentials.

* `--enabled` (expects a value)
  Whether access control should be enabled: 1 to enable, 0 to disable

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--no-wait` (`-W`)
  Do not wait for the operation to complete

* `--wait`
  Wait for the operation to complete (default)

### Examples

* Require a username and password:

```
upsun environment:http-access --auth myname:mypassword
```

* Restrict access to only one IP address:

```
upsun environment:http-access --access allow:69.208.1.192 --access deny:any
```

* Remove the password requirement, keeping IP restrictions:

```
upsun environment:http-access --auth 0
```

* Disable all HTTP access control:

```
upsun environment:http-access --enabled 0
```

## `environment:info`

Read or set properties for an environment

### Usage

```
upsun environment:info [--refresh] [--date-fmt DATE-FMT] [--format FORMAT] [-c|--columns COLUMNS] [--no-header] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [-W|--no-wait] [--wait] [--] [<property> [<value>]]
```

#### Arguments

* `property`(optional)
  The name of the property

* `value`(optional)
  Set a new value for the property

#### Options

* `--refresh`
  Whether to refresh the cache

* `--date-fmt` (expects a value)
  The date format (as a PHP date format string)

* `--format` (expects a value)
  The output format: table, csv, tsv, or plain

* `--columns` (`-c`) (expects a value)
  Columns to display. The % or \* characters may be used as a wildcard. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--no-header`
  Do not output the table header

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--no-wait` (`-W`)
  Do not wait for the operation to complete

* `--wait`
  Wait for the operation to complete (default)

### Examples

* Read all environment properties:

```
upsun environment:info 
```

* Show the environment's status:

```
upsun environment:info status
```

* Show the date the environment was created:

```
upsun environment:info created_at
```

* Enable email sending:

```
upsun environment:info enable_smtp true
```

* Change the environment title:

```
upsun environment:info title "New feature"
```

* Change the environment's parent branch:

```
upsun environment:info parent sprint-2
```

* Unset the environment's parent branch:

```
upsun environment:info parent -
```

## `environment:init`

Initialize an environment from a public Git repository

### Usage

```
upsun environment:init [--profile PROFILE] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [-W|--no-wait] [--wait] [--] <url>
```

#### Arguments

* `url`(required)
  A URL to a Git repository

#### Options

* `--profile` (expects a value)
  The name of the profile

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--no-wait` (`-W`)
  Do not wait for the operation to complete

* `--wait`
  Wait for the operation to complete (default)

## `environment:list`

Get a list of environments

Aliases: `environments`, `env`

### Usage

```
upsun environments [-I|--no-inactive] [--status STATUS] [--pipe] [--refresh REFRESH] [--sort SORT] [--reverse] [--type TYPE] [--format FORMAT] [-c|--columns COLUMNS] [--no-header] [-p|--project PROJECT]
```

#### Options

* `--no-inactive` (`-I`)
  Do not show inactive environments

* `--status` (expects a value)
  Filter environments by status (active, inactive, dirty, paused, deleting). Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--pipe`
  Output a simple list of environment IDs.

* `--refresh` (expects a value)
  Whether to refresh the list.

* `--sort` (expects a value)
  A property to sort by

* `--reverse`
  Sort in reverse (descending) order

* `--type` (expects a value)
  Filter the list by environment type(s). Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--format` (expects a value)
  The output format: table, csv, tsv, or plain

* `--columns` (`-c`) (expects a value)
  Columns to display. Available columns: id\*, title\*, status\*, type\*, created, machine\_name, updated (\* = default columns). The character "+" can be used as a placeholder for the default columns. The % or \* characters may be used as a wildcard. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--no-header`
  Do not output the table header

* `--project` (`-p`) (expects a value)
  The project ID or URL

## `environment:logs`

Read an environment's logs

Aliases: `log`

### Usage

```
upsun log [--lines LINES] [--tail] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [-A|--app APP] [--worker WORKER] [-I|--instance INSTANCE] [--task TASK] [--activity ACTIVITY] [--] [<type>]
```

#### Arguments

* `type`(optional)
  The log type, e.g. "access" or "error"

#### Options

* `--lines` (expects a value)
  The number of lines to show

* `--tail`
  Continuously tail the log

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--app` (`-A`) (expects a value)
  The remote application name

* `--worker` (expects a value)
  A worker name

* `--instance` (`-I`) (expects a value)
  An instance ID

* `--task` (expects a value)
  The name of a running task (instead of an app or worker)

* `--activity` (expects a value)
  The ID of the task run to target (with --task), when multiple runs are in progress

### Examples

* Display a choice of logs that can be read:

```
upsun environment:logs 
```

* Read the deploy log:

```
upsun environment:logs deploy
```

* Read the access log continuously:

```
upsun environment:logs access --tail
```

* Read the last 500 lines of the cron log:

```
upsun environment:logs cron --lines 500
```

## `environment:merge`

Merge an environment

Aliases: `merge`

### Usage

```
upsun merge [--resources-init RESOURCES-INIT] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [-W|--no-wait] [--wait] [--] [<environment>]
```

This command will initiate a Git merge of the specified environment into its parent environment.

#### Arguments

* `environment`(optional)
  The environment to merge

#### Options

* `--resources-init` (expects a value)
  Set the resources to use for new services: child, default, minimum or manual. If not set, "child" will be used.

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--no-wait` (`-W`)
  Do not wait for the operation to complete

* `--wait`
  Wait for the operation to complete (default)

### Examples

* Merge the environment "sprint-2" into its parent:

```
upsun environment:merge sprint-2
```

## `environment:pause`

Pause an environment

### Usage

```
upsun environment:pause [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [-W|--no-wait] [--wait]
```

Pausing an environment helps to reduce resource consumption and carbon emissions.

The environment will be unavailable until it is resumed. No data will be lost.

#### Options

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--no-wait` (`-W`)
  Do not wait for the operation to complete

* `--wait`
  Wait for the operation to complete (default)

## `environment:push`

Push code to an environment

Aliases: `push`

### Usage

```
upsun push [--target TARGET] [-f|--force] [--force-with-lease] [-u|--set-upstream] [--activate] [--parent PARENT] [--type TYPE] [--no-clone-parent] [-s|--deploy-strategy DEPLOY-STRATEGY] [--resources-init RESOURCES-INIT] [-W|--no-wait] [--wait] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [--] [<source>]
```

#### Arguments

* `source`(optional)
  The Git source ref, e.g. a branch name or a commit hash.

#### Options

* `--target` (expects a value)
  The target branch name. Defaults to the current branch.

* `--force` (`-f`)
  Allow non-fast-forward updates

* `--force-with-lease`
  Allow non-fast-forward updates, if the remote-tracking branch is up to date

* `--set-upstream` (`-u`)
  Set the target environment as the upstream for the source branch. This will also set the target project as the remote for the local repository.

* `--activate`
  Activate the environment. Paused environments will be resumed. This will ensure the environment is active even if no changes were pushed.

* `--parent` (expects a value)
  Set the environment parent (only used with --activate)

* `--type` (expects a value)
  Set the environment type (only used with --activate )

* `--no-clone-parent`
  Do not clone the parent branch's data (only used with --activate)

* `--deploy-strategy` (`-s`) (expects a value)
  Set the deployment strategy, rolling or stopstart (default)

* `--resources-init` (expects a value)
  Set the resources to use for new services: parent, default, minimum, or manual. Currently the default is "default" but this will change to "parent" in future.

* `--no-wait` (`-W`)
  Do not wait for the operation to complete

* `--wait`
  Wait for the operation to complete (default)

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

### Examples

* Push code to the current environment:

```
upsun environment:push 
```

* Push code, without waiting for deployment:

```
upsun environment:push --no-wait
```

* Push code, branching or activating the environment as a child of 'develop':

```
upsun environment:push --activate --parent develop
```

## `environment:redeploy`

Redeploy an environment

Aliases: `redeploy`

### Usage

```
upsun redeploy [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [-W|--no-wait] [--wait]
```

#### Options

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--no-wait` (`-W`)
  Do not wait for the operation to complete

* `--wait`
  Wait for the operation to complete (default)

## `environment:relationships`

Show an environment's relationships

Aliases: `relationships`, `rel`

### Usage

```
upsun relationships [-P|--property PROPERTY] [--refresh] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [-A|--app APP] [--] [<environment>]
```

#### Arguments

* `environment`(optional)
  The environment

#### Options

* `--property` (`-P`) (expects a value)
  The relationship property to view

* `--refresh`
  Whether to refresh the relationships

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--app` (`-A`) (expects a value)
  The remote application name

### Examples

* View all the current environment's relationships:

```
upsun environment:relationships 
```

* View the 'main' environment's relationships:

```
upsun environment:relationships main
```

* View the 'main' environment's database port:

```
upsun environment:relationships main --property database.0.port
```

## `environment:resume`

Resume a paused environment

### Usage

```
upsun environment:resume [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [-W|--no-wait] [--wait]
```

#### Options

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--no-wait` (`-W`)
  Do not wait for the operation to complete

* `--wait`
  Wait for the operation to complete (default)

## `environment:scp`

Copy files to and from an environment using scp

Aliases: `scp`

### Usage

```
upsun scp [-r|--recursive] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [-A|--app APP] [--worker WORKER] [-I|--instance INSTANCE] [--task TASK] [--activity ACTIVITY] [--] [<files>...]
```

#### Arguments

* `files`(optional; multiple values allowed)
  Files to copy. Use the remote: prefix to define remote locations.

#### Options

* `--recursive` (`-r`)
  Recursively copy entire directories

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--app` (`-A`) (expects a value)
  The remote application name

* `--worker` (expects a value)
  A worker name

* `--instance` (`-I`) (expects a value)
  An instance ID

* `--task` (expects a value)
  The name of a running task (instead of an app or worker)

* `--activity` (expects a value)
  The ID of the task run to target (with --task), when multiple runs are in progress

### Examples

* Copy local files a.txt and b.txt to remote mount var/files:

```
upsun environment:scp a.txt b.txt remote:var/files
```

* Copy remote files c.txt to current directory:

```
upsun environment:scp remote:c.txt .
```

* Copy subdirectory dump/ to remote mount var/files:

```
upsun environment:scp -r dump remote:var/logs
```

* Copy files inside subdirectory dump/ to remote mount var/files:

```
upsun environment:scp -r dump/* remote:var/logs
```

## `environment:ssh`

SSH to the current environment

Aliases: `ssh`

### Usage

```
upsun ssh [--pipe] [--all] [-o|--option OPTION] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [-A|--app APP] [--worker WORKER] [-I|--instance INSTANCE] [--task TASK] [--activity ACTIVITY] [--] [<cmd>...]
```

#### Arguments

* `cmd`(optional; multiple values allowed)
  A command to run on the environment.

#### Options

* `--pipe`
  Output the SSH URL only.

* `--all`
  Output all SSH URLs (for every app).

* `--option` (`-o`) (expects a value)
  Pass an extra option to SSH

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--app` (`-A`) (expects a value)
  The remote application name

* `--worker` (expects a value)
  A worker name

* `--instance` (`-I`) (expects a value)
  An instance ID

* `--task` (expects a value)
  The name of a running task (instead of an app or worker)

* `--activity` (expects a value)
  The ID of the task run to target (with --task), when multiple runs are in progress

### Examples

* Open a shell over SSH:

```
upsun environment:ssh 
```

* Open a shell into a running task container:

```
upsun environment:ssh --task mytask
```

* Pass an extra option to SSH:

```
upsun environment:ssh -o 'RequestTTY force'
```

* List files:

```
upsun environment:ssh ls
```

* Monitor the app log (use '--' before flags):

```
upsun environment:ssh tail /var/log/app.log -- -n50 -f
```

* Display relationships (use quotes for complex syntax):

```
upsun environment:ssh 'echo $PLATFORM_RELATIONSHIPS | base64 --decode'
```

## `environment:synchronize`

Synchronize an environment's code, data and/or resources from its parent

Aliases: `sync`

### Usage

```
upsun sync [--rebase] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [-W|--no-wait] [--wait] [--] [<synchronize>...]
```

This command synchronizes to a child environment from its parent environment.

Synchronizing "code" means there will be a Git merge from the parent to the
child.

Synchronizing "data" means that all files in all services (including
static files, databases, logs, search indices, etc.) will be copied from the
parent to the child.

Synchronizing "resources" means that the parent environment's resource sizes
will be used for all corresponding apps and services in the child environment.

#### Arguments

* `synchronize`(optional; multiple values allowed)
  List what to synchronize: "code", "data", and/or "resources".

#### Options

* `--rebase`
  Synchronize code by rebasing instead of merging

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--no-wait` (`-W`)
  Do not wait for the operation to complete

* `--wait`
  Wait for the operation to complete (default)

### Examples

* Synchronize data from the parent environment:

```
upsun environment:synchronize data
```

* Synchronize code and data from the parent environment:

```
upsun environment:synchronize code data
```

* Synchronize code, data and resources from the parent environment:

```
upsun environment:synchronize code data resources
```

## `environment:url`

Get the public URLs of an environment

Aliases: `url`

### Usage

```
upsun url [-1|--primary] [--browser BROWSER] [--pipe] [-p|--project PROJECT] [-e|--environment ENVIRONMENT]
```

#### Options

* `--primary` (`-1`)
  Only return the URL for the primary route

* `--browser` (expects a value)
  The browser to use to open the URL. Set 0 for none.

* `--pipe`
  Output the URL to stdout.

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

### Examples

* Give a choice of URLs to open (or print all URLs if there is no browser):

```
upsun environment:url 
```

* Print all URLs:

```
upsun environment:url --pipe
```

* Print and/or open the primary route URL:

```
upsun environment:url --primary
```

* Print the primary route URL:

```
upsun environment:url --primary --pipe
```

## `environment:xdebug`

Open a tunnel to Xdebug on the environment

Aliases: `xdebug`

### Usage

```
upsun xdebug [--port PORT] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [-A|--app APP] [--worker WORKER] [-I|--instance INSTANCE]
```

#### Options

* `--port` (expects a value)
  The local port

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--app` (`-A`) (expects a value)
  The remote application name

* `--worker` (expects a value)
  A worker name

* `--instance` (`-I`) (expects a value)
  An instance ID

### Examples

* Connect to Xdebug on the environment, listening locally on port 9000.:

```
upsun environment:xdebug 
```

## `integration:activity:get`

View detailed information on a single integration activity

### Usage

```
upsun integration:activity:get [-P|--property PROPERTY] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [--format FORMAT] [-c|--columns COLUMNS] [--no-header] [--date-fmt DATE-FMT] [--] [<integration> [<activity>]]
```

#### Arguments

* `integration`(optional)
  An integration ID. Leave blank to choose from a list.

* `activity`(optional)
  The activity ID. Defaults to the most recent integration activity.

#### Options

* `--property` (`-P`) (expects a value)
  The property to view

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  \[Deprecated option, not used]

* `--format` (expects a value)
  The output format: table, csv, tsv, or plain

* `--columns` (`-c`) (expects a value)
  Columns to display. The % or \* characters may be used as a wildcard. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--no-header`
  Do not output the table header

* `--date-fmt` (expects a value)
  The date format (as a PHP date format string)

## `integration:activity:list`

Get a list of activities for an integration

Aliases: `integration:activities`

### Usage

```
upsun integration:activities [--type TYPE] [-x|--exclude-type EXCLUDE-TYPE] [--limit LIMIT] [--start START] [--state STATE] [--result RESULT] [-i|--incomplete] [--format FORMAT] [-c|--columns COLUMNS] [--no-header] [--date-fmt DATE-FMT] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [--] [<id>]
```

#### Arguments

* `id`(optional)
  An integration ID. Leave blank to choose from a list.

#### Options

* `--type` (expects a value)
  Filter activities by type. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--exclude-type` (`-x`) (expects a value)
  Exclude activities by type. Values may be split by commas (e.g. "a,b,c") and/or whitespace. The % or \* characters can be used as a wildcard to exclude types.

* `--limit` (expects a value)
  Limit the number of results displayed

* `--start` (expects a value)
  Only activities created before this date will be listed

* `--state` (expects a value)
  Filter activities by state. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--result` (expects a value)
  Filter activities by result

* `--incomplete` (`-i`)
  Only list incomplete activities

* `--format` (expects a value)
  The output format: table, csv, tsv, or plain

* `--columns` (`-c`) (expects a value)
  Columns to display. Available columns: id\*, created\*, description\*, type\*, state\*, result\*, completed, progress, time\_build, time\_deploy, time\_execute, time\_wait (\* = default columns). The character "+" can be used as a placeholder for the default columns. The % or \* characters may be used as a wildcard. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--no-header`
  Do not output the table header

* `--date-fmt` (expects a value)
  The date format (as a PHP date format string)

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  \[Deprecated option, not used]

## `integration:activity:log`

Display the log for an integration activity

### Usage

```
upsun integration:activity:log [-t|--timestamps] [--date-fmt DATE-FMT] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [--] [<integration> [<activity>]]
```

#### Arguments

* `integration`(optional)
  An integration ID. Leave blank to choose from a list.

* `activity`(optional)
  The activity ID. Defaults to the most recent integration activity.

#### Options

* `--timestamps` (`-t`)
  Display a timestamp next to each message

* `--date-fmt` (expects a value)
  The date format (as a PHP date format string)

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  \[Deprecated option, not used]

## `integration:add`

Add an integration to the project

### Usage

```
upsun integration:add [--type TYPE] [--base-url BASE-URL] [--bitbucket-url BITBUCKET-URL] [--username USERNAME] [--token TOKEN] [--key KEY] [--secret SECRET] [--license-key LICENSE-KEY] [--server-project SERVER-PROJECT] [--repository REPOSITORY] [--build-merge-requests BUILD-MERGE-REQUESTS] [--build-pull-requests BUILD-PULL-REQUESTS] [--build-draft-pull-requests BUILD-DRAFT-PULL-REQUESTS] [--build-pull-requests-post-merge BUILD-PULL-REQUESTS-POST-MERGE] [--build-wip-merge-requests BUILD-WIP-MERGE-REQUESTS] [--merge-requests-clone-parent-data MERGE-REQUESTS-CLONE-PARENT-DATA] [--pull-requests-clone-parent-data PULL-REQUESTS-CLONE-PARENT-DATA] [--resync-pull-requests RESYNC-PULL-REQUESTS] [--fetch-branches FETCH-BRANCHES] [--prune-branches PRUNE-BRANCHES] [--resources-init RESOURCES-INIT] [--url URL] [--shared-key SHARED-KEY] [--file FILE] [--events EVENTS] [--states STATES] [--environments ENVIRONMENTS] [--excluded-environments EXCLUDED-ENVIRONMENTS] [--from-address FROM-ADDRESS] [--recipients RECIPIENTS] [--channel CHANNEL] [--routing-key ROUTING-KEY] [--category CATEGORY] [--index INDEX] [--sourcetype SOURCETYPE] [--protocol PROTOCOL] [--syslog-host SYSLOG-HOST] [--syslog-port SYSLOG-PORT] [--facility FACILITY] [--message-format MESSAGE-FORMAT] [--auth-mode AUTH-MODE] [--auth-token AUTH-TOKEN] [--verify-tls VERIFY-TLS] [--redaction REDACTION] [--header HEADER] [--excluded-services EXCLUDED-SERVICES] [-p|--project PROJECT] [-W|--no-wait] [--wait]
```

#### Options

* `--type` (expects a value)
  The integration type ('bitbucket', 'bitbucket\_server', 'github', 'gitlab', 'webhook', 'health.email', 'health.pagerduty', 'health.slack', 'health.webhook', 'httplog', 'script', 'newrelic', 'splunk', 'sumologic', 'syslog', 'otlplog')

* `--base-url` (expects a value)
  The base URL of the server installation

* `--bitbucket-url` (expects a value)
  The base URL of the Bitbucket Server installation

* `--username` (expects a value)
  The Bitbucket Server username

* `--token` (expects a value)
  An authentication or access token for the integration

* `--key` (expects a value)
  A Bitbucket OAuth consumer key

* `--secret` (expects a value)
  A Bitbucket OAuth consumer secret

* `--license-key` (expects a value)
  The New Relic Logs license key

* `--server-project` (expects a value)
  The project (e.g. 'namespace/repo')

* `--repository` (expects a value)
  The repository to track (e.g. 'owner/repository')

* `--build-merge-requests` (expects a value)
  GitLab: build merge requests as environments

* `--build-pull-requests` (expects a value)
  Build every pull request as an environment

* `--build-draft-pull-requests` (expects a value)
  Build draft pull requests

* `--build-pull-requests-post-merge` (expects a value)
  Build pull requests based on their post-merge state

* `--build-wip-merge-requests` (expects a value)
  GitLab: build WIP merge requests

* `--merge-requests-clone-parent-data` (expects a value)
  GitLab: clone data for merge requests

* `--pull-requests-clone-parent-data` (expects a value)
  Clone the parent environment's data for pull requests

* `--resync-pull-requests` (expects a value)
  Re-sync pull request environment data on every build

* `--fetch-branches` (expects a value)
  Fetch all branches from the remote (as inactive environments)

* `--prune-branches` (expects a value)
  Delete branches that do not exist on the remote

* `--resources-init` (expects a value)
  The resources to use when initializing a new service ('minimum', 'default', 'manual', 'parent')

* `--url` (expects a value)
  The URL or API endpoint for the integration

* `--shared-key` (expects a value)
  Webhook: the JWS shared secret key

* `--file` (expects a value)
  The name of a local file that contains the script to upload

* `--events` (expects a value)
  A list of events to act on, e.g. environment.push

* `--states` (expects a value)
  A list of states to act on, e.g. pending, in\_progress, complete

* `--environments` (expects a value)
  The environment IDs to include

* `--excluded-environments` (expects a value)
  The environment IDs to exclude

* `--from-address` (expects a value)
  \[Optional] Custom From address for alert emails

* `--recipients` (expects a value)
  The recipient email address(es)

* `--channel` (expects a value)
  The Slack channel

* `--routing-key` (expects a value)
  The PagerDuty routing key

* `--category` (expects a value)
  The Sumo Logic category, used for filtering

* `--index` (expects a value)
  The Splunk index

* `--sourcetype` (expects a value)
  The Splunk event source type

* `--protocol` (expects a value)
  Syslog transport protocol ('tcp', 'udp', 'tls')

* `--syslog-host` (expects a value)
  Syslog relay/collector host

* `--syslog-port` (expects a value)
  Syslog relay/collector port

* `--facility` (expects a value)
  Syslog facility

* `--message-format` (expects a value)
  Syslog message format ('rfc3164' or 'rfc5424')

* `--auth-mode` (expects a value)
  Authentication mode ('prefix' or 'structured\_data')

* `--auth-token` (expects a value)
  Authentication token

* `--verify-tls` (expects a value)
  Whether HTTPS certificate verification should be enabled (recommended)

* `--redaction` (expects a value)
  Whether to enable built-in PII redaction (e.g. email addresses) before forwarding log lines

* `--header` (expects a value)
  HTTP header(s) to use in POST requests. Separate names and values with a colon (:).

* `--excluded-services` (expects a value)
  A list of services to exclude from the log forwarding.

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--no-wait` (`-W`)
  Do not wait for the operation to complete

* `--wait`
  Wait for the operation to complete (default)

### Examples

* Add an integration with a GitHub repository:

```
upsun integration:add --type github --repository myuser/example-repo --token 9218376e14c2797e0d06e8d2f918d45f --fetch-branches 0
```

* Add an integration with a GitLab repository:

```
upsun integration:add --type gitlab --server-project mygroup/example-repo --token 22fe4d70dfbc20e4f668568a0b5422e2 --base-url https://gitlab.example.com
```

## `integration:delete`

Delete an integration from a project

### Usage

```
upsun integration:delete [-p|--project PROJECT] [-W|--no-wait] [--wait] [--] [<id>]
```

#### Arguments

* `id`(optional)
  The integration ID. Leave blank to choose from a list.

#### Options

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--no-wait` (`-W`)
  Do not wait for the operation to complete

* `--wait`
  Wait for the operation to complete (default)

## `integration:get`

View details of an integration

### Usage

```
upsun integration:get [-P|--property [PROPERTY]] [--format FORMAT] [-c|--columns COLUMNS] [--no-header] [-p|--project PROJECT] [--] [<id>]
```

#### Arguments

* `id`(optional)
  An integration ID. Leave blank to choose from a list.

#### Options

* `--property` (`-P`) (expects a value)
  The integration property to view

* `--format` (expects a value)
  The output format: table, csv, tsv, or plain

* `--columns` (`-c`) (expects a value)
  Columns to display. The % or \* characters may be used as a wildcard. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--no-header`
  Do not output the table header

* `--project` (`-p`) (expects a value)
  The project ID or URL

## `integration:list`

View a list of project integration(s)

Aliases: `integrations`

### Usage

```
upsun integrations [-t|--type TYPE] [--format FORMAT] [-c|--columns COLUMNS] [--no-header] [-p|--project PROJECT]
```

#### Options

* `--type` (`-t`) (expects a value)
  Filter by type

* `--format` (expects a value)
  The output format: table, csv, tsv, or plain

* `--columns` (`-c`) (expects a value)
  Columns to display. Available columns: id, summary, type. The % or \* characters may be used as a wildcard. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--no-header`
  Do not output the table header

* `--project` (`-p`) (expects a value)
  The project ID or URL

## `integration:update`

Update an integration

### Usage

```
upsun integration:update [--type TYPE] [--base-url BASE-URL] [--bitbucket-url BITBUCKET-URL] [--username USERNAME] [--token TOKEN] [--key KEY] [--secret SECRET] [--license-key LICENSE-KEY] [--server-project SERVER-PROJECT] [--repository REPOSITORY] [--build-merge-requests BUILD-MERGE-REQUESTS] [--build-pull-requests BUILD-PULL-REQUESTS] [--build-draft-pull-requests BUILD-DRAFT-PULL-REQUESTS] [--build-pull-requests-post-merge BUILD-PULL-REQUESTS-POST-MERGE] [--build-wip-merge-requests BUILD-WIP-MERGE-REQUESTS] [--merge-requests-clone-parent-data MERGE-REQUESTS-CLONE-PARENT-DATA] [--pull-requests-clone-parent-data PULL-REQUESTS-CLONE-PARENT-DATA] [--resync-pull-requests RESYNC-PULL-REQUESTS] [--fetch-branches FETCH-BRANCHES] [--prune-branches PRUNE-BRANCHES] [--resources-init RESOURCES-INIT] [--url URL] [--shared-key SHARED-KEY] [--file FILE] [--events EVENTS] [--states STATES] [--environments ENVIRONMENTS] [--excluded-environments EXCLUDED-ENVIRONMENTS] [--from-address FROM-ADDRESS] [--recipients RECIPIENTS] [--channel CHANNEL] [--routing-key ROUTING-KEY] [--category CATEGORY] [--index INDEX] [--sourcetype SOURCETYPE] [--protocol PROTOCOL] [--syslog-host SYSLOG-HOST] [--syslog-port SYSLOG-PORT] [--facility FACILITY] [--message-format MESSAGE-FORMAT] [--auth-mode AUTH-MODE] [--auth-token AUTH-TOKEN] [--verify-tls VERIFY-TLS] [--redaction REDACTION] [--header HEADER] [--excluded-services EXCLUDED-SERVICES] [-p|--project PROJECT] [-W|--no-wait] [--wait] [--] [<id>]
```

#### Arguments

* `id`(optional)
  The ID of the integration to update

#### Options

* `--type` (expects a value)
  The integration type ('bitbucket', 'bitbucket\_server', 'github', 'gitlab', 'webhook', 'health.email', 'health.pagerduty', 'health.slack', 'health.webhook', 'httplog', 'script', 'newrelic', 'splunk', 'sumologic', 'syslog', 'otlplog')

* `--base-url` (expects a value)
  The base URL of the server installation

* `--bitbucket-url` (expects a value)
  The base URL of the Bitbucket Server installation

* `--username` (expects a value)
  The Bitbucket Server username

* `--token` (expects a value)
  An authentication or access token for the integration

* `--key` (expects a value)
  A Bitbucket OAuth consumer key

* `--secret` (expects a value)
  A Bitbucket OAuth consumer secret

* `--license-key` (expects a value)
  The New Relic Logs license key

* `--server-project` (expects a value)
  The project (e.g. 'namespace/repo')

* `--repository` (expects a value)
  The repository to track (e.g. 'owner/repository')

* `--build-merge-requests` (expects a value)
  GitLab: build merge requests as environments

* `--build-pull-requests` (expects a value)
  Build every pull request as an environment

* `--build-draft-pull-requests` (expects a value)
  Build draft pull requests

* `--build-pull-requests-post-merge` (expects a value)
  Build pull requests based on their post-merge state

* `--build-wip-merge-requests` (expects a value)
  GitLab: build WIP merge requests

* `--merge-requests-clone-parent-data` (expects a value)
  GitLab: clone data for merge requests

* `--pull-requests-clone-parent-data` (expects a value)
  Clone the parent environment's data for pull requests

* `--resync-pull-requests` (expects a value)
  Re-sync pull request environment data on every build

* `--fetch-branches` (expects a value)
  Fetch all branches from the remote (as inactive environments)

* `--prune-branches` (expects a value)
  Delete branches that do not exist on the remote

* `--resources-init` (expects a value)
  The resources to use when initializing a new service ('minimum', 'default', 'manual', 'parent')

* `--url` (expects a value)
  The URL or API endpoint for the integration

* `--shared-key` (expects a value)
  Webhook: the JWS shared secret key

* `--file` (expects a value)
  The name of a local file that contains the script to upload

* `--events` (expects a value)
  A list of events to act on, e.g. environment.push

* `--states` (expects a value)
  A list of states to act on, e.g. pending, in\_progress, complete

* `--environments` (expects a value)
  The environment IDs to include

* `--excluded-environments` (expects a value)
  The environment IDs to exclude

* `--from-address` (expects a value)
  \[Optional] Custom From address for alert emails

* `--recipients` (expects a value)
  The recipient email address(es)

* `--channel` (expects a value)
  The Slack channel

* `--routing-key` (expects a value)
  The PagerDuty routing key

* `--category` (expects a value)
  The Sumo Logic category, used for filtering

* `--index` (expects a value)
  The Splunk index

* `--sourcetype` (expects a value)
  The Splunk event source type

* `--protocol` (expects a value)
  Syslog transport protocol ('tcp', 'udp', 'tls')

* `--syslog-host` (expects a value)
  Syslog relay/collector host

* `--syslog-port` (expects a value)
  Syslog relay/collector port

* `--facility` (expects a value)
  Syslog facility

* `--message-format` (expects a value)
  Syslog message format ('rfc3164' or 'rfc5424')

* `--auth-mode` (expects a value)
  Authentication mode ('prefix' or 'structured\_data')

* `--auth-token` (expects a value)
  Authentication token

* `--verify-tls` (expects a value)
  Whether HTTPS certificate verification should be enabled (recommended)

* `--redaction` (expects a value)
  Whether to enable built-in PII redaction (e.g. email addresses) before forwarding log lines

* `--header` (expects a value)
  HTTP header(s) to use in POST requests. Separate names and values with a colon (:).

* `--excluded-services` (expects a value)
  A list of services to exclude from the log forwarding.

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--no-wait` (`-W`)
  Do not wait for the operation to complete

* `--wait`
  Wait for the operation to complete (default)

### Examples

* Switch on the "fetch branches" option for a specific integration:

```
upsun integration:update ZXhhbXBsZSB --fetch-branches 1
```

## `integration:validate`

Validate an existing integration

### Usage

```
upsun integration:validate [-p|--project PROJECT] [--] [<id>]
```

This command allows you to check whether an integration is valid.

An exit code of 0 means the integration is valid, while 4 means it is invalid.
Any other exit code indicates an unexpected error.

Integrations are validated automatically on creation and on update. However,
because they involve external resources, it is possible for a valid integration
to become invalid. For example, an access token may be revoked, or an external
repository may be deleted.

#### Arguments

* `id`(optional)
  An integration ID. Leave blank to choose from a list.

#### Options

* `--project` (`-p`) (expects a value)
  The project ID or URL

## `local:dir`

Find the local project root

Aliases: `dir`

### Usage

```
upsun dir [<subdir>]
```

#### Arguments

* `subdir`(optional)
  The subdirectory to find ('local', 'web' or 'shared')

## `metrics:all`

Show CPU, disk and memory metrics for an environment

Aliases: `metrics`, `met`

### Usage

```
upsun metrics [-B|--bytes] [-r|--range RANGE] [-i|--interval INTERVAL] [--to TO] [-1|--latest] [-s|--service SERVICE] [--type TYPE] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [--format FORMAT] [-c|--columns COLUMNS] [--no-header] [--date-fmt DATE-FMT]
```

#### Options

* `--bytes` (`-B`)
  Show sizes in bytes

* `--range` (`-r`) (expects a value)
  The time range. Metrics will be loaded for this duration until the end time (--to). You can specify units: hours (h), minutes (m), or seconds (s). Minimum 5m, maximum 8h or more (depending on the project), default 10m.

* `--interval` (`-i`) (expects a value)
  The time interval. Defaults to a division of the range. You can specify units: hours (h), minutes (m), or seconds (s). Minimum 1m.

* `--to` (expects a value)
  The end time. Defaults to now.

* `--latest` (`-1`)
  Show only the latest single data point

* `--service` (`-s`) (expects a value)
  Filter by service or application name The % or \* characters may be used as a wildcard.

* `--type` (expects a value)
  Filter by service type (if --service is not provided). The version is not required. The % or \* characters may be used as a wildcard.

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--format` (expects a value)
  The output format: table, csv, tsv, or plain

* `--columns` (`-c`) (expects a value)
  Columns to display. Available columns: timestamp\*, service\*, cpu\_percent\*, mem\_percent\*, disk\_percent\*, inodes\_percent\*, tmp\_disk\_percent\*, tmp\_inodes\_percent\*, cpu\_limit, cpu\_used, disk\_limit, disk\_used, inodes\_limit, inodes\_used, mem\_limit, mem\_used, tmp\_disk\_limit, tmp\_disk\_used, tmp\_inodes\_limit, tmp\_inodes\_used, type (\* = default columns). The character "+" can be used as a placeholder for the default columns. The % or \* characters may be used as a wildcard. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--no-header`
  Do not output the table header

* `--date-fmt` (expects a value)
  The date format (as a PHP date format string)

### Examples

* Show metrics for the last 10m:

```
upsun metrics:all 
```

* Show metrics over the last hour:

```
upsun metrics:all  -r 1h
```

* Show metrics for all SQL services:

```
upsun metrics:all --type mariadb,%sql
```

## `metrics:cpu`

Show CPU usage of an environment

Aliases: `cpu`

### Usage

```
upsun cpu [-r|--range RANGE] [-i|--interval INTERVAL] [--to TO] [-1|--latest] [-s|--service SERVICE] [--type TYPE] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [--format FORMAT] [-c|--columns COLUMNS] [--no-header] [--date-fmt DATE-FMT]
```

#### Options

* `--range` (`-r`) (expects a value)
  The time range. Metrics will be loaded for this duration until the end time (--to). You can specify units: hours (h), minutes (m), or seconds (s). Minimum 5m, maximum 8h or more (depending on the project), default 10m.

* `--interval` (`-i`) (expects a value)
  The time interval. Defaults to a division of the range. You can specify units: hours (h), minutes (m), or seconds (s). Minimum 1m.

* `--to` (expects a value)
  The end time. Defaults to now.

* `--latest` (`-1`)
  Show only the latest single data point

* `--service` (`-s`) (expects a value)
  Filter by service or application name The % or \* characters may be used as a wildcard.

* `--type` (expects a value)
  Filter by service type (if --service is not provided). The version is not required. The % or \* characters may be used as a wildcard.

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--format` (expects a value)
  The output format: table, csv, tsv, or plain

* `--columns` (`-c`) (expects a value)
  Columns to display. Available columns: timestamp\*, service\*, used\*, limit\*, percent\*, type (\* = default columns). The character "+" can be used as a placeholder for the default columns. The % or \* characters may be used as a wildcard. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--no-header`
  Do not output the table header

* `--date-fmt` (expects a value)
  The date format (as a PHP date format string)

## `metrics:disk-usage`

Show disk usage of an environment

Aliases: `disk`

### Usage

```
upsun disk [-B|--bytes] [--tmp] [-r|--range RANGE] [-i|--interval INTERVAL] [--to TO] [-1|--latest] [-s|--service SERVICE] [--type TYPE] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [--format FORMAT] [-c|--columns COLUMNS] [--no-header] [--date-fmt DATE-FMT]
```

#### Options

* `--bytes` (`-B`)
  Show sizes in bytes

* `--tmp`
  Report temporary disk usage (shows columns: timestamp, service, tmp\_used, tmp\_limit, tmp\_percent, tmp\_ipercent)

* `--range` (`-r`) (expects a value)
  The time range. Metrics will be loaded for this duration until the end time (--to). You can specify units: hours (h), minutes (m), or seconds (s). Minimum 5m, maximum 8h or more (depending on the project), default 10m.

* `--interval` (`-i`) (expects a value)
  The time interval. Defaults to a division of the range. You can specify units: hours (h), minutes (m), or seconds (s). Minimum 1m.

* `--to` (expects a value)
  The end time. Defaults to now.

* `--latest` (`-1`)
  Show only the latest single data point

* `--service` (`-s`) (expects a value)
  Filter by service or application name The % or \* characters may be used as a wildcard.

* `--type` (expects a value)
  Filter by service type (if --service is not provided). The version is not required. The % or \* characters may be used as a wildcard.

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--format` (expects a value)
  The output format: table, csv, tsv, or plain

* `--columns` (`-c`) (expects a value)
  Columns to display. Available columns: timestamp\*, service\*, used\*, limit\*, percent\*, ipercent\*, tmp\_percent\*, ilimit, iused, tmp\_ilimit, tmp\_ipercent, tmp\_iused, tmp\_limit, tmp\_used, type (\* = default columns). The character "+" can be used as a placeholder for the default columns. The % or \* characters may be used as a wildcard. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--no-header`
  Do not output the table header

* `--date-fmt` (expects a value)
  The date format (as a PHP date format string)

## `metrics:memory`

Show memory usage of an environment

Aliases: `mem`, `memory`

### Usage

```
upsun mem [-B|--bytes] [-r|--range RANGE] [-i|--interval INTERVAL] [--to TO] [-1|--latest] [-s|--service SERVICE] [--type TYPE] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [--format FORMAT] [-c|--columns COLUMNS] [--no-header] [--date-fmt DATE-FMT]
```

#### Options

* `--bytes` (`-B`)
  Show sizes in bytes

* `--range` (`-r`) (expects a value)
  The time range. Metrics will be loaded for this duration until the end time (--to). You can specify units: hours (h), minutes (m), or seconds (s). Minimum 5m, maximum 8h or more (depending on the project), default 10m.

* `--interval` (`-i`) (expects a value)
  The time interval. Defaults to a division of the range. You can specify units: hours (h), minutes (m), or seconds (s). Minimum 1m.

* `--to` (expects a value)
  The end time. Defaults to now.

* `--latest` (`-1`)
  Show only the latest single data point

* `--service` (`-s`) (expects a value)
  Filter by service or application name The % or \* characters may be used as a wildcard.

* `--type` (expects a value)
  Filter by service type (if --service is not provided). The version is not required. The % or \* characters may be used as a wildcard.

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--format` (expects a value)
  The output format: table, csv, tsv, or plain

* `--columns` (`-c`) (expects a value)
  Columns to display. Available columns: timestamp\*, service\*, used\*, limit\*, percent\*, type (\* = default columns). The character "+" can be used as a placeholder for the default columns. The % or \* characters may be used as a wildcard. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--no-header`
  Do not output the table header

* `--date-fmt` (expects a value)
  The date format (as a PHP date format string)

## `mount:download`

Download files from a mount, using rsync

### Usage

```
upsun mount:download [-a|--all] [-m|--mount MOUNT] [--target TARGET] [--source-path] [--delete] [--exclude EXCLUDE] [--include INCLUDE] [--refresh] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [-A|--app APP] [--worker WORKER] [-I|--instance INSTANCE]
```

#### Options

* `--all` (`-a`)
  Download from all mounts

* `--mount` (`-m`) (expects a value)
  The mount (as an app-relative path)

* `--target` (expects a value)
  The directory to which files will be downloaded. If --all is used, the mount path will be appended

* `--source-path`
  Use the mount's source path (rather than the mount path) as a subdirectory of the target, when --all is used

* `--delete`
  Whether to delete extraneous files in the target directory

* `--exclude` (expects a value)
  File(s) to exclude from the download (pattern)

* `--include` (expects a value)
  File(s) not to exclude (pattern)

* `--refresh`
  Whether to refresh the cache

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--app` (`-A`) (expects a value)
  The remote application name

* `--worker` (expects a value)
  A worker name

* `--instance` (`-I`) (expects a value)
  An instance ID

## `mount:list`

Get a list of mounts

Aliases: `mounts`

### Usage

```
upsun mounts [--paths] [--refresh] [--format FORMAT] [-c|--columns COLUMNS] [--no-header] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [-A|--app APP] [--worker WORKER] [-I|--instance INSTANCE]
```

#### Options

* `--paths`
  Output the mount paths only (one per line)

* `--refresh`
  Whether to refresh the cache

* `--format` (expects a value)
  The output format: table, csv, tsv, or plain

* `--columns` (`-c`) (expects a value)
  Columns to display. Available columns: definition, path. The % or \* characters may be used as a wildcard. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--no-header`
  Do not output the table header

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--app` (`-A`) (expects a value)
  The remote application name

* `--worker` (expects a value)
  A worker name

* `--instance` (`-I`) (expects a value)
  An instance ID

## `mount:upload`

Upload files to a mount, using rsync

### Usage

```
upsun mount:upload [--source SOURCE] [-m|--mount MOUNT] [--delete] [--exclude EXCLUDE] [--include INCLUDE] [--refresh] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [-A|--app APP] [--worker WORKER] [-I|--instance INSTANCE]
```

#### Options

* `--source` (expects a value)
  A directory containing files to upload

* `--mount` (`-m`) (expects a value)
  The mount (as an app-relative path)

* `--delete`
  Whether to delete extraneous files in the mount

* `--exclude` (expects a value)
  File(s) to exclude from the upload (pattern)

* `--include` (expects a value)
  File(s) not to exclude (pattern)

* `--refresh`
  Whether to refresh the cache

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--app` (`-A`) (expects a value)
  The remote application name

* `--worker` (expects a value)
  A worker name

* `--instance` (`-I`) (expects a value)
  An instance ID

## `operation:list`

List runtime operations on an environment

Aliases: `ops`

### Usage

```
upsun ops [--full] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [-A|--app APP] [--worker WORKER] [--format FORMAT] [-c|--columns COLUMNS] [--no-header]
```

#### Options

* `--full`
  Do not limit the length of command to display. The default limit is 24 lines.

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--app` (`-A`) (expects a value)
  The remote application name

* `--worker` (expects a value)
  A worker name

* `--format` (expects a value)
  The output format: table, csv, tsv, or plain

* `--columns` (`-c`) (expects a value)
  Columns to display. Available columns: service\*, name\*, start\*, role, stop (\* = default columns). The character "+" can be used as a placeholder for the default columns. The % or \* characters may be used as a wildcard. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--no-header`
  Do not output the table header

## `operation:run`

Run an operation on the environment

### Usage

```
upsun operation:run [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [-A|--app APP] [--worker WORKER] [-W|--no-wait] [--wait] [--] [<operation>]
```

#### Arguments

* `operation`(optional)
  The operation name

#### Options

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--app` (`-A`) (expects a value)
  The remote application name

* `--worker` (expects a value)
  A worker name

* `--no-wait` (`-W`)
  Do not wait for the operation to complete

* `--wait`
  Wait for the operation to complete (default)

## `organization:billing:address`

View or change an organization's billing address

### Usage

```
upsun organization:billing:address [-o|--org ORG] [-p|--project PROJECT] [--date-fmt DATE-FMT] [--format FORMAT] [-c|--columns COLUMNS] [--no-header] [--] [<property> [<value> [<properties>...]]]
```

#### Arguments

* `property`(optional)
  The name of a property to view or change

* `value`(optional)
  A new value for the property

* `properties`(optional; multiple values allowed)
  Additional property/value pairs

#### Options

* `--org` (`-o`) (expects a value)
  The organization name (or ID)

* `--project` (`-p`) (expects a value)
  The project ID or URL, which auto-selects the organization if --org is not used

* `--date-fmt` (expects a value)
  The date format (as a PHP date format string)

* `--format` (expects a value)
  The output format: table, csv, tsv, or plain

* `--columns` (`-c`) (expects a value)
  Columns to display. The % or \* characters may be used as a wildcard. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--no-header`
  Do not output the table header

## `organization:billing:profile`

View or change an organization's billing profile

### Usage

```
upsun organization:billing:profile [-o|--org ORG] [-p|--project PROJECT] [--date-fmt DATE-FMT] [--format FORMAT] [-c|--columns COLUMNS] [--no-header] [--] [<property> [<value>]]
```

#### Arguments

* `property`(optional)
  The name of a property to view or change

* `value`(optional)
  A new value for the property

#### Options

* `--org` (`-o`) (expects a value)
  The organization name (or ID)

* `--project` (`-p`) (expects a value)
  The project ID or URL, which auto-selects the organization if --org is not used

* `--date-fmt` (expects a value)
  The date format (as a PHP date format string)

* `--format` (expects a value)
  The output format: table, csv, tsv, or plain

* `--columns` (`-c`) (expects a value)
  Columns to display. The % or \* characters may be used as a wildcard. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--no-header`
  Do not output the table header

## `organization:create`

Create a new organization

### Usage

```
upsun organization:create [--label LABEL] [--type TYPE] [--name NAME] [--country COUNTRY]
```

Organizations allow you to manage your Upsun Cloud projects, users and billing. Projects are owned by organizations.

You can add other users to your organization, for collaboratively managing the organization as well as its projects and billing information.

Access to individual projects (API and SSH) is managed separately, for now.

#### Options

* `--label` (expects a value)
  The full name of the organization, e.g. "ACME Inc."

* `--type` (expects a value)
  The organization type. ('flexible' or 'fixed')

* `--name` (expects a value)
  The organization machine name, used for URL paths and similar purposes.

* `--country` (expects a value)
  The organization country. Used as the default for the billing address.

## `organization:delete`

Delete an organization

### Usage

```
upsun organization:delete [-o|--org ORG] [-p|--project PROJECT]
```

#### Options

* `--org` (`-o`) (expects a value)
  The organization name (or ID)

* `--project` (`-p`) (expects a value)
  The project ID or URL, which auto-selects the organization if --org is not used

## `organization:info`

View or change organization details

### Usage

```
upsun organization:info [-o|--org ORG] [-p|--project PROJECT] [--refresh] [--date-fmt DATE-FMT] [--format FORMAT] [-c|--columns COLUMNS] [--no-header] [--] [<property> [<value>]]
```

#### Arguments

* `property`(optional)
  The name of a property to view or change

* `value`(optional)
  A new value for the property

#### Options

* `--org` (`-o`) (expects a value)
  The organization name (or ID)

* `--project` (`-p`) (expects a value)
  The project ID or URL, which auto-selects the organization if --org is not used

* `--refresh`
  Refresh the cache

* `--date-fmt` (expects a value)
  The date format (as a PHP date format string)

* `--format` (expects a value)
  The output format: table, csv, tsv, or plain

* `--columns` (`-c`) (expects a value)
  Columns to display. The % or \* characters may be used as a wildcard. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--no-header`
  Do not output the table header

### Examples

* View the organization "acme":

```
upsun organization:info --org acme
```

* Show the organization's label:

```
upsun organization:info --org acme label
```

* Change the organization label:

```
upsun organization:info --org acme label "ACME Inc."
```

## `organization:list`

List organizations

Aliases: `orgs`, `organizations`

### Usage

```
upsun orgs [--my] [--sort SORT] [--reverse] [--type TYPE] [--format FORMAT] [-c|--columns COLUMNS] [--no-header]
```

#### Options

* `--my`
  List only the organizations you own

* `--sort` (expects a value)
  An organization property to sort by

* `--reverse`
  Sort in reverse order

* `--type` (expects a value)
  Filter organizations by type

* `--format` (expects a value)
  The output format: table, csv, tsv, or plain

* `--columns` (`-c`) (expects a value)
  Columns to display. Available columns: name\*, label\*, type\*, owner\_email\*, created\_at, id, owner\_id, owner\_username, updated\_at (\* = default columns). The character "+" can be used as a placeholder for the default columns. The % or \* characters may be used as a wildcard. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--no-header`
  Do not output the table header

## `organization:subscription:list`

List subscriptions within an organization

Aliases: `org:subs`

### Usage

```
upsun org:subs [--page PAGE] [-c|--count COUNT] [-o|--org ORG] [-p|--project PROJECT] [--format FORMAT] [--columns COLUMNS] [--no-header]
```

#### Options

* `--page` (expects a value)
  Page number. This enables pagination, despite configuration or --count.

* `--count` (`-c`) (expects a value)
  The number of items to display per page. Use 0 to disable pagination. Ignored if --page is specified.

* `--org` (`-o`) (expects a value)
  The organization name (or ID)

* `--project` (`-p`) (expects a value)
  The project ID or URL, which auto-selects the organization if --org is not used

* `--format` (expects a value)
  The output format: table, csv, tsv, or plain

* `--columns` (expects a value)
  Columns to display. Available columns: id\*, project\_id\*, project\_title\*, project\_region\*, created\_at, updated\_at (\* = default columns). The character "+" can be used as a placeholder for the default columns. The % or \* characters may be used as a wildcard. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--no-header`
  Do not output the table header

## `organization:user:add`

Invite a user to an organization

### Usage

```
upsun organization:user:add [-o|--org ORG] [--permission PERMISSION] [--] [<email>]
```

#### Arguments

* `email`(optional)
  The email address of the user

#### Options

* `--org` (`-o`) (expects a value)
  The organization name (or ID)

* `--permission` (expects a value)
  Permission(s) for the user on the organization. Valid permissions are: billing, members, plans, projects:create, projects:list

## `organization:user:delete`

Remove a user from an organization

### Usage

```
upsun organization:user:delete [-o|--org ORG] [--] <email>
```

#### Arguments

* `email`(required)
  The email address of the user

#### Options

* `--org` (`-o`) (expects a value)
  The organization name (or ID)

## `organization:user:get`

View an organization user

### Usage

```
upsun organization:user:get [-o|--org ORG] [-P|--property PROPERTY] [--date-fmt DATE-FMT] [--format FORMAT] [-c|--columns COLUMNS] [--no-header] [--] [<email>]
```

#### Arguments

* `email`(optional)
  The email address of the user

#### Options

* `--org` (`-o`) (expects a value)
  The organization name (or ID)

* `--property` (`-P`) (expects a value)
  A property to display

* `--date-fmt` (expects a value)
  The date format (as a PHP date format string)

* `--format` (expects a value)
  The output format: table, csv, tsv, or plain

* `--columns` (`-c`) (expects a value)
  Columns to display. The % or \* characters may be used as a wildcard. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--no-header`
  Do not output the table header

## `organization:user:list`

List organization users

Aliases: `org:users`

### Usage

```
upsun org:users [-c|--count COUNT] [--sort SORT] [--reverse] [-o|--org ORG] [-p|--project PROJECT] [--date-fmt DATE-FMT] [--format FORMAT] [--columns COLUMNS] [--no-header]
```

#### Options

* `--count` (`-c`) (expects a value)
  The number of items to display per page. Use 0 to disable pagination.

* `--sort` (expects a value)
  A property to sort by (created\_at or updated\_at)

* `--reverse`
  Reverse the sort order

* `--org` (`-o`) (expects a value)
  The organization name (or ID)

* `--project` (`-p`) (expects a value)
  The project ID or URL, which auto-selects the organization if --org is not used

* `--date-fmt` (expects a value)
  The date format (as a PHP date format string)

* `--format` (expects a value)
  The output format: table, csv, tsv, or plain

* `--columns` (expects a value)
  Columns to display. Available columns: id\*, email\*, owner\*, permissions\*, created\_at, first\_name, last\_name, mfa\_enabled, sso\_enabled, updated\_at, username (\* = default columns). The character "+" can be used as a placeholder for the default columns. The % or \* characters may be used as a wildcard. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--no-header`
  Do not output the table header

## `organization:user:projects`

List the projects a user can access

Aliases: `oups`

### Usage

```
upsun oups [-o|--org ORG] [--list-all] [--format FORMAT] [-c|--columns COLUMNS] [--no-header] [--date-fmt DATE-FMT] [--] [<email>]
```

#### Arguments

* `email`(optional)
  The email address of the user

#### Options

* `--org` (`-o`) (expects a value)
  The organization name (or ID)

* `--list-all`
  List access across all organizations

* `--format` (expects a value)
  The output format: table, csv, tsv, or plain

* `--columns` (`-c`) (expects a value)
  Columns to display. Available columns: project\_id\*, project\_title\*, roles\*, updated\_at\*, granted\_at, organization\_id, organization\_label, organization\_name, region (\* = default columns). The character "+" can be used as a placeholder for the default columns. The % or \* characters may be used as a wildcard. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--no-header`
  Do not output the table header

* `--date-fmt` (expects a value)
  The date format (as a PHP date format string)

## `organization:user:update`

Update an organization user

### Usage

```
upsun organization:user:update [-o|--org ORG] [--permission PERMISSION] [--] [<email>]
```

#### Arguments

* `email`(optional)
  The email address of the user

#### Options

* `--org` (`-o`) (expects a value)
  The organization name (or ID)

* `--permission` (expects a value)
  Permission(s) for the user on the organization. Valid permissions are: billing, members, plans, projects:create, projects:list

## `project:clear-build-cache`

Clear a project's build cache

### Usage

```
upsun project:clear-build-cache [-p|--project PROJECT]
```

#### Options

* `--project` (`-p`) (expects a value)
  The project ID or URL

## `project:convert`

Generate an Upsun Cloud compatible configuration based on the configuration from another provider.

Aliases: `convert`

### Usage

```
upsun convert
```

#### Options

* `--help` (`-h`)
  Display this help message

* `--verbose` (`-v|vv|vvv`)
  Increase the verbosity of messages

* `--version` (`-V`)
  Display this application version

* `--yes` (`-y`)
  Answer "yes" to confirmation questions; accept the default value for other questions; disable interaction

* `--no-interaction`
  Do not ask any interactive questions; accept default values. Equivalent to using the environment variable: UPSUN\_CLI\_NO\_INTERACTION=1

* `--provider` (`-p`)
  The provider from which to convert the configuration. Currently, only 'platformsh' is supported.

### Examples

* Convert the Platform.sh project configuration files in your current directory:

```
upsun project:convert --provider=platformsh
```

## `project:create`

Create a new project

Aliases: `create`

### Usage

```
upsun create [-o|--org ORG] [--title TITLE] [--region REGION] [--plan PLAN] [--environments ENVIRONMENTS] [--storage STORAGE] [--default-branch DEFAULT-BRANCH] [--init-repo INIT-REPO] [--set-remote] [--no-set-remote]
```

Use this command to create a new project.

An interactive form will be presented with the available options. If the
command is run non-interactively (with --yes), the form will not be displayed,
and the --region option will be required.

A project subscription will be requested, and then checked periodically (every
3 seconds) until the project has been activated, or until the process times
out (15 minutes by default).

If known, the project ID will be output to STDOUT. All other output will be sent
to STDERR.

#### Options

* `--org` (`-o`) (expects a value)
  The organization name (or ID)

* `--title` (expects a value)
  The initial project title

* `--region` (expects a value)
  The region where the project will be hosted. Get a 3% discount on resources for regions with a carbon intensity of less than 100 gCO2eq/kWh.

* `--plan` (expects a value)
  The subscription plan

* `--environments` (expects a value)
  The number of environments

* `--storage` (expects a value)
  The amount of storage per environment, in GiB

* `--default-branch` (expects a value)
  The default Git branch name for the project (the production environment)

* `--init-repo` (expects a value)
  URL of a Git repository to use for initialization. A GitHub path such as "platformsh-templates/nuxtjs" can be used.

* `--set-remote`
  Set the new project as the remote for the local project directory. This is the default if no remote is already set.

* `--no-set-remote`
  Do not set the new project as the remote

## `project:delete`

Delete a project

### Usage

```
upsun project:delete [-p|--project PROJECT] [--] [<project>]
```

#### Arguments

* `project`(optional)
  The project ID

#### Options

* `--project` (`-p`) (expects a value)
  The project ID or URL

## `project:get`

Clone a project locally

Aliases: `get`

### Usage

```
upsun get [-e|--environment ENVIRONMENT] [--depth DEPTH] [-p|--project PROJECT] [--] [<project> [<directory>]]
```

#### Arguments

* `project`(optional)
  The project ID

* `directory`(optional)
  The directory to clone to. Defaults to the project title

#### Options

* `--environment` (`-e`) (expects a value)
  The environment ID to clone. Defaults to the project default, or the first available environment

* `--depth` (expects a value)
  Create a shallow clone: limit the number of commits in the history

* `--project` (`-p`) (expects a value)
  The project ID or URL

### Examples

* Clone the project "abc123" into the directory "my-project":

```
upsun project:get abc123 my-project
```

## `project:info`

Read or set properties for a project

### Usage

```
upsun project:info [--refresh] [--date-fmt DATE-FMT] [--format FORMAT] [-c|--columns COLUMNS] [--no-header] [-p|--project PROJECT] [-W|--no-wait] [--wait] [--] [<property> [<value>]]
```

#### Arguments

* `property`(optional)
  The name of the property

* `value`(optional)
  Set a new value for the property

#### Options

* `--refresh`
  Whether to refresh the cache

* `--date-fmt` (expects a value)
  The date format (as a PHP date format string)

* `--format` (expects a value)
  The output format: table, csv, tsv, or plain

* `--columns` (`-c`) (expects a value)
  Columns to display. The % or \* characters may be used as a wildcard. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--no-header`
  Do not output the table header

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--no-wait` (`-W`)
  Do not wait for the operation to complete

* `--wait`
  Wait for the operation to complete (default)

### Examples

* Read all project properties:

```
upsun project:info 
```

* Show the project's Git URL:

```
upsun project:info git
```

* Change the project's title:

```
upsun project:info title "My project"
```

## `project:init`

Initialize a project

Aliases: `init`, `ify`

### Usage

```
upsun init
```

This command will generate a starter configuration that you can build on.
You can use AI, or follow a step-by-step setup guide.

Using AI will send a sanitized repository digest to OpenAI for automated analysis.
You can review the digest at any time by running: upsun init --digest

#### Options

* `--ai` (expects a value)
  Use AI configuration

* `--context` (expects a value)
  Add extra context for AI configuration

* `--digest`
  Only show the repository digest (the AI configuration input), without sending it

* `--help` (`-h`)
  Display this help message

* `--verbose` (`-v|vv|vvv`)
  Increase the verbosity of messages

* `--version` (`-V`)
  Display this application version

* `--yes` (`-y`)
  Answer "yes" to confirmation questions; accept the default value for other questions; disable interaction

* `--no-interaction`
  Do not ask any interactive questions; accept default values. Equivalent to using the environment variable: UPSUN\_CLI\_NO\_INTERACTION=1

### Examples

* Create the starter YAML file(s) for your project:

```
upsun project:init 
```

* Disable AI mode:

```
upsun project:init --ai=false
```

* Add context for AI configuration:

```
upsun project:init --ai --context='Use PostgreSQL for the database'
```

## `project:list`

Get a list of all active projects

Aliases: `projects`, `pro`

### Usage

```
upsun projects [--pipe] [--region REGION] [--title TITLE] [--my] [--refresh REFRESH] [--sort SORT] [--reverse] [--page PAGE] [-c|--count COUNT] [-o|--org ORG] [--org-type ORG-TYPE] [--format FORMAT] [--columns COLUMNS] [--no-header] [--date-fmt DATE-FMT]
```

#### Options

* `--pipe`
  Output a simple list of project IDs. Disables pagination.

* `--region` (expects a value)
  Filter by region (exact match)

* `--title` (expects a value)
  Filter by title (case-insensitive search)

* `--my`
  Display only the projects you own (through organizations you own)

* `--refresh` (expects a value)
  Whether to refresh the list

* `--sort` (expects a value)
  A property to sort by

* `--reverse`
  Sort in reverse (descending) order

* `--page` (expects a value)
  Page number. This enables pagination, despite configuration or --count. Ignored if --pipe is specified.

* `--count` (`-c`) (expects a value)
  The number of projects to display per page. Use 0 to disable pagination. Ignored if --page is specified.

* `--org` (`-o`) (expects a value)
  Filter by organization name or ID

* `--org-type` (expects a value)
  Filter by organization type

* `--format` (expects a value)
  The output format: table, csv, tsv, or plain

* `--columns` (expects a value)
  Columns to display. Available columns: id\*, title\*, region\*, organization\_name\*, organization\_type\*, created\_at, organization\_id, organization\_label, status (\* = default columns). The character "+" can be used as a placeholder for the default columns. The % or \* characters may be used as a wildcard. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--no-header`
  Do not output the table header

* `--date-fmt` (expects a value)
  The date format (as a PHP date format string)

## `project:set-remote`

Set the remote project for the current Git repository

Aliases: `set-remote`

### Usage

```
upsun set-remote [<project>]
```

#### Arguments

* `project`(optional)
  The project ID

### Examples

* Set the remote project for this repository to "abcdef123456":

```
upsun project:set-remote abcdef123456
```

* Unset the remote project for this repository:

```
upsun project:set-remote -
```

## `repo:cat`

Read a file in the project repository

### Usage

```
upsun repo:cat [-c|--commit COMMIT] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [--] <path>
```

#### Arguments

* `path`(required)
  The path to the file

#### Options

* `--commit` (`-c`) (expects a value)
  The commit SHA. This can also accept "HEAD", and caret (^) or tilde (\~) suffixes for parent commits.

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

### Examples

* Read the services configuration file:

```
upsun repo:cat .upsun/services.yaml
```

## `repo:ls`

List files in the project repository

### Usage

```
upsun repo:ls [-d|--directories] [-f|--files] [--git-style] [-c|--commit COMMIT] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [--] [<path>]
```

#### Arguments

* `path`(optional)
  The path to a subdirectory

#### Options

* `--directories` (`-d`)
  Show directories only

* `--files` (`-f`)
  Show files only

* `--git-style`
  Style output similar to "git ls-tree"

* `--commit` (`-c`) (expects a value)
  The commit SHA. This can also accept "HEAD", and caret (^) or tilde (\~) suffixes for parent commits.

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

## `repo:read`

Read a directory or file in the project repository

Aliases: `read`

### Usage

```
upsun read [-c|--commit COMMIT] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [--] [<path>]
```

#### Arguments

* `path`(optional)
  The path to the directory or file

#### Options

* `--commit` (`-c`) (expects a value)
  The commit SHA. This can also accept "HEAD", and caret (^) or tilde (\~) suffixes for parent commits.

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

## `resources:build:get`

View the build resources of a project

Aliases: `build-resources:get`, `build-resources`

### Usage

```
upsun build-resources:get [-p|--project PROJECT] [--format FORMAT] [-c|--columns COLUMNS] [--no-header]
```

#### Options

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--format` (expects a value)
  The output format: table, csv, tsv, or plain

* `--columns` (`-c`) (expects a value)
  Columns to display. Available columns: cpu, memory. The % or \* characters may be used as a wildcard. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--no-header`
  Do not output the table header

## `resources:build:set`

Set the build resources of a project

Aliases: `build-resources:set`

### Usage

```
upsun build-resources:set [--cpu CPU] [--memory MEMORY] [-p|--project PROJECT]
```

#### Options

* `--cpu` (expects a value)
  Build CPU

* `--memory` (expects a value)
  Build memory (in MB)

* `--project` (`-p`) (expects a value)
  The project ID or URL

## `resources:get`

View the resources of apps, tasks and services on an environment

Aliases: `resources`, `res`

### Usage

```
upsun resources [-s|--service SERVICE] [--app APP] [--worker WORKER] [--task TASK] [--type TYPE] [--cpu-type [CPU-TYPE]] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [--format FORMAT] [-c|--columns COLUMNS] [--no-header]
```

#### Options

* `--service` (`-s`) (expects a value)
  Filter by service name. This can select any service, including apps, workers and tasks.

* `--app` (expects a value)
  Filter by app name

* `--worker` (expects a value)
  Filter by worker name

* `--task` (expects a value)
  Filter by task name

* `--type` (expects a value)
  Filter by service, app or worker type, e.g. "postgresql"

* `--cpu-type` (expects a value)
  Filter by CPU type, e.g "guaranteed"

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--format` (expects a value)
  The output format: table, csv, tsv, or plain

* `--columns` (`-c`) (expects a value)
  Columns to display. Available columns: service\*, profile\_size\*, cpu\_type\*, cpu\*, memory\*, disk\*, object\_storage\*, instance\_count\*, base\_memory, memory\_ratio, profile, type (\* = default columns). The character "+" can be used as a placeholder for the default columns. The % or \* characters may be used as a wildcard. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--no-header`
  Do not output the table header

## `resources:set`

Set the resources of apps, tasks and services on an environment

### Usage

```
upsun resources:set [-S|--size SIZE] [-C|--count COUNT] [-D|--disk DISK] [--object-storage OBJECT-STORAGE] [-f|--force] [--dry-run] [-s|--service SERVICE] [--app APP] [--worker WORKER] [--task TASK] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [-W|--no-wait] [--wait]
```

Configure the resources allocated to apps, workers, tasks and services on an environment.

The resources may be the profile size, the instance count, or the disk size (MB).
Tasks are run-to-completion containers: only their profile size can be set.

Profile sizes are predefined CPU & memory values that can be viewed by running: upsun resources:sizes

If the same service and resource is specified on the command line multiple times, only the final value will be used.

You can also configure autoscaling by running upsun autoscaling:set

#### Options

* `--size` (`-S`) (expects a value)
  Set the profile size (CPU and memory) of apps, workers, tasks, or services. Items are in the format name:value and may be comma-separated. The % or \* characters may be used as a wildcard for the name. List available sizes with the resources:sizes command. A value of 'default' will use the default size, and 'min' or 'minimum' will use the minimum.

* `--count` (`-C`) (expects a value)
  Set the instance count of apps or workers. Items are in the format name:value as above.

* `--disk` (`-D`) (expects a value)
  Set the disk size (in MB) of apps or services. Items are in the format name:value as above. A value of 'default' will use the default size, and 'min' or 'minimum' will use the minimum.

* `--object-storage` (expects a value)
  Set the object storage size (in MB) of apps. Items are in the format name:value as above. Only applicable to apps; a value of 0 disables the bucket.

* `--force` (`-f`)
  Try to run the update, even if it might exceed your limits

* `--dry-run`
  Show the changes that would be made, without changing anything

* `--service` (`-s`) (expects a value)
  Limit to a service name. This can select any service, including apps, workers and tasks.

* `--app` (expects a value)
  Limit to an app name

* `--worker` (expects a value)
  Limit to a worker name

* `--task` (expects a value)
  Limit to a task name

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--no-wait` (`-W`)
  Do not wait for the operation to complete

* `--wait`
  Wait for the operation to complete (default)

### Examples

* Set profile sizes for two apps and a service:

```
upsun resources:set --size frontend:0.1,backend:.25,database:1
```

* Give the "backend" app 3 instances:

```
upsun resources:set --count backend:3
```

* Give 512 MB disk to the "backend" app and 2 GB to the "database" service:

```
upsun resources:set --disk backend:512,database:2048
```

* Give 524288 MB (512 GB) of object storage to the "backend" app:

```
upsun resources:set --object-storage backend:524288
```

* Set the same profile size for the "backend" and "frontend" apps using a wildcard:

```
upsun resources:set --size '*end:0.1'
```

* Set the same instance count for all apps using a wildcard:

```
upsun resources:set --count '*:3'
```

## `resources:size:list`

List container profile sizes

Aliases: `resources:sizes`

### Usage

```
upsun resources:sizes [-s|--service SERVICE] [--profile PROFILE] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [--format FORMAT] [-c|--columns COLUMNS] [--no-header]
```

#### Options

* `--service` (`-s`) (expects a value)
  A service name

* `--profile` (expects a value)
  A profile name

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--format` (expects a value)
  The output format: table, csv, tsv, or plain

* `--columns` (`-c`) (expects a value)
  Columns to display. Available columns: size\*, cpu\*, memory\*, cpu\_type (\* = default columns). The character "+" can be used as a placeholder for the default columns. The % or \* characters may be used as a wildcard. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--no-header`
  Do not output the table header

## `route:get`

View detailed information about a route

### Usage

```
upsun route:get [--id ID] [-1|--primary] [-P|--property PROPERTY] [--refresh] [--date-fmt DATE-FMT] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [-A|--app APP] [-i|--identity-file IDENTITY-FILE] [--] [<route>]
```

#### Arguments

* `route`(optional)
  The route's original URL

#### Options

* `--id` (expects a value)
  A route ID to select

* `--primary` (`-1`)
  Select the primary route

* `--property` (`-P`) (expects a value)
  The property to display

* `--refresh`
  Bypass the cache of routes

* `--date-fmt` (expects a value)
  The date format (as a PHP date format string)

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--app` (`-A`) (expects a value)
  \[Deprecated option, no longer used]

* `--identity-file` (`-i`) (expects a value)
  \[Deprecated option, no longer used]

### Examples

* View the URL to the `https://{default}/` route:

```
upsun route:get 'https://{default}/' -P url
```

## `route:list`

List all routes for an environment

Aliases: `routes`

### Usage

```
upsun routes [--refresh] [--format FORMAT] [-c|--columns COLUMNS] [--no-header] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [--] [<environment>]
```

#### Arguments

* `environment`(optional)
  The environment ID

#### Options

* `--refresh`
  Bypass the cache of routes

* `--format` (expects a value)
  The output format: table, csv, tsv, or plain

* `--columns` (`-c`) (expects a value)
  Columns to display. Available columns: route\*, type\*, to\*, url (\* = default columns). The character "+" can be used as a placeholder for the default columns. The % or \* characters may be used as a wildcard. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--no-header`
  Do not output the table header

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

## `service:list`

List services in the project

Aliases: `services`

### Usage

```
upsun services [--refresh] [--pipe] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [--format FORMAT] [-c|--columns COLUMNS] [--no-header]
```

#### Options

* `--refresh`
  Whether to refresh the cache

* `--pipe`
  Output a list of service names only

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--format` (expects a value)
  The output format: table, csv, tsv, or plain

* `--columns` (`-c`) (expects a value)
  Columns to display. Available columns: disk, name, size, type. The % or \* characters may be used as a wildcard. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--no-header`
  Do not output the table header

## `service:mongo:dump`

Create a binary archive dump of data from MongoDB

Aliases: `mongodump`

### Usage

```
upsun mongodump [-c|--collection COLLECTION] [-z|--gzip] [-o|--stdout] [-r|--relationship RELATIONSHIP] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [-A|--app APP]
```

#### Options

* `--collection` (`-c`) (expects a value)
  The collection to dump

* `--gzip` (`-z`)
  Compress the dump using gzip

* `--stdout` (`-o`)
  Output to STDOUT instead of a file

* `--relationship` (`-r`) (expects a value)
  The service relationship to use

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--app` (`-A`) (expects a value)
  The remote application name

## `service:mongo:export`

Export data from MongoDB

Aliases: `mongoexport`

### Usage

```
upsun mongoexport [-c|--collection COLLECTION] [--jsonArray] [--type TYPE] [-f|--fields FIELDS] [-r|--relationship RELATIONSHIP] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [-A|--app APP]
```

#### Options

* `--collection` (`-c`) (expects a value)
  The collection to export

* `--jsonArray`
  Export data as a single JSON array

* `--type` (expects a value)
  The export type, e.g. "csv"

* `--fields` (`-f`) (expects a value)
  The fields to export

* `--relationship` (`-r`) (expects a value)
  The service relationship to use

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--app` (`-A`) (expects a value)
  The remote application name

### Examples

* Export a CSV from the "users" collection:

```
upsun service:mongo:export -c users --type csv -f name,email
```

## `service:mongo:restore`

Restore a binary archive dump of data into MongoDB

Aliases: `mongorestore`

### Usage

```
upsun mongorestore [-c|--collection COLLECTION] [-r|--relationship RELATIONSHIP] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [-A|--app APP]
```

#### Options

* `--collection` (`-c`) (expects a value)
  The collection to restore

* `--relationship` (`-r`) (expects a value)
  The service relationship to use

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--app` (`-A`) (expects a value)
  The remote application name

## `service:mongo:shell`

Use the MongoDB shell

Aliases: `mongo`

### Usage

```
upsun mongo [--eval EVAL] [-r|--relationship RELATIONSHIP] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [-A|--app APP]
```

#### Options

* `--eval` (expects a value)
  Pass a JavaScript fragment to the shell

* `--relationship` (`-r`) (expects a value)
  The service relationship to use

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--app` (`-A`) (expects a value)
  The remote application name

### Examples

* Display collection names:

```
upsun service:mongo:shell --eval 'printjson(db.getCollectionNames())'
```

## `service:redis-cli`

Access the Redis CLI

Aliases: `redis`

### Usage

```
upsun redis [-r|--relationship RELATIONSHIP] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [-A|--app APP] [--] [<args>...]
```

#### Arguments

* `args`(optional; multiple values allowed)
  Arguments to add to the redis-cli command

#### Options

* `--relationship` (`-r`) (expects a value)
  The service relationship to use

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--app` (`-A`) (expects a value)
  The remote application name

### Examples

* Open the redis-cli shell:

```
upsun service:redis-cli 
```

* Ping the Redis server:

```
upsun service:redis-cli ping
```

* Show Redis status information:

```
upsun service:redis-cli info
```

* Scan keys:

```
upsun service:redis-cli -- --scan
```

* Scan keys matching a pattern:

```
upsun service:redis-cli -- "--scan --pattern '*-11*'"
```

## `service:valkey-cli`

Access the Valkey CLI

Aliases: `valkey`

### Usage

```
upsun valkey [-r|--relationship RELATIONSHIP] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [-A|--app APP] [--] [<args>...]
```

#### Arguments

* `args`(optional; multiple values allowed)
  Arguments to add to the valkey-cli command

#### Options

* `--relationship` (`-r`) (expects a value)
  The service relationship to use

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--app` (`-A`) (expects a value)
  The remote application name

### Examples

* Open the valkey-cli shell:

```
upsun service:valkey-cli 
```

* Ping the valkey server:

```
upsun service:valkey-cli ping
```

* Show valkey status information:

```
upsun service:valkey-cli info
```

* Scan keys:

```
upsun service:valkey-cli -- --scan
```

* Scan keys matching a pattern:

```
upsun service:valkey-cli -- "--scan --pattern '*-11*'"
```

## `source-operation:list`

List source operations on an environment

Aliases: `source-ops`

### Usage

```
upsun source-ops [--full] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [--format FORMAT] [-c|--columns COLUMNS] [--no-header]
```

#### Options

* `--full`
  Do not limit the length of command to display. The default limit is 24 lines.

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--format` (expects a value)
  The output format: table, csv, tsv, or plain

* `--columns` (`-c`) (expects a value)
  Columns to display. Available columns: app, command, operation. The % or \* characters may be used as a wildcard. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--no-header`
  Do not output the table header

## `source-operation:run`

Run a source operation

### Usage

```
upsun source-operation:run [--variable VARIABLE] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [-W|--no-wait] [--wait] [--] [<operation>]
```

#### Arguments

* `operation`(optional)
  The operation name

#### Options

* `--variable` (expects a value)
  A variable to set during the operation, in the format type:name=value

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--no-wait` (`-W`)
  Do not wait for the operation to complete

* `--wait`
  Wait for the operation to complete (default)

### Examples

* Run the "update" operation, setting environment variable FOO=bar:

```
upsun source-operation:run update --variable env:FOO=bar
```

## `ssh-cert:load`

Generate an SSH certificate

### Usage

```
upsun ssh-cert:load [--refresh-only] [--new] [--new-key]
```

This command checks if a valid SSH certificate is present, and generates a
new one if necessary.

Certificates allow you to make SSH connections without having previously
uploaded a public key. They are more secure than keys and they allow for
other features.

Normally the certificate is loaded automatically during login, or when
making an SSH connection. So this command is seldom needed.

If you want to set up certificates without login and without an SSH-related
command, for example if you are writing a script that uses an API token via
an environment variable, then you would probably want to run this command
explicitly. For unattended scripts, remember to turn off interaction via
\--yes or the UPSUN\_CLI\_NO\_INTERACTION environment variable.

#### Options

* `--refresh-only`
  Only refresh the certificate, if necessary (do not write SSH config)

* `--new`
  Force the certificate to be refreshed

* `--new-key`
  Force a new key pair to be generated

## `ssh-key:add`

Add a new SSH key

### Usage

```
upsun ssh-key:add [--name NAME] [--] [<path>]
```

This command lets you add an SSH key to your account. It can generate a key using OpenSSH.

Notice:
SSH keys are no longer needed by default, as SSH certificates are supported.
Certificates offer more security than keys.

To load or check your SSH certificate, run: upsun ssh-cert:load

#### Arguments

* `path`(optional)
  The path to an existing SSH public key

#### Options

* `--name` (expects a value)
  A name to identify the key

## `ssh-key:delete`

Delete an SSH key

### Usage

```
upsun ssh-key:delete [<id>]
```

This command lets you delete SSH keys from your account.

Notice:
SSH keys are no longer needed by default, as SSH certificates are supported.
Certificates offer more security than keys.

To load or check your SSH certificate, run: upsun ssh-cert:load

#### Arguments

* `id`(optional)
  The ID of the SSH key to delete

### Examples

* Delete the key 123:

```
upsun ssh-key:delete 123
```

## `ssh-key:list`

Get a list of SSH keys in your account

Aliases: `ssh-keys`

### Usage

```
upsun ssh-keys [--format FORMAT] [-c|--columns COLUMNS] [--no-header]
```

This command lets you list SSH keys in your account.

Notice:
SSH keys are no longer needed by default, as SSH certificates are supported.
Certificates offer more security than keys.

To load or check your SSH certificate, run: upsun ssh-cert:load

#### Options

* `--format` (expects a value)
  The output format: table, csv, tsv, or plain

* `--columns` (`-c`) (expects a value)
  Columns to display. Available columns: id\*, title\*, path\*, fingerprint (\* = default columns). The character "+" can be used as a placeholder for the default columns. The % or \* characters may be used as a wildcard. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--no-header`
  Do not output the table header

## `subscription:info`

Read or modify subscription properties

### Usage

```
upsun subscription:info [-s|--id ID] [--date-fmt DATE-FMT] [--format FORMAT] [-c|--columns COLUMNS] [--no-header] [-p|--project PROJECT] [--] [<property> [<value>]]
```

#### Arguments

* `property`(optional)
  The name of the property

* `value`(optional)
  Set a new value for the property

#### Options

* `--id` (`-s`) (expects a value)
  The subscription ID

* `--date-fmt` (expects a value)
  The date format (as a PHP date format string)

* `--format` (expects a value)
  The output format: table, csv, tsv, or plain

* `--columns` (`-c`) (expects a value)
  Columns to display. The % or \* characters may be used as a wildcard. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--no-header`
  Do not output the table header

* `--project` (`-p`) (expects a value)
  The project ID or URL

### Examples

* View all subscription properties:

```
upsun subscription:info 
```

* View the subscription status:

```
upsun subscription:info status
```

* View the storage limit (in MiB):

```
upsun subscription:info storage
```

## `task:list`

Get a list of tasks on an environment

Aliases: `tasks`

### Usage

```
upsun tasks [--format FORMAT] [-c|--columns COLUMNS] [--no-header] [-p|--project PROJECT] [-e|--environment ENVIRONMENT]
```

#### Options

* `--format` (expects a value)
  The output format: table, csv, tsv, or plain

* `--columns` (`-c`) (expects a value)
  Columns to display. Available columns: command, name, timeout, type. The % or \* characters may be used as a wildcard. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--no-header`
  Do not output the table header

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

## `task:run`

Execute a task on an environment

### Usage

```
upsun task:run [--variable VARIABLE] [--wait] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [--] <task>
```

#### Arguments

* `task`(required)
  The name of the task to execute

#### Options

* `--variable` (expects a value)
  A variable to set when running the task, in the format type:name=value

* `--wait`
  Wait for the task to complete

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

### Examples

* Run the "migrate" task on the environment "main":

```
upsun task:run migrate --environment main
```

* Run the "migrate" task, setting environment variable FOO=bar:

```
upsun task:run migrate -e main --variable env:FOO=bar
```

## `team:create`

Create a new team

### Usage

```
upsun team:create [--label LABEL] [--no-check-unique] [-r|--role ROLE] [--output-id] [-o|--org ORG]
```

#### Options

* `--label` (expects a value)
  The team label

* `--no-check-unique`
  Do not error if another team exists with the same label in the organization

* `--role` (`-r`) (expects a value)
  Set the team's project and environment type roles Values may be split by commas (e.g. "a,b,c") and/or whitespace. The % or \* characters may be used as a wildcard.

* `--output-id`
  Output the new team's ID to stdout (instead of displaying the team info)

* `--org` (`-o`) (expects a value)
  The organization name (or ID)

## `team:delete`

Delete a team

### Usage

```
upsun team:delete [-o|--org ORG] [-t|--team TEAM]
```

#### Options

* `--org` (`-o`) (expects a value)
  The organization name (or ID)

* `--team` (`-t`) (expects a value)
  The team ID

## `team:get`

View a team

### Usage

```
upsun team:get [-o|--org ORG] [-p|--project PROJECT] [-t|--team TEAM] [-P|--property PROPERTY] [--date-fmt DATE-FMT] [--format FORMAT] [-c|--columns COLUMNS] [--no-header]
```

#### Options

* `--org` (`-o`) (expects a value)
  The organization name (or ID)

* `--project` (`-p`) (expects a value)
  The project ID or URL, which auto-selects the organization if --org is not used

* `--team` (`-t`) (expects a value)
  The team ID

* `--property` (`-P`) (expects a value)
  The name of a property to view

* `--date-fmt` (expects a value)
  The date format (as a PHP date format string)

* `--format` (expects a value)
  The output format: table, csv, tsv, or plain

* `--columns` (`-c`) (expects a value)
  Columns to display. The % or \* characters may be used as a wildcard. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--no-header`
  Do not output the table header

## `team:list`

List teams

Aliases: `teams`

### Usage

```
upsun teams [-c|--count COUNT] [--sort SORT] [--reverse] [-A|--all] [-o|--org ORG] [-p|--project PROJECT] [--date-fmt DATE-FMT] [--format FORMAT] [--columns COLUMNS] [--no-header]
```

#### Options

* `--count` (`-c`) (expects a value)
  The number of items to display per page. Use 0 to disable pagination.

* `--sort` (expects a value)
  A team property to sort by

* `--reverse`
  Sort in reverse order

* `--all` (`-A`)
  List all teams in the organization (regardless of a selected project)

* `--org` (`-o`) (expects a value)
  The organization name (or ID)

* `--project` (`-p`) (expects a value)
  The project ID or URL, which auto-selects the organization if --org is not used

* `--date-fmt` (expects a value)
  The date format (as a PHP date format string)

* `--format` (expects a value)
  The output format: table, csv, tsv, or plain

* `--columns` (expects a value)
  Columns to display. Available columns: id\*, label\*, member\_count\*, project\_count\*, project\_permissions\*, created\_at, granted\_at, updated\_at (\* = default columns). The character "+" can be used as a placeholder for the default columns. The % or \* characters may be used as a wildcard. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--no-header`
  Do not output the table header

### Examples

* List teams (in the current project, if any):

```
upsun team:list 
```

* List all teams in an organization:

```
upsun team:list --all
```

* List teams with access to a specified project, including when they were added:

```
upsun team:list --project myProjectId --columns +granted_at
```

## `team:project:add`

Add project(s) to a team

### Usage

```
upsun team:project:add [--all] [-o|--org ORG] [-t|--team TEAM] [--] [<projects>...]
```

#### Arguments

* `projects`(optional; multiple values allowed)
  The project ID(s). Values may be split by commas (e.g. "a,b,c") and/or whitespace.

#### Options

* `--all`
  Add all the projects that currently exist in the organization

* `--org` (`-o`) (expects a value)
  The organization name (or ID)

* `--team` (`-t`) (expects a value)
  The team ID

## `team:project:delete`

Remove a project from a team

### Usage

```
upsun team:project:delete [-o|--org ORG] [-t|--team TEAM] [--] [<project>]
```

#### Arguments

* `project`(optional)
  The project ID

#### Options

* `--org` (`-o`) (expects a value)
  The organization name (or ID)

* `--team` (`-t`) (expects a value)
  The team ID

## `team:project:list`

List projects in a team

Aliases: `team:projects`, `team:pro`

### Usage

```
upsun team:projects [-c|--count COUNT] [-o|--org ORG] [-t|--team TEAM] [--date-fmt DATE-FMT] [--format FORMAT] [--columns COLUMNS] [--no-header]
```

#### Options

* `--count` (`-c`) (expects a value)
  The number of items to display per page (max: 200). Use 0 to disable pagination

* `--org` (`-o`) (expects a value)
  The organization name (or ID)

* `--team` (`-t`) (expects a value)
  The team ID

* `--date-fmt` (expects a value)
  The date format (as a PHP date format string)

* `--format` (expects a value)
  The output format: table, csv, tsv, or plain

* `--columns` (expects a value)
  Columns to display. Available columns: id\*, title\*, granted\_at\*, updated\_at (\* = default columns). The character "+" can be used as a placeholder for the default columns. The % or \* characters may be used as a wildcard. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--no-header`
  Do not output the table header

## `team:update`

Update a team

### Usage

```
upsun team:update [--label LABEL] [--no-check-unique] [-r|--role ROLE] [-t|--team TEAM] [-o|--org ORG] [-W|--no-wait] [--wait]
```

#### Options

* `--label` (expects a value)
  Set a new team label

* `--no-check-unique`
  Do not error if another team exists with the same label in the organization

* `--role` (`-r`) (expects a value)
  Set the team's project and environment type roles Values may be split by commas (e.g. "a,b,c") and/or whitespace. The % or \* characters may be used as a wildcard.

* `--team` (`-t`) (expects a value)
  The team ID

* `--org` (`-o`) (expects a value)
  The organization name (or ID)

* `--no-wait` (`-W`)
  Do not wait for the operation to complete

* `--wait`
  Wait for the operation to complete (default)

## `team:user:add`

Add a user to a team

### Usage

```
upsun team:user:add [-o|--org ORG] [-t|--team TEAM] [--] [<user>]
```

#### Arguments

* `user`(optional)
  The user email address or ID

#### Options

* `--org` (`-o`) (expects a value)
  The organization name (or ID)

* `--team` (`-t`) (expects a value)
  The team ID

## `team:user:delete`

Remove a user from a team

### Usage

```
upsun team:user:delete [-o|--org ORG] [-t|--team TEAM] [--] [<user>]
```

#### Arguments

* `user`(optional)
  The user email address or ID

#### Options

* `--org` (`-o`) (expects a value)
  The organization name (or ID)

* `--team` (`-t`) (expects a value)
  The team ID

## `team:user:list`

List users in a team

Aliases: `team:users`

### Usage

```
upsun team:users [-c|--count COUNT] [-o|--org ORG] [-t|--team TEAM] [--date-fmt DATE-FMT] [--format FORMAT] [--columns COLUMNS] [--no-header]
```

#### Options

* `--count` (`-c`) (expects a value)
  The number of items to display per page. Use 0 to disable pagination

* `--org` (`-o`) (expects a value)
  The organization name (or ID)

* `--team` (`-t`) (expects a value)
  The team ID

* `--date-fmt` (expects a value)
  The date format (as a PHP date format string)

* `--format` (expects a value)
  The output format: table, csv, tsv, or plain

* `--columns` (expects a value)
  Columns to display. Available columns: id\*, email\*, created\_at\*, updated\_at (\* = default columns). The character "+" can be used as a placeholder for the default columns. The % or \* characters may be used as a wildcard. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--no-header`
  Do not output the table header

## `tunnel:close`

Close SSH tunnels

### Usage

```
upsun tunnel:close [-a|--all] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [-A|--app APP]
```

#### Options

* `--all` (`-a`)
  Close all tunnels

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--app` (`-A`) (expects a value)
  The remote application name

## `tunnel:info`

View relationship info for SSH tunnels

### Usage

```
upsun tunnel:info [-P|--property PROPERTY] [-c|--encode] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [-A|--app APP]
```

#### Options

* `--property` (`-P`) (expects a value)
  The relationship property to view

* `--encode` (`-c`)
  Output as base64-encoded JSON

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--app` (`-A`) (expects a value)
  The remote application name

## `tunnel:list`

List SSH tunnels

Aliases: `tunnels`

### Usage

```
upsun tunnels [-a|--all] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [-A|--app APP] [--format FORMAT] [-c|--columns COLUMNS] [--no-header]
```

#### Options

* `--all` (`-a`)
  View all tunnels

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--app` (`-A`) (expects a value)
  The remote application name

* `--format` (expects a value)
  The output format: table, csv, tsv, or plain

* `--columns` (`-c`) (expects a value)
  Columns to display. Available columns: port\*, project\*, environment\*, app\*, relationship\*, url (\* = default columns). The character "+" can be used as a placeholder for the default columns. The % or \* characters may be used as a wildcard. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--no-header`
  Do not output the table header

## `tunnel:open`

Open SSH tunnels to an app's relationships

### Usage

```
upsun tunnel:open [-g|--gateway-ports] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [-A|--app APP]
```

This command opens SSH tunnels to all of the relationships of an application.

Connections can then be made to the application's services as if they were
local, for example a local MySQL client can be used, or the Solr web
administration endpoint can be accessed through a local browser.

This command requires the posix and pcntl PHP extensions (as multiple
background CLI processes are created to keep the SSH tunnels open). The
tunnel:single command can be used on systems without these
extensions.

#### Options

* `--gateway-ports` (`-g`)
  Allow remote hosts to connect to local forwarded ports

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--app` (`-A`) (expects a value)
  The remote application name

## `tunnel:single`

Open a single SSH tunnel to an app relationship

### Usage

```
upsun tunnel:single [--port PORT] [-g|--gateway-ports] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [-A|--app APP] [-r|--relationship RELATIONSHIP]
```

#### Options

* `--port` (expects a value)
  The local port

* `--gateway-ports` (`-g`)
  Allow remote hosts to connect to local forwarded ports

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--app` (`-A`) (expects a value)
  The remote application name

* `--relationship` (`-r`) (expects a value)
  The service relationship to use

## `user:add`

Add a user to the project

### Usage

```
upsun user:add [-r|--role ROLE] [--force-invite] [-p|--project PROJECT] [-W|--no-wait] [--wait] [--] [<email>]
```

#### Arguments

* `email`(optional)
  The user's email address

#### Options

* `--role` (`-r`) (expects a value)
  The user's project role ('admin' or 'viewer') or environment type role (e.g. 'staging:contributor' or 'production:viewer'). To remove a user from an environment type, set the role as 'none'. The % or \* characters can be used as a wildcard for the environment type, e.g. '%:viewer' to give the user the 'viewer' role on all types. The role can be abbreviated, e.g. 'production:v'.

* `--force-invite`
  Send an invitation, even if one has already been sent

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--no-wait` (`-W`)
  Do not wait for the operation to complete

* `--wait`
  Wait for the operation to complete (default)

### Examples

* Add Alice as a project admin:

```
upsun user:add alice@example.com -r admin
```

* Add Bob as a viewer on the "production" environment type, and a contributor on "development" environments:

```
upsun user:add bob@example.com -r production:v -r development:c
```

* Add Charlie as viewer on "production" and "development":

```
upsun user:add charlie@example.com -r prod%:v -r dev%:v
```

## `user:delete`

Delete a user from the project

### Usage

```
upsun user:delete [-p|--project PROJECT] [-W|--no-wait] [--wait] [--] <email>
```

#### Arguments

* `email`(required)
  The user's email address

#### Options

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--no-wait` (`-W`)
  Do not wait for the operation to complete

* `--wait`
  Wait for the operation to complete (default)

### Examples

* Delete Alice from the project:

```
upsun user:delete alice@example.com
```

## `user:get`

View a user's role(s)

### Usage

```
upsun user:get [-l|--level LEVEL] [--pipe] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [-W|--no-wait] [--wait] [-r|--role ROLE] [--] [<email>]
```

#### Arguments

* `email`(optional)
  The user's email address

#### Options

* `--level` (`-l`) (expects a value)
  The role level ('project' or 'environment')

* `--pipe`
  Output the role to stdout (after making any changes)

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--no-wait` (`-W`)
  Do not wait for the operation to complete

* `--wait`
  Wait for the operation to complete (default)

* `--role` (`-r`) (expects a value)
  \[Deprecated: use user:update to change a user's role(s)]

### Examples

* View Alice's role on the project:

```
upsun user:get alice@example.com
```

* View Alice's role on the current environment:

```
upsun user:get alice@example.com --level environment --pipe
```

## `user:list`

List project users

Aliases: `users`

### Usage

```
upsun users [--format FORMAT] [-c|--columns COLUMNS] [--no-header] [-p|--project PROJECT]
```

#### Options

* `--format` (expects a value)
  The output format: table, csv, tsv, or plain

* `--columns` (`-c`) (expects a value)
  Columns to display. Available columns: email\*, name\*, role\*, id\*, granted\_at, permissions, updated\_at (\* = default columns). The character "+" can be used as a placeholder for the default columns. The % or \* characters may be used as a wildcard. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--no-header`
  Do not output the table header

* `--project` (`-p`) (expects a value)
  The project ID or URL

## `user:update`

Update user role(s) on a project

### Usage

```
upsun user:update [-r|--role ROLE] [-p|--project PROJECT] [-W|--no-wait] [--wait] [--] [<email>]
```

#### Arguments

* `email`(optional)
  The user's email address

#### Options

* `--role` (`-r`) (expects a value)
  The user's project role ('admin' or 'viewer') or environment type role (e.g. 'staging:contributor' or 'production:viewer'). To remove a user from an environment type, set the role as 'none'. The % or \* characters can be used as a wildcard for the environment type, e.g. '%:viewer' to give the user the 'viewer' role on all types. The role can be abbreviated, e.g. 'production:v'.

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--no-wait` (`-W`)
  Do not wait for the operation to complete

* `--wait`
  Wait for the operation to complete (default)

### Examples

* Make Bob an admin on the "development" and "staging" environment types:

```
upsun user:update bob@example.com -r development:a,staging:a
```

* Make Charlie a contributor on all environment types:

```
upsun user:update charlie@example.com -r %:c
```

## `variable:create`

Create a variable

### Usage

```
upsun variable:create [-u|--update] [-l|--level LEVEL] [--app-scope APP-SCOPE] [--name NAME] [--value VALUE] [--json JSON] [--sensitive SENSITIVE] [--prefix PREFIX] [--enabled ENABLED] [--inheritable INHERITABLE] [--visible-build VISIBLE-BUILD] [--visible-runtime VISIBLE-RUNTIME] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [-W|--no-wait] [--wait] [--] [<name>]
```

#### Arguments

* `name`(optional)
  The variable name

#### Options

* `--update` (`-u`)
  Update the variable if it already exists

* `--level` (`-l`) (expects a value)
  The level at which to set the variable ('project' or 'environment')

* `--app-scope` (expects a value)
  A list of application names to which this variable will apply.

* `--name` (expects a value)
  The variable name

* `--value` (expects a value)
  The variable's value

* `--json` (expects a value)
  Whether the variable value is JSON-formatted

* `--sensitive` (expects a value)
  Whether the variable value is sensitive

* `--prefix` (expects a value)
  The variable name's prefix which can determine its type, e.g. 'env'. Only applicable if the name does not already contain a prefix. (e.g. 'none' or 'env:')

* `--enabled` (expects a value)
  Whether the variable should be enabled on the environment

* `--inheritable` (expects a value)
  Whether the variable is inheritable by child environments

* `--visible-build` (expects a value)
  Whether the variable should be visible at build time

* `--visible-runtime` (expects a value)
  Whether the variable should be visible at runtime

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--no-wait` (`-W`)
  Do not wait for the operation to complete

* `--wait`
  Wait for the operation to complete (default)

## `variable:delete`

Delete a variable

### Usage

```
upsun variable:delete [-l|--level LEVEL] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [-W|--no-wait] [--wait] [--] <name>
```

#### Arguments

* `name`(required)
  The variable name

#### Options

* `--level` (`-l`) (expects a value)
  The variable level ('project', 'environment', 'p' or 'e')

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--no-wait` (`-W`)
  Do not wait for the operation to complete

* `--wait`
  Wait for the operation to complete (default)

### Examples

* Delete the variable "example":

```
upsun variable:delete example
```

## `variable:get`

View a variable

Aliases: `vget`

### Usage

```
upsun vget [-P|--property PROPERTY] [-l|--level LEVEL] [--format FORMAT] [-c|--columns COLUMNS] [--no-header] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [--pipe] [--] [<name>]
```

#### Arguments

* `name`(optional)
  The name of the variable

#### Options

* `--property` (`-P`) (expects a value)
  View a single variable property

* `--level` (`-l`) (expects a value)
  The variable level ('project', 'environment', 'p' or 'e')

* `--format` (expects a value)
  The output format: table, csv, tsv, or plain

* `--columns` (`-c`) (expects a value)
  Columns to display. The % or \* characters may be used as a wildcard. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--no-header`
  Do not output the table header

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--pipe`
  \[Deprecated option] Output the variable value only

### Examples

* View the variable "example":

```
upsun variable:get example
```

## `variable:list`

List variables

Aliases: `variables`, `var`

### Usage

```
upsun variables [-l|--level LEVEL] [--format FORMAT] [-c|--columns COLUMNS] [--no-header] [-p|--project PROJECT] [-e|--environment ENVIRONMENT]
```

#### Options

* `--level` (`-l`) (expects a value)
  The variable level ('project', 'environment', 'p' or 'e')

* `--format` (expects a value)
  The output format: table, csv, tsv, or plain

* `--columns` (`-c`) (expects a value)
  Columns to display. Available columns: is\_enabled, level, name, value. The % or \* characters may be used as a wildcard. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--no-header`
  Do not output the table header

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

## `variable:update`

Update a variable

### Usage

```
upsun variable:update [--allow-no-change] [-l|--level LEVEL] [--app-scope APP-SCOPE] [--value VALUE] [--json JSON] [--sensitive SENSITIVE] [--enabled ENABLED] [--inheritable INHERITABLE] [--visible-build VISIBLE-BUILD] [--visible-runtime VISIBLE-RUNTIME] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [-W|--no-wait] [--wait] [--] <name>
```

#### Arguments

* `name`(required)
  The variable name

#### Options

* `--allow-no-change`
  Return success (zero exit code) if no changes were provided

* `--level` (`-l`) (expects a value)
  The variable level ('project', 'environment', 'p' or 'e')

* `--app-scope` (expects a value)
  A list of application names to which this variable will apply.

* `--value` (expects a value)
  The variable's value

* `--json` (expects a value)
  Whether the variable value is JSON-formatted

* `--sensitive` (expects a value)
  Whether the variable value is sensitive

* `--enabled` (expects a value)
  Whether the variable should be enabled on the environment

* `--inheritable` (expects a value)
  Whether the variable is inheritable by child environments

* `--visible-build` (expects a value)
  Whether the variable should be visible at build time

* `--visible-runtime` (expects a value)
  Whether the variable should be visible at runtime

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--no-wait` (`-W`)
  Do not wait for the operation to complete

* `--wait`
  Wait for the operation to complete (default)

## `worker:list`

Get a list of all deployed workers

Aliases: `workers`

### Usage

```
upsun workers [--refresh] [--pipe] [-p|--project PROJECT] [-e|--environment ENVIRONMENT] [--format FORMAT] [-c|--columns COLUMNS] [--no-header]
```

#### Options

* `--refresh`
  Whether to refresh the cache

* `--pipe`
  Output a list of worker names only

* `--project` (`-p`) (expects a value)
  The project ID or URL

* `--environment` (`-e`) (expects a value)
  The environment ID. Use "." to select the project's default environment.

* `--format` (expects a value)
  The output format: table, csv, tsv, or plain

* `--columns` (`-c`) (expects a value)
  Columns to display. Available columns: commands, name, type. The % or \* characters may be used as a wildcard. Values may be split by commas (e.g. "a,b,c") and/or whitespace.

* `--no-header`
  Do not output the table header


# Use the Upsun Cloud CLI
Source: https://developer.upsun.com/cli/use

Run actions on your Upsun Cloud projects, select environments, execute remote commands, automate repetitive tasks, and enable tab autocompletion for the CLI.

The Upsun Cloud CLI lets you manage projects, run remote commands, and automate tasks directly from your terminal.

List all available commands:

```bash theme={null}
upsun list
```

To get help on a specific command, use `help`:

```bash theme={null}
upsun help get
```

You get output similar to the following:

```bash theme={null}
Command: project:get
Aliases: get
Description: Clone a project locally

Usage:
 upsun get [-e|--environment ENVIRONMENT] [--depth DEPTH] [--build] [-p|--project PROJECT] [--host HOST] [-i|--identity-file IDENTITY-FILE] [--] [<project>] [<directory>]

Arguments:
  project                            The project ID
  directory                          The directory to clone to. Defaults to the project title
```

## Select the right project and environment

If you run a command that requires a specific project and environment from an empty or unassociated directory, the CLI prompts you to select them.

If your working directory is inside a local checkout of your project, the CLI detects your project and environment automatically.

Specify the project and environment in either of two ways:

* As arguments for the command:

  ```bash theme={null}
  upsun environment:info --project=my-project --environment=staging
  ```

* With environment variables:

  ```bash theme={null}
  export PLATFORM_PROJECT=my-project;
  export PLATFORM_BRANCH=staging;
  upsun environment:info
  ```

In [multi-app](/docs/configure-apps/multi-app) projects, this also applies to selecting the app (use the `PLATFORM_APPLICATION_NAME` environment variable).

### RootNotFoundException

If you clone a project with Git directly instead of `upsun get`, the CLI might not be able to identify the project. Running a CLI command from inside that directory can produce this error:

```text theme={null}
[RootNotFoundException] Project root not found. This can only be run from inside a project directory.
```

This error means the CLI cannot determine the project. To fix it, run:

```bash theme={null}
upsun project:set-remote --project PROJECT_ID
```

Replace `PROJECT_ID` with the ID of your project.
Find your project ID in the Console, or run `upsun projects` to list all accessible projects.

## Choose between the CLI and Git commands

CLI commands in the `environment` namespace overlap with Git commands but offer more options. For example, `upsun push` supports `--activate` (to activate an environment before pushing) and `--no-wait` (to continue working without waiting for the push to complete).

CLI commands don't require a configured Git remote — a project ID is sufficient.

For example, `upsun merge` only merges code between remote environments. Your local codebase is not affected, and you don't need the code checked out locally.

## Run commands on your container

To run Upsun Cloud CLI commands against your container, you can use any command added in [dependencies](/docs/configure-apps/app-reference/single-runtime-image#dependencies) or a [hook](/docs/configure-apps/image-properties/hooks):

```bash theme={null}
upsun ssh -- COMMAND ARGUMENTS
```

For example, to run a specific Python script named `my-script.py` on your current environment,
run the following command:

```bash theme={null}
upsun ssh -- python my-script.py
```

Or to use [Drush](https://www.drush.org/latest/install/) to rebuild the cache on the `feature` environment,
run this command:

```bash theme={null}
upsun ssh -e feature -- drush -y cache-rebuild
```

## Customize the CLI

Customize CLI behavior using a configuration file (`~/.upsun-cli/config.yaml`) or environment variables. For details, see the [customization instructions on GitHub](https://github.com/upsun/cli/blob/main/legacy/README.md#customization).

### Automate repetitive tasks

Use the CLI in scripts to automate repetitive tasks like syncing files locally. To bypass confirmation prompts, set `UPSUN_CLI_NO_INTERACTION=1`.

For example, to sync all mount points for your app `myapp`:

```bash theme={null}
export PLATFORM_PROJECT=my-project;
export PLATFORM_BRANCH=main;
export UPSUN_CLI_NO_INTERACTION=1;
upsun mount:download --all --app myapp --target local-backup
```

## Autocomplete commands

The CLI provides tab autocompletion for commands, options, and some values (your projects, valid regions).
To enable autocompletion, follow these steps:

<Tabs>
  <Tab title="Homebrew">
    Follow the [Homebrew documentation on shell completion](https://docs.brew.sh/Shell-Completion).
  </Tab>

  <Tab title="Manually">
    Add the following to your shell's startup (`.bashrc`, `.zshrc`, or the equivalent):

    ```bash theme={null}
    eval $(upsun completion)
    ```
  </Tab>
</Tabs>


# Upsun Cloud
Source: https://developer.upsun.com/cloud/index

Docs, guides, and references for deploying and managing applications on Upsun Cloud — the platform for build, test, deploy, and run.

<div>
  <div>
    # Build on <span>Upsun Cloud</span>

    <p>
      Docs, guides, and references for deploying and managing applications on Upsun Cloud.
    </p>

    <div>
      <a href="/docs/get-started">
        Get Started

        <svg>
          <path />
        </svg>
      </a>

      <a href="/docs/core-concepts/index">
        Browse Docs
      </a>
    </div>
  </div>

  <div>
    <div>
      <h2>Explore</h2>
      <p>Jump into the topics that matter to you.</p>

      <CardGroup>
        <Card title="Quick Start" href="/docs/get-started" icon="zap">
          Deploy your first app step by step
        </Card>

        <Card title="Framework Guides" href="/docs/get-started/stacks" icon="layers">
          Next.js, Django, Laravel, Symfony, and more
        </Card>

        <Card title="Services & Databases" href="/docs/add-services" icon="database">
          PostgreSQL, MySQL, Redis, and more
        </Card>

        <Card title="Environments" href="/docs/environments" icon="sliders-horizontal">
          Branch, preview, and manage environments
        </Card>

        <Card title="Observability" href="/docs/observability" icon="activity">
          Monitoring, metrics, and performance
        </Card>

        <Card title="AI & Automation" href="/docs/get-started/ai" icon="cpu">
          MCP servers, AI agents, and CLI tools
        </Card>
      </CardGroup>
    </div>

    <div>
      <div>
        <div />

        <div>
          <h2>What's New</h2>

          <div>
            <div />

            <span>NEW</span>
          </div>
        </div>

        <div>
          <a href="/tutorials/ai/coding-agent">
            <div>
              <span>Tutorial</span>
            </div>

            <h3>Deploying a coding agent with opencode</h3>
            <p>Deploy opencode as a self-hosted AI coding agent with headless Chrome for web automation and performance testing.</p>
          </a>

          <a href="/tutorials/ai/langchain-chatbot">
            <div>
              <span>Tutorial</span>
            </div>

            <h3>Building a LangChain chatbot</h3>
            <p>Build a documentation chatbot with Node.js, LangChain, and OpenAI, with prompt injection defense and streaming responses.</p>
          </a>

          <a href="/tutorials/ai/rag-pipeline">
            <div>
              <span>Tutorial</span>
            </div>

            <h3>Building a RAG pipeline with Qdrant</h3>
            <p>Replace context stuffing with vector search using Qdrant for 25x lower cost per query.</p>
          </a>
        </div>
      </div>
    </div>

    <div>
      <h2>Deploy Your Stack</h2>
      <p>Get started with your favorite framework.</p>

      <CardGroup>
        <Card title="Next.js" href="/docs/get-started/stacks/nextjs" icon="react">
          Full-stack React with SSR
        </Card>

        <Card title="Django" href="/docs/get-started/stacks/django" icon="python">
          Python web framework
        </Card>

        <Card title="Laravel" href="/docs/get-started/stacks/laravel" icon="laravel">
          PHP framework for artisans
        </Card>

        <Card title="Express" href="/docs/get-started/stacks/express" icon="node-js">
          Minimal Node.js framework
        </Card>

        <Card title="Symfony" href="/docs/get-started/stacks/symfony" icon="symfony">
          Enterprise PHP framework
        </Card>

        <Card title="Flask" href="/docs/get-started/stacks/flask" icon="beaker">
          Lightweight Python framework
        </Card>

        <Card title="WordPress" href="/tutorials/wordpress" icon="wordpress">
          Popular CMS platform
        </Card>

        <Card title="All Frameworks →" href="/docs/get-started/stacks" icon="arrow-right">
          Go, Ruby, Rust, Elixir, Java
        </Card>
      </CardGroup>
    </div>

    <div>
      <div>
        <div>
          ## Configure. Commit. Deploy.

          <p>
            Define your infrastructure in YAML, then deploy with a single push.
          </p>

          <div>
            <div>
              <div>.upsun/config.yaml</div>

              <div>
                <div>applications:</div>
                <div>myapp:</div>
                <div>type: <span>nodejs:22</span></div>
                <div>hooks:</div>
                <div>build: <span>npm install</span></div>
                <div>web:</div>
                <div>commands:</div>
                <div>start: <span>npm start</span></div>

                <div />

                <div>services:</div>
                <div>database:</div>
                <div>type: <span>postgresql:16</span></div>
              </div>
            </div>

            <div>
              <div>Deploy with Git</div>

              <div>
                <div># Add your config</div>

                <div>
                  <span>\$</span>
                  <span>git add .upsun/config.yaml</span>
                </div>

                <div># Commit and push</div>

                <div>
                  <span>\$</span>
                  <span>git commit -m Add Upsun Cloud config</span>
                </div>

                <div>
                  <span>\$</span>
                  <span>git push upsun main</span>
                </div>

                <div>Building application 'myapp'...</div>
                <div>Provisioning services...</div>

                <div>
                  <span>✓</span>
                  <span>Deployment complete</span>
                </div>

                <div>[https://main-abc123.us-5.platformsh.site/](https://main-abc123.us-5.platformsh.site/)</div>
              </div>
            </div>
          </div>

          <div>
            <div>
              <div>1</div>
              <div>Configure</div>
              <div>Define apps & services in YAML</div>
            </div>

            <div>
              <div>2</div>
              <div>Commit</div>
              <div>Add to version control</div>
            </div>

            <div>
              <div>3</div>
              <div>Deploy</div>
              <div>Push and go live</div>
            </div>
          </div>
        </div>
      </div>
    </div>

    <div>
      <h2>Tutorials: AI Use Cases</h2>
      <p>LLM based applications and workflows</p>

      <CardGroup>
        <Card title="LangChain Chatbot" href="/tutorials/ai/langchain-chatbot" icon="message-circle">
          Build a conversational chatbot with Node.js and LangChain, deployed on Upsun Cloud
        </Card>

        <Card title="RAG Pipeline" href="/tutorials/ai/rag-pipeline" icon="database">
          Create a retrieval-augmented generation pipeline with Python and Qdrant for vector search
        </Card>

        <Card title="Coding Agent" href="/tutorials/ai/coding-agent" icon="code">
          Deploy a self-hosted coding agent using opencode on Upsun Cloud with proper workspace mounts
        </Card>

        <Card title="News Digest" href="/tutorials/ai/news-digest" icon="newspaper">
          Summarize daily news from free APIs using AI, output to a static page
        </Card>

        <Card title="Form Processing" href="/tutorials/ai/form-processing" icon="clipboard-list">
          Classify and extract fields from unstructured text like support tickets using AI
        </Card>

        <Card title="eCommerce Insights" href="/tutorials/ai/ecommerce-insights" icon="banknote">
          AI-powered business intelligence assistant that queries an ecommerce database using natural language
        </Card>
      </CardGroup>
    </div>

    <div>
      <h2>Platform Features</h2>
      <p>Everything you need to build and scale.</p>

      <CardGroup>
        <Card title="Clone environments instantly" icon="copy" href="/docs/environments">
          Work with full production-like environments, including data.
        </Card>

        <Card title="Deploy with Git" icon="git-branch" href="/docs/get-started/here/setup">
          Infrastructure, services, and code defined together.
        </Card>

        <Card title="Autoscale automatically" icon="trending-up" href="/docs/manage-resources/autoscaling">
          Handle traffic spikes without manual intervention.
        </Card>

        <Card title="Add services easily" icon="database" href="/docs/add-services">
          Databases, caches, queues, and more in a few lines of config.
        </Card>

        <Card title="Deploy with zero downtime" icon="rocket" href="/docs/core-concepts/build-deploy">
          Atomic deployments and instant rollbacks.
        </Card>

        <Card title="Debug with built-in observability" icon="activity" href="/docs/observability">
          Logs, metrics, traces, and profiling included.
        </Card>
      </CardGroup>
    </div>

    <div>
      <h2>Community & Resources</h2>
      <p>Connect, learn, and get inspired.</p>

      <CardGroup>
        <Card title="Example Projects" href="https://github.com/orgs/upsun/repositories?q=topic%3Aupsun-example" icon="github">
          Browse example projects on GitHub with ready-to-deploy configurations
        </Card>

        <Card title="Community Forum" href="https://community.upsun.com" icon="messages-square">
          Get help, share projects, and connect with developers
        </Card>

        <Card title="Agency Partners" href="https://upsun.com/agency-hosting-partner/" icon="users">
          Build long-term partnerships and grow your agency
        </Card>
      </CardGroup>
    </div>

    <div>
      <h2>Ready to Deploy?</h2>

      <p>
        Get your application live in production.
      </p>

      <div>
        <a href="/docs/get-started">
          Start Building →
        </a>

        <a href="https://console.upsun.com/projects/create-project">
          Deploy Demo Project
        </a>
      </div>

      <div>
        <span>✓ Git push to deploy</span>
        <span>✓ Zero-downtime deploys</span>
        <span>✓ Production-ready</span>
      </div>
    </div>
  </div>
</div>


# Use the Upsun Dispatch console
Source: https://developer.upsun.com/dispatch/docs/dashboard/index

Manage organizations, billing, repositories, workflow settings, runs, deliveries, notifications, and usage from the Upsun Dispatch web console.

The Upsun Dispatch console is the browser interface for day-to-day work in Upsun Dispatch. Use it to manage your organization, billing setup, connected repositories, workflow behavior, runs, deliveries, notifications, and usage.

Some console sections are available only when your role has access to those views.

## Open an organization

After signing in, open **Organizations** and choose the organization you want to manage. Organization pages are scoped to the selected organization, so repositories, workflow settings, runs, and usage shown in the console belong to that organization.

If you create a new organization, you become its owner. Owners and admins can update organization settings and manage access.

To manage organization details, open **Settings > General**. Owners can also use **Delete organization** from **Settings > General** and follow the confirmation flow when an organization should be removed.

## Manage members and invitations

Open **Settings > Members and roles** to manage people and access.

Use **Members and roles** to review current organization members, change roles, or remove members. Upsun Dispatch supports the **owner**, **admin**, and **member** roles.

Use invitations to add new organization members by email address and role. You can invite a single recipient or multiple recipients in bulk, then resend or revoke pending invitations when those actions are available. Recipients accept an invitation by opening the link in the invitation email.

## Manage billing

Open **Billing** to complete billing setup, review invoices and transactions, and manage billing access for the organization.

### Complete or upgrade billing setup

Use the Billing Setup Wizard to set up billing, upgrade billing, or link an organization to an existing billing profile. Depending on the mode, the wizard can guide you through these actions:

| Action | What you do |
| - | - |
| Select a billing account | Choose the billing account to use for Upsun Dispatch billing. |
| Select or create a billing profile | Choose the billing profile, or enter billing profile details. |
| Purchase credits | Add credits for Upsun Dispatch usage. |
| Attach an organization | Connect the organization to the selected billing profile. |
| Add a payment method | Enter the payment method required for credit purchases. |

<Warning>
  The payment method form is handled through Stripe. Use demo or test billing details only in non-production organizations.
</Warning>

### Manage billing users

Billing users are managed separately from organization members. Use the billing user forms to invite one or more email addresses, then assign each billing user one of these permissions:

| Permission | Access |
| - | - |
| `manage` | Can manage billing users and billing details. |
| `view` | Can view billing information. |

Use the edit billing user form to change a billing user's permission when their billing access needs to change.

### Review invoices and transactions

Use the billing area to review invoices and transaction history. Invoice details can include formatted invoice dates and billing periods. Transactions are grouped with descriptions so you can understand credit purchases, usage, and other billing events shown in the console.

## Browse repositories

Open **Repositories** to view repositories available through your organization's connected VCS integrations.

The repository list can be searched and filtered by integration. It can also show recent run activity when the console requests activity for a recent time window.

To connect VCS integrations, open **Settings > Integrations** or see:

* [Set up GitHub](/dispatch/docs/integrations/github)
* [Set up GitLab](/dispatch/docs/integrations/gitlab)

## Monitor operations

If you have access to operational views, use them to monitor activity across runs, deliveries, installations, queue health, connected Jira sites, organization usage, and organization limits.

### Operations dashboard

Open **Operations Dashboard** to view metrics and charts for runs and deliveries. Use it when you need an at-a-glance view of operational volume and outcomes before opening a specific run or delivery.

Run charts support selectable windows of 10, 30, or 90 days.

### Deliveries

Open **Deliveries** to browse delivery events, filter the list, group or aggregate deliveries, and review daily delivery charts. Select a delivery to open its detail panel.

Delivery details help you understand the delivery outcome and gates before the delivery created or updated run activity.

### Queue

Open **Queue** to view queue health, stuck runs, and lane backlog information. Use it to understand whether queued work is accumulating before opening individual runs for more detail.

### Installations

Open **Installations** to view and filter connected installations. Select an installation to open details such as its bot identity, connected repositories, status, and usage.

If your role allows editing operational limits, select an installation and use the Installation detail panel to edit its run cap.

For setup tasks, use **Settings > Integrations** or the integration-specific pages instead:

* [Set up GitHub](/dispatch/docs/integrations/github)
* [Set up GitLab](/dispatch/docs/integrations/gitlab)

### Organizations and caps

Open **Organizations** in the operational views to inspect organizations and per-organization usage. Select an organization to open usage charts and concurrency information.

If your role allows editing operational limits, use the organization caps editor to adjust daily or concurrent run caps.

### Jira connections

Use the Jira connections list to view connected Jira sites for the organization. Select a Jira connection to view token and webhook expiration details and related metadata.

For setup and disconnection steps, see [Set up Jira](/dispatch/docs/integrations/jira).

### GitLab service accounts and GitLab API usage

Open **GitLab Service Accounts** to list service accounts and inspect their access. Select a service account to view personal access token expiration details and related information.

Open **GitLab API Usage** to review daily charts and per-service-account usage. Usage volume categories are **ok**, **error**, and **rateLimited**. The view can also support sorting and filtering usage.

### Feature flags

Open **Feature Flags** to list flags and manage their state in the Feature Flag editor. Feature flag states are **unset**, **on**, and **off**.

### Egress policies

Open **Egress** to review egress policies and their allowed hosts. Use this view to confirm which hosts are allowed by policy.

## View workflow runs

Open **Runs** to monitor workflow activity for the organization. Runs are shown newest first.

The runs list can be searched and filtered by:

* Status
* Event type
* Workflow
* Source, including GitHub and GitLab
* Staff or non-staff activity, when that filter is available to your role
* Time range, including 24 hours, 7 days, and 30 days

Run statuses include:

| Status | Meaning |
| - | - |
| `queued` | Upsun Dispatch accepted the run and is waiting to start work. |
| `running` | Upsun Dispatch is actively processing the run. |
| `completed` | The run finished successfully. |
| `failed` | The run ended because a step failed or Upsun Dispatch could not complete the requested work. |
| `skipped` | Upsun Dispatch ended the run without further work because there was nothing applicable to do. |
| `canceled` | The run stopped before completion, such as because the associated pull or merge request was closed, because a [supported Code review cancel comment](/dispatch/docs/workflows/code-review) stopped the active review, or, for an Issue to code run before a pull or merge request exists, because the source issue or ticket was closed. |

A run can come from an automatic integration event, a manual trigger, or a manual comment command on GitHub or GitLab, depending on your workflow settings and integration.

Manual triggers and comment commands are subject to your organization's access and integration permissions.

For how workflows start, see [Workflows in Upsun Dispatch](/dispatch/docs/workflows#how-workflows-start). For supported commands on each integration and review behavior, see [Code review](/dispatch/docs/workflows/code-review).

## Open run details

Select a run to open its detail page. Run detail includes the run summary, status, duration, step statuses, timeline events, usage information, and capped log excerpts.

When a Jira-triggered Issue to code run includes a [plan approval gate](/dispatch/docs/workflows/issue-to-code#approve-or-revise-a-jira-plan), run detail also shows who approved the plan and the plan revisions that occurred within the run.

From run detail, you can:

* Check the current run status and duration.
* Review step-level progress and attempts.
* Inspect timeline events and the activity feed assembled from job logs.
* View prompts, tool calls, findings, artifacts, opened pull or merge requests, and push outcomes when the run produced them.
* View usage associated with the run.
* Open the related source entity display, when one is available.
* Re-run eligible finished runs.

The activity feed can include streamed job-log activity, step durations, prompts, tool calls, findings, and artifacts.

### Follow logs

Run detail includes capped log excerpts. For complete or live logs, open the logs for a specific job or step attempt.

Live log following streams entries until the job reaches a terminal state. Run status updates and log updates are separate, so a run can show status changes while logs are followed from the job log view.

### Re-run a run

You can re-run a run after it reaches one of these terminal states:

* `completed`
* `failed`
* `canceled`

A re-run starts new work from the original trigger and leaves the original run unchanged. Re-runs are accepted asynchronously, so the new run may still be held or suppressed by current workflow routing or gating.

## View the related entity

When a run is associated with a source entity, such as a pull request or merge request, the console can show the current entity display. This can include the entity title, lifecycle state, review decision, head SHA, and related decisions.

If a run has no associated entity, the entity view is not available.

## Configure workflow settings

Open **Settings > Workflows** to adjust organization-level workflow behavior.

Use **Workflows** to change supported settings, including trigger mode, summary mode, GitLab fork-author admission, plan approval, model integration selection, quality, and repository overrides. Not every setting applies to every workflow.

For what these settings control, see [Workflow settings](/dispatch/docs/workflows#workflow-settings). For Code review summary behavior, see [Summary behavior](/dispatch/docs/workflows/code-review#summary-behavior). For stored model keys and defaults, open **Settings > AI model keys** or see [AI models](/dispatch/docs/models).

<Warning>
  Turning summary mode off stops future summary content. It does not delete summaries that were already published.
</Warning>

### Set repository overrides

Repository overrides let you pin workflow settings for a specific connected repository instead of using the organization default.

Use an override when one repository needs different trigger, summary, plan approval, or model integration behavior than the rest of the organization. If you no longer need the override, remove it to restore inheritance from the organization setting.

For details about what each workflow does, see [Built-in workflows](/dispatch/docs/workflows/builtin).

## View notifications

Use the **Notifications** bell in the navbar to open the notification center. The bell is available from your account page and organization pages, and it can show your unread count.

In the notification center, you can page through notifications, mark individual notifications as read, mark all notifications as read, and dismiss notifications.

You can dismiss notifications you no longer need. Some notification types may clear over time.

## Search and navigate quickly

Use console search to find operational resources. If the command palette is available, use it to navigate quickly to specific runs or deliveries.

## View usage

Open **Usage** to review token and compute usage across organization runs. Usage can be grouped by **model**, **workflow**, or **model integration**, and bucketed by **day** or **month**.

By default, Usage groups data by **model** and uses the **day** bucket.

Usage charts aggregate recorded usage for your organization over the selected range.

The usage view supports these time ranges:

* 7 days
* 30 days
* 90 days
* all time

Usage breakdowns can include token volume, compute usage, and currency or cost summaries.

## Install Upsun Dispatch as an app

If your browser offers an install option, you can install Upsun Dispatch as a standalone Progressive Web App. The installed app opens Upsun Dispatch in its own window and uses the same sign-in flow as the browser console.

## Copy links safely

Run IDs are opaque, so avoid building run links by hand. To avoid encoding issues, copy links generated by the Upsun Dispatch console or from your browser's address bar after opening the run detail page.


# Get Started with Upsun Dispatch
Source: https://developer.upsun.com/dispatch/docs/get-started/index

Set up your account, organization, code integrations, and AI model keys for Upsun Dispatch.

Set up Upsun Dispatch by creating or joining an organization, inviting the people who need access, connecting GitHub or GitLab, and storing an AI model key for workflow runs.

For the shortest path to your first review, follow the [Quickstart](/dispatch/docs/get-started/quickstart). This page explains the onboarding pieces and links to detailed setup guides.

## What you can do with Upsun Dispatch

Use Upsun Dispatch to:

* **Request implementation work from supported issue systems** and let Upsun Dispatch open or update a pull or merge request.
* **Review code changes** on GitHub pull requests and GitLab merge requests.
* **Monitor workflow runs** with status, step details, timelines, logs, related source entities, and usage.
* **Manage organization access** with members, roles, and invitations.
* **Configure workflow behavior** at the organization level and with repository-specific overrides.
* **Review token usage** by model or workflow over time.

## Core concepts

### Organizations

An organization contains the integrations, model keys, repositories, members, workflow settings, runs, and usage data that belong together.

When you create an organization, you become its owner. Owners and admins can manage settings, members, and invitations from the [Upsun Dispatch console](/dispatch/docs/dashboard).

### Code integrations

Upsun Dispatch connects to your repositories through code integrations:

* **GitHub** uses the Upsun Dispatch GitHub App.
* **GitLab** uses organization-scoped service accounts and connected projects.

For setup details, see [Integrations](/dispatch/docs/integrations), [Set up GitHub](/dispatch/docs/integrations/github), and [Set up GitLab](/dispatch/docs/integrations/gitlab).

### AI model keys

Upsun Dispatch workflows require at least one organization-scoped AI model key. You can store keys for Anthropic, OpenAI, or both, then choose the default key Upsun Dispatch uses for runs.

After a key is stored, Upsun Dispatch shows only key metadata such as whether the key is set, the last four characters, and set or tested timestamps. See [AI models](/dispatch/docs/models) for model key setup, rotation, removal, default key selection, and API base URL settings.

### Built-in workflows

Upsun Dispatch includes built-in workflows for common development tasks:

* **Issue to code** starts from supported issue systems: GitHub Issues, Jira issues, and Linear issues. The entire issue body or a single comment must be exactly `@upsun-dispatch implement`; an optional trailing `!`, `.`, or `?` is allowed. Upsun Dispatch then plans the work and opens or updates a pull or merge request when it can complete the request. See [Issue to code](/dispatch/docs/workflows/issue-to-code).
* **Code review** reviews GitHub pull requests and GitLab merge requests. It can start automatically from supported code events or manually from supported comment commands. See [Code review](/dispatch/docs/workflows/code-review).

For a higher-level workflow overview, see [Workflows in Upsun Dispatch](/dispatch/docs/workflows) and [Built-in workflows](/dispatch/docs/workflows/builtin).

### Runs, logs, and usage

Every workflow execution appears as a run in the Upsun Dispatch console. Run detail shows status, step attempts, timeline events, capped log excerpts, and usage information. You can also open full or live logs for individual jobs and rerun eligible terminal runs.

Usage reports aggregate token usage across run step attempts and can be grouped by model or workflow.

See [Use the Upsun Dispatch console](/dispatch/docs/dashboard) for console tasks.

## How Upsun Dispatch fits into your workflow

1. You connect GitHub or GitLab to an organization.
2. You store at least one organization AI model key and choose the default key.
3. Upsun Dispatch receives supported code events or supported manual requests.
4. A built-in workflow runs and records progress in the console.
5. Upsun Dispatch publishes results back to GitHub or GitLab when the workflow produces review output or opens a pull or merge request.

## Before you begin

You need:

* An Upsun account you can use to sign in to Upsun Dispatch.
* Permission to create or manage the Upsun Dispatch organization you want to use.
* Access to the code integration you want to connect:
  * GitHub App installation access for GitHub repositories.
  * GitLab project and service-account credential access for GitLab merge request review.
* An Anthropic or OpenAI API key for the organization.

## 1. Sign in

Sign in with Upsun Auth. Upsun Dispatch redirects you to complete authentication in your browser, then returns you to Upsun Dispatch with a browser session for your user account, primary email address, and available organizations.

If Upsun Dispatch asks you to complete welcome or terms prompts, complete them before continuing.

## 2. Create or choose an organization

Create an Upsun Dispatch organization for the company, department, or group that owns integrations, repositories, workflow settings, members, and model keys. The user who creates an organization becomes its owner.

If you were invited to an existing organization, sign in with the email address that received the invitation, then accept the pending invitation shown for your account.

Organizations are the main boundary for Upsun Dispatch access:

* You only see organizations where you are a member.
* Organization owners and admins can update organization details and manage access.
* Upsun Dispatch protects organizations from being left without an owner.

For ongoing organization management in the web console, see [Use the Upsun Dispatch console](/dispatch/docs/dashboard).

## 3. Invite members

Owners and admins can invite people to join an organization as admins or members. Invitations are sent to an email address, and the invited person must sign in with that same email address to accept.

Invitation roles support **admin** or **member** only. Ownership is established when a user creates the organization or by changing a member's role after they join. For ongoing access management, see [Manage members and invitations](/dispatch/docs/dashboard#manage-members-and-invitations).

Owners and admins can also resend or revoke pending invitations, change member roles, and remove members from the organization.

<Note>
  Re-inviting a pending email address replaces the previous invitation. Invitation links are one-time use.
</Note>

## 4. Connect GitHub or GitLab

Connect at least one code integration so Upsun Dispatch can receive repository events and publish workflow results back to your code host.

<CardGroup>
  <Card title="Set up GitHub" icon="github" href="/dispatch/docs/integrations/github">
    Install and link the Upsun Dispatch GitHub App to your organization.
  </Card>

  <Card title="Set up GitLab" icon="gitlab" href="/dispatch/docs/integrations/gitlab">
    Register a GitLab service account and connect projects for merge request review.
  </Card>
</CardGroup>

Integrations belong to the organization. For example, an organization can link one or more GitHub App installations. Disconnecting a GitHub installation from Upsun Dispatch does not uninstall the GitHub App from GitHub.

For a single place to manage connected GitHub and GitLab access, ignored automation authors, and repository visibility, see [Integrations](/dispatch/docs/integrations).

## 5. Store an AI model key

Store an Anthropic or OpenAI key for the organization so workflow runs can use it. An organization can store keys for multiple AI model integrations and choose one default key for runs.

After a key is stored, Upsun Dispatch never shows the full key value again. The console shows only metadata, such as whether a key is set, the last four characters, and when it was set or tested.

Continue with [AI models](/dispatch/docs/models), [Store your Anthropic key](/dispatch/docs/models/anthropic), or [Store your OpenAI key](/dispatch/docs/models/openai).

## 6. Run your first workflow

After you connect GitHub or GitLab and store a model key, run one of the built-in workflows.

* Use the [Quickstart](/dispatch/docs/get-started/quickstart) to trigger your first code review from a pull request or merge request.
* Read [Built-in workflows](/dispatch/docs/workflows/builtin) to understand the available workflow types.
* Use [Workflows in Upsun Dispatch](/dispatch/docs/workflows) to learn how organization and repository settings control workflow behavior.

## Next steps

<CardGroup>
  <Card title="Issue to code" href="/dispatch/docs/workflows/issue-to-code">
    Learn how Upsun Dispatch can turn supported issue requests into pull or merge requests.
  </Card>

  <Card title="Code review" href="/dispatch/docs/workflows/code-review">
    Learn how Upsun Dispatch reviews pull requests and merge requests.
  </Card>

  <Card title="Use the Upsun Dispatch console" href="/dispatch/docs/dashboard">
    Monitor runs, logs, usage, and organization settings.
  </Card>

  <Card title="Configure workflows" href="/dispatch/docs/workflows">
    Adjust triggers, summaries, model selection, and repository-specific workflow settings.
  </Card>
</CardGroup>


# Quickstart
Source: https://developer.upsun.com/dispatch/docs/get-started/quickstart

Connect a repository, store a model key, choose a default model integration, and run your first Upsun Dispatch code review.

Use this quickstart to get from a new Upsun Dispatch account to your first code review run. You will create an organization, store an Anthropic or OpenAI model key, connect GitHub or GitLab, open a test pull request or merge request, and watch Upsun Dispatch publish review results.

## Before you begin

You need:

* Access to the Upsun Dispatch console.
* An Anthropic or OpenAI API key.
* A GitHub repository where you can install or link the Upsun Dispatch GitHub App, or a GitLab project that you can connect with the required project and service-account credentials.

For detailed setup options, see [Set up GitHub](/dispatch/docs/integrations/github), [Set up GitLab](/dispatch/docs/integrations/gitlab), and [AI models](/dispatch/docs/models).

## 1. Sign in

1. Open the Upsun Dispatch console.
2. Select **Sign in**.
3. Complete the Upsun sign-in flow.

After sign-in, Upsun Dispatch creates a browser session and shows the organizations you can access.

## 2. Create an organization

If you do not already have an organization:

1. Go to the organizations page in the Upsun Dispatch console.
2. Create an organization and enter a label for it.
3. Open the new organization.

The user who creates an organization becomes its owner. You can manage organization members, invitations, repositories, runs, usage, and settings from the [Upsun Dispatch console](/dispatch/docs/dashboard).

## 3. Store a model key

Upsun Dispatch uses organization-scoped model keys for workflow runs.

1. In your organization, go to **Settings** > **AI model keys**.
2. Select your model integration: **Anthropic** or **OpenAI**.
3. Select **Add key**.
4. Paste the API key.
5. Select **Save**.
6. If your organization stores more than one model key, choose the default model integration for organization runs.

After a key is stored, Upsun Dispatch only shows key metadata, such as the last four characters and set or tested timestamps. The full key value is not shown again. To change keys later, remove or replace the stored key from the same settings area.

For details, see [AI models](/dispatch/docs/models), [Store your Anthropic key](/dispatch/docs/models/anthropic), or [Store your OpenAI key](/dispatch/docs/models/openai).

## 4. Connect a source integration

Choose one integration for your first run.

<Tabs>
  <Tab title="GitHub">
    1. In your organization, go to **Settings** > **GitHub** or **Integrations**.
    2. Start the GitHub App installation flow.
    3. Complete the GitHub authorization and installation steps.
    4. Return to Upsun Dispatch and link the installation to your organization.

    An organization can link one or more GitHub App installations. For the complete setup flow, including pending-installation recovery and disconnecting an installation, see [Set up GitHub](/dispatch/docs/integrations/github).
  </Tab>

  <Tab title="GitLab">
    1. In your organization, go to **Settings** > **Integrations**.
    2. Register the shared GitLab service-account credentials required by your organization.
    3. Scan projects and connect the GitLab project you want Upsun Dispatch to review.
    4. Choose whether code writing is enabled for that project, if your organization uses workflows that write code.

    GitLab setup includes service-account registration, project scanning, and per-project code-writing controls. For the full setup flow and cleanup options, see [Set up GitLab](/dispatch/docs/integrations/gitlab).
  </Tab>
</Tabs>

## 5. Open a test pull request or merge request

Create a small change in a connected repository and open a pull request or merge request.

If the Code review workflow is set to automatic triggering, Upsun Dispatch starts a review when it receives a supported event:

* For GitHub, open or push to a pull request in a connected repository.
* For GitLab, open or update a merge request in a connected project.

If your organization has set review triggering to manual, request a review with a comment command instead:

* On GitHub, comment `@upsun-dispatch review` on the pull request.
* On GitLab, comment `@<configured-bot-username> review` on the merge request.

For more about automatic reviews, manual commands, full reviews, review limits, summaries, and GitHub or GitLab review output, see [Code review](/dispatch/docs/workflows/code-review).

## 6. Watch the run

1. In Upsun Dispatch, open your organization.
2. Go to **Runs**.
3. Open the newest run for your test pull request or merge request.

The run detail page shows the run status, duration, step statuses, timeline events, prompts, findings, artifacts, opened pull requests, push outcomes, log activity, and usage information. Active runs can stream live job logs. Completed runs keep recorded job log activity for later review.

GitHub and GitLab also show progress and results:

* GitHub reviews use check runs and review comments.
* GitLab reviews use progress notes, commit statuses, and merge request notes.

## 7. Adjust workflow settings

After your first run, tune Code review behavior for the organization or for individual repositories.

In **Settings** > **Workflows**, you can configure supported workflow settings, such as trigger mode, ignored authors, summary mode, GitLab fork-author admission, plan approval, model integration selection, and repository-specific overrides.

For the canonical settings overview, see [Workflows in Upsun Dispatch](/dispatch/docs/workflows). For Code review behavior, including summary behavior, see [Code review](/dispatch/docs/workflows/code-review). For console tasks such as browsing repositories, filtering runs, rerunning eligible runs, and viewing usage, see [Use the Upsun Dispatch console](/dispatch/docs/dashboard).

## Next steps

<CardGroup>
  <Card title="Explore built-in workflows" href="/dispatch/docs/workflows/builtin">
    Learn what Upsun Dispatch can run after your first code review.
  </Card>

  <Card title="Configure ignored authors" href="/dispatch/docs/integrations">
    Prevent automatic Code review runs from selected automation accounts.
  </Card>

  <Card title="Invite organization members" href="/dispatch/docs/dashboard#manage-members-and-invitations">
    Add people to the organization and manage their roles.
  </Card>

  <Card title="Review usage" href="/dispatch/docs/dashboard#view-usage">
    Track token usage after more workflow runs.
  </Card>
</CardGroup>


# Get support
Source: https://developer.upsun.com/dispatch/docs/get-started/support

Find out how to get help if you're experiencing issues with Upsun Dispatch.


## Create a support ticket

Organizations that pay for Upsun Dispatch, including by buying Upsun Dispatch credits or through an agreement with Upsun, can open support tickets. Organizations that haven't set up paid Upsun Dispatch access can't open support tickets.
If your organization can open support tickets, go to [Upsun Support](https://support.upsun.com) to create a ticket.

Use support tickets for issues with workflow runs, code review results, model configuration, integrations, possible bugs, general questions, or feature requests.

To review billing status or buy credits, open your organization in the Upsun Dispatch console and go to **Billing**. For more about finding billing and usage details in the Upsun Dispatch console, see [Use the Upsun Dispatch console](/dispatch/docs/dashboard).

<Tip>
  After you submit a support ticket, include any additional information in the ticket conversation rather than opening duplicate tickets for the same issue.
</Tip>

## Community

To talk about workflows, integrations, or other questions about Upsun Dispatch,
join other customers and engineers in the [Community Forum](https://community.upsun.com/).

<CommunityButtons />

## Contact Sales

If you have questions about pricing or need help figuring out if Upsun Dispatch is the right solution for your organization,
get in touch with [Sales](https://upsun.com/contact-us/).


# Set up GitHub
Source: https://developer.upsun.com/dispatch/docs/integrations/github

Connect a GitHub App installation to your Upsun Dispatch organization so Upsun Dispatch can review pull requests.

Connect GitHub to let Upsun Dispatch receive pull request events, read the connected repositories, and publish code review results back to GitHub.

<Note>
  Code review requires an organization-level AI model key. Upsun Dispatch supports model keys for OpenAI and Anthropic. If you have not added one yet, store it before running your first review. See [AI models](/dispatch/docs/models).
</Note>

## Before you start

You need:

* Access to the Upsun Dispatch organization you want to connect.
* Permission in GitHub to install or configure the Upsun Dispatch GitHub App for the repositories you want Upsun Dispatch to review.
* An organization model key stored for OpenAI or Anthropic. See [AI models](/dispatch/docs/models).

## Connect a GitHub installation

<Steps>
  <Step title="Open GitHub integration settings">
    In the Upsun Dispatch console, open your organization settings, then go to integrations and choose GitHub.
  </Step>

  <Step title="Start the GitHub App install">
    Select the action to install or connect the GitHub App. Upsun Dispatch sends you to GitHub to choose the account and repositories for the installation.
  </Step>

  <Step title="Approve the installation in GitHub">
    Complete the GitHub authorization and installation flow. GitHub returns you to Upsun Dispatch when the setup callback is complete.
  </Step>

  <Step title="Link the installation to your organization">
    After GitHub redirects you back, Upsun Dispatch links the installation to the organization you started from. Once linked, Upsun Dispatch refreshes repository information so connected repositories can appear in the console.
  </Step>
</Steps>

An organization can link more than one GitHub App installation. Use multiple installations when the repositories you want to review live under different GitHub accounts or installation scopes.

## Recover a pending installation

If you install the GitHub App but do not finish linking it to an Upsun Dispatch organization, Upsun Dispatch can show it as a pending installation. Return to your organization's GitHub integration settings and link the pending installation from there.

For a smooth recovery:

* Sign in to Upsun Dispatch with the same user who completed the GitHub setup.
* Link the installation to the intended organization.
* If Upsun Dispatch reports that the installation is already linked elsewhere, disconnect it from that organization first or choose a different installation.

## Disconnect or relink GitHub

You can disconnect a GitHub installation from the organization's integration settings.

Disconnecting in Upsun Dispatch detaches the installation from the organization. It does not uninstall the GitHub App in GitHub, and Upsun Dispatch preserves history so the installation can be linked again later.

To relink, start the GitHub setup again or use the pending installation flow if the installation is available for recovery.

## How GitHub code review runs start

After GitHub is connected, the built-in [Code review workflow](/dispatch/docs/workflows/code-review) can run on pull requests in connected repositories.

Upsun Dispatch supports both automatic and manual review starts:

* **Automatic reviews** run when a pull request is opened or updated on a connected GitHub repository, as long as the repository's workflow trigger mode is automatic.
* **Manual reviews** run when you comment a whole-message command on a pull request, such as `@upsun-dispatch review`.
* **Full reviews** run when you comment `@upsun-dispatch full review` on a pull request.
* **Cancellations** run when you comment `@upsun-dispatch cancel` on a pull request.

<Note>
  GitHub commands must be whole-message commands addressed to the Upsun Dispatch bot. Comments that are not addressed commands are ignored.
</Note>

GitHub issue comments that are not pull request conversation comments do not start code review.

For details about how Upsun Dispatch handles review commands, full versus incremental review behavior, automatic review limits, and summaries, see [Code review](/dispatch/docs/workflows/code-review).

## Where results appear

While a GitHub review is running, Upsun Dispatch creates a GitHub check run so contributors can see that review is in progress.

When the review finishes, Upsun Dispatch publishes GitHub review artifacts, including review comments or review summaries when the workflow settings allow them. Upsun Dispatch also records the run, step output, logs, and usage in the console. To inspect or manage runs, see [Use the Upsun Dispatch console](/dispatch/docs/dashboard).

For details about repository-level workflow overrides, see [Use the Upsun Dispatch console](/dispatch/docs/dashboard).


# Set up GitLab
Source: https://developer.upsun.com/dispatch/docs/integrations/gitlab

Connect a GitLab project to Upsun Dispatch so Upsun Dispatch can review merge requests.

Connect GitLab to run the built-in [Code review](/dispatch/docs/workflows/code-review) workflow on merge requests. After setup, Upsun Dispatch can receive GitLab merge request events, clone the connected project with read-only access, and publish review progress and results back to GitLab.

<Note>
  Code review requires an organization-level AI model key. Upsun Dispatch supports model keys for OpenAI and Anthropic. If you have not added one yet, store it before running your first review. See [AI models](/dispatch/docs/models).
</Note>

## What you need

To connect a GitLab project, prepare:

* A GitLab HTTPS instance URL, such as `https://gitlab.com`. Use only the origin, with no path, query string, username, or password.
* A shared GitLab service account for your Upsun Dispatch organization.
* An `api`-scope personal access token (PAT) for the service account.
* A read-only PAT for the same service account.
* A one-time token that can administer webhooks for the project you want to connect.
* The GitLab project path, for example `group/project`.

Upsun Dispatch verifies the service account credentials, stores them securely, and never shows the token values again.

## Register a GitLab service account

A GitLab service account gives Upsun Dispatch an organization-scoped identity for GitLab access.

1. In Upsun Dispatch, open your organization settings and go to **Integrations**.
2. Choose **GitLab**.
3. Add the GitLab instance URL.
4. Enter the service account `api`-scope PAT.
5. Enter the service account read-only PAT.
6. Save the service account.

Upsun Dispatch validates both tokens before storing them. If you later remove the stored GitLab credential, Upsun Dispatch refuses the removal while connected projects still depend on it, including paused connections.

## Connect a GitLab project

After the service account is registered, connect each project you want Upsun Dispatch to review.

<Steps>
  <Step title="Open GitLab integration settings">
    In Upsun Dispatch, open your organization settings, go to **Integrations**, and choose **GitLab**.
  </Step>

  <Step title="Start the project connection">
    Choose to connect a project.
  </Step>

  <Step title="Enter the GitLab project details">
    Enter the same GitLab instance URL and the project path, such as `group/project`.
  </Step>

  <Step title="Provide the one-time token">
    Enter a one-time token with permission to manage webhooks for that project.
  </Step>

  <Step title="Choose service account access if prompted">
    If prompted, choose whether Upsun Dispatch should invite or grant the service account access to the project.
  </Step>

  <Step title="Connect the project">
    Complete the connection from the GitLab integration settings.
  </Step>
</Steps>

During connection, Upsun Dispatch:

* Scans the available GitLab projects so you can pick the project path to connect.
* Verifies that the service account can access the project.
* Registers a project webhook so GitLab can send merge request and merge request note events.
* Creates a per-project read-only deploy/clone token for workflow runs.
* Records the connection and refreshes repository data so the project appears in Upsun Dispatch.

The one-time token and any project scan results are discarded after the request. Upsun Dispatch uses the per-project deploy token for current GitLab run cloning.

## Control write access for a GitLab project

GitLab project connections use read-only cloning by default. Keep write access off for projects that only need Code review. Turn on write access only for projects where an Upsun Dispatch workflow needs to write changes back to GitLab.

To change write access for a connected project:

1. In Upsun Dispatch, open your organization settings and go to **Integrations**.
2. Choose **GitLab**.
3. Open the connected project you want to update.
4. Use the project's write access control to enable or disable write access.

Write access is managed per project. Changing it for one connected GitLab project does not change write access for other connected projects.

## Review GitLab merge requests

When the project is connected, Upsun Dispatch can run Code review on GitLab merge requests. If the workflow trigger mode is automatic, opening or updating a merge request can start a review. Upsun Dispatch posts progress as a GitLab merge request note and commit status while the review runs, then publishes review findings back to GitLab.

For review behavior details, including automatic reviews, manual requests, summaries, and review outputs, see [Code review](/dispatch/docs/workflows/code-review).

### Start or cancel a review manually

GitLab commands must be whole-message commands addressed to the bot username configured for your GitLab connection. Ordinary notes, bot notes, system notes, and self-triggered notes are ignored.

Use comments like these on a merge request:

```text theme={null}
@<configured-bot-username> review
@<configured-bot-username> full review
@<configured-bot-username> cancel
```

`review` requests a review. `full review` forces a complete re-review. `cancel` requests cancellation of the current review. For behavior details, see [Code review](/dispatch/docs/workflows/code-review).

## Review merge requests from fork authors

GitLab merge request review includes an organization or repository workflow setting that can allow fork authors. Use this setting when you want Upsun Dispatch to review merge requests from fork-based contributors.

Manage workflow settings and repository overrides in the Upsun Dispatch console. See [Workflows in Upsun Dispatch](/dispatch/docs/workflows) for available workflow settings.

## Recheck, pause, resume, or clean up a connection

Use the GitLab integration controls in Upsun Dispatch to manage an existing project connection:

* **Recheck** verifies the connection again. Recheck is not available while the connection is paused. If the service account token has expired or been revoked, recheck reports that the credential is not OK without changing the project's connection status.
* **Pause** stops the connection from being active without deleting its record.
* **Resume** makes a paused connection active again.
* **Disconnect** removes the Upsun Dispatch connection record.
* **Webhook cleanup** removes the GitLab webhook when you provide a one-time token with the required project permission.
* **Deploy token cleanup** removes the per-project deploy token when you provide a one-time token with the required project permission.

<Warning>
  Disconnecting a GitLab project from Upsun Dispatch does not automatically remove the GitLab webhook or deploy token. Use the cleanup actions when you want Upsun Dispatch to remove those GitLab resources.
</Warning>

## Troubleshooting

### The project does not appear in Upsun Dispatch

Confirm that the project connection completed successfully and that the project path matches the GitLab project. Upsun Dispatch refreshes repository data after a successful connection.

### Recheck says the credential is not OK

The stored service account token may have expired or been revoked in GitLab. Register a valid service account credential before trying to use dependent project connections.

### Manual comments do not start a review

Check that the comment is a whole-message command addressed to the configured GitLab bot username, such as `@<configured-bot-username> review`. Comments that include unrelated text are treated as ordinary comments and ignored.


# Integration overview
Source: https://developer.upsun.com/dispatch/docs/integrations/index

Connect version control system and ticketing integrations to Upsun Dispatch, and find the AI model settings required to run workflows.

Use **Settings > Integrations** to connect the external tools Upsun Dispatch uses with your organization.

Integrations are grouped by what they connect:

* **Version control system integrations** connect repositories and pull request or merge request activity.
* **Ticketing integrations** connect issue-tracking tools.
* **AI model integrations** are managed as organization model keys in [AI models](/dispatch/docs/models).

<Note>
  Workflows require an organization model key. See [AI models](/dispatch/docs/models).
</Note>

## Version control system integrations

Connect a version control system integration so Upsun Dispatch can receive repository events and publish workflow results back to your code host.

Version control system and ticketing integrations are independent. For example, a GitHub integration can be used with Jira or Linear as the ticketing integration for Issue to code.

| Integration | Use it to | Setup |
| - | - | - |
| GitHub | Receive pull request events and let [Code review](/dispatch/docs/workflows/code-review) and [Issue to code](/dispatch/docs/workflows/issue-to-code) publish results back to GitHub. | [Set up GitHub](/dispatch/docs/integrations/github) |
| GitLab | Receive merge request events and let [Code review](/dispatch/docs/workflows/code-review) publish progress and results back to GitLab. Issue to code does not currently publish back to GitLab. | [Set up GitLab](/dispatch/docs/integrations/gitlab) |

<Note>
  Bitbucket support is under consideration. It is not available in Upsun Dispatch yet.
</Note>

## Ticketing integrations

Connect a ticketing integration so Upsun Dispatch can work with the issue tracker your organization uses.

| Integration | Setup |
| - | - |
| Jira | [Set up Jira](/dispatch/docs/integrations/jira) |
| Linear | [Set up Linear](/dispatch/docs/integrations/linear) |

## AI model integrations

Upsun Dispatch workflows also need an AI model integration key for your organization. AI model keys are managed separately from the Integrations settings page.

See [AI models](/dispatch/docs/models) to add, replace, remove, or choose the default model key.

## Ignored authors

Use ignored authors to prevent automatic Code review runs from automation accounts that GitHub or GitLab do not classify as bots.

Configure ignored authors in **Settings > Integrations** for each source control integration. Add either:

* An exact username, such as `automation-user`
* A prefix wildcard, such as `renovate*`, to match usernames that start with that prefix

Ignored authors only suppress automatic reviews. Explicit manual review requests still work.


# Set up Jira
Source: https://developer.upsun.com/dispatch/docs/integrations/jira

Connect a Jira site to Upsun Dispatch as a ticketing integration for your organization.

Connect Jira to make an Atlassian Jira site available as a ticketing integration in your Upsun Dispatch organization.

<Note>
  This page covers the Jira connection flow in Upsun Dispatch: connecting an Atlassian site, confirming the selected site, viewing the connection, and disconnecting it. Connecting Jira does not by itself create Jira issues or link existing issues.
</Note>

## Before you start

You need:

* Access to the Upsun Dispatch organization where you want to add the Jira integration.
* Access to the Atlassian account and Jira site you want to connect.
* Permission in Atlassian to authorize or approve the Jira integration for that site.

If your organization requires an Atlassian administrator, app approval, or a service account, use the Atlassian admin, Manage apps, and service account documentation links shown in Upsun Dispatch during setup.

## Connect a Jira site

<Steps>
  <Step title="Open integration settings">
    In Upsun Dispatch, open your organization settings, then go to integrations and choose Jira.
  </Step>

  <Step title="Start the Jira connection">
    Use the Jira connect action. Upsun Dispatch sends you to Atlassian to choose the Jira site for the organization.
  </Step>

  <Step title="Authorize in Atlassian">
    Sign in to Atlassian if prompted, review the requested permissions, and authorize access to the intended Jira site.
  </Step>

  <Step title="Confirm the selected site">
    After Atlassian returns you to Upsun Dispatch, confirm that the selected Jira site is the one you want to connect.
  </Step>
</Steps>

After the connection succeeds, the Jira site appears in Upsun Dispatch as a connected ticketing integration. You can view Jira connections in the Upsun Dispatch console. See [Use the Upsun Dispatch console](/dispatch/docs/dashboard) for console navigation.

## Required permissions

Upsun Dispatch does not ask you to paste Jira tokens or manually enter Jira scopes during the documented connection flow. Instead, Upsun Dispatch sends you to Atlassian so you can select and authorize the Jira site.

Review the permissions shown by Atlassian before authorizing the connection. If you cannot approve the integration, ask an Atlassian administrator for access or app approval for the Jira site.

## Issue creation and linking

The Jira setup flow only connects the Atlassian site to Upsun Dispatch. It does not include a separate step that creates Jira issues or links existing Jira issues.

If an Upsun Dispatch workflow or screen offers Jira issue creation or linking, use the connected Jira site shown there. If no Jira issue action is available where you expect it, first confirm that the Jira connection is present in your organization's integration settings.

## Manage the connection

Use the Jira integration settings in Upsun Dispatch to disconnect a Jira connection from the organization.

Disconnecting removes the connection from Upsun Dispatch. If your Atlassian organization also requires app cleanup or permission review, use the Atlassian admin or Manage apps links shown in Upsun Dispatch.

## Troubleshooting

### I cannot authorize the Jira site

Confirm that you are signed in to the Atlassian account that has access to the Jira site. If Atlassian requires administrator approval, ask an Atlassian administrator to approve or configure the integration.

### The wrong Jira site was selected

Return to the Jira integration settings in Upsun Dispatch and repeat the connection flow for the intended site. Confirm the selected site after Atlassian redirects you back to Upsun Dispatch.

### The Jira connection does not appear in Upsun Dispatch

Confirm that the Atlassian authorization completed and that you confirmed the selected site in Upsun Dispatch. If setup stopped before confirmation, start the Jira connection again from your organization's integration settings.

### I need to remove the connection

Disconnect Jira from the organization's integration settings. If you also need to review Atlassian-side access, use the Atlassian Manage apps or admin links shown in Upsun Dispatch.

For the broader integrations list, see [Integrations](/dispatch/docs/integrations).


# Set up Linear
Source: https://developer.upsun.com/dispatch/docs/integrations/linear

Connect Linear to your Upsun Dispatch organization as a ticketing integration.

Connect Linear to make it available as a ticketing integration for your Upsun Dispatch organization. The Linear settings page is for authorizing and maintaining the connection.

## Before you start

You need:

* Access to the Upsun Dispatch organization you want to connect.
* Permission in Upsun Dispatch to manage organization integrations.
* Permission in Linear to authorize integrations for the Linear organization you want to connect.

<Note>
  Linear shows the exact permissions requested during authorization. Review that screen before approving the connection, and grant access only if it matches your organization's policy.
</Note>

## Connect Linear

<Steps>
  <Step title="Open the Linear integration settings">
    In the Upsun Dispatch console, open your organization settings, go to integrations, and choose Linear.
  </Step>

  <Step title="Start the connection">
    Select **Connect** on the Linear integration card. Upsun Dispatch sends you to Linear to authorize the connection.
  </Step>

  <Step title="Authorize Upsun Dispatch in Linear">
    Review the Linear authorization screen and approve the requested access for the intended Linear organization.
  </Step>

  <Step title="Return to Upsun Dispatch">
    After authorization, Linear returns you to Upsun Dispatch. Confirm that the Linear integration shows as connected for the organization.
  </Step>
</Steps>

## Required permissions

Upsun Dispatch relies on the permissions requested in the Linear authorization flow. Those permissions allow Upsun Dispatch to establish and maintain the Linear ticketing integration for the selected organization.

If you cannot approve the authorization request, ask a Linear administrator for access to authorize integrations, or have that person complete the connection from Upsun Dispatch.

## Issue creation and linking

Connecting Linear does not create or link issues by itself. It authorizes Upsun Dispatch to use Linear as a ticketing integration where Linear-backed behavior is available in the product.

Use the relevant Upsun Dispatch workflow or run view for the action you are taking. If a workflow or run references Linear, keep the Linear integration connected so Upsun Dispatch can use the authorized Linear organization.

## Manage the connection

Use the Linear integration settings in Upsun Dispatch to check whether Linear is connected for the organization. If you no longer want Upsun Dispatch to use Linear, disconnect the integration from the same settings area.

Disconnecting Linear removes the Upsun Dispatch connection for the organization. It does not delete Linear issues or change unrelated Linear organization settings.

For the broader integrations list, see [Integrations](/dispatch/docs/integrations).

## Troubleshooting

### Linear does not show as connected

Return to the Linear integration settings in Upsun Dispatch and start the connection again. Make sure the authorization finishes in Linear and redirects back to Upsun Dispatch.

### You cannot authorize the connection

Confirm that you are signed in to the correct Linear organization and that your Linear account can authorize integrations. If the authorization screen blocks approval, ask a Linear administrator to approve the connection.

### The wrong Linear organization was connected

Disconnect Linear in Upsun Dispatch, then connect it again and choose the intended Linear organization during authorization.

### Linear issue behavior is not visible

The integration setup page only manages the Linear connection. Open the relevant Upsun Dispatch workflow or run view to confirm whether that part of Upsun Dispatch supports Linear issue behavior.


# Store your Anthropic key
Source: https://developer.upsun.com/dispatch/docs/models/anthropic

Store the Anthropic API key your organization uses for Upsun Dispatch workflows.

Upsun Dispatch workflows that use an AI model require a model key for your organization. Upsun Dispatch supports organization-level model keys for Anthropic and [OpenAI](/dispatch/docs/models/openai).

<Info>
  Model keys belong to the organization, not to an individual repository, GitHub installation, or GitLab project. Store the key once for the organization before running workflows such as [Code review](/dispatch/docs/workflows/code-review).
</Info>

## Store an Anthropic key

1. Sign in to Upsun Dispatch and open the organization you want to configure.
2. Go to the organization's **AI model keys** settings.
3. Select **Anthropic**.
4. Select **Add key**.
5. Enter your Anthropic API key in **API key**.
6. Select **Save**.

Upsun Dispatch validates the key with Anthropic before storing it. If the key is accepted, Upsun Dispatch stores it for the organization and does not show the full value again.

## Check key status

After a key is stored, Upsun Dispatch shows secret-free metadata only, including:

* the last four characters of the stored key,
* when the key was set, and
* when the key was last tested.

Upsun Dispatch never returns or displays the complete API key after storage.

## Rotate a key

To rotate the organization's Anthropic key, store the new key from the same settings area. The new key replaces the previous stored value.

After rotation, use the key status metadata to confirm the new key is set. The full key value is still hidden.

## Remove a key

Remove the Anthropic key if the organization should no longer use it.

Removing the key does not require you to disconnect source integrations. However, workflow runs that need the Anthropic key fail until you store a new key.

## Next steps

<CardGroup>
  <Card title="Run your first review" href="/dispatch/docs/get-started/quickstart">
    Connect a repository, open a pull request or merge request, and watch Upsun Dispatch publish a review.
  </Card>

  <Card title="Learn about Code review" href="/dispatch/docs/workflows/code-review">
    See how Upsun Dispatch reviews GitHub pull requests and GitLab merge requests.
  </Card>
</CardGroup>


# AI models
Source: https://developer.upsun.com/dispatch/docs/models/index

Store the model keys Upsun Dispatch uses to run AI-backed workflows.

Upsun Dispatch workflows that use an AI model require a model key for your organization. Model keys belong to the organization, not to an individual repository, GitHub installation, or GitLab project.

An organization can store model keys for Anthropic and OpenAI. If you store more than one key, choose the default model integration Upsun Dispatch should use for workflows unless a workflow setting or repository override selects a different model integration.

<Note>
  Store at least one model key before running workflows such as [Code review](/dispatch/docs/workflows/code-review). To configure workflow-level model selection or repository overrides, see [Workflows in Upsun Dispatch](/dispatch/docs/workflows#workflow-settings).
</Note>

## Supported model integrations

<CardGroup>
  <Card title="Store your Anthropic key" href="/dispatch/docs/models/anthropic">
    Add, replace, or remove the Anthropic key for your organization.
  </Card>

  <Card title="Store your OpenAI key" href="/dispatch/docs/models/openai">
    Add, replace, or remove the OpenAI key for your organization.
  </Card>
</CardGroup>

## Manage organization model keys

In your organization's AI keys settings, use model key management to:

<img alt="AI model keys settings showing Anthropic as the default integration and the OpenAI key form." />

The Models settings screen shows stored keys and the default model integration.

* add a model key for Anthropic or OpenAI,
* replace an existing key when you rotate it,
* remove a key your organization should no longer use,
* choose the default model integration for workflows, and
* manage an optional API base URL for model integration settings.

After a key is stored, Upsun Dispatch keeps it at the organization level and does not tie it to one connected source integration. Workflow runs that require a model key need an available key for the selected model integration.


# Store your OpenAI key
Source: https://developer.upsun.com/dispatch/docs/models/openai

Store the OpenAI API key your organization uses for Upsun Dispatch workflows.

Upsun Dispatch workflows that use OpenAI require an OpenAI model key for your organization. Store the key once at the organization level, then use workflow settings when a workflow or repository override should select that model integration.

<Info>
  Model keys belong to the organization, not to an individual repository, GitHub installation, or GitLab project. For default model integration selection and shared model-key settings, see [AI models](/dispatch/docs/models).
</Info>

## Store an OpenAI key

1. Sign in to Upsun Dispatch and open the organization you want to configure.
2. Open **Settings** > **AI model keys**.
3. Select **OpenAI**.
4. Select **Add key**.
5. Enter the OpenAI API key in **API key**.
6. Select **Save**.

After the key is stored, Upsun Dispatch can use it for workflows that select OpenAI. To choose OpenAI for a specific workflow or repository override, configure model selection in [Workflows in Upsun Dispatch](/dispatch/docs/workflows#workflow-settings).

## Check key status

Use the OpenAI row in AI keys settings to confirm whether an OpenAI key is stored and which key-management actions are available.

If your organization also stores other model keys, use the AI keys settings to choose the default model integration. Upsun Dispatch uses that default unless a workflow setting or repository override selects a different model integration.

## Rotate a key

To rotate the organization's OpenAI key, return to the OpenAI row in AI keys settings and use the replace-key control. Store the new key in the same settings area.

The new key replaces the previous OpenAI key for the organization.

## Set an API base URL

AI keys settings include an optional API base URL setting for model integration configuration. Set an API base URL only when your organization has an OpenAI API base URL to use.

## Remove a key

Remove the OpenAI key if the organization should no longer use it.

Before removing the key, make sure workflows that should continue running are configured to use an available model key. You can change workflow-level model selection and repository overrides in [Workflows in Upsun Dispatch](/dispatch/docs/workflows#workflow-settings).

## Next steps

<CardGroup>
  <Card title="Configure workflow settings" href="/dispatch/docs/workflows#workflow-settings">
    Select the model integration Upsun Dispatch should use for workflows or repository overrides.
  </Card>

  <Card title="Learn about Code review" href="/dispatch/docs/workflows/code-review">
    See how Upsun Dispatch reviews GitHub pull requests and GitLab merge requests.
  </Card>
</CardGroup>


# Built-in workflows
Source: https://developer.upsun.com/dispatch/docs/workflows/builtin

Use Upsun Dispatch built-in workflows to turn issues into pull or merge requests and review pull or merge requests.

Upsun Dispatch includes built-in workflows for common development tasks. Use this page as a quick catalog of what each workflow does and what starts it.

<Note>
  Before you use a workflow, connect the relevant integrations and add an organization AI model key. See [Set up GitHub](/dispatch/docs/integrations/github), [Set up GitLab](/dispatch/docs/integrations/gitlab), [Set up Jira](/dispatch/docs/integrations/jira), [Set up Linear](/dispatch/docs/integrations/linear), and [AI models](/dispatch/docs/models).
</Note>

## Workflow catalog

| Workflow | Supported sources | What starts it | What Upsun Dispatch publishes |
| - | - | - | - |
| [Issue to code](/dispatch/docs/workflows/issue-to-code) | GitHub issues, Jira issues, and Linear issues | The entire issue body or a single comment is exactly `@upsun-dispatch implement`, with an optional trailing `!`, `.`, or `?`. Issue to code has no automatic mode of its own. | A plan, generated implementation, critic review, pull or merge request when supported by your version control integration, and link-back comment. See [Integrations](/dispatch/docs/integrations) for supported publish targets. |
| [Code review](/dispatch/docs/workflows/code-review) | GitHub pull requests and GitLab merge requests | Supported pull request or merge request activity when automatic Code review is enabled, or a supported manual review command in a pull request or merge request comment | Review feedback such as check runs, review comments, merge request notes, commit statuses, and summaries |

## Ticketing integrations

Issue to code can use ticketing integrations as issue sources. Connect Jira with [Set up Jira](/dispatch/docs/integrations/jira) or Linear with [Set up Linear](/dispatch/docs/integrations/linear) before starting issue-based work from those tools.

For Jira-triggered Issue to code, include the target repository as `owner/repo` or a full repository URL in the Jira issue description. See [Start from an issue or ticket](/dispatch/docs/workflows/issue-to-code#start-from-an-issue-or-ticket) for details.

## View and manage workflow runs

Use the [Upsun Dispatch console](/dispatch/docs/dashboard) to view repositories, follow runs and logs, rerun eligible runs, inspect results, and adjust workflow settings or repository overrides.

For the workflow settings that control built-in workflows, see [Workflows in Upsun Dispatch](/dispatch/docs/workflows).


# Code review
Source: https://developer.upsun.com/dispatch/docs/workflows/code-review

Use Upsun Dispatch Code review to review GitHub pull requests and GitLab merge requests with an LLM-backed review agent.

The **Code review** workflow reviews GitHub pull requests and GitLab merge requests with an LLM-backed review agent. It inspects the change in a read-only checkout, then publishes integration-native review artifacts such as check runs, review comments, merge request notes, and commit statuses.

Use Code review when you want Upsun Dispatch to:

* review a new or updated pull request or merge request,
* post inline findings and body-only findings,
* summarize the change when configured to do so,
* recognize previously reviewed file sets so unchanged work is not reviewed again unnecessarily, and
* show progress and terminal status in GitHub or GitLab.

You can review workflow runs and their logs in the [Upsun Dispatch console](/dispatch/docs/dashboard). Manage trigger mode, summary mode, and repository overrides in [Workflows in Upsun Dispatch](/dispatch/docs/workflows#workflow-settings).

## GitHub and GitLab reviews

<Tabs>
  <Tab title="GitHub">
    For connected GitHub repositories, Upsun Dispatch listens for pull request changes and pull request conversation comments.

    #### Automatic reviews

    When Code review is configured for automatic triggering, opening or pushing to a GitHub pull request starts a review.

    If another push arrives while a review is already running, Upsun Dispatch waits instead of starting several overlapping reviews. After the active review finishes, Upsun Dispatch drains one fresh follow-up run against the latest pull request head. This collapses push storms into a single current review.

    #### Manual commands

    You can control reviews from a pull request comment. GitHub commands must be the whole comment message and addressed to the Upsun Dispatch bot.

    ```text theme={null}
    @upsun-dispatch review
    @upsun-dispatch full review
    @upsun-dispatch cancel
    @upsun-dispatch help
    ```

    Supported command behavior:

    * `review` requests a review. If a review is already active, Upsun Dispatch waits for it to finish, then runs a fresh review.
    * `full review` forces a full review instead of an incremental review. If a review is already active, Upsun Dispatch waits for it to finish, then runs a fresh full review.
    * `cancel` stops the active review.
    * `help` can post command help.

    Upsun Dispatch ignores ordinary pull request comments that do not match a supported command. Plain GitHub issue comments are handled by [Issue to code](/dispatch/docs/workflows/issue-to-code), not Code review.

    #### Progress and results

    While the review runs, Upsun Dispatch creates a GitHub check run so contributors can see that work is in progress. When the review completes, Upsun Dispatch concludes the check run and publishes the review result to GitHub.

    Depending on the review result, GitHub may receive:

    * a completed check run,
    * pull request review feedback,
    * inline comments,
    * body-only findings, and
    * summary text when summaries are enabled.

    If a run fails or is canceled before the final review step completes, Upsun Dispatch attempts to update the GitHub check run so GitHub does not show stale in-progress status.
  </Tab>

  <Tab title="GitLab">
    For connected GitLab projects, Upsun Dispatch listens for merge request changes, merge request notes, and reviewer changes.

    #### Automatic reviews

    When Code review is configured for automatic triggering, opening or updating a GitLab merge request starts a review. GitLab merge request review uses the same wait behavior as GitHub: if a review is already active, a newer change waits and Upsun Dispatch runs one current follow-up review after the active review ends.

    Closing or merging a merge request cancels an in-flight review instead of starting a new one.

    #### Manual commands

    You can control reviews from a merge request note by mentioning the bot username configured for that GitLab connection.

    ```text theme={null}
    @<configured-bot-username> review
    @<configured-bot-username> full review
    @<configured-bot-username> cancel
    @<configured-bot-username> help
    ```

    Supported command behavior:

    * `review` requests a review. If a review is already active, Upsun Dispatch waits for it to finish, then runs a fresh review.
    * `full review` forces a full review instead of an incremental review. If a review is already active, Upsun Dispatch waits for it to finish, then runs a fresh full review.
    * `cancel` stops the active review.
    * `help` can post command help.

    Upsun Dispatch classifies GitLab commands against the connection-specific bot username. Bot notes, system notes, self-triggered notes, and unrelated notes are ignored.

    Assigning or re-requesting the GitLab service account as reviewer on a merge request also requests a review.

    #### Progress and results

    While the review runs, Upsun Dispatch publishes GitLab progress indicators such as a merge request note and commit status. When the review completes, Upsun Dispatch updates or concludes those artifacts and publishes the review result to GitLab.

    Depending on the review result, GitLab may receive:

    * merge request notes,
    * inline findings,
    * body-only findings,
    * commit statuses, and
    * summary text when summaries are enabled.

    If a run fails or is canceled before the final review step completes, Upsun Dispatch attempts to conclude or recover the GitLab progress note and status.
  </Tab>
</Tabs>

## Review limits

Automatic Code review runs are capped at 10 completed automatic reviews per pull request or merge request. When that cap is reached, Upsun Dispatch posts a notice on the pull request or merge request. Manual review requests bypass this cap, including `review` and `full review` commands.

Reopening a pull request or merge request resets the automatic review cap for that item.

## How Code review decides what to review

Before the LLM review begins, Upsun Dispatch assesses the current pull request or merge request. It reads the latest GitHub or GitLab data, checks prior Upsun Dispatch review markers and unresolved threads, and decides whether to:

* skip the review,
* perform a full review, or
* perform an incremental review.

If the `assess-changes` step determines there is nothing new to review, Upsun Dispatch ends the run as `skipped` instead of starting the LLM review step.

Upsun Dispatch passes the assessment to the sandboxed review step together with review settings such as the selected model, effort level, token limit, and summary mode.

## Summary behavior

Code review can publish summary text as part of the GitHub or GitLab result. The exact summary behavior depends on workflow settings and the integration receiving the review.

When summary mode is set to `auto`, the review agent can mark a summary as optional if the pull request or merge request description already summarizes the change. In that case:

* GitHub publishes the optional summary only when an existing Upsun Dispatch summary comment needs updating.
* GitLab can omit an optional summary from a new note.

When summary mode is `off`, Upsun Dispatch stops rendering and publishing new summary text. It does not delete older summary comments or notes that were already posted.

Manage summary mode and repository overrides in [Workflows in Upsun Dispatch](/dispatch/docs/workflows#workflow-settings).


# Workflows in Upsun Dispatch
Source: https://developer.upsun.com/dispatch/docs/workflows/index

Understand the built-in Upsun Dispatch workflows, how they start, and how workflow settings control their behavior.

Workflows are the automations Upsun Dispatch runs after your organization connects an integration and stores the required [AI model key](/dispatch/docs/models). A workflow listens for supported activity, creates a run, executes the work, and publishes results back to the relevant integration and the Upsun Dispatch console.

Upsun Dispatch currently provides two built-in workflows:

* **[Issue to code](/dispatch/docs/workflows/issue-to-code)** starts when an issue body or comment is exactly `@upsun-dispatch implement`, with an optional trailing `!`, `.`, or `?`, and turns the issue request into code work.
* **[Code review](/dispatch/docs/workflows/code-review)** reviews GitHub pull requests and GitLab merge requests, then publishes review feedback such as checks, statuses, comments, notes, and summaries.

For a compact list of built-in workflows and their supported triggers, see [Built-in workflows](/dispatch/docs/workflows/builtin).

## How workflows start

Workflows can start from integration events or from a manual action, depending on the workflow and your settings.

### Automatic triggers

Trigger mode applies to **Code review only**. Its default is `automatic`, which means supported events can start Code review runs without a separate action from you. For Code review, this includes changes to connected GitHub pull requests and GitLab merge requests.

Code review uses wait behavior for rapid updates: if a new push arrives while a review is already running, Upsun Dispatch holds the new delivery and runs one fresh review after the active review finishes. This prevents a burst of pushes from creating redundant reviews.

Issue to code does not have an automatic or manual trigger mode. It starts only when the entire trimmed issue body or a comment is exactly `@upsun-dispatch implement`, with an optional trailing `!`, `.`, or `?`.

### Manual triggers

Some workflows can be started manually from comments.

For **Code review**, users can request a review, force a full review, or request cancellation of an active review from the pull or merge request conversation:

* On GitHub pull requests, use whole-message commands addressed to the Upsun Dispatch bot, such as `@upsun-dispatch review`, `@upsun-dispatch full review`, or `@upsun-dispatch cancel`.
* On GitLab merge requests, use the bot username configured for that GitLab connection, such as `@<configured-bot-username> review`, `@<configured-bot-username> full review`, or `@<configured-bot-username> cancel`.

For **Issue to code**, the whole trimmed issue body or comment must be exactly `@upsun-dispatch implement`, with an optional trailing `!`, `.`, or `?`. Issue to code has no automatic or manual mode of its own. This exact issue command is the trigger. See [Issue to code](/dispatch/docs/workflows/issue-to-code) for examples and non-matching command behavior.

Use `@upsun-dispatch help` to post command help. Ordinary comments that do not match a supported command are ignored.

You can observe runs in the Upsun Dispatch console, including viewing run details, following logs, and rerunning eligible terminal runs. See [Use the Upsun Dispatch console](/dispatch/docs/dashboard) for those actions.

## Workflow settings

Workflow settings control how Upsun Dispatch behaves for a workflow across your organization. Settings are available per configurable workflow and integration.

In **Organization Settings > Workflows**, use **Model integration** to choose which stored AI model key a workflow uses. Use **Quality level** to set the model effort level for that workflow. To add or manage stored model keys, see [AI models](/dispatch/docs/models).

Available settings include:

| Setting | Applies to | Default | What it controls |
| - | - | - | - |
| **Trigger mode** | Code review only | `automatic` | Choose whether supported Code review events start runs automatically or require manual action. |
| **Ignored authors** | Configurable workflows and integrations | No ignored authors | Set authors whose activity should not start workflow runs. |
| **Allow fork authors** | GitLab merge request review | `off` | Choose whether fork authors are admitted. |
| **Plan approval gate** | Jira-only for Issue to code; no separate plan approval gate for GitHub or Linear today. | `off` | Choose whether Issue to code pauses for approval at the plan step before continuing for Jira-triggered runs. |
| **Summary mode** | Review-producing workflows | `auto` | Choose how review summaries are published. The available values are `always`, `auto`, and `off`; `auto` is the default. |
| **AI model integration selection and pinning** | Configurable workflows | Organization default AI model key | Choose which stored AI model key a workflow uses, or let the workflow follow the organization default from [AI models](/dispatch/docs/models). |
| **Quality level** | Configurable workflows | Workflow setting | Set the model effort level Upsun Dispatch uses for workflow runs. |

<Note>
  Turning summary mode off stops Upsun Dispatch from publishing future summary content. It does not delete summaries that were already posted.
</Note>

The Plan approval gate setting does not make Issue to code automatic. Issue to code still starts only from its exact trigger phrase. The gate only controls whether eligible Jira-triggered Issue to code runs pause at the plan step before continuing.

## Repository overrides

Organization-level workflow settings act as defaults. You can also create repository overrides for individual repositories when one repository needs different behavior from the rest of the organization.

Repository overrides pin selected settings for that repository independently from the organization default. For example, you can keep Code review automatic for most repositories while making one repository manual-only, or pin a repository to a specific stored AI model key.

Manage organization workflow settings and repository overrides in the Upsun Dispatch console. See [Use the Upsun Dispatch console](/dispatch/docs/dashboard) for where to change these settings.

## Where results appear

Each workflow run is visible in the Upsun Dispatch console with status, steps, timeline events, logs, and usage information. Code review also publishes results back to GitHub and GitLab, such as GitHub checks and review comments or GitLab progress notes, commit statuses, and merge request notes.

To inspect a run, follow logs, or rerun an eligible completed, failed, or canceled run, use the Upsun Dispatch console.


# Issue to code
Source: https://developer.upsun.com/dispatch/docs/workflows/issue-to-code

Use Upsun Dispatch Issue to code to turn a GitHub issue, Jira ticket, or Linear issue into a planned code change and pull or merge request when supported by your version control integration.

The **Issue to code** workflow turns a GitHub issue, Jira ticket, or Linear issue into a planned code change, generated implementation, critic review, pull or merge request (when supported by your version control integration), and link-back comment. See [Integrations](/dispatch/docs/integrations) for supported publish targets.

Use Issue to code when you want Upsun Dispatch to:

* read issue or ticket context,
* plan an implementation,
* post that plan back to the issue or ticket,
* generate code changes,
* run a critic pass before opening a pull or merge request (when supported by your version control integration),
* push a branch and open or update a pull or merge request (when supported by your version control integration), and
* comment on the issue or ticket with a link to the pull or merge request (when supported by your version control integration).

<Note>
  Issue to code has no automatic mode and no manual trigger setting. It starts only when an issue body, ticket body, or comment is a valid Issue to code trigger.
</Note>

## Start from an issue or ticket

Issue to code starts from a GitHub issue, Jira ticket, or Linear issue when the whole trimmed issue or ticket body, or whole trimmed comment, is exactly this request:

```text theme={null}
@upsun-dispatch implement
```

A trailing `!`, `.`, or `?` is allowed. Leading and trailing whitespace is ignored.

Upsun Dispatch starts Issue to code when:

* a new issue or ticket is opened with only the trigger text in the body, or
* a new comment is added to an issue or ticket with only the trigger text in the comment body.

A longer issue body, ticket body, or comment does not start Issue to code, even if it contains the trigger phrase. For example, these do not start a run:

```text theme={null}
@upsun-dispatch implement this
```

```text theme={null}
We need to update the payment flow.

@upsun-dispatch implement
```

When Upsun Dispatch sees a nonmatching mention or command, it posts the command list instead of starting a run.

For most issues and tickets, open the item with your description as usual, then add a comment whose entire text is:

```text theme={null}
@upsun-dispatch implement
```

You can also open the item with only `@upsun-dispatch implement` as the body.

<Note>
  For Jira-triggered runs, include the target repository in the Jira issue description as `owner/repo` or as the full repository URL. Start the run by posting the trigger as a separate comment whose entire body is the trigger text. Do not put the trigger in the Jira issue description, because the whole-body trigger rule applies there too. The repository reference does not need to be a clickable link.
</Note>

Upsun Dispatch does not start Issue to code when:

* the trigger text appears only in the issue or ticket title,
* an existing issue or ticket body is edited to add the trigger text,
* an existing comment is edited to add the trigger text,
* the comment is on a pull or merge request conversation instead of a plain issue or ticket, or
* the trigger was posted by Upsun Dispatch itself.

If you add a valid trigger while Issue to code is already active for that issue or ticket, Upsun Dispatch drops the repeated trigger instead of queuing another run. After the active run ends (completes, fails, or is canceled), a later valid trigger starts a new run. For the same source issue or ticket, Upsun Dispatch reuses the same branch, such as `upsun-dispatch/issue-42`, so the next run updates the existing branch and, when supported by your version control integration, the existing pull or merge request instead of opening a separate one.

You cannot cancel an active run from the [Upsun Dispatch console](/dispatch/docs/dashboard). While Issue to code is still in progress before a pull or merge request exists for an integration that supports one, close the source issue or ticket to stop it. After Upsun Dispatch opens or updates a pull or merge request (when supported by your version control integration) and posts the link back, later implementation work starts from a new valid trigger and follows the same branch reuse behavior.

## What the workflow does

Issue to code runs through these stages:

1. **Check push access.** Upsun Dispatch verifies that it has permission to write repository contents before spending time on planning and code generation.
2. **Gather context.** Upsun Dispatch reads issue or ticket metadata, comments, linked references, related pull or merge requests or issues, and relevant repository files into a bounded context bundle.
3. **Plan.** The planning agent creates an implementation plan and Upsun Dispatch posts the plan back to the originating issue or ticket. For Jira-triggered runs, if **Plan approval** is enabled in [Settings > Workflows](/dispatch/docs/workflows#workflow-settings), the run pauses here until an approval decision is posted. For other trigger sources, Issue to code does not use a separate plan approval gate.
4. **Code.** The coding agent works from a fresh clone and the plan. It produces materialized file contents, a summary, a pull or merge request title (when supported by your version control integration), a commit message, changed-file metadata, and review material for the critic.
5. **Critic.** The critic reviews a capped projection of the generated change before a pull or merge request is opened, when supported by your version control integration. Fatal findings block pull or merge request creation. Nonfatal findings can appear in the pull or merge request body when one is opened, or in run presentation.
6. **Push and open.** Upsun Dispatch applies the generated file contents, pushes a branch, and opens or updates a pull or merge request (when supported by your version control integration).
7. **Link back.** When a pull or merge request is opened or updated (when supported by your version control integration), Upsun Dispatch posts a final comment on the originating issue or ticket with a link to it.

The workflow is single-pass after planning is approved or allowed to continue: it codes, runs the critic, and then opens or updates a pull or merge request (when supported by your version control integration). Issue to code does not revise the implementation after critic feedback.

## Understand the plan

The Issue to code plan is structured so you can review both the proposed work and its expected scope. A plan includes:

* **Summary:** two or three sentences describing the intended change.
* **Full plan:** a detailed Markdown plan.
* **Files affected:** repo-relative paths the run expects to change. At least one file is listed.
* **Complexity:** one of `trivial`, `simple`, `moderate`, or `complex`.
* **Assumptions:** important conditions the plan depends on.
* **Risks:** potential issues or uncertainties to review before implementation continues.

You can inspect run activity, logs, and details in the [Upsun Dispatch console](/dispatch/docs/dashboard). Planning output can also include per-run usage reporting.

## Approve or revise a Jira plan

The plan approval gate applies only to Jira-triggered Issue to code runs when **Plan approval** is enabled in **Settings > Workflows**. For other trigger sources, there is no separate plan approval gate.

When the gate is active, a Jira-triggered run pauses after posting the plan and waits for a comment that mentions the Upsun Dispatch bot followed by one of these commands:

```text theme={null}
@upsun-dispatch plan approve
```

```text theme={null}
@upsun-dispatch plan reject [reason]
```

```text theme={null}
@upsun-dispatch plan revise <feedback>
```

Use `plan approve` to continue to coding. Use `plan reject [reason]` to stop the run. Use `plan revise <feedback>` to send feedback and rerun planning; the feedback text is required.

If no approval decision is posted for 7 days, the gate expires and the agent's context for the request clears. Resuming the work later reruns the request from scratch and consumes additional usage.

## Branch naming

For GitHub issues, Upsun Dispatch uses a stable branch for the same issue, based on the configured branch prefix and the issue number. Repeated completed runs for the same issue can update the same pull request branch.

A typical branch name looks like this:

```text theme={null}
upsun-dispatch/issue-42
```

## When a pull or merge request is not opened

A run can end without opening a pull or merge request for different reasons. Unsupported Issue to code publishing is separate from fatal blockers.

When your version control integration does not support Issue to code publishing, the workflow does not open a pull or merge request. For example, GitLab currently does not support Issue to code publishing. See [Integrations](/dispatch/docs/integrations) for supported publish targets. For GitLab merge request automation, use [Code review](/dispatch/docs/workflows/code-review).

Upsun Dispatch refuses to open a pull or merge request when it cannot safely do so. For example:

* Upsun Dispatch does not have repository contents write permission,
* the coding action reports incomplete work with blocking issues,
* the critic reports fatal findings such as compile or parse failures or clear contradictions with the plan, or
* the generated result is blocked or incomplete.

For fatal blockers, Upsun Dispatch posts a blocked explanation instead of a pull or merge request link. Check the issue or ticket comments and the run detail in the [Upsun Dispatch console](/dispatch/docs/dashboard) for the reported blocker.

If no pull or merge request is opened because of a fatal blocker, the run fails so you do not see a successful run that delivered no code change.


# Upsun Dispatch
Source: https://developer.upsun.com/dispatch/index

Docs, guides, and references for Upsun Dispatch, governed AI-agent workflows to plan, code, review, and optimize your software. Connect a repo, leave a comment, and Upsun Dispatch takes it from there.

<div>
  <div>
    <div>
      <div />
    </div>

    <div>
      <div>
        <span />

        <span>Part of the Upsun platform</span>
      </div>

      Less backlog, more shipped code
      <span>with <span>Upsun Dispatch™.</span></span>
      ===============================================

      <p>
        Upsun Dispatch reviews your pull requests and turns issues into pull requests.
      </p>

      <p>
        Connect a repo, leave a comment, and Upsun Dispatch takes it from there.
      </p>

      <div>
        <a href="/dispatch/docs/get-started">
          Get started

          <Icon icon="arrow-right" />
        </a>

        <a href="/dispatch/docs/get-started">
          Browse docs
        </a>
      </div>
    </div>
  </div>

  <div>
    <div>
      <div>
        <h3>One platform, full lifecycle coverage</h3>

        <div>
          <div>
            <span>Upsun Dispatch</span>

            <div />

            <div>
              <div>
                <span>Plan</span>
                <span>Code</span>
              </div>

              <div>
                <span>Review</span>
                <span>Optimize</span>
              </div>
            </div>
          </div>

          <div>
            <div>
              <div />

              <div>
                <span>✓</span>
                <span>Git push</span>
              </div>

              <div>
                <div />

                <Icon icon="chevron-down" />
              </div>
            </div>

            <div>
              <span>Upsun Dispatch</span>

              <div />

              <div>
                <div>
                  <div />

                  <div>
                    <span>✓</span>
                    <span>Git push</span>
                  </div>

                  <div>
                    <div />

                    <Icon icon="arrow-right" />
                  </div>
                </div>
              </div>
            </div>
          </div>

          <div>
            <span>Upsun Cloud</span>

            <div />

            <div>
              <div>
                <span>Build</span>
                <span>Test</span>
              </div>

              <div>
                <span>Deploy</span>
                <span>Run</span>
              </div>
            </div>
          </div>
        </div>

        <p>
          Use either product on its own, or connect them at the git push handoff for full coverage.
        </p>
      </div>
    </div>

    <div>
      <div>
        <div />

        <span>Why organizations use Upsun Dispatch</span>
      </div>

      <h2>Keep code moving</h2>
      <p>Stalled pull requests and growing issue backlogs cost your organization time it doesn't have to spend.</p>
    </div>

    <div>
      <div>
        <div>
          <div>
            <Icon icon="hourglass" />
          </div>

          <p>Friday's pull request is still open Monday morning.</p>
        </div>

        <p>Comment <span>@upsun-dispatch review</span></p>
      </div>

      <div>
        <div>
          <div>
            <Icon icon="circle-dot" />
          </div>

          <p>Twelve new issues this sprint. Eleven still open.</p>
        </div>

        <p>Comment <span>@upsun-dispatch implement</span></p>
      </div>

      <div>
        <div>
          <div>
            <Icon icon="layers" />
          </div>

          <p>Small papercuts pile up. Nobody owns fixing them.</p>
        </div>

        <p>Comment <span>@upsun-dispatch implement</span></p>
      </div>
    </div>

    <div>
      <div>
        <h2>Connect. Trigger. Ship.</h2>
        <p>Whether it's Friday's stalled PR or this sprint's growing backlog, it starts the same way: connect once, then comment.</p>

        <div>
          <div />

          <div>
            <div>
              <div>1</div>
              <h3>Connect</h3>
              <p>Link GitHub or GitLab to your organization and store your Anthropic key.</p>
              <div>GitHub App · GitLab project · Anthropic key</div>
            </div>

            <div>
              <div>2</div>
              <h3>Trigger</h3>
              <p>Push a change, or mention Upsun Dispatch in an issue or pull request.</p>

              <div>
                <div><span>@upsun-dispatch</span> <span>implement</span></div>
                <div><span>@upsun-dispatch</span> <span>review</span></div>
                <div><span>@upsun-dispatch</span> <span>full review</span></div>
              </div>
            </div>

            <div>
              <div>3</div>
              <h3>Ship</h3>
              <p>Upsun Dispatch posts checks, comments, and pull requests back where you work, and records every run in the Upsun Dispatch console.</p>

              <div>
                <div>#128 · upsun-dispatch/issue-42</div>

                <div>
                  <span>✓</span>
                  <span>Pull request opened</span>
                </div>
              </div>
            </div>
          </div>
        </div>
      </div>
    </div>

    <div>
      <div>
        <div>
          <div>
            <Icon icon="users" />
          </div>

          <div>
            <h3>Everyone works from the same run</h3>
            <p>Captured as it happens. Visible to the whole organization, not just whoever kicked it off.</p>
          </div>
        </div>

        <div>
          <img alt="Upsun Dispatch run timeline showing an approved plan step and a live code step" />
        </div>
      </div>
    </div>

    <div>
      <h2>Under the hood</h2>
      <p>Built-in workflows are just the beginning.</p>
    </div>

    <div>
      <div>
        <a href="/dispatch/docs/workflows/issue-to-code">
          <div>
            <Icon icon="code" />
          </div>

          <h3>Issue to code</h3>
        </a>

        <ul>
          <li>
            <Icon icon="check" />

            <span>Starts from a simple <span>@upsun-dispatch implement</span> mention</span>
          </li>

          <li>
            <Icon icon="check" />

            <span>Plans, implements, and self-reviews before publishing</span>
          </li>

          <li>
            <Icon icon="check" />

            <span>Opens or updates a pull request linked to the issue</span>
          </li>
        </ul>

        <div>
          <div>
            <span />

            <span />

            <span />

            <span>issue #42 → dispatch</span>
          </div>

          <div>
            <div># @upsun-dispatch implement</div>
            <div>Gathering issue context</div>
            <div>Planning implementation</div>
            <div>Generating code changes</div>
            <div>Running critic pass</div>

            <div>
              <span>✓</span>
              <span>Pull request opened</span>
            </div>

            <div>#128 · upsun-dispatch/issue-42</div>
          </div>
        </div>
      </div>

      <div>
        <a href="/dispatch/docs/workflows/code-review">
          <div>
            <Icon icon="search-check" />
          </div>

          <h3>Code review</h3>
        </a>

        <ul>
          <li>
            <Icon icon="check" />

            <span>Runs on push or on demand with <span>@upsun-dispatch review</span></span>
          </li>

          <li>
            <Icon icon="check" />

            <span>Inline comments on the exact lines that need attention</span>
          </li>

          <li>
            <Icon icon="check" />

            <span>Publishes checks and statuses natively in GitHub and GitLab</span>
          </li>
        </ul>

        <div>
          <div>
            <Icon icon="git-pull-request" />

            <span>Pull request #128</span>
            <span>Open</span>
          </div>

          <div>
            <div>
              <span>✓</span>
              <span>Upsun Dispatch · Code review</span>
              <span>passed</span>
            </div>

            <div>
              <div>src/auth/session.ts:42</div>
              <div>Upsun Dispatch</div>
              <div>Validate token expiry before refreshing. This branch can throw on a null claim.</div>
            </div>

            <div>
              <span>✓</span>
              <span>Summary published</span>
            </div>
          </div>
        </div>
      </div>
    </div>

    <div>
      <div>
        <div>
          <p>
            <span>Custom workflows</span> for your own development process are coming soon.

            <br />

            Got an idea for a workflow? <a href="https://support.upsun.com/hc/en-us/requests/new?ticket_form_id=37982573191442">Tell us</a> and help decide what we build next.
          </p>
        </div>

        <WorkflowBuilderAnimation />
      </div>
    </div>

    <div>
      <h2>Connect a repo and leave a comment.</h2>

      <p>
        That's the whole onboarding. Upsun Dispatch handles the rest.
      </p>

      <div>
        <a href="/dispatch/docs/get-started/quickstart">
          Get started →
        </a>

        <a href="/dispatch/docs/get-started">
          Browse docs
        </a>
      </div>

      <div>
        <span>✓ Automated code review</span>
        <span>✓ Issue to pull request</span>
        <span>✓ GitHub and GitLab</span>
      </div>
    </div>
  </div>
</div>


# ClickHouse
Source: https://developer.upsun.com/docs/add-services/clickhouse



ClickHouse is a high-performance column-oriented, distributed, OLAP (Online Analytical Processing) database.<br />
It allows you to generate real-time analytical data reports using SQL queries.<br />
For more information, see the [ClickHouse documentation](https://ClickHouse.com/docs).

<Note>
  Upsun Cloud supports ClickHouse with the following limitations:

  * High availability of service isn't supported.
  * You can only configure single-node ClickHouse clusters.
</Note>

## Supported versions

* <span>26.8</span>
* <span>26.3</span>

Upsun plans on supporting long-term support ClickHouse versions in priority.

## Deprecated versions

The following versions are still available in your projects,
but they're at their end of life and are no longer receiving security updates from upstream.

* <span>25.8</span>
* <span>25.3</span>
* <span>24.3</span>
* <span>23.8</span>

To ensure your project remains stable in the future,
switch to a [supported version](#supported-versions).

## Retired versions

The following versions have been retired and are no longer available.
If your project uses a retired version, you must update to a [supported version](#supported-versions).

*No retired versions.*

## Relationship reference

For each service [defined via a relationship](#usage-example) to your application,
Upsun Cloud automatically generates corresponding environment variables within your application container,
in the `$<RELATIONSHIP-NAME>_<SERVICE-PROPERTY>` format.

Here is example information available through the [service environment variables](/docs/development/variables#service-environment-variables) themselves,
or through the [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables).

<Tabs>
  <Tab title="Service environment variables">
    You can obtain the complete list of available service environment variables in your app container by running `upsun ssh env`.

    Note that the information about the relationship can change when an app is redeployed or restarted or the relationship is changed. So your apps should only rely on the [service environment variables](/docs/development/variables#service-environment-variables) directly rather than hard coding any values.
  </Tab>

  <Tab title="`PLATFORM_RELATIONSHIPS` environment variable">
    For some advanced use cases, you can use the [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables).
    The structure of the `PLATFORM_RELATIONSHIPS` environment variable can be obtained by running `upsun relationships` in your terminal:

    Here is an example of how to gather [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables) information in a [`.environment` file](/docs/development/variables/set-variables#when-to-use-env-files):

    ```bash .environment theme={null}
    # Decode the built-in credentials object variable.
    export RELATIONSHIPS_JSON="$(echo "$PLATFORM_RELATIONSHIPS" | base64 --decode)"

    # Set environment variables for individual credentials.
    export APP_CLICKHOUSE_HOST=="$(echo "$RELATIONSHIPS_JSON" | jq -r '.clickhouse[0].host')"
    ```
  </Tab>
</Tabs>

## Usage example

### 1. Configure the service

To define the service, use the `clickhouse` type:

Note that changing the name of the service replaces it with a brand new service and all existing data is lost. Back up your data before changing the service.

### 2. Define the relationship

To define the relationship, use one of the following endpoints.

#### `clickhouse` endpoint

The `clickhouse` endpoint allows you to use the Native Protocol port (also known as ClickHouse TCP protocol).
This protocol is used by ClickHouse apps and processes such as `clickhouse-server`, `clickhouse-client`, and native ClickHouse tools. It is also used for inter-server communication for distributed queries.

Use the following configuration:

<Tabs>
  <Tab title="Using default endpoints">
    You can define `SERVICE_NAME` as you like.
  </Tab>

  <Tab title="Using explicit endpoints">
    You can define `SERVICE_NAME` and `<RELATIONSHIP_NAME>` as you like, but it's best if they're distinct.
    With this definition, the application container (`<APP_NAME>:`) now has access to the service via the corresponding [service environment variables](/docs/development/variables#service-environment-variables).
  </Tab>
</Tabs>

#### `clickhouse-http` endpoint

The `clickhouse-http` endpoint allows you to use the HTTP API Port for HTTP requests.
This protocol is used by [JDBC](https://docs.oracle.com/javase/8/docs/technotes/guides/jdbc/), [ODBC](https://learn.microsoft.com/en-us/sql/odbc/microsoft-open-database-connectivity-odbc?view=sql-server-ver16), and web interfaces.

Use the following configuration:

You can define `SERVICE_NAME` and `<RELATIONSHIP_NAME>` as you like, so long as it's unique between all defined services and relationships
and matches in both the application and services configuration.

With this definition, the application container (`<APP_NAME>:`) now has access to the service via the corresponding [service environment variables](/docs/development/variables#service-environment-variables).

### Example configuration

If you want to change the `clickhouse` endpoint to `clickhouse-http`, you need to use explicit endpoint definition as it defaults to `clickhouse` endpoint when using default endpoint (aka. `<SERVICE_NAME>` as relationship definition).

## Multiple databases

You can configure multiple databases, much like [with PostgreSQL](/docs/add-services/postgresql#multiple-databases).
To do so, you can use a configuration similar to the following:

## Exporting Data

ClickHouse data can be exported using the native `clickhouse-client` tool over an SSH tunnel.

1. Open an SSH tunnel to your ClickHouse service:

```bash Terminal theme={null}
upsun tunnel:single --relationship <RELATIONSHIP_NAME>
```

By default this opens the tunnel on `127.0.0.1:30000`.

2. Export a table or the result of a query to a file:

```bash Terminal theme={null}
clickhouse-client \
  --host 127.0.0.1 \
  --port 9000 \
  --user <CLICKHOUSE_USERNAME> \
  --password <CLICKHOUSE_PASSWORD> \
  --database <CLICKHOUSE_PATH> \
  --query "SELECT * FROM <TABLE_NAME>" \
  --format CSVWithNames > table_export.csv
```

You can replace `CSVWithNames` with any [ClickHouse output format](https://clickhouse.com/docs/en/interfaces/formats)
such as `Parquet`, `JSONEachRow`, or `Native` depending on your needs.

3. To export the full schema of your database:

```bash Terminal theme={null}
clickhouse-client \
  --host 127.0.0.1 \
  --port 9000 \
  --user <CLICKHOUSE_USERNAME> \
  --password <CLICKHOUSE_PASSWORD> \
  --query "SHOW CREATE TABLE <TABLE_NAME>"
```

The credentials (`<CLICKHOUSE_USERNAME>`, `<CLICKHOUSE_PASSWORD>`, `<CLICKHOUSE_PATH>`) are available
in the service environment variables. Run `upsun ssh -- env | grep CLICKHOUSE` to retrieve them.


# Meilisearch
Source: https://developer.upsun.com/docs/add-services/docker-images/docker-meilisearch

Deploy the official Meilisearch Docker image on Upsun Cloud for fast, self-hosted search.

Deploy the official [Meilisearch](https://hub.docker.com/r/getmeili/meilisearch) image on Upsun Cloud using Docker image support.

For prerequisites and limitations, see [Self-hosted services from public Docker images](/docs/add-services/docker-images).

## Before you begin

1. [Install the Upsun Cloud CLI](/cli/install).
2. Run the following commands to log in and connect the current Git repository to the correct Upsun Cloud project. Replace `<PROJECT_ID>` with your project ID (run `upsun projects` to list them).

   ```bash theme={null}
   upsun login
   upsun auth:info
   upsun set-remote <PROJECT_ID>
   upsun project:info
   upsun environment:info
   ```

## 1. Configure Meilisearch as an app

Add the following configuration to `.upsun/config.yaml`.

* This configuration uses [the startup command defined by the image](/docs/add-services/docker-images#startup-commands). The official Meilisearch image already starts Meilisearch and listens on `0.0.0.0:7700`, so this example does not set `web.commands.start` to override it.
* The `/meili_data` mount maps to the path used by the official image for indexes, dumps, and snapshots.

```yaml theme={null}
applications:
  meilisearch:
    type: docker:1
    container_profile: HIGH_MEMORY

    # Pin the image tag for repeatable deploys. Avoid `latest` in production;
    # update this tag intentionally when you are ready to upgrade Meilisearch.
    image:
      name: "getmeili/meilisearch:v1.45.2"

    # Production baseline after deployment:
    #   upsun resources:set --size meilisearch:2 --disk meilisearch:10240
    # This keeps one Meilisearch instance with 2 CPU and, under HIGH_MEMORY,
    # roughly 4 GB RAM. Increase disk for larger indexes and snapshots.

    # /meili_data exists in the official image and is the documented Docker
    # volume path for Meilisearch data, dumps, and snapshots.
    mounts:
      "/meili_data":
        source: storage
        source_path: meili_data

    variables:
      env:
        # Production mode requires a valid MEILI_MASTER_KEY. Keep that key out
        # of Git and set it as a sensitive runtime variable instead:
        #   upsun variable:create --level environment --prefix env: --name MEILI_MASTER_KEY --value '<LONG_RANDOM_MASTER_KEY>' --sensitive true --visible-runtime true --visible-build false
        MEILI_ENV: "production"
        MEILI_DB_PATH: "/meili_data"

        # These are Meilisearch defaults relative to the Docker working
        # directory, but keeping them explicit makes backup/export locations
        # obvious and keeps the deployed runtime stable.
        MEILI_DUMP_DIR: "/meili_data/dumps"
        MEILI_SNAPSHOT_DIR: "/meili_data/snapshots"

        # The official image already binds to 0.0.0.0:7700. Keep this aligned
        # with web.upstream.socket_family: tcp and the route target below.
        MEILI_HTTP_ADDR: "0.0.0.0:7700"
        MEILI_NO_ANALYTICS: "true"

    web:
      upstream:
        # Meilisearch serves HTTP directly on a TCP port; passthrough lets the
        # Upsun Cloud router forward requests without expecting a local Unix socket.
        socket_family: tcp
      locations:
        "/":
          passthru: true

# This project does not need Upsun Cloud-managed services because Meilisearch is
# running as the app container itself.
services: null

routes:
  # Use a dedicated subdomain so clients can address Meilisearch directly.
  "https://meilisearch.{default}/":
    type: upstream
    upstream: "meilisearch:http"
```

## 2. Set or update the Meilisearch master key

Set `MEILI_MASTER_KEY` as a sensitive runtime environment variable instead of committing it to `.upsun/config.yaml`.

1. Generate a long random value for the master key:

   ```bash theme={null}
   openssl rand -hex 32
   ```

2. Use the generated value in place of `<LONG_RANDOM_MASTER_KEY>`:

   ```bash theme={null}
   upsun variable:create --level environment --prefix env: --name MEILI_MASTER_KEY --value '<LONG_RANDOM_MASTER_KEY>' --sensitive true --visible-runtime true --visible-build false
   ```

If the `MEILI_MASTER_KEY` variable already exists, update it:

```bash theme={null}
upsun variable:update env:MEILI_MASTER_KEY --level environment --value '<LONG_RANDOM_MASTER_KEY>' --sensitive true --visible-runtime true --visible-build false
```

## 3. Deploy the app

Commit the changes to `.upsun/config.yaml` and push them to Upsun Cloud:

```bash theme={null}
git add .upsun/config.yaml
git commit -m "Add Meilisearch Docker image app"
upsun push
```

## 4. Allocate Meilisearch resources

The first deployment [defaults to a minimal resource allocation](/docs/manage-resources/resource-init) regardless of app type (0.5 CPU, 512 MB disk, and [1408 MB memory](/docs/manage-resources/adjust-resources#shared-cpu-container-sizes)). That's enough to boot the container, but not to handle real indexing and search traffic, so set a production baseline for the app:

```bash theme={null}
upsun resources:set --size meilisearch:2 --disk meilisearch:10240
```

With `container_profile: HIGH_MEMORY`, the Meilisearch app gets 2 CPU, about 4 GB RAM, 10 GB disk, and one instance. If your indexes, dumps, or snapshots grow past that, [increase the disk size](/docs/manage-resources/adjust-resources#vertical-scaling).

If you changed resources after the app was already deployed, redeploy the environment:

```bash theme={null}
upsun environment:redeploy
```

## 5. Validate the deployment

List the routes, and confirm that the HTTPS route mapped to the `meilisearch` app appears. You'll use it in place of `<MEILISEARCH_ROUTE>` in the next step.

```bash theme={null}
upsun route:list
```

Check the health endpoint. Replace `<MEILISEARCH_ROUTE>` with the HTTPS route for the Meilisearch app:

```bash theme={null}
curl https://<MEILISEARCH_ROUTE>/health
```

Expected response:

```json theme={null}
{"status":"available"}
```

If the health check doesn't return this, or you run into other issues deploying the app, [debug the app over SSH](/docs/add-services/docker-images#debug-an-app-over-ssh) to check `/var/log/app.log` and the container's process state.

## Updating the image version

To use a different Meilisearch version, update the version in `image.name`:

```yaml theme={null}
applications:
  meilisearch:
    type: docker:1
    image:
      name: "getmeili/meilisearch:<VERSION>"
```

Then, commit and push the change:

```bash theme={null}
git add .upsun/config.yaml
git commit -m "Update Meilisearch image version"
upsun push
```


# n8n
Source: https://developer.upsun.com/docs/add-services/docker-images/docker-n8n

Deploy the official n8n Docker image on Upsun Cloud for workflow automation, AI agent orchestration, and webhook-driven integrations.

[n8n](https://github.com/n8n-io/n8n/pkgs/container/n8n) is a workflow automation platform with a visual editor, webhook triggers, and built-in AI agent nodes. This guide deploys the official Docker image on Upsun Cloud using Docker image support, with a persistent SQLite database for workflows, credentials, and execution history.

For prerequisites and Docker image limitations, see [Self-hosted services from public Docker images](/docs/add-services/docker-images).

If you don't need a persistent workflow UI and just want to run a job on demand or on a schedule, [task containers](/docs/configure-apps/tasks) or [crons](/docs/configure-apps/image-properties/crons) may be a simpler fit than n8n.

## Before you begin

1. [Install the Upsun Cloud CLI](/cli/install).
2. Run the following commands to log in and connect the current Git repository to the correct Upsun Cloud project. Replace `<PROJECT_ID>` with your project ID (run `upsun projects` to list them).

   ```bash theme={null}
   upsun login
   upsun auth:info
   upsun set-remote <PROJECT_ID>
   upsun project:info
   upsun environment:info
   ```

## 1. Configure n8n as an app

Add the following configuration to `.upsun/config.yaml`.

* This configuration uses [the startup command defined by the image](/docs/add-services/docker-images#startup-commands). The official n8n image already starts n8n and listens on `0.0.0.0:5678`, so this example does not set `web.commands.start` to override it.
* The `/home/node` mount contains n8n's SQLite database, configuration, credentials, and cache. Mounting the full home directory ensures both `.n8n` and `.cache` are writable and persistent.
* `HIGH_MEMORY` is a [container profile](/docs/configure-apps/image-properties/container_profile) — a preset ratio of memory to CPU. Choose the profile that matches n8n's actual resource needs.

```yaml theme={null}
applications:
  n8n:
    type: docker:1
    container_profile: HIGH_MEMORY

    # Pin the image tag for repeatable deploys. Avoid `latest` in production;
    # update this tag intentionally when you are ready to upgrade n8n.
    image:
      name: "ghcr.io/n8n-io/n8n:2.34.1"

    # Production baseline after deployment:
    #   upsun resources:set --size n8n:1 --disk n8n:2048
    # This keeps one n8n instance with 1 CPU and, under HIGH_MEMORY, roughly
    # 2 GB RAM. Increase disk for execution history and binary data.

    # /home/node exists in the official image. n8n stores its SQLite database
    # and instance configuration in .n8n and compiled editor assets in .cache.
    mounts:
      "/home/node":
        source: storage
        source_path: node-home

    variables:
      env:
        # Keep the encryption key out of Git and set it as a sensitive runtime
        # variable instead:
        #   upsun variable:create --level environment --prefix env: --name N8N_ENCRYPTION_KEY --value '<LONG_RANDOM_ENCRYPTION_KEY>' --sensitive true --visible-runtime true --visible-build false

        # Upsun Cloud starts the wrapped image from /app. Set the n8n user folder to
        # the persistent mount instead of allowing it to default to /app/.n8n.
        N8N_USER_FOLDER: "/home/node"
        N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS: "true"

        # n8n serves HTTP directly on TCP port 5678. Trust one proxy hop so n8n
        # uses the forwarding headers supplied by the Upsun Cloud router.
        N8N_LISTEN_ADDRESS: "0.0.0.0"
        N8N_PROXY_HOPS: "1"

        # Change these values to the timezone used by scheduled workflows.
        GENERIC_TIMEZONE: "Etc/UTC"
        TZ: "Etc/UTC"

        # Register tini as a child subreaper because the image entrypoint runs
        # inside Upsun Cloud's application wrapper rather than as PID 1.
        TINI_SUBREAPER: "true"

    web:
      upstream:
        # n8n serves HTTP directly on a TCP port; passthrough lets the Upsun Cloud
        # router forward requests without expecting a local Unix socket.
        socket_family: tcp
      locations:
        "/":
          passthru: true
          request_buffering:
            enabled: false

# This project does not need Upsun Cloud-managed services because this example uses
# n8n's persistent SQLite database.
services: null

routes:
  # Use a dedicated subdomain so the editor and webhooks share one public URL.
  "https://n8n.{default}/":
    type: upstream
    upstream: "n8n:http"
    cache:
      enabled: false
```

## 2. Set or update the n8n encryption key

Set `N8N_ENCRYPTION_KEY` as a sensitive runtime environment variable instead of committing it to `.upsun/config.yaml`.

1. Generate a long random value for the encryption key:

   ```bash theme={null}
   openssl rand -hex 32
   ```

2. Use the generated value in place of `<LONG_RANDOM_ENCRYPTION_KEY>`:

   ```bash theme={null}
   upsun variable:create --level environment --prefix env: --name N8N_ENCRYPTION_KEY --value '<LONG_RANDOM_ENCRYPTION_KEY>' --sensitive true --visible-runtime true --visible-build false
   ```

If the `N8N_ENCRYPTION_KEY` variable already exists, update it:

```bash theme={null}
upsun variable:update env:N8N_ENCRYPTION_KEY --level environment --value '<LONG_RANDOM_ENCRYPTION_KEY>' --sensitive true --visible-runtime true --visible-build false
```

Keep the key backed up securely. Changing it after n8n has stored credentials makes those credentials unreadable unless you migrate them using the previous key.

## 3. Deploy the app

Commit the changes to `.upsun/config.yaml` and push them to Upsun Cloud:

```bash theme={null}
git add .upsun/config.yaml
git commit -m "Add n8n Docker image app"
upsun push
```

## 4. Allocate n8n resources

The first deployment [defaults to a minimal resource allocation](/docs/manage-resources/resource-init) regardless of app type (0.5 CPU, 512 MB disk, and [1408 MB memory](/docs/manage-resources/adjust-resources#shared-cpu-container-sizes)). That's enough to boot n8n and run small workflows, but workflow concurrency, execution history, and binary data can require more resources. Set a baseline for the app:

```bash theme={null}
upsun resources:set --size n8n:1 --disk n8n:2048
```

With `container_profile: HIGH_MEMORY`, the n8n app gets 1 CPU, about 2 GB RAM, 2 GB disk, and one instance. Increase CPU and memory for concurrent or memory-intensive workflows, and [increase the disk size](/docs/manage-resources/adjust-resources#vertical-scaling) as execution history and binary data grow.

If you changed resources after the app was already deployed, redeploy the environment:

```bash theme={null}
upsun environment:redeploy
```

## 5. Set the public URLs

List the routes and copy the HTTPS hostname mapped to the `n8n` app:

```bash theme={null}
upsun route:list
```

Replace `<N8N_HOSTNAME>` with that hostname, without a path:

```bash theme={null}
upsun variable:create --level environment --prefix env: --name N8N_WEBHOOK_URL --value 'https://<N8N_HOSTNAME>/' --visible-runtime true --visible-build false

upsun variable:create --level environment --prefix env: --name N8N_EDITOR_BASE_URL --value 'https://<N8N_HOSTNAME>/' --visible-runtime true --visible-build false
```

If either variable already exists, update it:

```bash theme={null}
upsun variable:update env:N8N_WEBHOOK_URL --level environment --value 'https://<N8N_HOSTNAME>/' --visible-runtime true --visible-build false

upsun variable:update env:N8N_EDITOR_BASE_URL --level environment --value 'https://<N8N_HOSTNAME>/' --visible-runtime true --visible-build false
```

These variables make webhook URLs and editor links use the public HTTPS route.

<Note>
  Preview environment URLs are ephemeral by default, so `<N8N_HOSTNAME>` changes with every new preview environment. If external services need a stable webhook URL, [set up a custom domain](/docs/domains/steps/custom-domains-preview-environments) for the environment.
</Note>

## 6. Validate the deployment

List the routes and confirm that the HTTPS route mapped to the `n8n` app appears. You'll use its hostname in place of `<N8N_HOSTNAME>` in the next step.

```bash theme={null}
upsun route:list
```

Check the health endpoint. Replace `<N8N_HOSTNAME>` with the hostname for the n8n app:

```bash theme={null}
curl https://<N8N_HOSTNAME>/healthz
```

Expected response:

```json theme={null}
{"status":"ok"}
```

Open `https://<N8N_HOSTNAME>/` to create the n8n owner account.

If the health check doesn't return this, or you run into other issues deploying the app, [debug the app over SSH](/docs/add-services/docker-images#debug-an-app-over-ssh) to check `/var/log/app.log` and the container's process state.

## Updating the image version

To use a different n8n version, update the version in `image.name`:

```yaml theme={null}
applications:
  n8n:
    type: docker:1
    image:
      name: "ghcr.io/n8n-io/n8n:<VERSION>"
```

Then, commit and push the change:

```bash theme={null}
git add .upsun/config.yaml
git commit -m "Update n8n image version"
upsun push
```

## Limitations

* This configuration uses SQLite and one n8n instance, so it can't handle high workflow volume and provides no redundancy during restarts, deployments, or instance failures.

  Don't fix this by [increasing instance count](/docs/manage-resources/adjust-resources#horizontal-scaling) alone: [`storage` mounts are shared between instances of the same app](/docs/configure-apps/image-properties/mounts), so multiple instances would write to the same SQLite file concurrently — something SQLite can't handle safely.

  To scale horizontally and gain high availability, switch to queue mode: [PostgreSQL](/docs/add-services/postgresql) for shared state, [Valkey](/docs/add-services/valkey) (Upsun Cloud's Redis-compatible service) for the job queue, and separate worker instances. Until then, schedule redeploys during low-traffic windows and design workflows to tolerate an interrupted execution being retried.

## Operational considerations

* Backups: [Production environments back up automatically](/docs/environments/backup) with only 2 days of retention by default, and non-production environments aren't backed up at all. Since this configuration has no external database, that backup is the only copy of your workflows, credentials, and execution history — consider a longer retention policy and n8n's own execution-data pruning settings to limit how much there is to back up.
* Monitoring/alerts: Upsun Cloud has no built-in alerting. Forward n8n's logs to an external tool via [log forwarding](/docs/observability/logs/forward-logs), or use [Upsun Blackfire](/docs/observability/application-metrics/blackfire) for performance profiling, then alert from whatever tool receives that data.
* SMTP: n8n needs an SMTP provider for workflow notification emails. You can optionally use Upsun Cloud's [built-in SMTP proxy](/docs/development/email) instead of a third-party provider — preview environments are limited to 12,000 email credits per calendar month.

## Related

* n8n is commonly used to orchestrate AI agent workflows. If those workflows need to manage Upsun infrastructure itself (for example, triggering deploys or querying environment status from an agent), see the [Upsun MCP Server](/docs/get-started/ai/using-the-mcp).


# Self-hosted services from public Docker images
Source: https://developer.upsun.com/docs/add-services/docker-images/index

Run self-hosted services by using Docker images from public registries.

Deploy a self-hosted service straight from its public Docker image, without writing a Dockerfile or maintaining a build process yourself. Use this approach when the service you need already ships an official, production-ready image.

Unlike Upsun Cloud's other app types, which build your repository code into a runtime image, a Docker image app skips that build step: you provide an already-built image, and Upsun Cloud deploys it exactly as-is.

If you already configure environment variables, mounts, or service relationships for other apps in your project, you can do the same for a Docker image app, with the adjustments noted in [Mounts](#mounts) and [Environment variables](#environment-variables).

## Verified examples

The following services are verified to run on Upsun Cloud using the ready-to-use configuration provided in the corresponding topic.

* [Meilisearch](/docs/add-services/docker-images/docker-meilisearch)
* [n8n](/docs/add-services/docker-images/docker-n8n)

## Before you begin

1. [Install the Upsun Cloud CLI](/cli/install).
2. Run the following commands to log in and connect the current Git repository to the correct Upsun Cloud project. Replace `<PROJECT_ID>` with your project ID (run `upsun projects` to list them).

   ```bash theme={null}
   upsun login
   upsun auth:info
   upsun set-remote <PROJECT_ID>
   upsun project:info
   upsun environment:info
   ```

## Configure an app

Define each Docker image as an application in `.upsun/config.yaml`. At minimum:

* Set `type` to `docker:1`.
* Set `image.name` to the image tag to run. Images without a registry hostname are pulled from [Docker Hub](https://hub.docker.com/search?badges=official). For images from other registries, include the full registry hostname in `image.name`.

Add a custom start command, persistent storage, or environment variables to the same app definition as needed — see [Startup commands](#startup-commands), [Mounts](#mounts), and [Environment variables](#environment-variables).

```yaml theme={null}
# Minimal configuration. Add a custom start command, mounts, or
# environment variables to this app definition as needed.
applications:
  myapp:
    type: docker:1
    image:
      name: "<registry-or-namespace>/<image>:<tag>"

    web:
      upstream:
        socket_family: tcp
      locations:
        "/":
          passthru: true

routes:
  "https://myapp.{default}/":
    type: upstream
    upstream: "myapp:http"
```

## Deploy an app

Commit the changes to `.upsun/config.yaml` and push them to Upsun Cloud:

```bash theme={null}
git add .upsun/config.yaml
git commit -m "Add Docker image app"
upsun push
```

List routes after deployment:

```bash theme={null}
upsun route:list
```

## Startup commands

By default, Upsun Cloud runs the startup command defined by the image. `$PORT` typically matches the port exposed by the image.

Set `web.commands.start` in `.upsun/config.yaml` only when the image's default command is not suitable. If you set `web.commands.start`:

* `$PORT` changes to a platform-assigned value. Make sure the command indicates to listen on `$PORT`; otherwise, the app may listen on the wrong port and return `502 Bad Gateway` errors.
* Environment variables in `web.commands.start` are passed literally unless the command runs through a shell. If the image includes `sh`, use `sh -c "..."` when you need environment variable expansion.

```yaml theme={null}
applications:
  myapp:
    type: docker:1
    image:
      name: "example/myapp:1.0.0"
    web:
      commands:
        start: 'sh -c "./myapp --listen=:$PORT --db-host=$DATABASE_HOST"'
```

## Mounts

Any path configured under `mounts` must already exist as a directory in the image. Upsun Cloud does not create missing directories inside the image at runtime.

```yaml theme={null}
applications:
  myapp:
    type: docker:1
    image:
      name: "example/myapp:1.0.0"
    mounts:
      "/data":
        source: storage
        source_path: data
```

## Environment variables

Variables under `variables.env` are exposed to the running container.

```yaml theme={null}
applications:
  myapp:
    type: docker:1
    image:
      name: "example/myapp:1.0.0"
    variables:
      env:
        APP_ENV: "production"
```

If the app connects to Upsun Cloud services, use direct service variables such as `DATABASE_HOST`, `DATABASE_PORT`, `DATABASE_USERNAME`, and `DATABASE_PASSWORD`.

Avoid relying on `PLATFORM_RELATIONSHIPS` inside minimal Docker images. It requires base64 and JSON parsing tools that may not exist in the image. Use direct service variables instead.

## Updating the image version

Change the image tag in `image.name`, then commit and push the change.

* For fixed version tags, this is enough — the tag change triggers a rebuild automatically.
* For `latest` tags, the tag itself doesn't change, so a plain redeploy reuses the last build and won't pull a newer image. [Force a rebuild](/docs/troubleshooting/general#manually-trigger-builds) instead — either push any code change, or create or update a build-time environment variable via the CLI or Console — so Upsun Cloud pulls the current image for that tag.

## Debug an app over SSH

If a container fails to start, a health check fails, or the image has no shell of its own, connect over SSH to debug it:

```bash theme={null}
upsun ssh --app myapp
```

This connects to the LXC container, the layer Upsun Cloud controls around the image, not the image's own container (consistent with other Upsun Cloud app images). From the LXC container, you can:

* View logs, such as `/var/log/app.log`, to debug start command failures.

* Inspect the environment around the image's container, for example mounts, networking, and process state, without needing a shell inside the image. The process list shows whether the app's start command is running, still starting, or crash-looping, which is the main signal available when the health check fails and the image has no shell to exec into:

  ```bash theme={null}
  pwd
  env
  ps -ef
  ls -la /
  ```

* Enter the image's own container, if it includes a shell. Upsun Cloud cannot inject a shell into an image it does not control.

The Docker CLI is not available inside the shell. Use standard shell commands to inspect the running app.

## Limitations

* Docker image apps use pre-built images. Upsun Cloud does not build a Dockerfile from the repository for this app type.
* Build hooks are not supported for Docker image apps.
* Meilisearch and n8n are the only images currently verified to work on Upsun Cloud. Other public images may work but have not been tested.
* You are responsible for updating images when image publishers release security fixes.
* Docker images include their own filesystem and can use more project storage than Upsun Cloud's built-in runtime images.
* Keep images under 4 GB. Larger images require different storage handling. To use an image larger than 4 GB, create a support ticket and provide the full image name and registry path.

  To keep image size down:

  * Use a minimal base image such as `alpine`, `distroless`, or `busybox`.
  * Avoid bundling build tools or caches into your production image.
  * Use multi-stage builds to separate build and runtime layers.

  Minimal images such as `distroless` and `busybox` may not include shell tools such as `sh`, `base64`, or `jq`. This affects startup command expansion and any logic that depends on decoding `PLATFORM_RELATIONSHIPS`.


# Elasticsearch and Enterprise Search (search service)
Source: https://developer.upsun.com/docs/add-services/elasticsearch

Add Elastic Enterprise Search to your Upsun Cloud project as a Premium service. Legacy Elasticsearch versions (up to 7.10) remain available but are at end of life.


Upsun Cloud offers two Elasticsearch-based search services:

* **[Elastic Enterprise Search](#elastic-enterprise-search-current)**: current Premium service, recommended for all new projects.
* **[Elasticsearch (end of life)](#elasticsearch-end-of-life)**: versions up to 7.10, no longer maintained.

## Elastic Enterprise Search (current)

Elastic Enterprise Search is available as a Premium service. It replaces the legacy Elasticsearch service, which is no longer receiving security
updates. For full feature documentation, see the [Elastic Enterprise Search docs](https://www.elastic.co/guide/en/enterprise-search/current/index.html).

To add this service, [contact Sales](https://upsun.com/contact-us/).

### Enterprise Search supported versions

You can select the major and minor version.

Patch versions are applied periodically for bug fixes and other maintenance updates. By default, you get the latest available patches each time you deploy. If your project has a [maintenance window](/docs/core-concepts/build-deploy#maintenance-window) configured, Upsun Cloud applies patches only during that window. Upsun Cloud may still apply urgent or critical fixes outside of the maintenance window.

* <span>9.3</span>
* <span>8.19</span>

### Enterprise Search deprecated versions

*No deprecated versions.*

### Enterprise Search retired versions

The following versions have been retired and are no longer available.
If your project uses a retired version, you must update to a [supported version](#enterprise-search-supported-versions) of Elastic
Enterprise search, available as a premium service.

* <span>7.17</span>

## Elasticsearch (end of life)

<Info>
  <h4>Replaced by Elastic Enterprise Search</h4>
  Elasticsearch changed its license in version 7.11 and is no longer open source. Instead, Upsun Cloud offers
  [Elastic Enterprise Search](#elastic-enterprise-search-current) as a premium service. [Contact Sales](https://upsun.com/contact-us/) to
  add it to your project.
</Info>

Versions up to 7.10 remain available but receive no further security updates from upstream. For full reference documentation, see the [Elasticsearch docs](https://www.elastic.co/guide/en/elasticsearch/reference/current/index.html). If you don't need the Enterprise Search feature set, [OpenSearch](/docs/add-services/opensearch) is a free, actively maintained alternative. To switch, follow the same procedure as for [upgrading](#upgrading).

### Elasticsearch supported versions

You can select the major and minor version.

Patch versions are applied periodically for bug fixes and other maintenance updates. By default, you get the latest available patches each time you deploy. If your project has a [maintenance window](/docs/core-concepts/build-deploy#maintenance-window) configured, Upsun Cloud applies patches only during that window. Upsun Cloud may still apply urgent or critical fixes outside of the maintenance window.

* <span>7.10</span>

### Elasticsearch deprecated versions

*No deprecated versions.*

### Elasticsearch retired versions

The following versions have been retired and are no longer available.
If your project uses a retired version, you must update to a [supported version](#elasticsearch-supported-versions) of Elasticsearch or a
[supported version of Enterprise Search](#elastic-enterprise-search-current), available as a premium service.

* <span>7.9</span>
* <span>7.7</span>
* <span>7.6</span>
* <span>7.5</span>
* <span>7.2</span>
* <span>6.8</span>
* <span>6.5</span>

## Usage example

### 1. Configure the service

To define the service, use the `elasticsearch` type:

For [Elastic Enterprise Search](/docs/add-services/elasticsearch#elastic-enterprise-search-current), use the `elasticsearch-enterprise` type and specify a supported version.

Changing the name of the service replaces it with a new service and all existing data is lost. Back up your data before changing the service.

### 2. Define the relationship

To define the relationship, use the following configuration:

<Tabs>
  <Tab title="Using default endpoints">
    You can define `SERVICE_NAME` as you like, so long as it's unique between all defined services
    and matches in both the application and services configuration.

    The example above uses [default endpoint](/docs/configure-apps/image-properties/relationships) configuration for
    relationships.
    That is, it uses default endpoints behind the scenes, providing a [relationship](/docs/configure-apps/image-properties/relationships)
    (the network address a service is accessible from) that is identical to the *name* of that service.

    Depending on your needs, instead of default endpoint configuration,
    you can use [explicit endpoint configuration](/docs/configure-apps/image-properties/relationships).

    With the above definition, the application container now has [access to the service](#use-in-app) through the relationship
    `SERVICE_NAME` and its corresponding [service environment variables](/docs/development/variables#service-environment-variables).
  </Tab>

  <Tab title="Using explicit endpoints">
    You can define `SERVICE_NAME` and `<RELATIONSHIP_NAME>` as you like, so long as it's unique between all defined
    services and relationships
    and matches in both the application and services configuration.

    The example above uses [explicit endpoint](/docs/configure-apps/image-properties/relationships) configuration for
    relationships.

    Depending on your needs, instead of explicit endpoint configuration,
    you can use [default endpoint configuration](/docs/configure-apps/image-properties/relationships).

    With the above definition, the application container now has [access to the service](#use-in-app) through the relationship
    `<RELATIONSHIP_NAME>` and its corresponding [service environment variables](/docs/development/variables#service-environment-variables).
  </Tab>
</Tabs>

### Example configuration

<Tabs>
  <Tab title="Using default endpoints">
    For [Elastic Enterprise Search](/docs/add-services/elasticsearch#elastic-enterprise-search-current), use the `elasticsearch-enterprise` type and specify a supported version.
  </Tab>

  <Tab title="Using explicit endpoints">
    For [Elastic Enterprise Search](/docs/add-services/elasticsearch#elastic-enterprise-search-current), use the `elasticsearch-enterprise` type and specify a supported version.
  </Tab>
</Tabs>

### Use in app

To use the configured service in your app, add a configuration file similar to the following to your project.

Configuration for [Elastic Enterprise Search](#elastic-enterprise-search-current) can differ. Specify `elasticsearch-enterprise` as the service type.

This configuration defines a single application (`myapp`).
`myapp` has access to the `elasticsearch` service through the corresponding [service environment variables](/docs/development/variables#service-environment-variables)
(as per [default endpoint](/docs/configure-apps/image-properties/relationships) configuration for relationships).

From this, `myapp` can retrieve access credentials to the service through the [relationship environment variable](/docs/add-services/elasticsearch#relationship-reference).

```bash myapp/.environment theme={null}
# Set environment variables for individual credentials.
# See: /docs/development/variables#service-environment-variables
export ELASTIC_SCHEME="${ELASTICSEARCH_SCHEME}"
export ELASTIC_HOST="${ELASTICSEARCH_HOST}"
export ELASTIC_PORT="${ELASTICSEARCH_PORT}"

# Surface more common Elasticsearch connection string variables for use in app.
export ELASTIC_USERNAME="${ELASTICSEARCH_USERNAME}"
export ELASTIC_PASSWORD="${ELASTICSEARCH_PASSWORD}"
export ELASTIC_HOSTS=["$ELASTIC_SCHEME://$ELASTIC_HOST:$ELASTIC_PORT"]
```

The `.environment` file in the `myapp` directory is automatically sourced by Upsun Cloud into the runtime environment, making `ELASTIC_HOSTS` available to connect to the service.

`ELASTIC_HOSTS`, and all [Upsun Cloud service environment variables](/docs/development/variables#service-environment-variables) like `ELASTICSEARCH_HOST`,
are environment-dependent.
Unlike the build produced for a given commit,
they can’t be reused across environments and only allow your app to connect to a single service instance on a single environment.

A file similar to this is generated automatically for you when using the `upsun ify` command to [migrate a codebase to Upsun Cloud](/docs/get-started).

<Note>
  When you create an index on Elasticsearch,
  don't specify the `number_of_shards` or `number_of_replicas` settings in your Elasticsearch API call.
  These values are set automatically based on available resources.
</Note>

## Relationship reference

For each service [defined through a relationship](#usage-example) to your application,
Upsun Cloud automatically generates corresponding environment variables within your application container,
in the `$<RELATIONSHIP-NAME>_<SERVICE-PROPERTY>` format.

Here is example information available through the [service environment variables](/docs/development/variables#service-environment-variables) themselves,
or through the [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables).

<Tabs>
  <Tab title="Service environment variables">
    You can obtain the complete list of available service environment variables in your app container by running `upsun ssh env`.

    The information about the relationship can change when an app is redeployed or restarted or the relationship is changed. Your apps should only rely on the [service environment variables](/docs/development/variables#service-environment-variables) directly rather than hard-coding any values.
  </Tab>

  <Tab title="`PLATFORM_RELATIONSHIPS` environment variable">
    For some advanced use cases, you can use the [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables).
    The structure of the `PLATFORM_RELATIONSHIPS` environment variable can be obtained by running `upsun relationships` in your terminal:

    Here is an example of how to gather [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables) information in a [`.environment` file](/docs/development/variables/set-variables#when-to-use-env-files):

    ```bash .environment theme={null}
    # Decode the built-in credentials object variable.
    export RELATIONSHIPS_JSON="$(echo "$PLATFORM_RELATIONSHIPS" | base64 --decode)"

    # Set environment variables for individual credentials.
    export APP_ELASTICSEARCH_HOST=="$(echo "$RELATIONSHIPS_JSON" | jq -r '.elasticsearch[0].host')"
    ```
  </Tab>
</Tabs>

For [Elastic Enterprise Search](#elastic-enterprise-search-current), use `elasticsearch-enterprise` as the service type.

## Authentication

This section applies to the [Elasticsearch (end of life)](#elasticsearch-end-of-life) service only.

By default, Elasticsearch (end of life) has no authentication.
No username or password is required to connect to it.

Starting with Elasticsearch 7.2, you can optionally enable HTTP Basic authentication.
To do so, include the following in your `.upsun/config.yaml` configuration:

For [Elastic Enterprise Search](#elastic-enterprise-search-current), use the `elasticsearch-enterprise` type and specify a supported version.

That enables mandatory HTTP Basic auth on all requests.
The credentials are available in any relationships that point at that service,
in the `username` and `password` properties.

You can obtain the complete list of available service environment variables in your app container by running `upsun ssh env`.

Note that the information about the relationship can change when an app is redeployed or restarted or the relationship is changed. So your apps should only rely on the [service environment variables](/docs/development/variables#service-environment-variables) directly rather than hard coding any values.

This functionality is generally not required if Elasticsearch isn't exposed on its own public HTTP route.
However, certain applications may require it, or it lets you safely expose Elasticsearch directly to the web.
To do so, add a route to `.upsun/config.yaml` that has `elasticsearch:elasticsearch` as its upstream
(where `elasticsearch` is whatever you named the service).

For example:

## Plugins

Elasticsearch offers a number of plugins.
To enable them, list them under the `configuration.plugins` key in your `.upsun/config.yaml` file:

For [Elastic Enterprise Search](#elastic-enterprise-search-current), use the `elasticsearch-enterprise` type and specify a supported version.

In this example, the `analysis-icu` plugin is enabled.

If there is a publicly available plugin you need that isn't listed here, [contact support](/docs/core-concepts/get-support).

### Available plugins

This is the complete list of official Elasticsearch plugins that can be enabled:

| Plugin | Description | 2.4 | 5.x | 6.x | 7.x | 8.x |
| - | - | - | - | - | - | - |
| `analysis-icu` | Support ICU Unicode text analysis | \* | \* | \* | \* | \* |
| `analysis-nori` | Integrates Lucene Nori analysis module into Elasticsearch | | | \* | \* | \* |
| `analysis-kuromoji` | Japanese language support | \* | \* | \* | \* | \* |
| `analysis-smartcn` | Smart Chinese Analysis Plugins | \* | \* | \* | \* | \* |
| `analysis-stempel` | Stempel Polish Analysis Plugin | \* | \* | \* | \* | \* |
| `analysis-phonetic` | Phonetic analysis | \* | \* | \* | \* | \* |
| `analysis-ukrainian` | Ukrainian language support | | \* | \* | \* | \* |
| `cloud-aws` | AWS Cloud plugin, allows storing indices on AWS S3 | \* | | | | |
| `delete-by-query` | Support for deleting documents matching a given query | \* | | | | |
| `discovery-multicast` | Ability to form a cluster using TCP/IP multicast messages | \* | | | | |
| `ingest-attachment` | Extract file attachments in common formats (such as PPT, XLS, and PDF) | | \* | \* | \* | \* |
| `ingest-user-agent` | Extracts details from the user agent string a browser sends with its web requests | | \* | \* | | |
| `lang-javascript` | JavaScript language plugin, allows the use of JavaScript in Elasticsearch scripts | | \* | | | |
| `lang-python` | Python language plugin, allows the use of Python in Elasticsearch scripts | \* | \* | | | |
| `mapper-annotated-text` | Adds support for text fields with markup used to inject annotation tokens into the index | | | \* | \* | \* |
| `mapper-attachments` | Mapper attachments plugin for indexing common file types | \* | \* | | | |
| `mapper-murmur3` | Murmur3 mapper plugin for computing hashes at index-time | \* | \* | \* | \* | \* |
| `mapper-size` | Size mapper plugin, enables the `_size` meta field | \* | \* | \* | \* | \* |
| `transport-nio` | Support for NIO transport | | | | \* | \* |

### Plugin removal

Removing plugins previously added in your `.upsun/config.yaml` file doesn't automatically uninstall them from your Elasticsearch instances.
This is deliberate, as removing a plugin can result in data loss or corruption of existing data that relied on that plugin.
Removing a plugin usually requires reindexing.

To permanently remove a previously enabled plugin,
[upgrade the service](#upgrading) to create a new instance of Elasticsearch and migrate to it.
In most cases this isn't necessary, as an unused plugin has no appreciable impact on the server.

## Upgrading

The Elasticsearch data format sometimes changes between versions in incompatible ways.
Elasticsearch doesn't include a data upgrade mechanism as it's expected that all indexes can be regenerated from stable data if needed.
To upgrade (or downgrade) Elasticsearch, use a new service from scratch.

There are two approaches.

### Destructive upgrade

In your `.upsun/config.yaml` file, change the version *and* name of your Elasticsearch service.
Also update the reference to the renamed service in the application's `relationship` block.

When you push the change to Upsun Cloud, the old service is deleted and a new one with the new name is created with no data.
You can then have your application reindex data as appropriate.

This approach has the downsides of temporarily having an empty Elasticsearch instance,
which your application might or might not handle gracefully, and needing to rebuild your index afterward.
Depending on the size of your data that could take a while.

### Transitional upgrade

With a transitional approach, you temporarily have two Elasticsearch services.
Add a second Elasticsearch service with the new version, a new name, and give it a new relationship in `.upsun/config.yaml`.
You can optionally run in that configuration for a while to allow your application to populate indexes in the new service as well.

Once you're ready to switch over, remove the old Elasticsearch service and relationship.
You can optionally give the new Elasticsearch service the old relationship name if that's easier for your app to handle.
Your application is now using the new Elasticsearch service.

This approach has the benefit of never being without a working Elasticsearch instance.
On the downside, it requires two running Elasticsearch servers temporarily,
each of which consumes resources and needs adequate disk space.
Depending on the size of your data, this can require significant space.

## Exporting data

Elasticsearch data is stored in on-disk indexes. The recommended way to export it is
using the [Snapshot and Restore API](https://www.elastic.co/guide/en/elasticsearch/reference/current/snapshot-restore.html)
over an SSH tunnel.

1. Open an SSH tunnel to your Elasticsearch service:

```bash Terminal theme={null}
upsun tunnel:single --relationship <RELATIONSHIP_NAME>
```

2. Register a snapshot repository (a local filesystem path accessible inside the service):

```bash Terminal theme={null}
curl -X PUT "http://127.0.0.1:9200/_snapshot/my_backup" \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "fs",
    "settings": {
      "location": "/tmp/es-snapshots"
    }
  }'
```

3. Trigger a snapshot:

```bash Terminal theme={null}
curl -X PUT "http://127.0.0.1:9200/_snapshot/my_backup/snapshot_1?wait_for_completion=true"
```

4. Retrieve the snapshot files from the service container using the CLI:

```bash Terminal theme={null}
upsun ssh -- tar -czf /tmp/es-snapshot.tar.gz /tmp/es-snapshots
upsun scp remote:/tmp/es-snapshot.tar.gz ./es-snapshot.tar.gz
```

Alternatively, you can re-index all your data from the primary data source
(for example your application database) instead of using snapshots.

If authentication is enabled on your Elasticsearch service, add the `-u user:password` flag to the `curl` commands.


# Gotenberg
Source: https://developer.upsun.com/docs/add-services/gotenberg

Gotenberg is a user-friendly API for PDF files.

Gotenberg is a stateless API for converting various document formats into PDF files.
For more information, see the [Gotenberg documentation](https://gotenberg.dev/docs/getting-started/introduction).

## Supported versions

* <span>8</span>

You can select the major version. But the latest compatible minor version is applied automatically and can’t be overridden.

Patch versions are applied periodically for bug fixes and other maintenance updates. By default, you get the latest available patches each time you deploy. If your project has a [maintenance window](/docs/core-concepts/build-deploy#maintenance-window) configured, Upsun Cloud applies patches only during that window. Upsun Cloud may still apply urgent or critical fixes outside of the maintenance window.

## Deprecated versions

The following versions are still available in your projects,
but they're at their end of life and are no longer receiving security updates from upstream.

*No deprecated versions.*

To ensure your project remains stable in the future,
switch to a [supported version](#supported-versions).

## Retired versions

The following versions have been retired and are no longer available.
If your project uses a retired version, you must update to a [supported version](#supported-versions).

*No retired versions.*

## Relationship reference

For each service [defined via a relationship](#usage-example) to your application,
Upsun Cloud automatically generates corresponding environment variables within your application container,
in the `$<RELATIONSHIP-NAME>_<SERVICE-PROPERTY>` format.

Here is example information available through the [service environment variables](/docs/development/variables#service-environment-variables) themselves,
or through the [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables).

<Tabs>
  <Tab title="Service environment variables">
    You can obtain the complete list of available service environment variables in your app container by running `upsun ssh env`.

    Note that the information about the relationship can change when an app is redeployed or restarted or the relationship is changed. So your apps should only rely on the [service environment variables](/docs/development/variables#service-environment-variables) directly rather than hard coding any values.

    ```bash theme={null}
    GOTENBERG_INSTANCE_IPS=["249.45.240.83"]
    GOTENBERG_SCHEME=http
    GOTENBERG_HOSTNAME=rssjaxyeoorjje6axcq35xu5gq.gotenberg.service._.eu-5.platformsh.site >}}
    GOTENBERG_SERVICE=gotenberg
    GOTENBERG_CLUSTER=p2f2xrzyq7a6k-main-bvxea6i
    GOTENBERG_IP=169.254.137.3
    GOTENBERG_TYPE=gotenberg:8
    GOTENBERG_HOST=gotenberg.internal
    GOTENBERG_PORT=3000
    GOTENBERG_REL=http
    ```
  </Tab>

  <Tab title="`PLATFORM_RELATIONSHIPS` environment variable">
    For some advanced use cases, you can use the [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables).
    The structure of the `PLATFORM_RELATIONSHIPS` environment variable can be obtained by running `upsun relationships` in your terminal:

    Here is an example of how to gather [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables) information
    in a [`.environment` file](/docs/development/variables/set-variables#when-to-use-env-files):

    ```bash .environment theme={null}
    # Decode the built-in credentials object variable.
    export RELATIONSHIPS_JSON="$(echo "$PLATFORM_RELATIONSHIPS" | base64 --decode)"

    # Set environment variables for individual credentials.
    export APP_GOTENBERG_HOST=="$(echo $RELATIONSHIPS_JSON | jq -r '.gotenberg[0].host')"
    ```
  </Tab>
</Tabs>

## Usage example

### 1. Configure the service

To define the service, use the `gotenberg` type:

Note that changing the name of the service replaces it with a brand new service and all existing data is lost. Back up your data before changing the service.

### 2. Define the relationship

To define the relationship, use the `http` endpoint:

<Tabs>
  <Tab title="Using default endpoints">
    You can define `SERVICE_NAME` as you like, so long as it’s unique between all defined services and matches in both the application and services configuration.
  </Tab>

  <Tab title="Using explicit endpoints">
    You can define `SERVICE_NAME` and `<RELATIONSHIP_NAME>` as you like, so long as it's unique between all defined services and relationships
    and matches in both the application and services configuration.
  </Tab>
</Tabs>

With the above definition, Upsun Cloud uses the `http` endpoint,
providing a [relationship](/docs/configure-apps/image-properties/relationships) (the network address a service is accessible from) that is identical to the *name* of that service.

The `http` endpoint uses port `3000` by default.

### Example configuration

<Tabs>
  <Tab title="Using default endpoints">
    ```yaml .upsun/config.yaml theme={null}
    applications:
      # The name of the app container. Must be unique within a project.
      myapp:
        # Relationships enable access from this app to a given service.
        # The example below shows simplified configuration leveraging a default service
        # (identified from the relationship name) and a default endpoint.
        # See the Application reference for all options for defining relationships and endpoints.
        relationships:
          gotenberg:
    services:
      # The name of the service container. Must be unique within a project.
      gotenberg:
        type: gotenberg:8
    ```
  </Tab>
</Tabs>

## Generate a PDF using Gotenberg

As an example, to generate a PDF file of the  website, run the following cURL command:

```bash Terminal theme={null}
curl \
--request POST http://yduimhaby523ase4lju3qhimre.gotenberg8.service._.eu-3.platformsh.site/forms/chromium/convert/url \
--form url=https://upsun.com \
--form landscape=true \
--form marginTop=1 \
--form marginBottom=1 \
-o my.pdf
```


# Headless Chrome
Source: https://developer.upsun.com/docs/add-services/headless-chrome

Headless Chrome is a headless browser that can be configured on projects like any other service on Upsun Cloud.


You can interact with the `chrome-headless` service container using Puppeteer, a Node.js library that provides an API to control Chrome over the DevTools Protocol.

Puppeteer can be used to generate PDFs and screenshots of web pages, automate form submission, and test your project's UI. You can find out more information about using Puppeteer on [GitHub](https://github.com/GoogleChrome/puppeteer) or in their [documentation](https://pptr.dev/).

## Supported versions

You can select the major version. But the latest compatible minor version is applied automatically and can’t be overridden.

Patch versions are applied periodically for bug fixes and other maintenance updates. By default, you get the latest available patches each time you deploy. If your project has a [maintenance window](/docs/core-concepts/build-deploy#maintenance-window) configured, Upsun Cloud applies patches only during that window. Upsun Cloud may still apply urgent or critical fixes outside of the maintenance window.

* <span>120</span>
* <span>113</span>

## Deprecated versions

The following versions are still available in your projects,
but they're at their end of life and are no longer receiving security updates from upstream.

*No deprecated versions.*

To ensure your project remains stable in the future,
switch to a [supported version](#supported-versions).

## Retired versions

The following versions have been retired and are no longer available.
If your project uses a retired version, you must update to a [supported version](#supported-versions).

* <span>95</span>
* <span>91</span>
* <span>86</span>
* <span>84</span>
* <span>83</span>
* <span>81</span>
* <span>80</span>
* <span>73</span>

## Relationship reference

For each service [defined via a relationship](#usage-example) to your application,
Upsun Cloud automatically generates corresponding environment variables within your application container,
in the `$<RELATIONSHIP-NAME>_<SERVICE-PROPERTY>` format.

Here is example information available through the [service environment variables](/docs/development/variables#service-environment-variables) themselves,
or through the [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables).

<Tabs>
  <Tab title="Service environment variables">
    You can obtain the complete list of available service environment variables in your app container by running `upsun ssh env`.

    Note that the information about the relationship can change when an app is redeployed or restarted or the relationship is changed. So your apps should only rely on the [service environment variables](/docs/development/variables#service-environment-variables) directly rather than hard coding any values.
  </Tab>

  <Tab title="`PLATFORM_RELATIONSHIPS` environment variable">
    For some advanced use cases, you can use the [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables).
    The structure of the `PLATFORM_RELATIONSHIPS` environment variable can be obtained by running `upsun relationships` in your terminal:

    Here is an example of how to gather [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables) information in a [`.environment` file](/docs/development/variables/set-variables#when-to-use-env-files):

    ```bash .environment theme={null}
    # Decode the built-in credentials object variable.
    export RELATIONSHIPS_JSON="$(echo "$PLATFORM_RELATIONSHIPS" | base64 --decode)"

    # Set environment variables for individual credentials.
    export APP_HEADLESSCHROME_HOST=="$(echo "$RELATIONSHIPS_JSON" | jq -r '.chrome-headless[0].host')"
    ```
  </Tab>
</Tabs>

## Requirements

Puppeteer requires at least Node.js version 6.4.0, while using the async and await examples below requires Node 7.6.0 or greater.

If your app container uses a language other than Node.js, upgrade the Node.js version before using Puppeteer.
See how to [manage your Node.js version](/docs/languages/nodejs/node-version).

## Usage example

### 1. Configure the service

To define the service, use the `chrome-headless` type:

Note that changing the name of the service replaces it with a brand new service and all existing data is lost. Back up your data before changing the service.

### 2. Define the relationship

To define the relationship, use the following configuration:

<Tabs>
  <Tab title="Using default endpoints">
    You can define `SERVICE_NAME` as you like, so long as it's unique between all defined services
    and matches in both the application and services configuration.

    The example above leverages [default endpoint](/docs/configure-apps/image-properties/relationships) configuration for relationships.
    That is, it uses default endpoints behind the scenes, providing a [relationship](/docs/configure-apps/image-properties/relationships)
    (the network address a service is accessible from) that is identical to the *name* of that service.

    Depending on your needs, instead of default endpoint configuration,
    you can use [explicit endpoint configuration](/docs/configure-apps/image-properties/relationships).

    With the above definition, the application container now has [access to the service](#use-in-app) via the relationship `SERVICE_NAME` and its corresponding [service environment variables](/docs/development/variables#service-environment-variables).
  </Tab>

  <Tab title="Using explicit endpoints">
    You can define `SERVICE_NAME` and `<RELATIONSHIP_NAME>` as you like, so long as it's unique between all defined services and relationships
    and matches in both the application and services configuration.

    The example above leverages [explicit endpoint](/docs/configure-apps/image-properties/relationships) configuration for relationships.

    Depending on your needs, instead of explicit endpoint configuration,
    you can use [default endpoint configuration](/docs/configure-apps/image-properties/relationships).

    With the above definition, the application container now has [access to the service](#use-in-app) via the relationship `<RELATIONSHIP_NAME>` and its corresponding [service environment variables](/docs/development/variables#service-environment-variables).
  </Tab>
</Tabs>

### Example configuration

### Use in app

After configuration, include [Puppeteer](https://www.npmjs.com/package/puppeteer) as a dependency:

<Tabs>
  <Tab title="npm">
    ```bash theme={null}
    npm install puppeteer
    ```
  </Tab>

  <Tab title="pnpm">
    ```bash theme={null}
    pnpm add puppeteer
    ```
  </Tab>

  <Tab title="Yarn">
    ```bash theme={null}
    yarn add puppeteer
    ```
  </Tab>
</Tabs>

Configuration for a project looks similar to the following:

This configuration defines a single application (`myapp`), whose source code exists in the `<PROJECT_ROOT>/myapp` directory.<br />
`myapp` has access to the `chrome-headless` service, via a relationship whose name is [identical to the service name](#2-define-the-relationship)
(as per [default endpoint](/docs/configure-apps/image-properties/relationships) configuration for relationships).

From this, `myapp` can retrieve access credentials to the service through the [relationship environment variable](/docs/add-services/elasticsearch#relationship-reference).

```bash myapp/.environment theme={null}
# Set environment variables for individual credentials,
# For more information, please visit /docs/development/variables#service-environment-variables.
export CHROME_IP="${CHROME_HEADLESS_IP}"
export CHROME_PORT="${CHROME_HEADLESS_PORT}"

# Combine into a single base URL to be used within app.
export CHROME_BASEURL="http://${CHROME_IP}:${CHROME_PORT}"
```

The above file — `.environment` in the `myapp` directory — is automatically sourced by Upsun Cloud into the runtime environment, so that the variable `CHROME_BASEURL` can be used within the application to connect to the service.

Note that `CHROME_BASEURL` and all Upsun Cloud [service environment variables](/docs/development/variables#service-environment-variables) like `CHROME_HEADLESS_HOST`, are environment-dependent. Unlike the build produced for a given commit, they can't be reused across environments and only allow your app to connect to a single service instance on a single environment.

A file very similar to this is generated automatically for your when using the `upsun ify` command to [migrate a codebase to Upsun Cloud](/docs/get-started).

Puppeteer allows your application to [create screenshots](https://pptr.dev/#?product=Puppeteer\&version=v13.0.1\&show=api-pagescreenshotoptions), [emulate a mobile device](https://pptr.dev/#?product=Puppeteer\&version=v13.0.1\&show=api-pageemulateoptions), [generate PDFs](https://pptr.dev/#?product=Puppeteer\&version=v13.0.1\&show=api-pagepdfoptions), and much more.


# Add services
Source: https://developer.upsun.com/docs/add-services/index

See how to add services such as databases, cache, and search engines and configure them to suit your needs.

Upsun Cloud includes many services, so you don't have to subscribe to external cache or search engine services.
Because the services are included in your project, you can manage them through Git
and they're backed up together with the rest of your project.

Your project defines the services configuration from a top-level key called `services`, which is placed in a unified configuration file like `.upsun/config.yaml`.

If you don't need any services (such as for a static website), you don't need to include this configuration. Read on to see how to add services.

## Add a service

Adding a service is a two-step process.

### 1. Configure the service

All service configuration happens in the `.upsun/config.yaml` file in your Git repository.

Configure your service in the following pattern:

An example service configuration for two databases might look like this:

This YAML file contains a dictionary defining all of the services you want to use.
The top-level key `services` defines an object of all of the services to be provisioned for the project.
Below that, come custom service names (`<SERVICE_NAME>`; in the example, `mariadb` and `postgresql`), which you use to identify the service in step 2.

You can give it any name you want with lowercase alphanumeric characters, hyphens, and underscores.

<Note>
  Changing the service name is interpreted as creating an entirely new service.
  This **removes all data in that service**.
  Always back up your data before changing existing services in your `.upsun/config.yaml` file.
</Note>

#### Service options

The following table presents the keys you can define for each service:

| Name | Type | Required | Description |
| - | - | - | - |
| `type` | `string` | Yes | One of the [available services](#available-services) in the format `type:version`. |
| `configuration` | dictionary | For some services | Some services have additional specific configuration options that can be defined here, such as specific endpoints. See the given service page for more details. |
| `relationships` | dictionary | For some services | Some services require a relationship to your app. The content of the dictionary has the same type as the `relationships` dictionary for [app configuration](/docs/configure-apps/image-properties/relationships). The `endpoint_name` for apps is always `http`. |

#### Resources (CPU, RAM, disk)

Upsun Cloud allows you to configure resources (CPU, RAM, and disk) per environment for each of your services.
For more information, see how to [manage resources](/docs/manage-resources).

You configure the disk size in [MB](/docs/glossary#mb).
Your actual available disk space is slightly smaller with some space used for formatting and the filesystem journal.
When checking available space, note whether it's reported in MB or MiB.

You can decrease the size of an existing disk for a service.
If you do so, be aware that:

* You need to [create new backups](/docs/environments/backup) that the downsized disk can accommodate.
  Backups from before the downsize cannot be restored unless you increase the disk size again.
* The downsize fails if there's more data on the disk than the desired size.

### 2. Define the relationship

To define the relationship, use the following configuration:

<Tabs>
  <Tab title="Using default endpoints">
    You can define `SERVICE_NAME` as you like, so long as it's unique between all defined services
    and matches in both the application and services configuration.

    The example above leverages [default endpoint](/docs/configure-apps/image-properties/relationships) configuration for relationships.
    That is, it uses default endpoints behind the scenes, providing a [relationship](/docs/configure-apps/image-properties/relationships)
    (the network address a service is accessible from) that is identical to the *name* of that service.

    Depending on your needs, instead of default endpoint configuration,
    you can use [explicit endpoint configuration](/docs/configure-apps/image-properties/relationships).
  </Tab>

  <Tab title="Using explicit endpoints">
    * `<RELATIONSHIP_NAME>` is the name you want to give to the relationship.
    * `SERVICE_NAME` is the name of the service as defined in the `services` section.
    * `<ENDPOINT_NAME>` is the endpoint your app will use to connect to the service (refer to the service reference to know which value to use).
  </Tab>
</Tabs>

An example relationship to connect to the databases given in the [example in step 1](#1-configure-the-service):

<Tabs>
  <Tab title="Using explicit endpoints">
    As with the service name, you can give the relationship any name you want
    with lowercase alphanumeric characters, hyphens, and underscores.
    It helps if the service name and relationship name are different, but it isn't required.
  </Tab>
</Tabs>

Each service offers one or more endpoints for connections, depending on the service.
An endpoint is a named set of credentials to give access to other apps and services in your project.
If you don't specify one in the [service configuration](#service-options), a default endpoint is created.
The default endpoint varies by service, generally being its type (such as `mysql` or `solr`).

## Available services

The following table presents the available service types and their versions.
Add them to the `type` key of the [service configuration](#1-configure-the-service) in the format `type:version`.

| Name | Type | Latest Version |
| - | - | - |
| [ClickHouse](/docs/add-services/clickhouse) | `clickhouse` | <span>26.8</span> |
| [Elasticsearch](/docs/add-services/elasticsearch) | `elasticsearch` | <span>7.10</span> |
| [elasticsearch-enterprise](/docs/add-services/elasticsearch) | `elasticsearch-enterprise` | <span>9.3</span> |
| [Gotenberg](/docs/add-services/gotenberg) | `gotenberg` | <span>8</span> |
| [Headless Chrome](/docs/add-services/headless-chrome) | `chrome-headless` | <span>120</span> |
| [InfluxDB](/docs/add-services/influxdb) | `influxdb` | <span>3</span> |
| [Kafka](/docs/add-services/kafka) | `kafka` | <span>4.3</span> |
| [MariaDB/MySQL](/docs/add-services/mysql) | `mariadb` | <span>12.3</span> |
| [MariaDB/MySQL](/docs/add-services/mysql) | `mysql` | <span>12.3</span> |
| [Memcached](/docs/add-services/memcached) | `memcached` | <span>1.6</span> |
| [mercure](/docs/add-services/mercure) | `mercure` | <span>0</span> |
| [mongodb](/docs/add-services/mongodb) | `mongodb` | <span>4.0</span> |
| [MongoDB](/docs/add-services/mongodb) | `mongodb-enterprise` | <span>7.0</span> |
| [Network Storage](/docs/add-services/network-storage) | `network-storage` | <span>2.0</span> |
| [OpenSearch](/docs/add-services/opensearch) | `opensearch` | <span>3</span> |
| [Oracle MySQL](/docs/add-services/mysql) | `oracle-mysql` | <span>8.4</span> |
| [PostgreSQL](/docs/add-services/postgresql) | `postgresql` | <span>18</span> |
| [RabbitMQ](/docs/add-services/rabbitmq) | `rabbitmq` | <span>4.3</span> |
| [Redis](/docs/add-services/redis) | `redis` | <span>8.8</span> |
| [Solr](/docs/add-services/solr) | `solr` | <span>10.0</span> |
| [Valkey](/docs/add-services/valkey) | `valkey` | <span>9.0</span> |
| [Varnish](/docs/add-services/varnish) | `varnish` | <span>9.0</span> |
| [Vault KMS](/docs/add-services/vault) | `vault-kms` | <span>1.12</span> |

### Service versions

These services generally follow [semantic versioning conventions](https://semver.org/).
You can select the major version, but the latest compatible minor is applied automatically and can’t be overridden.

Patch versions are applied periodically for bug fixes and other maintenance updates. By default, you get the latest available patches each time you deploy. If your project has a [maintenance window](/docs/core-concepts/build-deploy#maintenance-window) configured, Upsun Cloud applies patches only during that window. Upsun Cloud may still apply urgent or critical fixes outside of the maintenance window.

## Service timezones

All services have their system timezone set to UTC by default.
For some services, you can change the timezone for the running service
(this doesn't affect the container itself and so logs are still in UTC).

* [MySQL](/docs/add-services/mysql#service-timezone)
* [PostgreSQL](/docs/add-services/postgresql#service-timezone)

## Connect to a service

For security reasons, you can't access services directly through HTTP.
You can connect through your app or by opening an SSH tunnel to access the service directly.

<Tabs>
  <Tab title="In an app">
    Once a service is running and exposed via a relationship,
    its credentials (such as the host, username, and password) are automatically available as [service environment variables](/docs/development/variables#service-environment-variables),
    in the `$<RELATIONSHIP-NAME>_<SERVICE-PROPERTY>` format.
    The available information is documented on each service's page, along with sample code for how to connect to it from your app.

    The service environment variable names are fixed, but the values may change if you change the relationship name to the service.
    So **use the environment variable** rather than hard coding the values.
  </Tab>

  <Tab title="Through an SSH tunnel">
    Connecting to a service using an SSH tunnel is a two-step process.

    ### 1. Obtain service credentials

    To get the credentials for a given service, run the following command:

    ```bash theme={null}
    upsun relationships
    ```

    You get output like the following:

    With this example, you can connect to the `mariadb` relationship
    with the user `user`, an empty password, and the database name `main` (from the `path`).
    The `url` property shows a full database connection that can be used from your app.

    You can obtain the complete list of available service environment variables in your app container by running `upsun ssh env`.

    Note that the information about the relationship can change when an app is redeployed or restarted or the relationship is changed. So your apps should only rely on the [service environment variables](/docs/development/variables#service-environment-variables) directly rather than hard coding any values.

    ### 2. Open an SSH tunnel

    Open a single [SSH tunnel](/docs/development/ssh#connect-to-services) by running the following CLI command:

    ```bash theme={null}
    upsun tunnel:single --relationship <RELATIONSHIP_NAME>
    ```

    By default, this opens a tunnel at `127.0.0.1:30000`.
    You can specify the port for the connection using the `--port` flag.

    You can then connect to this service in a separate terminal or locally running app.
    With the example above, you connect to a URL like the following:
    `mysql://user:@127.0.0.1:30000/main`
  </Tab>
</Tabs>

## Upgrading services

Upsun Cloud provides a large number of [managed service versions](#available-services).
As new versions are made available, you will inevitably upgrade infrastructure to a more recent (or latest version).

When you do so, we would recommend:

1. **Use preview environments**. Leverage preview (non-production environments) to perform the upgrade, then merge the upgrade into production (promotion). This will give you an opportunity to test inherited production data in a safe, isolated environment first.
2. **Upgrade progressively**. For one reason or another, you may be more than a single version behind the upgrade you are trying to perform. To avoid data loss issues caused by large differences in versions, [upgrade one version at a time](https://www.rabbitmq.com/upgrade.html#rabbitmq-version-upgradability).


# InfluxDB (Database service)
Source: https://developer.upsun.com/docs/add-services/influxdb

InfluxDB is a time series database optimized for high-write-volume use cases such as logs, sensor data, and real-time analytics.


It exposes an HTTP API for client interaction. See the [InfluxDB documentation](https://docs.influxdata.com/influxdb) for more information.

## Supported versions

You can select the major and minor version.

Patch versions are applied periodically for bug fixes and other maintenance updates. By default, you get the latest available patches each time you deploy. If your project has a [maintenance window](/docs/core-concepts/build-deploy#maintenance-window) configured, Upsun Cloud applies patches only during that window. Upsun Cloud may still apply urgent or critical fixes outside of the maintenance window.

* <span>3</span>
* <span>2.7</span>
* <span>2.3</span>

## Deprecated versions

The following versions are still available in your projects,
but they're at their end of life and are no longer receiving security updates from upstream.

*No deprecated versions.*

To ensure your project remains stable in the future,
switch to a [supported version](#supported-versions).
See more information on [how to upgrade to version 2.3 or later](#upgrade-to-version-23-or-later).

## Retired versions

The following versions have been retired and are no longer available.
If your project uses a retired version, you must update to a [supported version](#supported-versions).

* <span>2.2</span>
* <span>2.0</span>
* <span>1.8</span>
* <span>1.7</span>
* <span>1.3</span>
* <span>1.2</span>

## Relationship reference

For each service [defined via a relationship](#usage-example) to your application,
Upsun Cloud automatically generates corresponding environment variables within your application container,
in the `$<RELATIONSHIP-NAME>_<SERVICE-PROPERTY>` format.

Here is example information available through the [service environment variables](/docs/development/variables#service-environment-variables) themselves,
or through the [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables).

<Tabs>
  <Tab title="Service environment variables">
    You can obtain the complete list of available service environment variables in your app container by running `upsun ssh env`.

    Note that the information about the relationship can change when an app is redeployed or restarted or the relationship is changed. So your apps should only rely on the [service environment variables](/docs/development/variables#service-environment-variables) directly rather than hard-coding any values.
  </Tab>

  <Tab title="`PLATFORM_RELATIONSHIPS` environment variable">
    For some advanced use cases, you can use the [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables).
    The structure of the `PLATFORM_RELATIONSHIPS` environment variable can be obtained by running `upsun relationships` in your terminal:

    Here is an example of how to gather [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables) information in a [`.environment` file](/docs/development/variables/set-variables#when-to-use-env-files):

    ```bash .environment theme={null}
    # Decode the built-in credentials object variable.
    export RELATIONSHIPS_JSON="$(echo "$PLATFORM_RELATIONSHIPS" | base64 --decode)"

    # Set environment variables for individual credentials.
    export APP_INFLUXDB_HOST="$(echo $RELATIONSHIPS_JSON | jq -r '.influxdb[0].host')"
    ```
  </Tab>
</Tabs>

## Usage example

### 1. Configure the service

To define the service, use the `influxdb` type:

Note that changing the name of the service replaces it with a brand new service and all existing data is lost. Back up your data before changing the service.

### 2. Define the relationship

To define the relationship, use the following configuration:

<Tabs>
  <Tab title="Using default endpoints">
    You can define `SERVICE_NAME` as you like, so long as it's unique between all defined services
    and matches in both the application and services configuration.

    The example above leverages [default endpoint](/docs/configure-apps/image-properties/relationships) configuration for relationships.
    That is, it uses default endpoints behind the scenes, providing a [relationship](/docs/configure-apps/image-properties/relationships)
    (the network address a service is accessible from) that is identical to the *name* of that service.

    Depending on your needs, instead of default endpoint configuration,
    you can use [explicit endpoint configuration](/docs/configure-apps/image-properties/relationships).

    With the above definition, the application container now has [access to the service](#use-in-app) via the relationship `SERVICE_NAME` and its corresponding [service environment variables](/docs/development/variables#service-environment-variables).
  </Tab>

  <Tab title="Using explicit endpoints">
    You can define `SERVICE_NAME` and `<RELATIONSHIP_NAME>` as you like, so long as it's unique between all defined services and relationships
    and matches in both the application and services configuration.

    The example above leverages [explicit endpoint](/docs/configure-apps/image-properties/relationships) configuration for relationships.

    Depending on your needs, instead of explicit endpoint configuration,
    you can use [default endpoint configuration](/docs/configure-apps/image-properties/relationships).

    With the above definition, the application container now has [access to the service](#use-in-app) via the relationship `<RELATIONSHIP_NAME>` and its corresponding [service environment variables](/docs/development/variables#service-environment-variables).
  </Tab>
</Tabs>

### Example configuration

### Use in app

To use the configured service in your app, add a configuration file similar to the following to your project.

This configuration defines a single application (`myapp`), whose source code exists in the `<PROJECT_ROOT>/myapp` directory.<br />
`myapp` has access to the `influxdb` service, via a relationship whose name is [identical to the service name](#2-define-the-relationship)
(as per [default endpoint](/docs/configure-apps/image-properties/relationships) configuration for relationships).

From this, `myapp` can retrieve access credentials to the service through the [relationship environment variables](#relationship-reference).

```bash myapp/.environment theme={null}
# Set environment variables for common InfluxDB credentials.
# For more information, please visit /docs/development/variables#service-environment-variables.
export INFLUX_USER="${INFLUXDB_USERNAME}"
export INFLUX_HOST="${INFLUXDB_HOST}"
export INFLUX_ORG="$(echo "$INFLUXDB_QUERY" | jq -r '.org')"
export INFLUX_TOKEN="$(echo "$INFLUXDB_QUERY" | jq -r '.api_token')"
export INFLUX_BUCKET="$(echo "$INFLUXDB_QUERY" | jq -r '.bucket')"
```

The above file — `.environment` in the `myapp` directory — is automatically sourced by Upsun Cloud into the runtime environment, so that the variable `INFLUX_HOST` can be used within the application to connect to the service.

Note that `INFLUX_HOST`, and all [Upsun Cloud-service environment variables](/docs/development/variables#service-environment-variables) like `INFLUXDBDATABASE_HOST`,
are environment-dependent.
Unlike the build produced for a given commit,
they can’t be reused across environments and only allow your app to connect to a single service instance on a single environment.

A file very similar to this is generated automatically for your when using the `upsun ify` command to [migrate a codebase to Upsun Cloud](/docs/get-started).

## Export data

To export your data from InfluxDB, follow these steps:

1. Install and set up the [`influx` CLI](https://docs.influxdata.com/influxdb/cloud/tools/influx-cli/).

2. Connect to your InfluxDB service with the [Upsun Cloud CLI](/cli):

   ```bash theme={null}
   upsun tunnel:single
   ```

   This opens an SSH tunnel to your InfluxDB service on your current environment and produces output like the following:

   ```bash theme={null}
   SSH tunnel opened to <RELATIONSHIP_NAME> at: http://127.0.0.1:30000
   ```

3. Get the username, password and token from the [relationship](#relationship-reference) by running the following command:

   ```bash theme={null}
   upsun relationships -P <RELATIONSHIP_NAME>
   ```

4. Adapt and run [InfluxDB's CLI export command](https://docs.influxdata.com/influxdb/v2.3/reference/cli/influx/backup/).

   ```bash theme={null}
   influx backup --host <URL_FROM_STEP_2> --token <API_TOKEN_FROM_STEP_3>
   ```

## Upgrade to version 2.3 or later

### From a previous 2.x version

From version 2.3 onward, the structure of relationships changes.

If you're using a prior 2.x version, your app might currently rely on pulling the `bucket`, `org`, `api_token`,
or `user` values available in the [`PLATFORM_RELATIONSHIPS` environment variable](#relationship-reference).

If so, to ensure your upgrade is successful, make the following changes to your connection logic:

* Rename the `user` key to `username`.
* Move the `org`, `bucket` and `api_token` keys so they're contained in a dictionary under the `query` key.

If you're relying on any other attributes connecting to InfluxDB, they remain accessible as environment variable from the [service environment variable](#relationship-reference), aside from those addressed above:

### From a 1.x version

From version 2.3 onward, InfluxDB includes an upgrade utility that can convert databases from previous versions to version 2.3 or later.

To upgrade from a 1.x version to 2.3 or later,
change the service version in your `.upsun/config.yaml` file and push your project.
Any existing data you had in your 1.x system is automatically upgraded for you into the 2.3+ system.

<Note>
  During an upgrade from a 1.x version to a 2.3 version or later,
  a new admin password and a new admin API token are automatically generated.
  Previous credentials can't be retained.

  You can retrieve your new credentials through the [service environment variables](/docs/development/variables#service-environment-variables).
</Note>


# Kafka (Message queue service)
Source: https://developer.upsun.com/docs/add-services/kafka

Apache Kafka is an open-source stream-processing software platform.


It is a framework for storing, reading and analyzing streaming data. See the [Kafka documentation](https://kafka.apache.org/documentation) for more information.

## Supported versions

You can select the major and minor version.

Patch versions are applied periodically for bug fixes and other maintenance updates. By default, you get the latest available patches each time you deploy. If your project has a [maintenance window](/docs/core-concepts/build-deploy#maintenance-window) configured, Upsun Cloud applies patches only during that window. Upsun Cloud may still apply urgent or critical fixes outside of the maintenance window.

* <span>4.3</span>
* <span>4.1</span>
* <span>3.7</span>
* <span>3.6</span>

## Deprecated versions

The following versions are still available in your projects,
but they're at their end of life and are no longer receiving security updates from upstream.

*No deprecated versions.*

To ensure your project remains stable in the future,
switch to a [supported version](#supported-versions).

## Retired versions

The following versions have been retired and are no longer available.
If your project uses a retired version, you must update to a [supported version](#supported-versions).

* <span>3.4</span>
* <span>3.2</span>
* <span>2.7</span>
* <span>2.6</span>
* <span>2.5</span>
* <span>2.4</span>
* <span>2.3</span>
* <span>2.2</span>
* <span>2.1</span>

## Relationship reference

For each service [defined via a relationship](#usage-example) to your application,
Upsun Cloud automatically generates corresponding environment variables within your application container,
in the `$<RELATIONSHIP-NAME>_<SERVICE-PROPERTY>` format.

Here is example information available through the [service environment variables](/docs/development/variables#service-environment-variables) themselves,
or through the [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables).

You can obtain the complete list of available service environment variables in your app container by running `upsun ssh env`.

Note that the information about the relationship can change when an app is redeployed or restarted or the relationship is changed. So your apps should only rely on the [service environment variables](/docs/development/variables#service-environment-variables) directly rather than hard coding any values.

<Tabs>
  <Tab title="`PLATFORM_RELATIONSHIPS` environment variable">
    For some advanced use cases, you can use the [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables).
    The structure of the `PLATFORM_RELATIONSHIPS` environment variable can be obtained by running `upsun relationships` in your terminal:

    Here is an example of how to gather [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables) information in a [`.environment` file](/docs/development/variables/set-variables#when-to-use-env-files):

    ```bash .environment theme={null}
    # Decode the built-in credentials object variable.
    export RELATIONSHIPS_JSON="$(echo "$PLATFORM_RELATIONSHIPS" | base64 --decode)"

    # Set environment variables for individual credentials.
    export APP_KAFKA_HOST="$(echo "$RELATIONSHIPS_JSON" | jq -r '.kafka[0].host')"
    ```
  </Tab>
</Tabs>

## Usage example

### 1. Configure the service

To define the service, use the `kafka` type:

Note that changing the name of the service replaces it with a brand new service and all existing data is lost. Back up your data before changing the service.

### 2. Define the relationship

To define the relationship, use the following configuration:

<Tabs>
  <Tab title="Using default endpoints">
    You can define `SERVICE_NAME` as you like, so long as it's unique between all defined services
    and matches in both the application and services configuration.

    The example above leverages [default endpoint](/docs/configure-apps/image-properties/relationships) configuration for relationships.
    That is, it uses default endpoints behind the scenes, providing a [relationship](/docs/configure-apps/image-properties/relationships)
    (the network address a service is accessible from) that is identical to the *name* of that service.

    Depending on your needs, instead of default endpoint configuration,
    you can use [explicit endpoint configuration](/docs/configure-apps/image-properties/relationships).

    With the above definition, the application container (`APP_NAME`) now has [access to the service](/docs/add-services/kafka) via the relationship `SERVICE_NAME` and its corresponding [service environment variables](/docs/development/variables#service-environment-variables)
  </Tab>

  <Tab title="Using explicit endpoints">
    You can define `SERVICE_NAME` and `<RELATIONSHIP_NAME>` as you like, so long as it's unique between all defined services and relationships
    and matches in both the application and services configuration.

    The example above leverages [explicit endpoint](/docs/configure-apps/image-properties/relationships) configuration for relationships.

    Depending on your needs, instead of explicit endpoint configuration,
    you can use [default endpoint configuration](/docs/configure-apps/image-properties/relationships).

    With the above definition, the application container now has [access to the service](#usage-example) via the relationship `<RELATIONSHIP_NAME>` and its corresponding [service environment variables](/docs/development/variables#service-environment-variables).
  </Tab>
</Tabs>

### Example configuration

## Exporting Data

Kafka stores messages in on-disk topic partitions. You can export messages using the
`kafka-console-consumer` tool over an SSH session.

1. Open an SSH session to your app container (Kafka is not directly accessible via `tunnel:single`):

```bash Terminal theme={null}
upsun ssh
```

2. From the app container, list available topics:

```bash Terminal theme={null}
kafka-topics.sh \
  --bootstrap-server $KAFKA_HOST:$KAFKA_PORT \
  --list
```

3. Export all messages from a topic to a file:

```bash Terminal theme={null}
kafka-console-consumer.sh \
  --bootstrap-server $KAFKA_HOST:$KAFKA_PORT \
  --topic <TOPIC_NAME> \
  --from-beginning \
  --max-messages <NUMBER> \
  --timeout-ms 5000 \
  > /tmp/kafka-export-<TOPIC_NAME>.txt
```

4. Download the exported file:

```bash Terminal theme={null}
# From your local machine
upsun scp remote:/tmp/kafka-export-<TOPIC_NAME>.txt ./kafka-export-<TOPIC_NAME>.txt
```

The Kafka connection credentials (`KAFKA_HOST`, `KAFKA_PORT`) are available as
[service environment variables](/docs/development/variables#service-environment-variables)
inside the app container.

Note that Kafka is designed as a streaming platform, not a primary data store.
In most architectures, the authoritative copy of your data exists elsewhere (for example in a database),
and Kafka topics can be replayed or re-populated from that source.


# Memcached (Object cache)
Source: https://developer.upsun.com/docs/add-services/memcached

Memcached is a simple in-memory object store well-suited for application level caching.


See the [Memcached documentation](https://memcached.org) for more information.

Both Memcached and Redis can be used for application caching. As a general rule, Memcached is simpler and thus more widely supported while Redis is more robust. Upsun recommends using Redis if possible but Memcached is fully supported if an application favors that cache service.

## Supported versions

You can select the major and minor version.

Patch versions are applied periodically for bug fixes and other maintenance updates. By default, you get the latest available patches each time you deploy. If your project has a [maintenance window](/docs/core-concepts/build-deploy#maintenance-window) configured, Upsun Cloud applies patches only during that window. Upsun Cloud may still apply urgent or critical fixes outside of the maintenance window.

* <span>1.6</span>

## Deprecated versions

The following versions are still available in your projects,
but they're at their end of life and are no longer receiving security updates from upstream.

*No deprecated versions.*

To ensure your project remains stable in the future, switch to a [supported version](#supported-versions).

## Retired versions

The following versions have been retired and are no longer available.
If your project uses a retired version, you must update to a [supported version](#supported-versions).

* <span>1.5</span>
* <span>1.4</span>

## Relationship reference

For each service [defined via a relationship](#usage-example) to your application,
Upsun Cloud automatically generates corresponding environment variables within your application container,
in the `$<RELATIONSHIP-NAME>_<SERVICE-PROPERTY>` format.

Here is example information available through the [service environment variables](/docs/development/variables#service-environment-variables) themselves,
or through the [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables).

<Tabs>
  <Tab title="Service environment variables">
    You can obtain the complete list of available service environment variables in your app container by running `upsun ssh env`.

    Note that the information about the relationship can change when an app is redeployed or restarted or the relationship is changed. So your apps should only rely on the [service environment variables](/docs/development/variables#service-environment-variables) directly rather than hard coding any values.
  </Tab>

  <Tab title="`PLATFORM_RELATIONSHIPS` environment variable">
    For some advanced use cases, you can use the [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables).
    The structure of the `PLATFORM_RELATIONSHIPS` environment variable can be obtained by running `upsun relationships` in your terminal:

    Here is an example of how to gather [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables) information in a [`.environment` file](/docs/development/variables/set-variables#when-to-use-env-files):

    ```bash .environment theme={null}
    # Decode the built-in credentials object variable.
    export RELATIONSHIPS_JSON="$(echo "$PLATFORM_RELATIONSHIPS" | base64 --decode)"

    # Set environment variables for individual credentials.
    export APP_MEMCACHED_HOST="$(echo "$RELATIONSHIPS_JSON" | jq -r '.memcached[0].host')"
    ```
  </Tab>
</Tabs>

## Usage example

### 1. Configure the service

To define the service, use the `memcached` type:

Note that changing the name of the service replaces it with a brand new service and all existing data is lost. Back up your data before changing the service.

### 2. Define the relationship

To define the relationship, use the following configuration:

<Tabs>
  <Tab title="Using default endpoints">
    You can define `SERVICE_NAME` as you like, so long as it's unique between all defined services
    and matches in both the application and services configuration.

    The example above leverages [default endpoint](/docs/configure-apps/image-properties/relationships) configuration for relationships.
    That is, it uses default endpoints behind the scenes, providing a [relationship](/docs/configure-apps/image-properties/relationships)
    (the network address a service is accessible from) that is identical to the *name* of that service.

    With the above definition, the application container now has [access to the service](#use-in-app) via the relationship `SERVICE_NAME` and its corresponding [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables).
  </Tab>

  <Tab title="Using explicit endpoints">
    You can define `SERVICE_NAME` and `<RELATIONSHIP_NAME>` as you like, so long as it's unique between all defined services and relationships
    and matches in both the application and services configuration.

    The example above leverages [explicit endpoint](/docs/configure-apps/image-properties/relationships) configuration for relationships.

    Depending on your needs, instead of explicit endpoint configuration,
    you can use [default endpoint configuration](/docs/configure-apps/image-properties/relationships).

    With the above definition, the application container now has [access to the service](#use-in-app) via the relationship `<RELATIONSHIP_NAME>` and its corresponding [service environment variables](/docs/development/variables#service-environment-variables).
  </Tab>
</Tabs>

For PHP, enable the [extension](/docs/languages/php/extensions) for the service:

For Python, include the proper dependency:

### Example configuration

### Use in app

To use the configured service in your app, add a configuration file similar to the following to your project.

This configuration defines a single application (`myapp`), whose source code exists in the `<PROJECT_ROOT>/myapp` directory.<br />
`myapp` has access to the `influxdb` service, via a relationship whose name is [identical to the service name](#2-define-the-relationship)
(as per [default endpoint](/docs/configure-apps/image-properties/relationships) configuration for relationships).

From this, `myapp` can retrieve access credentials to the service through the [relationship environment variables](#relationship-reference).

```bash myapp/.environment theme={null}
# Surface a Memcached connection string for use in app.
# For more information, please visit /docs/development/variables#service-environment-variables.
export CACHE_URL="${MEMCACHED_HOST}:${MEMCACHED_PORT}"
```

The above file — `.environment` in the `myapp` directory — is automatically sourced by Upsun Cloud into the runtime environment, so that the variable `CACHE_URL` can be used within the application to connect to the service.

Note that `CACHE_URL`, and all Upsun Cloud [service environment variables](/docs/development/variables#service-environment-variables) like `MEMCACHEDCACHE_HOST`, are environment-dependent.
Unlike the build produced for a given commit,
they can’t be reused across environments and only allow your app to connect to a single service instance on a single environment.

A file very similar to this is generated automatically for your when using the `upsun ify` command to [migrate a codebase to Upsun Cloud](/docs/get-started).

## Accessing Memcached directly

To access the Memcached service directly you can use `netcat` as Memcached doesn't have a dedicated client tool.
Assuming your Memcached relationship is named `memcached`, the host name `MEMCACHED_HOST` and port number `MEMCACHED_PORT` obtained from the [service environment variable](#relationship-reference) would be `memcached.internal` and `11211`.
<br />Open an [SSH session](/docs/development/ssh) and access the Memcached server as follows:

```bash Terminal theme={null}
netcat memcached.internal 11211
```

You can obtain the complete list of available service environment variables in your app container by running `upsun ssh env`.

Note that the information about the relationship can change when an app is redeployed or restarted or the relationship is changed. So your apps should only rely on the [service environment variables](/docs/development/variables#service-environment-variables) directly rather than hard coding any values.


# Mercure
Source: https://developer.upsun.com/docs/add-services/mercure

[Mercure](https://mercure.rocks/) is a real-time communication protocol and hub designed for modern web apps. It allows servers to instantly push updates to browsers, mobile clients, and backend workers through Server-Sent Events (SSE).


Built for simplicity and performance, Mercure is widely used in the Symfony ecosystem and beyond for reactive UIs, real-time notifications, and live data streaming.

### Supported versions

You can select the major and minor version.

Patch versions are applied periodically for bug fixes and other maintenance updates. By default, you get the latest available patches each time you deploy. If your project has a [maintenance window](/docs/core-concepts/build-deploy#maintenance-window) configured, Upsun Cloud applies patches only during that window. Upsun Cloud may still apply urgent or critical fixes outside of the maintenance window.

* <span>0</span>

## Deprecated versions

The following versions are still available in your projects,
but they're at their end of life and are no longer receiving security updates from upstream.

*No deprecated versions.*

To ensure your project remains stable in the future, switch to a [supported version](#supported-versions).

## Retired versions

The following versions have been retired and are no longer available.
If your project uses a retired version, you must update to a [supported version](#supported-versions).

*No retired versions.*

## JWT Token Secret

The service generates the JSON Web Token (JWT) token secret. It's available in the `password` field of the Mercure relationship in the `PLATFORM_RELATIONSHIPS` environment variable.

## Relationship reference

For each service [defined via a relationship](#usage-example) to your application,
Upsun Cloud automatically generates corresponding environment variables within your application container,
in the `$<RELATIONSHIP-NAME>_<SERVICE-PROPERTY>` format.

Here is example information available through the [service environment variables](/docs/development/variables#service-environment-variables) themselves,
or through the [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables).

<Tabs>
  <Tab title="Service environment variables">
    You can obtain the complete list of available service environment variables in your app container by running `upsun ssh env`.

    Note that the information about the relationship can change when an app is redeployed or restarted or the relationship is changed. So your apps should only rely on the [service environment variables](/docs/development/variables#service-environment-variables) directly rather than hard coding any values.
  </Tab>

  <Tab title="`PLATFORM_RELATIONSHIPS` environment variable">
    For some advanced use cases, you can use the [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables).
    The structure of the `PLATFORM_RELATIONSHIPS` environment variable can be obtained by running `upsun relationships` in your terminal:

    Here is an example of how to gather [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables) information in a [`.environment` file](/docs/development/variables/set-variables#when-to-use-env-files):

    ```bash .environment theme={null}
    # Decode the built-in credentials object variable.
    export RELATIONSHIPS_JSON="$(echo "$PLATFORM_RELATIONSHIPS" | base64 --decode)"

    # Set environment variables for individual credentials.
    export APP_MERCURE_HOST="$(echo $RELATIONSHIPS_JSON | jq -r '.mercure[0].host')"
    ```
  </Tab>
</Tabs>

## Usage example

### 1. Configure the service

To define the service, use the `mercure` type:

Note that changing the name of the service replaces it with a brand new service and all existing data is lost. Back up your data before changing the service.

#### Configuration options

You can pass additional options under the `configuration` key:

| Option | Type | Default | Description |
| - | - | - | - |
| `anonymous` | boolean | `false` | Allows unauthenticated subscribers to connect without a JWT token. |
| `cors_origins` | list of strings | — | Domains allowed to make cross-origin requests to the Mercure hub. Requires environment-specific values in your YAML — see the [routing step warning](#2-define-the-route) before using. |

### 2. Define the route

To access the service URL, add an entry to the `.routes` key as shown below, replacing `<SERVICE_NAME>` with the name of your service.

<Warning>
  By default, the Upsun Cloud Mercure image doesn't expose CORS headers.
  If your Mercure hub will be accessed from a browser (e.g. subscribing to Server-Sent Events via JavaScript),
  you **must** route it as a sub-path of your main domain rather than on a dedicated subdomain.
  A subdomain like `mercure.{default}` is treated as a different origin by browsers,
  and without CORS headers, requests will be blocked.

  If you can't use a sub-path route, you can configure [`cors_origins`](#configuration-options) as a last resort.
  Be aware that hardcoding domain names directly in your YAML config is an anti-pattern on Upsun Cloud:
  those values are environment-specific (production, staging, preview each have different domains),
  which means your config file no longer describes a single consistent state.
</Warning>

Use a **sub-path route** so the hub shares the same origin as your frontend (recommended for browser usage):

Use a **subdomain route** if the Mercure hub is only consumed server-side (no browser clients — CORS headers aren't required):

### 3. Define the relationship

Define the relationship to the app as shown below:

<Tabs>
  <Tab title="Using default endpoints">
    You can define `SERVICE_NAME` as you like, so long as it's unique between all defined services
    and matches in both the application and services configuration.

    The example above leverages [default endpoint](/docs/configure-apps/image-properties/relationships) configuration for relationships.
    That is, it uses default endpoints behind the scenes, providing a [relationship](/docs/configure-apps/image-properties/relationships)
    (the network address a service is accessible from) that is identical to the *name* of that service.

    Depending on your needs, instead of default endpoint configuration,
    you can use [explicit endpoint configuration](/docs/configure-apps/image-properties/relationships).

    With the above definition, the application container (`APP_NAME`) now has [access to the service](#use-in-app) via the relationship `SERVICE_NAME` and its corresponding [service environment variables](/docs/development/variables#service-environment-variables).
  </Tab>

  <Tab title="Using explicit endpoints">
    You can define `SERVICE_NAME` and `<RELATIONSHIP_NAME>` as you like, so long as it's unique between all defined services and relationships
    and matches in both the application and services configuration.

    The example above leverages [explicit endpoint](/docs/configure-apps/image-properties/relationships) configuration for relationships.

    Depending on your needs, instead of explicit endpoint configuration,
    you can use [default endpoint configuration](/docs/configure-apps/image-properties/relationships).

    With the above definition, the application container now has [access to the service](#use-in-app) via the relationship `<RELATIONSHIP_NAME>` and its corresponding [service environment variables](/docs/development/variables#service-environment-variables).
  </Tab>
</Tabs>

#### Example configuration

### Use in app

To use the configured service in your app, add a configuration file similar to the following to your project.

This configuration defines a single application (`myapp`), whose source code exists in the `<PROJECT_ROOT>/myapp` directory.<br />
`myapp` has access to the `mercure` service via a relationship whose name is [identical to the service name](#2-define-the-relationship)
(as per [default endpoint](/docs/configure-apps/image-properties/relationships) configuration for relationships).

From this, `myapp` can retrieve access credentials to the service through the [relationship environment variables](#relationship-reference).

```bash myapp/.environment theme={null}
# Set environment variables for common Mercure credentials.
# For more information, please visit https://developer.upsun.com/docs/development/variables#service-environment-variables.
export MERCURE_USER="${MERCURE_USERNAME}"
export MERCURE_HOST="${MERCURE_HOST}"
export MERCURE_QUERY="${MERCURE_QUERY}"
```

The `.environment` shown above in the `myapp` directory is automatically sourced by Upsun Cloud into the runtime environment, so that the variable `MERCURE_HOST` can be used within the application to connect to the service.

Note that `DATABASE_URL` and all Upsun Cloud [service environment variables](/docs/development/variables#service-environment-variables), such as `MERCURE_HOST`, are environment-dependent.
Unlike the build produced for a given commit,
they can’t be reused across environments and only allow your app to connect to a single service instance on a single environment.

A file very similar to this is generated automatically for your when using the `upsun project:init` command to [migrate a codebase to Upsun Cloud](/docs/get-started).


# MongoDB (Database service)
Source: https://developer.upsun.com/docs/add-services/mongodb

MongoDB is a cross-platform, document-oriented database. For more information on using MongoDB, see MongoDB's own documentation.

## Enterprise edition

<Info>
  <h4>Premium Service</h4>
  MongoDB Enterprise isn’t included in any Upsun Cloud plan.
  You need to add it separately at an additional cost.
  To add MongoDB Enterprise, [contact Sales](https://upsun.com/contact-us/).
</Info>

### Supported versions

You can select the major and minor version.

Patch versions are applied periodically for bug fixes and other maintenance updates. By default, you get the latest available patches each time you deploy. If your project has a [maintenance window](/docs/core-concepts/build-deploy#maintenance-window) configured, Upsun Cloud applies patches only during that window. Upsun Cloud may still apply urgent or critical fixes outside of the maintenance window.

* <span>7.0</span>

<Note>
  These versions are not yet available but are expected to be released soon.

  * <span>8.0</span>
</Note>

### Deprecated versions

The following versions are still available in your projects,
but they're at their end of life and are no longer receiving security updates from upstream.

*No deprecated versions.*

To ensure your project remains stable in the future, switch to a [supported version](#supported-versions).

### Retired versions

The following versions have been retired and are no longer available.
If your project uses a retired version, you must update to a [supported version](#supported-versions).

* <span>6.0</span>
* <span>5.0</span>
* <span>4.4</span>
* <span>4.2</span>
* <span>4.0</span>

## Legacy edition

Previous non-Enterprise versions are available in your projects (and are listed below),
but they're at their [end of life](https://www.mongodb.com/support-policy/legacy)
and are no longer receiving security updates from upstream.

### Supported versions

You can select the major and minor version.

Patch versions are applied periodically for bug fixes and other maintenance updates. By default, you get the latest available patches each time you deploy. If your project has a [maintenance window](/docs/core-concepts/build-deploy#maintenance-window) configured, Upsun Cloud applies patches only during that window. Upsun Cloud may still apply urgent or critical fixes outside of the maintenance window.

* <span>4.0</span>

<Note>
  <h4>Warning</h4>
  Downgrades of MongoDB aren't supported.
  MongoDB updates its own data files to a new version automatically but can't downgrade them.
  If you want to experiment with a later version without committing to it use a preview environment.
</Note>

### Deprecated versions

The following versions are still available in your projects,
but they're at their end of life and are no longer receiving security updates from upstream.

*No deprecated versions.*

To ensure your project remains stable in the future, switch to a [supported version](#supported-versions).

### Retired versions

The following versions have been retired and are no longer available.
If your project uses a retired version, you must update to a [supported version](#supported-versions).

* <span>3.6</span>
* <span>3.4</span>
* <span>3.2</span>
* <span>3.0</span>

## Relationship reference

For each service [defined via a relationship](#usage-example) to your application,
Upsun Cloud automatically generates corresponding environment variables within your application container,
in the `$<RELATIONSHIP-NAME>_<SERVICE-PROPERTY>` format.

Here is example information available through the [service environment variables](/docs/development/variables#service-environment-variables) themselves,
or through the [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables).

<Tabs>
  <Tab title="Service environment variables">
    You can obtain the complete list of available service environment variables in your app container by running `upsun ssh env`.

    Note that the information about the relationship can change when an app is redeployed or restarted or the relationship is changed. So your apps should only rely on the [service environment variables](/docs/development/variables#service-environment-variables) directly rather than hard coding any values.
  </Tab>

  <Tab title="`PLATFORM_RELATIONSHIPS` environment variable">
    For some advanced use cases, you can use the [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables).
    The structure of the `PLATFORM_RELATIONSHIPS` environment variable can be obtained by running `upsun relationships` in your terminal:

    Here is an example of how to gather [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables) information in a [`.environment` file](/docs/development/variables/set-variables#when-to-use-env-files):

    ```bash .environment theme={null}
    # Decode the built-in credentials object variable.
    export RELATIONSHIPS_JSON="$(echo "$PLATFORM_RELATIONSHIPS" | base64 --decode)"

    # Set environment variables for individual credentials.
    export APP_MONGODBDATABASE_HOST="$(echo "$RELATIONSHIPS_JSON" | jq -r '.mongodb[0].host')"
    ```
  </Tab>
</Tabs>

## Usage example

### Enterprise edition example

#### 1. Configure the service

To define the service, use the `mongodb-enterprise` type:

Note that changing the name of the service replaces it with a brand new service and all existing data is lost. Back up your data before changing the service.

#### 2. Define the relationship

To define the relationship, use the following configuration:

<Tabs>
  <Tab title="Using default endpoints">
    You can define `SERVICE_NAME` as you like, so long as it's unique between all defined services
    and matches in both the application and services configuration.

    The example above leverages [default endpoint](/docs/configure-apps/image-properties/relationships) configuration for relationships.
    That is, it uses default endpoints behind the scenes, providing a [relationship](/docs/configure-apps/image-properties/relationships)
    (the network address a service is accessible from) that is identical to the *name* of that service.

    Depending on your needs, instead of default endpoint configuration,
    you can use [explicit endpoint configuration](/docs/configure-apps/image-properties/relationships).

    With the above definition, the application container (`APP_NAME`) now has [access to the service](#use-in-app) via the relationship `SERVICE_NAME` and its corresponding [service environment variables](/docs/development/variables#service-environment-variables).
  </Tab>

  <Tab title="Using explicit endpoints">
    You can define `SERVICE_NAME` and `<RELATIONSHIP_NAME>` as you like, so long as it's unique between all defined services and relationships
    and matches in both the application and services configuration.

    The example above leverages [explicit endpoint](/docs/configure-apps/image-properties/relationships) configuration for relationships.

    Depending on your needs, instead of explicit endpoint configuration,
    you can use [default endpoint configuration](/docs/configure-apps/image-properties/relationships).

    With the above definition, the application container now has [access to the service](#use-in-app) via the relationship `<RELATIONSHIP_NAME>` and its corresponding [service environment variables](/docs/development/variables#service-environment-variables).
  </Tab>
</Tabs>

For PHP, enable the [extension](/docs/languages/php/extensions) for the service:

#### Example configuration

### Legacy edition example

#### 1. Configure the service

To define the service, use the `mongodb` type:

Note that changing the name of the service replaces it with a brand new service and all existing data is lost. Back up your data before changing the service.

#### 2. Define the relationship

To define the relationship, use the following configuration:

<Tabs>
  <Tab title="Using default endpoints">
    You can define `SERVICE_NAME` as you like, so long as it's unique between all defined services
    and matches in both the application and services configuration.

    The example above leverages [default endpoint](/docs/configure-apps/image-properties/relationships) configuration for relationships.
    That is, it uses default endpoints behind the scenes, providing a [relationship](/docs/configure-apps/image-properties/relationships)
    (the network address a service is accessible from) that is identical to the *name* of that service.

    Depending on your needs, instead of default endpoint configuration,
    you can use [explicit endpoint configuration](/docs/configure-apps/image-properties/relationships).

    With the above definition, the application container (`APP_NAME`) now has [access to the service](#use-in-app) via the relationship `SERVICE_NAME` and its corresponding [service environment variables](/docs/development/variables#service-environment-variables).
  </Tab>

  <Tab title="Using explicit endpoints">
    You can define `SERVICE_NAME` and `<RELATIONSHIP_NAME>` as you like, so long as it's unique between all defined services and relationships
    and matches in both the application and services configuration.

    The example above leverages [explicit endpoint](/docs/configure-apps/image-properties/relationships) configuration for relationships.

    Depending on your needs, instead of explicit endpoint configuration,
    you can use [default endpoint configuration](/docs/configure-apps/image-properties/relationships).

    With the above definition, the application container now has [access to the service](#use-in-app) via the relationship `<RELATIONSHIP_NAME>` and its corresponding [service environment variables](/docs/development/variables#service-environment-variables).
  </Tab>
</Tabs>

For PHP, enable the [extension](/docs/languages/php/extensions) for the service:

#### Example configuration

### Use in app

To use the configured service in your app, add a configuration file similar to the following to your project.

This configuration defines a single application (`myapp`), whose source code exists in the `<PROJECT_ROOT>/myapp` directory.<br />
`myapp` has access to the `mongodb` service, via a relationship whose name is [identical to the service name](#2-define-the-relationship)
(as per [default endpoint](/docs/configure-apps/image-properties/relationships) configuration for relationships).

From this, `myapp` can retrieve access credentials to the service through the [relationship environment variables](#relationship-reference).

```bash myapp/.environment theme={null}
# Set environment variables for individual credentials.
# For more information, please visit /docs/development/variables#service-environment-variables.
export DB_CONNECTION=="${MONGODB_SCHEME}"
export DB_USERNAME="${MONGODB_USERNAME}"
export DB_PASSWORD="${MONGODB_PASSWORD}"
export DB_HOST="${MONGODB_HOST}"
export DB_PORT="${MONGODB_PORT}"
export DB_DATABASE="${MONGODB_PATH}"

# Surface connection string variable for use in app.
export DATABASE_URL="${DB_CONNECTION}://${DB_USERNAME}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT}/${DB_DATABASE}"
```

The above file — `.environment` in the `myapp` directory — is automatically sourced by Upsun Cloud into the runtime environment, so that the variable `DATABASE_URL` can be used within the application to connect to the service.

Note that `DATABASE_URL`, and all Upsun Cloud [service environment variables](/docs/development/variables#service-environment-variables) like `MONGODB_HOST`, are environment-dependent.
Unlike the build produced for a given commit,
they can’t be reused across environments and only allow your app to connect to a single service instance on a single environment.

A file very similar to this is generated automatically for your when using the `upsun ify` command to [migrate a codebase to Upsun Cloud](/docs/get-started).

## Access the service directly

You can access MongoDB from you app container via [SSH](/docs/development/ssh).
Get the `host` from your [relationship](#relationship-reference).
Then run the following command:

```bash theme={null}
mongosh <MONGODB_HOST>
```

With the example value, that would be the following:

```bash theme={null}
mongosh mongodb.internal
```

You can obtain the complete list of available service environment variables in your app container by running `upsun ssh env`.

Note that the information about the relationship can change when an app is redeployed or restarted or the relationship is changed. So your apps should only rely on the [service environment variables](/docs/development/variables#service-environment-variables) directly rather than hard coding any values.

## Exporting data

The most straightforward way to export data from a MongoDB database is to open an SSH tunnel to it
and export the data directly using MongoDB's tools.

First, open an SSH tunnel with the Upsun Cloud CLI:

```bash theme={null}
upsun tunnel:open
```

That opens an SSH tunnel to all services on your current environment and produce output like the following:

```bash theme={null}
SSH tunnel opened on port 30000 to relationship: mongodb
```

The port may vary in your case.
You also need to obtain the user, password, and database name from the relationships array, as above.

Then, connect to that port locally using `mongodump` (or your favorite MongoDB tools) to export all data in that server:

```bash theme={null}
mongodump --port 30000 -u main -p main --authenticationDatabase main --db main
```

(If necessary, vary the `-u`, `-p`, `--authenticationDatabase` and `--db` flags.)

As with any other shell command it can be piped to another command to compress the output or redirect it to a specific file.

For further references, see the [official `mongodump` documentation](https://www.mongodb.com/docs/database-tools/mongodump/).

## Large databases

Upsun Cloud supports MongoDB databases of any size, including multi-terabyte deployments. The same service configuration applies whether your database holds gigabytes or tens of terabytes. Only the resources you allocate to it differ.

### Cloning at any size

When you create a [preview environment](/docs/environments), Upsun Cloud clones the entire parent environment (including its database) at the storage layer. The clone completes in seconds to under a minute regardless of database size. A 10 TB database clones in roughly the same time as a 10 GB one.

### What drives performance

Total disk size is rarely the limiting factor for query performance. What matters is the **active dataset** (or working set), the subset of documents, indexes, and pages your application actually reads and writes.

A 10 TB database that serves queries against 5 GB of hot data can outperform a 50 GB database. The smaller database performs worse if it scans entire collections on every request. As long as the active dataset fits in WiredTiger's internal cache, queries are served from memory without touching disk.

By contrast, queries that read most of a collection become more expensive as the collection grows. The same is true of indexes that effectively scan everything.

### Sizing for large datasets

Memory is the lever that keeps the active dataset hot. MongoDB containers use the [`HIGH_MEMORY` container profile](/docs/manage-resources/adjust-resources#advanced-container-profiles) by default. Combined with [Guaranteed CPU](/docs/manage-resources/guaranteed-resources), you can allocate up to **512 GB of RAM** to a single MongoDB container.

To work efficiently with a large database:

* Size memory to fit the active dataset in WiredTiger's cache.
* Make sure queries hit indexes, and avoid full collection scans on large collections.
* Watch index selectivity. An index that scans most of a large collection on each query loads gigabytes into memory, evicting the active dataset.
* Use [`explain()`](https://www.mongodb.com/docs/manual/reference/explain-results/) to verify which indexes a query uses and how many documents it examines.

Disk size alone, even into the multi-terabyte range, does not determine database performance. It determines what data you can store. Memory and query patterns determine how fast you can serve it.

## Upgrading

To upgrade to 6.0 from a version earlier than 5.0, you must successively upgrade major releases until you have upgraded to 5.0.
For example, if you are running a 4.2 image, you must upgrade first to 4.4 and then upgrade to 5.0 before you can upgrade to 6.0.

For more details on upgrading and how to handle potential application backward compatibility issues,
see the [MongoDB release notes](https://www.mongodb.com/docs/manual/release-notes/).

<Warning>
  Make sure you first test your migration on a separate branch.

  Also, be sure to take a backup of your production environment **before** you merge this change.
</Warning>

Downgrading isn't supported. If you want, for whatever reason, to downgrade you should create a mongodump, remove the service, recreate the service, and import your dump.


# MariaDB/MySQL (database service)
Source: https://developer.upsun.com/docs/add-services/mysql/index

See how to configure a MariaDB/MySQL server to store your data.

Upsun Cloud supports both MariaDB and Oracle MySQL to manage your relational databases.
Their infrastructure setup is nearly identical, though they differ in some features.
See the [MariaDB documentation](https://mariadb.org/documentation/)
or the Oracle [MySQL Server documentation](https://dev.mysql.com/doc/refman/en/) for more information.

<Info>
  <h4>MariaDB note</h4>
  The [example](#mariadb-example) provided later in this topic is specific to using only a **primary** MariaDB database. For details about using read-only replicas to improve performance of read-heavy applications, see the [MariaDB read-only replication](/docs/add-services/mysql/mysql-readonly-replication) topic.
</Info>

## Supported versions

You can select the major and minor version.

Patch versions are applied periodically for bug fixes and other maintenance updates. By default, you get the latest available patches each time you deploy. If your project has a [maintenance window](/docs/core-concepts/build-deploy#maintenance-window) configured, Upsun Cloud applies patches only during that window. Upsun Cloud may still apply urgent or critical fixes outside of the maintenance window.

<Info>
  * Both `mariadb` and `mysql` service types use MariaDB.\
    They behave identically, so the information on this page applies to both of them.
  * The service type `oracle-mysql` refers to MySQL as released by Oracle, Inc.
</Info>

<Tabs>
  <Tab title="mariadb / mysql">
    * <span>12.3</span>
    * <span>11.8</span>
    * <span>11.4</span>
    * <span>10.11</span>
  </Tab>

  <Tab title="oracle-mysql">
    * <span>8.4</span>
  </Tab>
</Tabs>

### Upgrade

1. Branch locally from production. For example: `git branch -c database-upgrade`.
2. **Important:** Push the branch (`git push`) before making any changes. This step is required — it ensures your data is copied to a new container before the upgrade begins.
3. In `.upsun/config.yaml`, update the service `type` key to include the target version.
   You can upgrade directly to any higher supported version — sequential upgrades are not required.

<Warning>
  **Do not change the service name.** Changing the service name deletes the existing container and all its data.
</Warning>

4. Commit and push the changes.
5. You can now test the new version on the branch you created in step 1 (e.g. the `database-upgrade` branch).
6. Verify the upgrade; then, merge your branch (e.g. `database-upgrade`) into production. Expect a slightly longer deployment as the database restarts during the upgrade.

### Downgrade

<Warning>
  Downgrading requires changing the service name, which permanently deletes the existing container and all its data.

  Before downgrading, back up your environment for rollback, and export your data — you'll reimport it into the re-created service.
</Warning>

1. [Back up your environment](/docs/environments/backup#create-a-manual-backup). If you accidentally delete the wrong service (or make an error in your configuration files) and need to revert your entire environment, the backup enables you to do so.

2. [Export the data](#exporting-data). Exporting the data to a portable file enables you to import it later. You cannot import data directly from a backup of your environment.

   <Accordion title="Review the dump file for version compatibility issues.">
     Your exported data might contain features that don’t exist in the older target version. Review the dump file for compatibility issues such as:

     * Lines starting with `/*!` followed by a number (e.g. `/*!100200`). These are version-conditional statements — if the number corresponds to a version newer than your target, that SQL may not run correctly.
     * Data types introduced after the target version (e.g. `JSON` columns added in MariaDB 10.2)
     * SQL syntax introduced after the target version, such as window functions or CTEs (`WITH`)
   </Accordion>

3. In `.upsun/config.yaml`, change the service name and replace the version in the service `type` key with the lower target version.

4. Commit and push the changes. A new container is created with an empty database.

5. [Import the data](#importing-data) into the new service.

## Deprecated versions

The following versions are still available in your projects,
but they're at their end of life and are no longer receiving security updates from upstream.

<Tabs>
  <Tab title="mariadb / mysql">
    *No deprecated versions.*
  </Tab>

  <Tab title="oracle-mysql">
    *No deprecated versions.*
  </Tab>
</Tabs>

To ensure your project remains stable in the future, switch to a [supported version](#supported-versions).

## Retired versions

The following versions have been retired and are no longer available.
If your project uses a retired version, you must update to a [supported version](#supported-versions).

<Tabs>
  <Tab title="mariadb / mysql">
    * <span>11.2</span>
    * <span>11.0</span>
    * <span>10.6</span>
    * <span>10.5</span>
    * <span>10.4</span>
    * <span>10.3</span>
    * <span>10.2</span>
    * <span>10.1</span>
    * <span>10.0</span>
    * <span>5.5</span>
  </Tab>

  <Tab title="oracle-mysql">
    * <span>8.0</span>
    * <span>5.7</span>
  </Tab>
</Tabs>

## Relationship reference

For each service [defined via a relationship](#usage-example) to your application,
Upsun Cloud automatically generates corresponding environment variables within your application container,
in the `$<RELATIONSHIP-NAME>_<SERVICE-PROPERTY>` format.

Here is example information available through the [service environment variables](/docs/development/variables#service-environment-variables) themselves,
or through the [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables).

### MariaDB reference

<Tabs>
  <Tab title="Service environment variables">
    You can obtain the complete list of available service environment variables in your app container by running `upsun ssh env`.

    Service connection details can change whenever your app restarts or redeploys. To keep your connection stable, use [service environment variables](/docs/development/variables#service-environment-variables) rather than hard-coding values.
  </Tab>

  <Tab title="`PLATFORM_RELATIONSHIPS` environment variable">
    For some advanced use cases, you can use the [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables).
    The structure of the `PLATFORM_RELATIONSHIPS` environment variable can be obtained by running `upsun relationships` in your terminal.

    Example on how to gather [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables) information in a [`.environment` file](/docs/development/variables/set-variables#when-to-use-env-files):

    ```bash .environment theme={null}
    # Decode the built-in credentials object variable.
    export RELATIONSHIPS_JSON="$(echo "$PLATFORM_RELATIONSHIPS" | base64 --decode)"

    # Set environment variables for individual credentials.
    export APP_DATABASE_HOST="$(echo "$PLATFORM_RELATIONSHIPS" | base64 --decode | jq -r ".mariadb[0].host")"
    ```
  </Tab>
</Tabs>

### Oracle MySQL reference

<Tabs>
  <Tab title="Service environment variables">
    You can obtain the complete list of available service environment variables in your app container by running `upsun ssh env`.

    Service connection details can change whenever your app restarts or redeploys. **To keep your connection stable, use [service environment variables](/docs/development/variables#service-environment-variables) rather than hard-coding values.**
  </Tab>

  <Tab title="`PLATFORM_RELATIONSHIPS` environment variable">
    For some advanced use cases, you can use the [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables).
    The structure of the `PLATFORM_RELATIONSHIPS` environment variable can be obtained by running `upsun relationships` in your terminal.

    Example on how to gather [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables) information in a [`.environment` file](/docs/development/variables/set-variables#when-to-use-env-files):

    ```bash .environment theme={null}
    # Decode the built-in credentials object variable.
    export RELATIONSHIPS_JSON="$(echo "$PLATFORM_RELATIONSHIPS" | base64 --decode)"

    # Set environment variables for individual credentials.
    export APP_ORACLE_HOST="$(echo "$RELATIONSHIPS_JSON" | jq -r '.oraclemysql[0].host')"
    ```
  </Tab>
</Tabs>

## Usage example

Configure your service with at least 256 MB in disk space.

### 1. Configure the service

To define the service, use the `mariadb` or `mysql` type for MariaDB or the `oracle-mysql` type for Oracle MySQL :

Note that changing the name of the service replaces it with a brand new service and all existing data is lost.
Back up your data before changing the service.

### 2. Define the relationship

To define the relationship, use the following configuration:

<Tabs>
  <Tab title="Using default endpoints">
    You can define `SERVICE_NAME` as you like, so long as it’s unique between all defined services and matches in both the application and services configuration.

    The example above leverages [default endpoint](/docs/configure-apps/image-properties/relationships) configuration for relationships.
    That is, it uses default endpoints behind the scenes,
    providing a [relationship](/docs/configure-apps/image-properties/relationships) (the network address a service is accessible from) that is identical to the name of that service.

    Depending on your needs, instead of default endpoint configuration, you can use [explicit endpoint configuration](/docs/configure-apps/image-properties/relationships).

    With the above definition, the application container (`APP_NAME`) now has [access to the service](#use-in-app) via the relationship `SERVICE_NAME` and its corresponding [service environment variables](/docs/development/variables#service-environment-variables).
  </Tab>

  <Tab title="Using explicit endpoints">
    You can define `SERVICE_NAME` and `<RELATIONSHIP_NAME>` as you like, so long as it's unique between all defined services and relationships
    and matches in both the application and services configuration.

    The example above leverages [explicit endpoint](/docs/configure-apps/image-properties/relationships) configuration for relationships.

    Depending on your needs, instead of explicit endpoint configuration,
    you can use [default endpoint configuration](/docs/configure-apps/image-properties/relationships).

    With the above definition, the application container now has [access to the service](#use-in-app) via the relationship `<RELATIONSHIP_NAME>` and its corresponding [service environment variables](/docs/development/variables#service-environment-variables).
  </Tab>
</Tabs>

### MariaDB example

<Info>
  Use the steps and sample code below if your application will connect to a **primary** MariaDB database. For details about using read-only replicas to improve performance of read-heavy applications, see the [MariaDB read-only replication](/docs/add-services/mysql/mysql-readonly-replication) topic.
</Info>

### OracleMySQL example

### Use in app

To use the configured service in your app, add a configuration file similar to the following to your project.

This configuration defines a single application (`myapp`), whose source code exists in the `<PROJECT_ROOT>/myapp` directory.
`myapp` has access to the `mariadb` service, via a relationship whose name is [identical to the service name](#2-define-the-relationship)
(as per [default endpoint](/docs/configure-apps/image-properties/relationships) configuration for relationships).

From this, `myapp` can retrieve access credentials to the service through the [relationship environment variables](#relationship-reference).

```bash myapp/.environment theme={null}
# Set environment variables for individual credentials.
# For more information, please visit /docs/development/variables#service-environment-variables.
export DB_CONNECTION="${MARIADB_SCHEME}"
export DB_USERNAME="${MARIADB_USERNAME}"
export DB_PASSWORD="${MARIADB_PASSWORD}"
export DB_HOST="${MARIADB_HOST}"
export DB_PORT="${MARIADB_PORT}"
export DB_DATABASE="${MARIADB_PATH}"

# Surface connection string variable for use in app.
export DATABASE_URL="${DB_CONNECTION}://${DB_USERNAME}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT}/${DB_DATABASE}"
```

The above file — `.environment` in the `myapp` directory — is automatically sourced by Upsun Cloud into the runtime environment, so that the variable `MARIADB_URL` can be used within the application to connect to the service.

Note that `DATABASE_URL`, and all Upsun Cloud [service environment variables](/docs/development/variables#service-environment-variables) like `MARIADB_HOST`,
are environment-dependent.
Unlike the build produced for a given commit,
they can’t be reused across environments and only allow your app to connect to a single service instance on a single environment.

A file very similar to this is generated automatically for your when using the `upsun ify` command to [migrate a codebase to Upsun Cloud](/docs/get-started).

### Configure connections

There may be cases where you want to configure a database connection manually.

To get the URL to connect to the database, run the following command:

```bash theme={null}
upsun ssh env
```

The result is the complete [information for all relationships](#relationship-reference) with an additional `DATABASE_URL` property, defined on step [Use in app](#use-in-app).
<br />Use the `DATABASE_URL` property as your connection.

You can obtain the complete list of available service environment variables in your app container by running `upsun ssh env`.

Service connection details can change whenever your app restarts or redeploys. **To keep your connection stable, use [service environment variables](/docs/development/variables#service-environment-variables) rather than hard-coding values.**

You can also see a guide on how to [convert the `PLATFORM_RELATIONSHIPS` environment variable to a different form](https://support.platform.sh/hc/en-us/community/posts/16439596373010).

## Configuration options

You can configure your MySQL service in the [services configuration](..) with the following options:

| Name | Type | Version | Description |
| - | - | - | - |
| `schemas` | `string` array | 10.0+ | All databases to be created. Defaults to a single `main` database. |
| `endpoints` | An endpoints dictionary | 10.0+ | Endpoints with their permissions. See [multiple databases](#multiple-databases). |
| `properties` | A properties dictionary | MariaDB: 10.1+; Oracle MySQL: 8.0+ | Additional properties for the database. Equivalent to using a `my.cnf` file. See [property options](#configure-the-database). |
| `rotate_passwords` | A boolean | 10.3+ | Defaults to `true`. When set to `false`, [password rotation](#password-rotation) is disabled. |

Example configuration:

## Access the service directly

You can access the service using the Upsun Cloud CLI by running `upsun sql`.

You can also access it from you app container via [SSH](/docs/development/ssh).
From your [relationship data](#relationship-reference), you need: `MARIADB_HOST`, `MARIADB_PORT`, `MARIADB_USERNAME`, `MARIADB_PATH` values.
Then run the following command:
\`

Assuming the values from the [MariaDB reference](#mariadb-reference), that would be:

```bash theme={null}
mysql -h mariadb.internal -P 3306 -u user main
```

If your database relationship has a password, pass the `-p` switch and enter the password when prompted:

```bash theme={null}
mysql -p -h mariadb.internal -P 3306 -u user main
```

## Define permissions

With version `10.0` or later, you can define multiple users with different permissions for your database.
To do so, define multiple endpoints in your [service configuration](#configuration-options).

For each endpoint you add, you can define the following properties:

| Name | Type | Required | Description |
| - | - | - | - |
| `default_schema` | `string` | | Which of the defined schemas to default to. If not specified, the `path` property of the relationship is `null` and so tools such as the Upsun Cloud CLI can't access the relationship. |
| `privileges` | A permissions dictionary | | For each defined schema, specifies the permissions of the endpoint. |

Available permissions:

| Name | Type | Description |
| - | - | - |
| Read-only | `ro` | Can select, create temporary tables, and see views. |
| Read-write | `rw` | In addition to read-only permissions, can also insert, update, delete, manage and execute events, execute routines, create and drop indexes, manage and execute triggers, and lock tables. |
| Admin | `admin` | In addition to read-write permissions, can also create, drop, and alter tables; create views; and create and alter routines. |
| Replication | `replication` | For [replicating databases](/docs/add-services/mysql/mysql-replication). In addition to read-only permissions, can also lock tables. |
| Replication admin | `replication-admin` | For managing replicas across projects; can run statements such as SHOW REPLICA STATUS, CHANGE MASTER TO, START REPLICA, and so on (see this related [Dev Center article](https://devcenter.upsun.com/posts/connect-multiple-projects-applications-or-services-together/)). |

## Multiple databases

With version `10.0` or later, you can define multiple databases.
To do so, define multiple `schemas` in your [service configuration](#configuration-options).

You can also specify multiple `endpoints` for [permissions](#define-permissions).
If neither `schemas` nor `endpoints` is included, it's equivalent to the following default:

If either `schemas` or `endpoints` are defined, no default is applied and you have to specify the full configuration.

<Note>
  Removing a schema from the list of `schemas` on further deployments results in the deletion of the schema.
</Note>

### Multiple databases example

The following configuration example creates a single MariaDB service named `mariadb` with two databases, `main` and `legacy`.
Access to the database is defined through three endpoints:

* `admin` has full access to both databases.
* `reporter` has SELECT query access to `main` but no access to `legacy`.
* `importer` has SELECT/INSERT/UPDATE/DELETE (but not DDL) access to `legacy` but no access to `main`.

Expose these endpoints to your app as relationships in your [app configuration](/docs/configure-apps):

```yaml .upsun/config.yaml theme={null}
applications:
  # The name of the app container. Must be unique within a project.
  myapp:
    # The location of the application's code.
    source:
      root: "myapp"

    [...]

    # Relationships enable access from this app to a given service.
    # The example below shows configuration with explicitly set service names and endpoints.
    # See the Application reference for all options for defining relationships and endpoints.
    relationships:
      database:
        service: mariadb
        endpoint: admin
      reports:
        service: mariadb
        endpoint: reporter
      imports:
        service: mariadb
        endpoint: importer
```

These relationships are then available in the [service environment variables](#relationship-reference).
Each has its own credentials, prefixed with the relationship name, you can use to connect to the given database.

## Configure the database

For MariaDB 10.1 and later and Oracle MySQL 8.0 and later, you can set some configuration properties
(equivalent to using a `my.cnf` file).

In your settings, add the `properties` key to the `configuration` key.
It offers the following properties:

| Name | Type | Default | Description |
| - | - | - | - |
| `max_allowed_packet` | `integer` | `16` | The maximum size for packets in MB. Can be from `1` to `100`. |
| `default_charset` | `string` | `utf8mb4` after February 2020 and `latin1` before | The default character set. Affects any tables created after it's set. |
| `default_collation` | `string` | `utf8mb4_unicode_ci` after February 2020 and `latin1` before | The default collation. Affects any tables created after it's set. |
| `optimizer_switch` | `string` | | A place to set various server optimization variables. See the [MariaDB documentation](https://mariadb.com/kb/en/optimizer-switch/). |
| `optimizer_use_condition_selectivity` | `integer` | `4` in version 10.4.1+ and `1` before that | Which statistics are used by the optimizer. From `1` to `5`. See the [MariaDB documentation](https://mariadb.com/kb/en/server-system-variables/#optimizer_use_condition_selectivity). |
| `innodb_adaptive_hash_index` | `integer` | `0` in version 10.5+ and `1` before that | Enable/Disable InnoDB Hash Index. See the [MariaDB documentation](https://mariadb.com/kb/en/innodb-system-variables/#innodb_adaptive_hash_index). |
| `max_heap_table_size` | `integer` | `32` | The maximum size for user-created MEMORY tables in MB. Can be from `1` to `4096`. |
| `table_definition_cache` | `integer` | `400` | The number of table definitions that can be cached. See the [MariaDB documentation](https://mariadb.com/kb/en/server-system-variables/#table_definition_cache). |
| `table_open_cache` | `integer` | `400` | The maximum number of open tables cached in one table cache instance. See the [MariaDB documentation](https://mariadb.com/kb/en/server-system-variables/#table_open_cache). |
| `wsrep_sync_wait` | `integer` | `0` (Disabled) | Ensure execution of statements in fully synced nodes. See the [MariaDB documentation](https://mariadb.com/kb/en/galera-cluster-system-variables/#wsrep_sync_wait). |

An example of setting these properties:

You can also change a table's character set and collation through `ALTER TABLE` commands:

```sql theme={null}
-- To change defaults when creating new tables:
ALTER DATABASE main CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

-- To change defaults when creating new columns:
ALTER TABLE table_name CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

-- To convert existing data:
ALTER TABLE table_name CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

For further details, see the [MariaDB documentation](https://mariadb.com/kb/en/character-set-and-collation-overview/).

<Info>
  MariaDB configuration properties like [`max_connections`](https://mariadb.com/docs/server/server-management/variables-and-modes/server-system-variables#max_connections) and [`innodb_buffer_pool_size`](https://mariadb.com/kb/en/innodb-buffer-pool/#innodb_buffer_pool_size) are not directly configurable from `configuration.properties` in your services configuration.
  They can, however, be set indirectly, which can be useful for solving `Too many connection` errors.
  See [the troubleshooting documentation](/docs/add-services/mysql/troubleshoot#too-many-connections) for more details.
</Info>

## Password generation

If your YAML file does not specify a `schema` and `endpoint` for the MariaDB or MySQL service, no password is generated.

Because the database container is strictly isolated, it remains invisible to any resource until you [define an explicit relationship](/docs/add-services/mysql#2-define-the-relationship) between it and other apps or workers. The container's "walls" ensure that only authorized applications and workers can reach the data, while all other processes are blocked at the network level.

If you prefer to have Upsun Cloud generate a password, you must define [`schemas` and custom `endpoints`](#1-configure-the-service) in the `services` configuration – see the example in the [multiple databases](#multiple-databases) section of this topic.
For each custom endpoint that you define, Upsun Cloud generates a password. Note that you cannot customize these generated passwords.

<Note>
  Make sure you don't change `services.<SERVICE_NAME>`. **Changing the service name creates a new service,
  which removes existing data from your database.**
</Note>

After your custom endpoints are exposed as relationships in your [app configuration](/docs/configure-apps),
you can retrieve the password for each endpoint
through the `PLATFORM_RELATIONSHIPS` [environment variable](/docs/development/variables/use-variables#use-provided-variables)
within your [application containers](/docs/development/variables/use-variables#access-variables-in-your-app).

Using this method to retrieve password credentials is considered a best practice: passwords change automatically (or [*rotate*](#password-rotation)) over time, and using incorrect passwords results in application downtime. **Avoid using hard-coded passwords in your application (and code base), which can cause security issues.**

## Password rotation

<Note>
  For rotation to occur, you must define a `schema` and `endpoint` in your service configuration (see [Password generation](#password-generation) above); otherwise, no password is generated to be rotated.
</Note>

By default, password rotation is enabled (`rotate_passwords: true`), which enables Upsun Cloud to automatically rotate MariaDB passwords during image updates or as defined by MariaDB lifetime settings.

Specific scenarios might warrant disabling password rotation by [setting `rotate_passwords=false`](/docs/add-services/mysql#configuration-options): for example, choosing to accommodate users who access a database via an SSH tunnel and provide a password in their request because they cannot retrieve the database credentials stored in the [service or `$PLATFORM_RELATIONSHIPS` MariaDB environment variables](#mariadb-reference).

Passwords do **not** rotate automatically when you reset this value to `true`.

<Warning>
  <h4>Important</h4>
  Disabling password rotation can jeopardize compliance with security certifications - make sure you weigh this risk alongside the convenience of SSH-tunneling access.
</Warning>

## Storage Engine

It's best to use the InnoDB storage engine wherever possible instead of MyISAM.
If MyISAM tables have been inadvertently created or imported in your environments
(if you see `ENGINE=MyISAM` in the response to `SHOW CREATE TABLE EXISTING_TABLE`),
convert them to use the InnoDB storage engine as follows:

1. Rename the existing table.

2. Create a new table from the data in the existing table.

Now when you run `SHOW CREATE TABLE EXISTING_TABLE`, you see `ENGINE=InnoDB`.

## Service timezone

To change the timezone for a given connection, run `SET time_zone = TIMEZONE;`.

## Exporting data

To download all data from your SQL database, use the Upsun Cloud CLI.
If you have a single SQL database, the following command exports all data to a local file:

```bash theme={null}
upsun db:dump
```

If you have multiple SQL databases, you are prompted for which one to export.
You can also specify a database by its relationship name:

### Compression

By default, the file is uncompressed.
To compress it, use the `--gzip` (`-z`) option:

```bash theme={null}
upsun db:dump --gzip
```

### Using the output in bash

To pipe the result to another command, use the `--stdout` option.
For example, to create a bzip2-compressed file, run:

```bash theme={null}
upsun db:dump --stdout | bzip2 > dump.sql.bz2
```

## Importing data

To load data into a database, pipe an SQL dump through the `upsun sql` command, like so:

```bash theme={null}
upsun sql < my_database_backup.sql
```

That runs the database backup against the SQL database on Upsun Cloud.
That works for any SQL file, so the usual caveats about importing an SQL dump apply
(for example, it's best to run against an empty database).

As with exporting, you can specify a specific environment and a specific database relationship to use:

<Note>
  Importing a database backup is a destructive operation.
  It overwrites data already in your database.
  It's best to run it against an empty database.
  If not, make a backup or do a database export before importing.
</Note>

## Sanitizing data

To ensure people who review code changes can't access personally identifiable information stored in your database,
[sanitize your preview environments](/docs/development/sanitize-db).

## Large databases

Upsun Cloud supports MariaDB and Oracle MySQL databases of any size, including multi-terabyte deployments. The same service configuration applies whether your database holds gigabytes or tens of terabytes. Only the resources you allocate to it differ.

### Cloning at any size

When you create a [preview environment](/docs/environments), Upsun Cloud clones the entire parent environment (including its database) at the storage layer. The clone completes in seconds to under a minute regardless of database size. A 10 TB database clones in roughly the same time as a 10 GB one. Service start-up time also stays largely the same with larger datasets on these engines.

### What drives performance

Total disk size is rarely the limiting factor for query performance. What matters is the **active dataset** (or working set), the subset of rows, indexes, and pages your application actually reads and writes.

A 10 TB database that serves queries against 5 GB of hot data can outperform a 50 GB database. The smaller database performs worse if it scans entire tables on every request. As long as the active dataset fits in the [InnoDB buffer pool](https://mariadb.com/kb/en/innodb-buffer-pool/), queries are served from memory without touching disk.

By contrast, queries that read most of a table become more expensive as the table grows. The same is true of indexes that effectively scan the whole table.

### Sizing for large datasets

Memory is the lever that keeps the active dataset hot. MariaDB and Oracle MySQL containers use the [`HIGH_MEMORY` container profile](/docs/manage-resources/adjust-resources#advanced-container-profiles) by default. Combined with [Guaranteed CPU](/docs/manage-resources/guaranteed-resources), you can allocate up to **512 GB of RAM** to a single database container.

To work efficiently with a large database:

* Size memory to fit the active dataset in the InnoDB buffer pool. The buffer pool is derived from the container's available memory. See the [troubleshooting guide](/docs/add-services/mysql/troubleshoot#too-many-connections) for the exact formula.
* Make sure queries hit indexes, and avoid full table scans on large tables.
* Watch index selectivity. An index that scans most of a large table on each query loads gigabytes into memory, evicting the active dataset.
* Use [`EXPLAIN`](https://mariadb.com/kb/en/explain/) to verify which indexes a query uses and how many rows it examines.

Disk size alone, even into the multi-terabyte range, does not determine database performance. It determines what data you can store. Memory and query patterns determine how fast you can serve it.

## Replication

There is no on-site primary/replica support in your environments.

In rare cases (such as for certain backup purposes),
you can also enable [remote replication](/docs/add-services/mysql/mysql-replication) to your own replica data.
The replica isn't available to your application.

## Troubleshoot

If you run into issues, [troubleshoot MySQL](/docs/add-services/mysql/troubleshoot).


# MariaDB read-only replication
Source: https://developer.upsun.com/docs/add-services/mysql/mysql-readonly-replication

Configure and access read-only MariaDB replicas to ease the load on a primary database.

<Info>
  <h4>Horizontal autoscaling for replicas</h4>
  You can configure horizontal autoscaling for `mariadb-replica` services. The platform automatically adjusts the number of running replicas based on CPU and/or memory thresholds you define — no redeployment required.

  * Your application is responsible for directing read queries to the replica connection string, available via `PLATFORM_RELATIONSHIPS` under the replica relationship name (e.g. `database-readonly`).
  * Configure autoscaling in the [Console (on the Configure resources tab)](/docs/manage-resources/autoscaling#enable-autoscaling) or by using the [CLI](/cli/install).

  To learn more, see [Autoscaling](/docs/manage-resources/autoscaling).
</Info>

You can improve the performance of read-heavy applications by defining read-only replicas of your MariaDB database and then connecting your applications to those replicas.

Examples of read-heavy applications include:

* Listing pages or dashboards
* Reporting or analytics jobs
* Background jobs that frequently query data

<Info>
  <h4>Note</h4>

  * **Replication is asynchronous**: Delays of a few milliseconds might occur between writes on the primary database and reads on the replica database.
  * **Replicas are read-only**: This restriction ensures data consistency and integrity. Attempts to modify data will result in an SQL error.
</Info>

### Read-only vs. external replicas

Read-only replicas are used primarily to improve application performance by distributing database read requests from read-heavy applications.

Other common use cases for read-only replicas include:

* Cross-region backup: Replicating data to different geographical regions
* Data warehousing: Extracting data from production to analytics projects

[External replicas](/docs/add-services/mysql/mysql-replication) reside on remote servers and have different use cases, including disaster recovery.

### Replica scope and sharing services

MariaDB services (which provide access to databases and replicas) defined in a project cannot be accessed by or shared with applications in other projects.

## 1. Configure the primary and replica services

The following code fragment defines two MariaDB services: a primary and a replica. You can use this fragment as a template by copying it into your `.upsun/config.yaml` file.

Be sure to:

* Replace `VERSION` with the [supported MariaDB version](/docs/add-services/mysql#supported-versions) that you need.
* **Important:** Use `replicator` as the endpoint name when you define the replica service. This is a special endpoint name that the replica service uses to connect to the database.

<Warning>
  The primary and replica services must use the **same MariaDB version**.
  Mismatched versions between `mariadb` and `mariadb-replica` prevent replication from working.
</Warning>

### How it works

Using the sample code fragment above:

1. The primary service (`db`) defines an additional `replicator` endpoint, granting the `replication` privilege. This enables a replica to connect and continuously replicate data from the primary database.

   ```yaml theme={null}
   replicator:
     privileges:
       main: replication
   ```

2. The replica services (`db-replica1` and `db-replica2`) use the `mariadb-replica` image type and connect back to the primary database service through the primary relationship. This establishes a replication link from `db` (the source) to `db-replica` (the target).

   ```yaml theme={null}
   relationships:
     primary: db:replicator
   ```

The `db-replica1` and `db-replica2` replica services continuously stream data from the primary endpoint, maintaining a read-only copy of the primary database content. Write operations are not permitted on the replicas.

## 2. Define the relationship between the application and the replicas

Even if your application won't access the replication endpoint, you must expose the endpoint to an application as a relationship so that you can connect to it over SSH.

Define a new relationship in your application container, as shown below:

```yaml .upsun/config.yaml theme={null}
applications: 
  myapp:
    #... other properties

    # Relationships enable an app container's access to a service.
    relationships:
      # More information: https://developer.upsun.com/docs/configure-apps/image-properties/relationships
      database:
        service: db
        endpoint: main
      database-readonly:
        service: db-replica1
        endpoint: replicator
```

If your application's performance is still not what you expect, you can configure additional replicas as described above.


# MariaDB/MySQL external replication
Source: https://developer.upsun.com/docs/add-services/mysql/mysql-replication

In rare cases, it may be useful to maintain a replica instance of your MySQL/MariaDB database outside of Upsun Cloud on a remote server.

Typically, an automated backup is better for short-term usage and a `mysqldump` for longer term storage, but in some cases the data set is large enough that `mysqldump` is prohibitive.
In that case, you can enable external replication using an extra permission.

This guide explains replication on the Upsun Cloud side only; you must also set up and maintain your own replica instance. Consult the MySQL or MariaDB documentation for details.

## Create a replication user

To set up replication you need to create a replication-enabled user.
For each database that you'd like to replicate, you need to assign a `replication` permission/role, under a corresponding `endpoint`:

The preceding example:

* Creates a `replicator` user.
* Grants read-only and table locking rights on the `main` database (namely `Select_priv`, `Show_view_priv`, `Create_tmp_table_priv`, `Lock_tables_priv` privileges).
* Grants global replication rights (namely `Repl_slave_priv` and `Repl_client_priv` privileges).
* Grants flushing rights (`Reload_priv` used for flushing before reading the binary log position).
* If at least one `replication` permission is defined, the bin-logging is enabled on the primary server, which is essential for the replication.

## Define a relationship for the new endpoint

Even if your application won’t access the replication endpoint, you still need to expose it to an application as a relationship so that you can connect to it over SSH.
Add a new relationship to your application container:

```yaml .upsun/config.yaml theme={null}
applications:
  # The name of the app container. Must be unique within a project.
  myapp:
    # The location of the application's code.
    source:
      root: "/"

    [...]

    # Relationships enable an app container's access to a service.
    relationships:
      database:
        service: mariadb
        endpoint: mysql
      replication:
        service: mariadb
        endpoint: replicator

```

## Get the primary's binary log co-ordinates

Open the MySQL CLI to the `replication` relationship, either by accessing the credentials while on the app container or using the following command.

```bash theme={null}
upsun sql -r replication
```

Now you need to prevent any changes to the data while you view the binary log position. You'll use this to tell the replica at exactly which point it should start replicating from. On the primary server, flush and lock all tables by running `FLUSH TABLES WITH READ LOCK`. Keep this session running - exiting it releases the lock. Get the current position in the binary log by running `SHOW MASTER STATUS`:

```sql theme={null}
mysql> FLUSH TABLES WITH READ LOCK;
Query OK, 0 rows affected (0.016 sec)

mysql> SHOW MASTER STATUS;
+-----------------+----------+--------------+------------------+
| File            | Position | Binlog_Do_DB | Binlog_Ignore_DB |
+-----------------+----------+--------------+------------------+
| binlogs.000002  |  1036    | dflt         |                  |
+-----------------+----------+--------------+------------------+
```

Record the `File` and `Position` details. If binary logging has just been enabled, these are blank. Now, with the lock still in place, copy the data from the primary to the replica.

Login to the app container, then run:

```sh theme={null}
# Dump the data from primary. Note that it dumps only the databases, which "replicator" user has access to.
$ mysqldump --all-databases --single-transaction -h database.internal -P 3306 -u replicator -p > /path/to/dump.sql
```

Download the dump file, then move it to the server where your replica lives so that the replica can import it.

```bash theme={null}
# Copy the dump to your replica
$ mysql -u root < /path/to/dump.sql
```

Note for live databases: It is sufficient to make a local copy of the data; you don’t need to keep the primary locked until the replica has imported the data. Once the `mysqldump` has completed, you can release the lock on the primary by running `UNLOCK TABLES`.

```sql theme={null}
mysql> UNLOCK TABLES;
```

## Set up the replica

### Configure the replica

As mentioned above you have to set up a replica on your own. Assuming that you have a running MariaDB/MySQL replica instance, give the replica a unique `server_id` (distinct from primary). You can find out primary's `server_id` by running:

```sql theme={null}
mysql> SHOW VARIABLES LIKE 'server_id';

+---------------+-------+
| Variable_name | Value |
+---------------+-------+
| server_id     | 1     |
+---------------+-------+
```

Then set a distinct `server_id` number (e.g. server\_id+1) in your replica config (e.g. `my.cnf`) under:

```
[mysqld]
server_id=2
```

Next, reload the replica instance for the changes to take effect.

### Set up SSH tunneling

You need to set up an SSH tunnel from the replica server to the primary, tunneled through the application.

<Note>
  The SSH tunnel is interrupted every time the environment redeploys. For replication to continue you must set up an auto-restart for the tunnel. There are many ways to do so that are out of the scope of this documentation.
</Note>

You can set up an SSH tunnel using one of the following methods:

* Manually using SSH. Using this method makes it easier to set up an auto-restart for the tunnel. Consult the SSH documentation for details on setting up the tunnel and the auto-restart.

* Run the following Upsun Cloud CLI command
  (replacing `<BRANCH_NAME>` with the name of your production branch):

  ```bash theme={null}
    upsun tunnel:open --project <PROJECT_ID> --environment <BRANCH_NAME>
  ```

  This command opens local SSH tunnels to all services accessible from the application.

To configure an auto-restart, you need the project's SSH address, which you can retrieve by running:

```bash theme={null}
upsun ssh --pipe --project <PROJECT_ID>
```

For details about this command, see the [Upsun Cloud CLI reference](/cli/reference#environmentssh).

### Binary log retention and cleanup

When replication is disabled, the MariaDB service stops managing the binary logs and they remain on the file system. **You must delete these logs manually**. If the remote replica has been unreachable for some time, these logs can consume a significant amount of storage.

### Start the Replica

Once the data has been imported, you are ready to start replicating. Begin by running a `CHANGE MASTER TO`, making sure that `MASTER_LOG_FILE` matches the file and `MASTER_LOG_POS` the position returned by the earlier `SHOW MASTER STATUS` on the Upsun Cloud database. For example:

```sql theme={null}
mysql> CHANGE MASTER TO
  MASTER_HOST='<REPLICATION_HOST>',
  MASTER_USER='replicator',
  MASTER_PASSWORD='<REPLICATION_PASSWORD>',
  MASTER_PORT=3306,
  MASTER_LOG_FILE='binlogs.000002',
  MASTER_LOG_POS=1036,
  MASTER_CONNECT_RETRY=10;
```

Where `<REPLICATION_HOST>` varies depending on the SSH tunneling configuration you have, and the `<REPLICATION_PASSWORD>` can be obtained by running `upsun ssh env`.

Now start the replica with the `START SLAVE` command:

```sql theme={null}
mysql> START SLAVE;
```

Check that the replication is working by running the `SHOW SLAVE STATUS` command:

```sql theme={null}
mysql> SHOW SLAVE STATUS \G
```

If replication is working correctly, the values of both `Slave_IO_Running` and `Slave_SQL_Running` should be `Yes`:

```sql theme={null}
Slave_IO_Running: Yes
Slave_SQL_Running: Yes
```

### \[Optional/Troubleshooting] Skipping invalid binary log queries

In some cases, after applying primary's dump to the replica and starting the replica, you might experience replication errors (`Slave_SQL_Running: No` and `Error:` in the output of `SHOW SLAVE STATUS \G` above). Each of such errors needs a careful inspection, but you might be able to just skip some of them. For example:

```sql theme={null}
mysql> STOP SLAVE; SET GLOBAL SQL_SLAVE_SKIP_COUNTER = 1; START SLAVE;
mysql> SHOW SLAVE STATUS \G
```

In case you have multiple errors you would need to repeat the steps above (preferred) or set `SQL_SLAVE_SKIP_COUNTER` (which corresponds to skipping the next N events from the primary) to a larger value.


# Troubleshoot MySQL
Source: https://developer.upsun.com/docs/add-services/mysql/troubleshoot



For more general information, see how to [troubleshoot development](/docs/troubleshooting/general).

## Lock wait timeout

If a process running in your application acquired a lock from MySQL for a long period of time,
you receive MySQL error messages like this:

```sql theme={null}
SQLSTATE[HY000]: General error: 1205 Lock wait timeout exceeded;
```

This is typically caused by one of the following:

* There are multiple places acquiring locks in different order.
  For example, code path 1 first locks record A and then locks record B,
  while code path 2 first locks record B and then locks record A.
* There is a long-running background process executed by your application that holds the lock until it ends.

If you're using [MariaDB 10+](/docs/add-services/mysql), use the SQL query `SHOW FULL PROCESSLIST \G` to list DB queries waiting for locks.
To determine where to debug, find output like the following:

```sql theme={null}
< skipped >
Command: Query
Time: ...
State: Waiting for table metadata lock
Info: SELECT ...
< skipped >
```

To find active background processes, run `ps aufx` on your application container.

Make sure that locks are acquired in a pre-defined order and released as soon as possible.

## Definer/invoker of view lack rights to use them

There is a single MySQL user, so you cannot use the "DEFINER" Access Control mechanism for Stored Programs and Views.

When creating a `VIEW`, you may need to explicitly set the `SECURITY` parameter to `INVOKER`:

```sql theme={null}
CREATE OR REPLACE SQL SECURITY INVOKER
VIEW `view_name` AS
SELECT
```

## Server has gone away

### Disk space issues

Errors such as `PDO Exception 'MySQL server has gone away'` are usually the result of exhausting your available disk space.
Get an estimate of current disk usage using the CLI command `upsun db:size`.
Note that this is an estimate, not an exact value.

Allocate more space to the service by running the `upsun resources:set` command.
For more information, see how to [manage resources](/docs/manage-resources).

As table space can grow rapidly,
set your database mount size to twice the size reported by the `db:size` command.

Consider adding a [low-disk warning](/docs/integrations/notifications#low-disk-warning)
to get notified about low disk space before it becomes an issue.

### Packet size limitations

`MySQL server has gone away` errors may be caused by the size of the database packets.
If so, the logs may show warnings like `Error while sending QUERY packet` before the error.

One way to resolve the issue is to use the [`max_allowed_packet` parameter](/docs/add-services/mysql#configure-the-database).

### Worker timeout

`MySQL server has gone away` errors may be caused by server timeouts.
MySQL has a built-in timeout for idle connections, which defaults to 10 minutes.
Most typical web connections end long before that's ever approached,
but a long-running worker may idle and not need the database for longer than the timeout, leading to a "server has gone away" message.

The best approach is to wrap your connection logic in code that detects a "server has gone away" exception
and tries to re-establish the connection.

Alternatively, if your worker is idle for too long it can self-terminate.
Upsun Cloud automatically restarts the worker process and the new process can establish a new database connection.

## Too many connections

You may get the following [error message](https://mariadb.com/kb/en/e1040/): `Error 1040: Too many connections`.

A common way to solve this issue is to increase the `max_connections` property in your MariaDB service configuration.
However, on Upsun Cloud, you **cannot** configure `max_connections`, as it is calculated automatically based on available memory.

The `max_connections` property cannot be configured in Upsun Cloud service configurations, nor can it be influenced by any other config. It is calculated automatically based on available container memory and increases automatically when the container size increases.

### How it works

The following formula determines `max_connections` for a given container:

```
  avg_memory_per_connection_mb = 4
  free = container_memory - (50 + container_memory * 0.70)
  max_connections = int(free // avg_memory_per_connection_mb)
```

The memory for a given container from its `size` depends on its [container profile](/docs/manage-resources/adjust-resources#advanced-container-profiles).

For example, [MariaDB](/docs/manage-resources/adjust-resources#default-container-profiles) has a [`HIGH_MEMORY` container profile](/docs/manage-resources/adjust-resources#advanced-container-profiles).
For `--size mariadb:1`, this means 1 CPU and 2432 MB of memory.

Using the configuration above, where `--size mariadb:1` is 2432 MB, the calculation becomes:

```
  avg_memory_per_connection_mb = 4
  free = 2432 - (50 + 2432 * 0.70) # 2432 - 1752.4 = 679.6
  max_connections = int(679.6 // 4) # = 169
```

<Note>
  Additionally, `max_connections` has a minimum value of 15 and a maximum value of 500.
  If the result is less than 15, it is set to 15.
  If the result is greater than 500, it is capped at 500.
</Note>


# Network Storage
Source: https://developer.upsun.com/docs/add-services/network-storage



The Network Storage service enables a new kind of [mount](/docs/configure-apps/image-properties/mounts)
that refers to a shared service rather than to a local directory.
This service allows you to store data and share it between different apps.

<Note>
  Writing to network mounts is slightly slower than to local mounts, most noticeably during high-volume sequential
  file creation — in that case, a local mount is more effective. Applications polling network mounts for a new file
  may not immediately detect it even though it exists.

  Detection can be delayed by approximately 30 seconds, so polling logic should account for this delay and not treat
  a missing file as an error until that window has passed.
</Note>

## Supported versions

You can select the major and minor version.

Patch versions are applied periodically for bug fixes and other maintenance updates. By default, you get the latest available patches each time you deploy. If your project has a [maintenance window](/docs/core-concepts/build-deploy#maintenance-window) configured, Upsun Cloud applies patches only during that window. Upsun Cloud may still apply urgent or critical fixes outside of the maintenance window.

* <span>1.0</span>

This service is the Upsun Cloud network storage implementation, not the version of a third-party application.

<Warning>
  It isn't possible to upgrade or downgrade the network storage service version while keeping existing data in place.
  Changing the service version requires that the service be reinitialized.
  Any change to the service version results in existing data becoming inaccessible.
</Warning>

## Deprecated versions

The following versions are still available in your projects,
but they're at their end of life and are no longer receiving security updates from upstream.

* <span>2.0</span>

To ensure your project remains stable in the future,switch to a [supported version](#supported-versions).

## Retired versions

The following versions have been retired and are no longer available.
If your project uses a retired version, you must update to a [supported version](#supported-versions).

*No retired versions.*

## Usage example

### 1. Configure the service

To define the service, use the `network-storage` type:

`SERVICE_NAME` must be [RFC 1123](https://tools.ietf.org/html/rfc1123) compliant, since it's used as the network storage's hostname:

* At most 63 characters
* Lowercase alphanumeric characters or `-` only (no underscores)
* Starts and ends with an alphanumeric character

Name the service for what it stores, for example, `shared-uploads`.

<Warning>
  Changing the name of an existing service replaces it with a brand new service and all existing data is lost.
  Back up your data before changing the service.
</Warning>

### 2. Add the mount

To define the mount accessible by your application, use the following configuration:

* `<TARGET_PATH>` is the path to your mount within the app container (relative to the app’s root).
* `SERVICE_NAME` is the name you [defined in step 1](#1-configure-the-service).
* `<SOURCE_PATH>` specifies where the mount points inside the service.<br />
  If the `source_path` is an empty string (`""`), your mount points to the entire service.<br />
  If you don’t define a `source_path`, Upsun Cloud uses the `MOUNT_PATH` as default value, without leading or trailing slashes.
  For example, if your mount lives in the `/my/files/` directory within your app container, it will point to a `my/files` directory within the service.

### Example configuration

## Multi-application usage

If your project contains [multiple apps](/docs/configure-apps/multi-app),
they may [share `storage` mounts](/docs/configure-apps/image-properties/mounts#share-a-mount-between-several-apps).

Alternatively, they may use shared `service` mounts.
If the `source_path` is the same for both apps,
the files are shared between the two applications even if the mount location is different.

It's also possible to have one app mount a `source_path` that's a subdirectory of another application's mount.
For example:

```yaml .upsun/config.yaml theme={null}
applications:
  # The name of the app container. Must be unique within a project.
  app1:
    # The location of the application's code.
    source:
      root: "app1"

    [...]

    mounts:
      # The path to your mount within the app container (relative to the app's root).
      'web/uploads':
        # Specifies that the mount points to a network storage service that can be shared between apps.
        source: service
        # The name of the network storage service the mount points to.
        service: shared-uploads
        # Specifies where your mount points inside the external directory that is mounted to your app container.
        source_path: uploads

  # The name of the app container. Must be unique within a project.
  app2:
    # The location of the application's code.
    source:
      root: "app2"

    [...]

    mounts:
      # The path to your mount within the app container (relative to the app's root).
      'process':
        # Specifies that the mount points to a network storage service that can be shared between apps.
        source: service
        # The name of the network storage service the mount points to.
        service: shared-uploads
        # Specifies where your mount points inside the external directory that is mounted to your app container.
        # Since the target is the uploads directory app1's mount already points to,
        # the network storage service is effectively shared between app1 and app2.
        source_path: uploads/incoming
      # The path to your mount within the app container (relative to the app's root).
      'done':
        # Specifies that the mount points to a network storage service that can be shared between apps.
        source: service
        # The name of the network storage service the mount points to.
        service: shared-uploads
        # Specifies where your mount points inside the external directory that is mounted to your app container.
        # Since the target is the uploads directory app1's mount already points to,
        # the network storage service is effectively shared between app1 and app2.
        source_path: uploads/done
```

In this example, `app1` has access to the entire `uploads` directory by writing to `web/uploads`.
`app2` has two mounts that it can write to: `process` and `done`.
The `process` mount refers to the same directory as the `web/uploads/incoming` directory does on `app1`,
and the `done` mount refers to the same directory as the `web/uploads/done` directory on `app1`.

## How do I give my workers access to my main application’s files?

If you need to use a worker with access to the same file mount as your web-serving app,
define all the necessary mounts as `service` mounts.

The following example assumes a Network Storage service named `files` has been defined in `.upsun/config.yaml`.
Drupal files directories are shared between the `web` and `worker` instances,
while the Drush backup directory is unique to the `web` instance.

## How can I migrate data from a `storage` mount to a `service` mount?

Network Storage `service` mounts can be shared between different apps,
while `storage` mounts can only be shared between different *instances* of the same app.
To move data from a `storage` mount to a `service` one, follow these instructions.

Assuming you have the following `storage` mount:

```yaml .upsun/config.yaml theme={null}
applications:
  myapp:

    [...]

    mounts:
      web/uploads:
        source: storage
        source_path: uploads
```

1. Add a new `network-storage` service to your configuration, naming it `shared-uploads`:

<Note>
  Make sure you [allocate enough disk space](/docs/manage-resources/adjust-resources#vertical-scaling) to your `shared-uploads` service
  for your existing files with some buffer.
</Note>

2. Add a new `service` mount, named `new-uploads`:

Note that each mount is on a different storage service, which is why they can have the same `source_path`.

3. Deploy your changes.

4. Copy all your files from the `storage` (`web/uploads`) mount to the `service` (`new-uploads`) mount using `rsync`:

   ```bash theme={null}
   rsync -avz web/uploads/* new-uploads/
   ```

5. Reverse the mounts.
   To do so, rename the `storage` mount to `old-uploads`, and point the `web/uploads` directory to the `service` mount:

6) Push your changes and check that the files are now accessible from the `service` mount (now named `web/uploads`).
   To check that no files were lost during the transfer, run the following command:

   ```bash theme={null}
   rsync -avz old-uploads/* web/uploads/
   ```

7) Delete the contents of the `old-uploads` `storage` mount before removing it.

8) Push your changes again.


# OpenSearch (search service)
Source: https://developer.upsun.com/docs/add-services/opensearch

OpenSearch is a distributed RESTful search engine built for the cloud.


See the [OpenSearch documentation](https://opensearch.org/docs/latest/) for more information.

To switch from Elasticsearch, follow the same procedure as for [upgrading](#upgrading).

## Supported versions

In the list below, notice that there you only specify the major version.
Each version represents a rolling release of the latest minor version available from the upstream.
The latest compatible minor version and patches are applied automatically.

* <span>3</span>

## Deprecated versions

The following versions are still available in your projects,
but they're at their end of life and are no longer receiving security updates from upstream,
or are no longer the recommended way to configure the service on Upsun Cloud.

* <span>2</span>

To ensure your project remains stable in the future,
switch to [a supported version](#supported-versions).

## Retired versions

The following versions have been retired and are no longer available.
If your project uses a retired version, you must update to a [supported version](#supported-versions).

* <span>1.2</span>
* <span>1.1</span>
* <span>1</span>

## Relationship reference

For each service [defined via a relationship](#usage-example) to your application,
Upsun Cloud automatically generates corresponding environment variables within your application container,
in the `$<RELATIONSHIP-NAME>_<SERVICE-PROPERTY>` format.

Here is example information available through the [service environment variables](/docs/development/variables#service-environment-variables) themselves,
or through the [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables).

<Tabs>
  <Tab title="Service environment variables">
    You can obtain the complete list of available service environment variables in your app container by running `upsun ssh env`.

    Note that the information about the relationship can change when an app is redeployed or restarted or the relationship is changed. So your apps should only rely on the [service environment variables](/docs/development/variables#service-environment-variables) directly rather than hard coding any values.
  </Tab>

  <Tab title="`PLATFORM_RELATIONSHIPS` environment variable">
    For some advanced use cases, you can use the [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables).
    The structure of the `PLATFORM_RELATIONSHIPS` environment variable can be obtained by running `upsun relationships` in your terminal:

    Here is an example of how to gather [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables) information in a [`.environment` file](/docs/development/variables/set-variables#when-to-use-env-files):

    ```bash .environment theme={null}
    # Decode the built-in credentials object variable.
    export RELATIONSHIPS_JSON="$(echo "$PLATFORM_RELATIONSHIPS" | base64 --decode)"

    # Set environment variables for individual credentials.
    export APP_OPENSEARCH_HOST="$(echo "$RELATIONSHIPS_JSON" | jq -r '.opensearch[0].host')"
    ```
  </Tab>
</Tabs>

## Usage example

### 1. Configure the service

To define the service, use the `opensearch` type:

Note that changing the name of the service replaces it with a brand new service and all existing data is lost. Back up your data before changing the service.

### 2. Define the relationship

To define the relationship, use the following configuration:

<Tabs>
  <Tab title="Using default endpoints">
    You can define `SERVICE_NAME` as you like, so long as it's unique between all defined services
    and matches in both the application and services configuration.

    The example above leverages [default endpoint](/docs/configure-apps/image-properties/relationships) configuration for relationships.
    That is, it uses default endpoints behind the scenes, providing a [relationship](/docs/configure-apps/image-properties/relationships)
    (the network address a service is accessible from) that is identical to the *name* of that service.

    Depending on your needs, instead of default endpoint configuration,
    you can use [explicit endpoint configuration](/docs/configure-apps/image-properties/relationships).

    With the above definition, the application container (`APP_NAME`) now has [access to the service](#use-in-app) via the relationship `SERVICE_NAME` and its corresponding [service environment variables](/docs/development/variables#service-environment-variables).
  </Tab>

  <Tab title="Using explicit endpoints">
    You can define `SERVICE_NAME` and `<RELATIONSHIP_NAME>` as you like, so long as it's unique between all defined services and relationships
    and matches in both the application and services configuration.

    The example above leverages [explicit endpoint](/docs/configure-apps/image-properties/relationships) configuration for relationships.

    Depending on your needs, instead of explicit endpoint configuration,
    you can use [default endpoint configuration](/docs/configure-apps/image-properties/relationships).

    With the above definition, the application container now has [access to the service](#use-in-app) via the relationship `<RELATIONSHIP_NAME>` and its corresponding [service environment variables](/docs/development/variables#service-environment-variables).
  </Tab>
</Tabs>

### Example configuration

### Use in app

To use the configured service in your app, add a configuration file similar to the following to your project.

This configuration defines a single application (`myapp`), whose source code exists in the `<PROJECT_ROOT>/myapp` directory.<br />
`myapp` has access to the `opensearch` service, via a relationship whose name is [identical to the service name](#2-define-the-relationship)
(as per [default endpoint](/docs/configure-apps/image-properties/relationships) configuration for relationships).

From this, `myapp` can retrieve access credentials to the service through the [relationship environment variables](#relationship-reference).

```bash myapp/.environment theme={null}
# Set environment variables for individual credentials.
# For more information, please visit /docs/development/variables#service-environment-variables.
export OS_SCHEME="${OPENSEARCH_SCHEME}"
export OS_HOST="${OPENSEARCH_HOST}"
export OS_PORT="${OPENSEARCH_PORT}"

# Surface more common OpenSearch connection string variables for use in app.
export OS_USERNAME="${OPENSEARCH_USERNAME}"
export OS_PASSWORD="${OPENSEARCH_PASSWORD}"
export OPENSEARCH_HOSTS=[\"$OS_SCHEME://$OS_HOST:$OS_PORT\"]
```

The above file — `.environment` in the `myapp` directory — is automatically sourced by Upsun Cloud into the runtime environment, so that the variable `OPENSEARCH_HOSTS` can be used within the application to connect to the service.

Note that `OPENSEARCH_HOSTS`, and all Upsun Cloud [service environment variables](/docs/development/variables#service-environment-variables) like `OPENSEARCH_HOST`, are environment-dependent.
Unlike the build produced for a given commit,
they can’t be reused across environments and only allow your app to connect to a single service instance on a single environment.

A file very similar to this is generated automatically for your when using the `upsun ify` command to [migrate a codebase to Upsun Cloud](/docs/get-started).

<Note>
  When you create an index on OpenSearch,
  don't specify the `number_of_shards` or `number_of_replicas` settings in your OpenSearch API call.
  These values are set automatically based on available resources.
</Note>

## Authentication

By default, OpenSearch has no authentication.
No username or password is required to connect to it.

You may optionally enable HTTP Basic authentication.
To do so, include the following in your `.upsun/config.yaml` configuration:

That enables mandatory HTTP Basic auth on all requests.
The credentials are available in any relationships that point at that service,
in the `OPENSEARCH_USERNAME` and `OPENSEARCH_PASSWORD` [service environment variables](/docs/development/variables#service-environment-variables).

You can obtain the complete list of available service environment variables in your app container by running `upsun ssh env`.

Note that the information about the relationship can change when an app is redeployed or restarted or the relationship is changed. So your apps should only rely on the [service environment variables](/docs/development/variables#service-environment-variables) directly rather than hard coding any values.

This functionality is generally not required if OpenSearch isn't exposed on its own public HTTP route.
However, certain applications may require it, or it allows you to safely expose OpenSearch directly to the web.
To do so, add a route to `.upsun/config.yaml` that has `opensearch:opensearch` as its upstream
(where `opensearch` is whatever you named the service).
For example:

```yaml .upsun/config.yaml theme={null}
routes:
  "https://www.os.{default}/":
    type: redirect
    to: "https://os.{default}/"
  "https://os.{default}/":
    type: upstream
    upstream: "opensearch:opensearch"

services:
  # The name of the service container. Must be unique within a project.
  opensearch:
    configuration:
      authentication:
        enabled: true
```

## Plugins

OpenSearch offers a number of plugins.
To enable them, list them under the `configuration.plugins` key in your `.upsun/config.yaml` file, like so:

```yaml .upsun/config.yaml theme={null}
services:
  # The name of the service container. Must be unique within a project.
  opensearch:
    configuration:
      plugins:
        - analysis-icu
```

In this example you'd have the ICU analysis plugin and the size mapper plugin.

If there is a publicly available plugin you need that isn't listed here, [contact support](/docs/core-concepts/get-support).

### Available plugins

This is the complete list of plugins that can be enabled:

| Plugin | Description | 1 | 2 | 3 | | | | |
| - | - | - | - | - | - | - | - | - |
| `analysis-icu` | Support ICU Unicode text analysis | \* | \* | \* | | | | |
| `analysis-kuromoji` | Japanese language support | \* | \* | \* | | | | |
| `analysis-nori` | Integrates Lucene Nori analysis module into OpenSearch | \* | \* | \* | | | | |
| `analysis-phonetic` | Phonetic analysis | \* | \* | \* | | | | |
| `analysis-smartcn` | Smart Chinese Analysis Plugins | \* | \* | \* | | | | |
| `analysis-stempel` | Stempel Polish Analysis Plugin | \* | \* | \* | | | | |
| `analysis-ukrainian` | Ukrainian language support | \* | \* | \* | | | | |
| `ingest-attachment` | Extract file attachments in common formats (such as PPT, XLS, and PDF) | \* | \* | \* | | | | |
| `mapper-annotated-text` | Adds support for text fields with markup used to inject annotation tokens into the index | \* | \* | \* | | | | |
| `mapper-murmur3` | Murmur3 mapper plugin for computing hashes at index-time | \* | \* | \* | | | | |
| `mapper-size` | Size mapper plugin, enables the `_size` meta field | \* | \* | \* | | \* | \* | \* |

### Alternative plugins

These plugins are currently available for OpenSearch `2.0` and `3.0`. The names below show exactly how they should be added to your configuration. For example, to use the `alerting` plugin, specify it in your `.upsun/config.yaml` as so:

<Warning>
  <h4>Different names used</h4>
  It should be noted that **these names may differ to what they are commonly known as in the [OpenSearch docs](https://opensearch.org/docs/latest/).** To help your understanding of what each plugin does, please click each plugin for a link to the corresponding GitHub repositories.
</Warning>

| Plugin | Description | 1 | 2 | 3 |
| - | - | - | - | - |
| [`alerting`](https://github.com/opensearch-project) | Monitor data and send alert notifications automatically | N/A | \* | \* |
| [`opensearch-anomaly-detection`](https://github.com/opensearch-project/anomaly-detection) | Detect anomalies as your log data and monitor data in near real time | N/A | \* | \* |
| [`asynchronous-search`](https://github.com/opensearch-project/asynchronous-search) | Run search queries in the background and retrieve results as they become available | N/A | \* | \* |
| [`opensearch-cross-cluster-replication`](https://github.com/opensearch-project/cross-cluster-replication) | Replicate data across two OpenSearch clusters | N/A | \* | \* |
| [`opensearch-custom-codecs`](https://github.com/opensearch-project/custom-codecs) | Provide custom Lucene codecs for loading through Apache Lucene's `NamedSPILoader` | N/A | \* | \* |
| [`opensearch-flow-framework`](https://github.com/opensearch-project/flow-framework) | Innovate AI applications on OpenSearch | N/A | \* | \* |
| [`notifications`](https://github.com/opensearch-project/notifications) | A central location for all of your notifications from OpenSearch plugins | N/A | \* | \* |
| [`opensearch-reports-scheduler`](https://github.com/opensearch-project/reporting) | Export and share reports from OpenSearch Dashboards dashboards, saved search, alerts and visualizations | N/A | \* | \* |
| [`geospatial`](https://github.com/opensearch-project/geospatial) | An OpenSearch plugin that contains geospatial specific features | N/A | \* | \* |
| [`opensearch-index-management`](https://github.com/opensearch-project/index-management) | A suite of features to monitor and manage indexes | N/A | \* | \* |
| [`opensearch-job-scheduler`](https://github.com/opensearch-project/job-scheduler) | Schedule periodical jobs running within OpenSearch nodes | N/A | \* | \* |
| [`opensearch-knn`](https://github.com/opensearch-project/k-NN) | Easily run the nearest neighbor search on billions of documents | N/A | \* | \* |
| [`opensearch-ml-plugin`](https://github.com/opensearch-project/ml-commons/) | Leverage existing open source machine learning algorithms | N/A | \* | \* |
| [`opensearch-skills`](https://github.com/opensearch-project/skills) | Provides tools for ml-common's agent framework OpenSearch ml-commons | N/A | \* | \* |
| [`neural-search`](https://github.com/opensearch-project/neural-search) | Index documents and conduct a neural search on indexed documents | N/A | \* | \* |
| [`opensearch-observability`](https://github.com/opensearch-project/observability) | Collection of plugins and applications that let you visualize data-driven events | N/A | \* | \* |
| [`performance-analyzer`](https://github.com/opensearch-project/performance-analyzer) | A REST API that allows you to query numerous performance metrics | N/A | \* | \* |
| [`opensearch-sql-plugin`](https://github.com/opensearch-project/sql) | Extract insights out of OpenSearch using the familiar SQL or Piped Processing Language (PPL) query syntax | N/A | \* | \* |

### Plugin removal

Removing plugins previously added in your `.upsun/config.yaml` file doesn't automatically uninstall them from your OpenSearch instances.
This is deliberate, as removing a plugin may result in data loss or corruption of existing data that relied on that plugin.
Removing a plugin usually requires reindexing.

To permanently remove a previously enabled plugin,
[upgrade the service](#upgrading) to create a new instance of OpenSearch and migrate to it.
In most cases it isn't necessary as an unused plugin has no appreciable impact on the server.

## Upgrading

The OpenSearch data format sometimes changes between versions in incompatible ways.
OpenSearch doesn't include a data upgrade mechanism as it's expected that all indexes can be regenerated from stable data if needed.
To upgrade (or downgrade) OpenSearch, use a new service from scratch.

There are two approaches.

### Destructive upgrade

In your `.upsun/config.yaml` file, change the version *and* name of your OpenSearch service.
Be sure to also update the reference to the now changed service name in it's corresponding application's `relationship` block.

When you push that to Upsun Cloud, the old service is deleted and a new one with the new name is created with no data.
You can then have your application reindex data as appropriate.

This approach has the downsides of temporarily having an empty OpenSearch instance,
which your application may or may not handle gracefully, and needing to rebuild your index afterward.
Depending on the size of your data that could take a while.

### Transitional upgrade

With a transitional approach, you temporarily have two OpenSearch services.
Add a second OpenSearch service with the new version a new name and give it a new relationship in `.upsun/config.yaml`.
You can optionally run in that configuration for a while to allow your application to populate indexes in the new service as well.

Once you're ready to switch over, remove the old OpenSearch service and relationship.
You may optionally have the new OpenSearch service use the old relationship name if that's easier for your app to handle.
Your application is now using the new OpenSearch service.

This approach has the benefit of never being without a working OpenSearch instance.
On the downside, it requires two running OpenSearch servers temporarily,
each of which consumes resources and needs adequate disk space.
Depending on the size of your data, that may be a lot of disk space.

## Exporting data

The export procedure for OpenSearch is identical to [Elasticsearch](/docs/add-services/elasticsearch#exporting-data),
using the [Snapshot and Restore API](https://opensearch.org/docs/latest/tuning-your-cluster/availability-and-recovery/snapshots/snapshot-restore/).

1. Open an SSH tunnel:

```bash Terminal theme={null}
upsun tunnel:single --relationship <RELATIONSHIP_NAME>
```

2. Register a snapshot repository:

```bash Terminal theme={null}
curl -X PUT "http://127.0.0.1:9200/_snapshot/my_backup" \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "fs",
    "settings": {
      "location": "/tmp/os-snapshots"
    }
  }'
```

3. Trigger a snapshot:

```bash Terminal theme={null}
curl -X PUT "http://127.0.0.1:9200/_snapshot/my_backup/snapshot_1?wait_for_completion=true"
```

4. Download the snapshot from the container:

```bash Terminal theme={null}
upsun ssh -- tar -czf /tmp/os-snapshot.tar.gz /tmp/os-snapshots
upsun scp remote:/tmp/os-snapshot.tar.gz ./os-snapshot.tar.gz
```


# PostgreSQL (Database service)
Source: https://developer.upsun.com/docs/add-services/postgresql/index



PostgreSQL is a high-performance, standards-compliant relational SQL database.

See the [PostgreSQL documentation](https://www.postgresql.org/docs/9.6/index.html) for more information.

<Note>
  The [example](#usage-example) provided later in this topic is specific to using only a **primary** database. For details about using read-only replicas to improve performance of read-heavy applications, see the [PostgreSQL read-only replication](/docs/add-services/postgresql/postgresql-readonly-replication) topic.
</Note>

## Supported versions

You can select the major version. But the latest compatible minor version is applied automatically and can’t be overridden.

Patch versions are applied periodically for bug fixes and other maintenance updates. By default, you get the latest available patches each time you deploy. If your project has a [maintenance window](/docs/core-concepts/build-deploy#maintenance-window) configured, Upsun Cloud applies patches only during that window. Upsun Cloud may still apply urgent or critical fixes outside of the maintenance window.

* <span>18</span>
* <span>17</span>
* <span>16</span>
* <span>15</span>
* <span>14</span>

<Note>
  You can't upgrade to PostgreSQL 12 with the `postgis` extension enabled.
  For more details, see how to [upgrade to PostgreSQL 12 with `postgis`](#upgrade-to-postgresql-12-with-the-postgis-extension).
</Note>

## Deprecated versions

The following versions are still available in your projects,
but they're at their end of life and are no longer receiving security updates from upstream.

*No deprecated versions.*

To ensure your project remains stable in the future, switch to a [supported version](#supported-versions).

## Retired versions

The following versions have been retired and are no longer available.
If your project uses a retired version, you must update to a [supported version](#supported-versions).

* <span>13</span>
* <span>12</span>
* <span>11</span>
* <span>10</span>
* <span>9.6</span>
* <span>9.5</span>
* <span>9.3</span>

## Relationship reference

For each service [defined via a relationship](#usage-example) to your application,
Upsun Cloud automatically generates corresponding environment variables within your application container,
in the `$<RELATIONSHIP-NAME>_<SERVICE-PROPERTY>` format.

Here is example information available through the [service environment variables](/docs/development/variables#service-environment-variables) themselves,
or through the [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables).

<Tabs>
  <Tab title="Service environment variables">
    You can obtain the complete list of available service environment variables in your app container by running `upsun ssh env`.

    Service connection details can change whenever your app restarts or redeploys. **To keep your connection stable, use [service environment variables](/docs/development/variables#service-environment-variables) rather than hard-coding values.**
  </Tab>

  <Tab title="`PLATFORM_RELATIONSHIPS` environment variable">
    For some advanced use cases, you can use the [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables).
    The structure of the `PLATFORM_RELATIONSHIPS` environment variable can be obtained by running `upsun relationships` in your terminal:

    Here is an example of how to gather [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables) information in a [`.environment` file](/docs/development/variables/set-variables#when-to-use-env-files):

    ```bash .environment theme={null}
    # Decode the built-in credentials object variable.
    export RELATIONSHIPS_JSON="$(echo "$PLATFORM_RELATIONSHIPS" | base64 --decode)"

    # Set environment variables for individual credentials.
    export APP_POSTGRESQL_HOST="$(echo "$RELATIONSHIPS_JSON" | jq -r '.postgresql[0].host')"
    ```
  </Tab>
</Tabs>

## Usage example

<Info>
  Use the steps and sample code below if your application will connect to a **primary** PostgreSQL database. For details about using read-only replicas to improve performance of read-heavy applications, see the [PostgreSQL read-only replication](/docs/add-services/postgresql/postgresql-readonly-replication) topic.
</Info>

### 1. Configure the service

To define the service, use the `postgresql` type:

Note that changing the name of the service replaces it with a brand new service and all existing data is lost. Back up your data before changing the service.

### 2. Define the relationship

To define the relationship, use the following configuration:

<Tabs>
  <Tab title="Using default endpoints">
    You can define `SERVICE_NAME` as you like, so long as it's unique between all defined services
    and matches in both the application and services configuration.

    The example above leverages [default endpoint](/docs/configure-apps/image-properties/relationships) configuration for relationships.
    That is, it uses default endpoints behind the scenes, providing a [relationship](/docs/configure-apps/image-properties/relationships)
    (the network address a service is accessible from) that is identical to the *name* of that service.

    Depending on your needs, instead of default endpoint configuration,
    you can use [explicit endpoint configuration](/docs/configure-apps/image-properties/relationships).

    With the above definition, the application container (`APP_NAME`) now has access to the service via the relationship `SERVICE_NAME` and its corresponding [service environment variables](/docs/development/variables#service-environment-variables).
  </Tab>

  <Tab title="Using explicit endpoints">
    You can define `SERVICE_NAME` and `<RELATIONSHIP_NAME>` as you like, so long as it's unique between all defined services and relationships
    and matches in both the application and services configuration.

    The example above leverages [explicit endpoint](/docs/configure-apps/image-properties/relationships) configuration for relationships.

    Depending on your needs, instead of explicit endpoint configuration,
    you can use [default endpoint configuration](/docs/configure-apps/image-properties/relationships).

    With the above definition, the application container now has [access to the service](#use-in-app) via the relationship `<RELATIONSHIP_NAME>` and its corresponding [service environment variables](/docs/development/variables#service-environment-variables).
  </Tab>
</Tabs>

For PHP, enable the [extension](/docs/languages/php/extensions) for the service:

### Example configuration

### Use in app

To use the configured service in your app, add a configuration file similar to the following to your project.

This configuration defines a single application (`myapp`), whose source code exists in the `<PROJECT_ROOT>/myapp` directory.<br />
`myapp` has access to the `postgresql` service, via a relationship whose name is [identical to the service name](#2-define-the-relationship)
(as per [default endpoint](/docs/configure-apps/image-properties/relationships) configuration for relationships).

From this, `myapp` can retrieve access credentials to the service through the [relationship environment variables](#relationship-reference).

```bash myapp/.environment theme={null}
# Set environment variables for individual credentials.
# For more information, please visit /docs/development/variables#service-environment-variables.
export DB_CONNECTION="${POSTGRESQL_SCHEME}"
export DB_USERNAME="${POSTGRESQL_USERNAME}"
export DB_PASSWORD="${POSTGRESQL_PASSWORD}"
export DB_HOST="${POSTGRESQL_HOST}"
export DB_PORT="${POSTGRESQL_PORT}"
export DB_DATABASE="${POSTGRESQL_PATH}"

# Surface connection string variable for use in app.
export DATABASE_URL="${DB_CONNECTION}://${DB_USERNAME}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT}/${DB_DATABASE}"
```

The above file — `.environment` in the `myapp` directory — is automatically sourced by Upsun Cloud into the runtime environment, so that the variable `DATABASE_URL` can be used within the application to connect to the service.

Note that `DATABASE_URL`, and all Upsun Cloud [service environment variables](/docs/development/variables#service-environment-variables) like `POSTGRESQL_HOST`, are environment-dependent.
Unlike the build produced for a given commit,
they can’t be reused across environments and only allow your app to connect to a single service instance on a single environment.

A file very similar to this is generated automatically for your when using the `upsun ify` command to [migrate a codebase to Upsun Cloud](/docs/get-started).

## Access the service directly

Access the service using the Upsun Cloud CLI by running `upsun sql`.

You can also access it from your app container via [SSH](/docs/development/ssh).
From your [relationship data](#relationship-reference), you need: `POSTGRESQL_USERNAME`, `POSTGRESQL_HOST`, and `POSTGRESQL_PORT`.
Then run the following command:

```bash theme={null}
psql -U <POSTGRESQL_USERNAME> -h <POSTGRESQL_HOST> -p <POSTGRESQL_PORT>
```

Using the values from the [example](#relationship-reference), that would be:

```bash theme={null}
psql -U main -h postgresql.internal -p 5432
```

You can obtain the complete list of available service environment variables in your app container by running `upsun ssh env`.

Service connection details can change whenever your app restarts or redeploys. **To keep your connection stable, use [service environment variables](/docs/development/variables#service-environment-variables) rather than hard-coding values.**

## Exporting data

The easiest way to download all data in a PostgreSQL instance is with the Upsun Cloud CLI. If you have a single SQL database, the following command exports all data using the `pg_dump` command to a local file:

```bash theme={null}
upsun db:dump
```

If you have multiple SQL databases it prompts you which one to export. You can also specify one by relationship name explicitly:

```bash theme={null}
upsun db:dump --relationship postgresql
```

By default the file is uncompressed. If you want to compress it, use the `--gzip` (`-z`) option:

```bash theme={null}
upsun db:dump --gzip
```

You can use the `--stdout` option to pipe the result to another command. For example, if you want to create a bzip2-compressed file, you can run:

```bash theme={null}
upsun db:dump --stdout | bzip2 > dump.sql.bz2
```

It is also possible to generate the dump locally if you have the `pg_dump` command installed with `upsun tunnel:single`. The command will first ask for the service and then will provide a prompt for the URI string that you can use. For example:

```bash theme={null}
pg_dump -d postgresql://REPLACE_URI_FROM_OUTPUT -f dump.sql
```

## Importing data

Make sure that the imported file contains objects with cleared ownership and `IF EXISTS` clauses. For example, you can create a DB dump with following parameters:

```bash theme={null}
pg_dump --no-owner --clean --if-exists
```

The easiest way to load data into a database is to pipe an SQL dump through the `upsun sql` command, like so:

```bash theme={null}
upsun sql < my_database_backup.sql
```

That runs the database backup against the SQL database on Upsun Cloud.
That works for any SQL file, so the usual caveats about importing an SQL dump apply
(for example, it's best to run against an empty database).
As with exporting, you can also specify a specific environment to use and a specific database relationship to use, if there are multiple.

<Note>
  Importing a database backup is a destructive operation. It overwrites data already in your database.
  Taking a backup or a database export before doing so is strongly recommended.
</Note>

## Sanitizing data

To ensure people who review code changes can't access personally identifiable information stored in your database,
[sanitize your preview environments](/docs/development/sanitize-db/postgresql).

## Set locale for database

You can choose your locale when a database is created by setting locale-related variables. There are three ways to set a locale option, as detailed in the table below:

| Name | Type | Default | Description |
| - | - | - | - |
| `default_ctype` | `string` | `C.UTF-8` | The default character classification. Affects any tables created after it's set. |
| `default_collation` | `string` | `C.UTF-8` | The default collation rules. Affects any tables created after it's set. |
| `default_charset` | `string` | `UTF8` | The default encoding character set. Affects any tables created after it's set. |

## Multiple databases

Support for defining multiple databases and multiple users with different permissions is available in versions `10` and later of this service.
To do so requires defining multiple endpoints.
Under the `configuration` key of your service there are two additional keys:

* `databases`:  This is a YAML array listing the databases that should be created. If not specified, a single database named `main` is created.

  Note that removing a schema from the list of `schemas` on further deployments results in **the deletion of the schema.**
* `endpoints`: This is a nested YAML object defining different credentials. Each endpoint may have access to one or more schemas (databases), and may have different levels of permission for each. The valid permission levels are:
  * `ro`: Using this endpoint only `SELECT` queries are allowed.
  * `rw`: Using this endpoint `SELECT` queries as well as `INSERT`/`UPDATE`/`DELETE` queries are allowed.
  * `admin`: Using this endpoint all queries are allowed, including DDL queries (`CREATE TABLE`, `DROP TABLE`, etc.).

Consider the following illustrative example:

This example creates a single PostgreSQL service named `postgresql`. The server has two databases, `main` and `legacy` with three endpoints created.

* `admin`: has full access to both databases.
* `reporter`: has `SELECT` query access to the `main` database, but no access to `legacy`.
* `importer`: has `SELECT`/`INSERT`/`UPDATE`/`DELETE` access (but not DDL access) to the `legacy` database. It doesn't have access to `main`.

If a given endpoint has access to multiple databases you should also specify which is listed by default in the relationships array. If one isn't specified, the `path` property of the relationship is `null`. While that may be acceptable for an application that knows the name of the database it's connecting to, automated tools like the Upsun Cloud CLI can't access the database on that relationship. For that reason, defining the `default_database` property is always recommended.

Once these endpoints are defined, you need to expose them to your application as a relationship. Continuing with the above example, your `relationships` in `.upsun/config.yaml` might look like:

Each database is accessible to your application through the `database`, `reports`, and `imports` relationships.
They'll be available in the [service environment variables](/docs/development/variables#service-environment-variables) and all have the same structure documented [above](#relationship-reference), but with different credentials. You can use those to connect to the appropriate database with the specified restrictions using whatever the SQL access tools are for your language and application.

A service configuration without the `configuration` block defined is equivalent to the following default values:

If you do not define `database` but `endpoints` are defined, then the single database `main` is created with the following assumed configuration:

Alternatively, if you define multiple databases but no endpoints, a single user `main` is created with `admin` access to each of your databases, equivalent to the configuration below:

## Password generation

If your YAML file does not specify a `schema` and `endpoint` for a database service, no password is generated.

Because your database is isolated on a private network and cannot be seen from the internet, you can omit a password without compromising security. This simplifies your workflow by removing the need to manage credentials, while container isolation ensures that only your application can access the data.

If you prefer to have Upsun Cloud generate a password, you must define [`schemas` and custom `endpoints`](#1-configure-the-service) in the `services` configuration – see the example in the [multiple databases](#multiple-databases) section of this topic.
For each custom endpoint that you define, Upsun Cloud generates a password. Note that you cannot customize these generated passwords.

<Note>
  Make sure you don't change `services.<SERVICE_NAME>`. **Changing the service name creates a new service,
  which removes existing data from your database.**
</Note>

After your custom endpoints are exposed as relationships in your [app configuration](/docs/configure-apps),
you can retrieve the password for each endpoint
through the [service environment variables](/docs/development/variables#service-environment-variables)
within your [application containers](/docs/development/variables/use-variables#access-variables-in-your-app).

Using this method to retrieve password credentials is considered a best practice: passwords might change over time, and using incorrect passwords results in application downtime. **Avoid using hard-coded passwords in your application (and code base), which can cause security issues.**

## Service timezone

To change the timezone for the current session, run `SET TIME ZONE <TIMEZONE>;`.

## Extensions

Upsun Cloud supports a number of PostgreSQL extensions. To enable them, list them under the `configuration.extensions` key in your `.upsun/config.yaml` file, like so:

In this case, you have `pg_trgm` installed, providing functions to determine the similarity of text based on trigram matching, and `hstore` providing a key-value store.

### Available extensions

The following is the extensive list of supported extensions. Note that you can't currently add custom
extensions not listed here.

<div>
  <div><div><table><thead><tr><th>Extension</th><th>Description</th><th>Supported versions</th></tr></thead><tbody><tr><td><code>address\_standardizer</code></td><td>Used to parse an address into constituent elements. Generally used to support geocoding address normalization step.</td><td><div><span>18.3</span><span>18</span><span>17.9</span><span>17</span><span>16.13</span><span>16</span><span>15.17</span><span>15</span><span>14.22</span><span>14</span><span>13.23</span><span>13</span><span>12.22</span><span>12</span><span>11.22</span><span>11</span><span>10.22</span><span>10</span><span>9.6</span><span>9.5</span><span>9.3</span></div></td></tr><tr><td><code>address\_standardizer\_data\_us</code></td><td>For standardizing addresses based on US dataset example.</td><td><div><span>18.3</span><span>18</span><span>17.9</span><span>17</span><span>16.13</span><span>16</span><span>15.17</span><span>15</span><span>14.22</span><span>14</span><span>13.23</span><span>13</span><span>12.22</span><span>12</span><span>11.22</span><span>11</span><span>10.22</span><span>10</span><span>9.6</span><span>9.5</span><span>9.3</span></div></td></tr><tr><td><code>adminpack</code></td><td>Administrative functions for PostgreSQL (only available in versions less than 17).</td><td><div><span>18.3</span><span>18</span><span>17.9</span><span>17</span><span>16.13</span><span>16</span><span>15.17</span><span>15</span><span>14.22</span><span>14</span><span>13.23</span><span>13</span><span>12.22</span><span>12</span><span>11.22</span><span>11</span><span>10.22</span><span>10</span><span>9.6</span><span>9.5</span><span>9.3</span></div></td></tr><tr><td><code>autoinc</code></td><td>Functions for auto-incrementing fields.</td><td><div><span>18.3</span><span>18</span><span>17.9</span><span>17</span><span>16.13</span><span>16</span><span>15.17</span><span>15</span><span>14.22</span><span>14</span><span>13.23</span><span>13</span><span>12.22</span><span>12</span><span>11.22</span><span>11</span><span>10.22</span><span>10</span><span>9.6</span><span>9.5</span><span>9.3</span></div></td></tr><tr><td><code>bloom</code></td><td>Bloom access method - signature file based index (requires 9.6 or higher).</td><td><div><span>18.3</span><span>18</span><span>17.9</span><span>17</span><span>16.13</span><span>16</span><span>15.17</span><span>15</span><span>14.22</span><span>14</span><span>13.23</span><span>13</span><span>12.22</span><span>12</span><span>11.22</span><span>11</span><span>10.22</span><span>10</span><span>9.6</span><span>9.5</span><span>9.3</span></div></td></tr><tr><td><code>btree\_gin</code></td><td>Support for indexing common data types in GIN.</td><td><div><span>18.3</span><span>18</span><span>17.9</span><span>17</span><span>16.13</span><span>16</span><span>15.17</span><span>15</span><span>14.22</span><span>14</span><span>13.23</span><span>13</span><span>12.22</span><span>12</span><span>11.22</span><span>11</span><span>10.22</span><span>10</span><span>9.6</span><span>9.5</span><span>9.3</span></div></td></tr><tr><td><code>btree\_gist</code></td><td>Support for indexing common data types in GiST.</td><td><div><span>18.3</span><span>18</span><span>17.9</span><span>17</span><span>16.13</span><span>16</span><span>15.17</span><span>15</span><span>14.22</span><span>14</span><span>13.23</span><span>13</span><span>12.22</span><span>12</span><span>11.22</span><span>11</span><span>10.22</span><span>10</span><span>9.6</span><span>9.5</span><span>9.3</span></div></td></tr><tr><td><code>chkpass</code></td><td>Data type for auto-encrypted passwords.</td><td><div><span>18.3</span><span>18</span><span>17.9</span><span>17</span><span>16.13</span><span>16</span><span>15.17</span><span>15</span><span>14.22</span><span>14</span><span>13.23</span><span>13</span><span>12.22</span><span>12</span><span>11.22</span><span>11</span><span>10.22</span><span>10</span><span>9.6</span><span>9.5</span><span>9.3</span></div></td></tr><tr><td><code>citext</code></td><td>Data type for case-insensitive character strings.</td><td><div><span>18.3</span><span>18</span><span>17.9</span><span>17</span><span>16.13</span><span>16</span><span>15.17</span><span>15</span><span>14.22</span><span>14</span><span>13.23</span><span>13</span><span>12.22</span><span>12</span><span>11.22</span><span>11</span><span>10.22</span><span>10</span><span>9.6</span><span>9.5</span><span>9.3</span></div></td></tr><tr><td><code>cube</code></td><td>Data type for multidimensional cubes.</td><td><div><span>18.3</span><span>18</span><span>17.9</span><span>17</span><span>16.13</span><span>16</span><span>15.17</span><span>15</span><span>14.22</span><span>14</span><span>13.23</span><span>13</span><span>12.22</span><span>12</span><span>11.22</span><span>11</span><span>10.22</span><span>10</span><span>9.6</span><span>9.5</span><span>9.3</span></div></td></tr><tr><td><code>dblink</code></td><td>Connect to other PostgreSQL databases from within a database.</td><td><div><span>18.3</span><span>18</span><span>17.9</span><span>17</span><span>16.13</span><span>16</span><span>15.17</span><span>15</span><span>14.22</span><span>14</span><span>13.23</span><span>13</span><span>12.22</span><span>12</span><span>11.22</span><span>11</span><span>10.22</span><span>10</span><span>9.6</span><span>9.5</span><span>9.3</span></div></td></tr><tr><td><code>dict\_int</code></td><td>Text search dictionary template for integers.</td><td><div><span>18.3</span><span>18</span><span>17.9</span><span>17</span><span>16.13</span><span>16</span><span>15.17</span><span>15</span><span>14.22</span><span>14</span><span>13.23</span><span>13</span><span>12.22</span><span>12</span><span>11.22</span><span>11</span><span>10.22</span><span>10</span><span>9.6</span><span>9.5</span><span>9.3</span></div></td></tr><tr><td><code>dict\_xsyn</code></td><td>Text search dictionary template for extended synonym processing.</td><td><div><span>18.3</span><span>18</span><span>17.9</span><span>17</span><span>16.13</span><span>16</span><span>15.17</span><span>15</span><span>14.22</span><span>14</span><span>13.23</span><span>13</span><span>12.22</span><span>12</span><span>11.22</span><span>11</span><span>10.22</span><span>10</span><span>9.6</span><span>9.5</span><span>9.3</span></div></td></tr><tr><td><code>earthdistance</code></td><td>Calculate great-circle distances on the surface of the Earth.</td><td><div><span>18.3</span><span>18</span><span>17.9</span><span>17</span><span>16.13</span><span>16</span><span>15.17</span><span>15</span><span>14.22</span><span>14</span><span>13.23</span><span>13</span><span>12.22</span><span>12</span><span>11.22</span><span>11</span><span>10.22</span><span>10</span><span>9.6</span><span>9.5</span><span>9.3</span></div></td></tr><tr><td><code>file\_fdw</code></td><td>Foreign-data wrapper for flat file access.</td><td><div><span>18.3</span><span>18</span><span>17.9</span><span>17</span><span>16.13</span><span>16</span><span>15.17</span><span>15</span><span>14.22</span><span>14</span><span>13.23</span><span>13</span><span>12.22</span><span>12</span><span>11.22</span><span>11</span><span>10.22</span><span>10</span><span>9.6</span><span>9.5</span><span>9.3</span></div></td></tr><tr><td><code>fuzzystrmatch</code></td><td>Determine similarities and distance between strings.</td><td><div><span>18.3</span><span>18</span><span>17.9</span><span>17</span><span>16.13</span><span>16</span><span>15.17</span><span>15</span><span>14.22</span><span>14</span><span>13.23</span><span>13</span><span>12.22</span><span>12</span><span>11.22</span><span>11</span><span>10.22</span><span>10</span><span>9.6</span><span>9.5</span><span>9.3</span></div></td></tr><tr><td><code>hstore</code></td><td>Data type for storing sets of (key, value) pairs.</td><td><div><span>18.3</span><span>18</span><span>17.9</span><span>17</span><span>16.13</span><span>16</span><span>15.17</span><span>15</span><span>14.22</span><span>14</span><span>13.23</span><span>13</span><span>12.22</span><span>12</span><span>11.22</span><span>11</span><span>10.22</span><span>10</span><span>9.6</span><span>9.5</span><span>9.3</span></div></td></tr><tr><td><code>insert\_username</code></td><td>Functions for tracking who changed a table.</td><td><div><span>18.3</span><span>18</span><span>17.9</span><span>17</span><span>16.13</span><span>16</span><span>15.17</span><span>15</span><span>14.22</span><span>14</span><span>13.23</span><span>13</span><span>12.22</span><span>12</span><span>11.22</span><span>11</span><span>10.22</span><span>10</span><span>9.6</span><span>9.5</span><span>9.3</span></div></td></tr><tr><td><code>intagg</code></td><td>Integer aggregator and enumerator (obsolete).</td><td><div><span>18.3</span><span>18</span><span>17.9</span><span>17</span><span>16.13</span><span>16</span><span>15.17</span><span>15</span><span>14.22</span><span>14</span><span>13.23</span><span>13</span><span>12.22</span><span>12</span><span>11.22</span><span>11</span><span>10.22</span><span>10</span><span>9.6</span><span>9.5</span><span>9.3</span></div></td></tr><tr><td><code>intarray</code></td><td>Functions, operators, and index support for 1-D arrays of integers.</td><td><div><span>18.3</span><span>18</span><span>17.9</span><span>17</span><span>16.13</span><span>16</span><span>15.17</span><span>15</span><span>14.22</span><span>14</span><span>13.23</span><span>13</span><span>12.22</span><span>12</span><span>11.22</span><span>11</span><span>10.22</span><span>10</span><span>9.6</span><span>9.5</span><span>9.3</span></div></td></tr><tr><td><code>isn</code></td><td>Data types for international product numbering standards.</td><td><div><span>18.3</span><span>18</span><span>17.9</span><span>17</span><span>16.13</span><span>16</span><span>15.17</span><span>15</span><span>14.22</span><span>14</span><span>13.23</span><span>13</span><span>12.22</span><span>12</span><span>11.22</span><span>11</span><span>10.22</span><span>10</span><span>9.6</span><span>9.5</span><span>9.3</span></div></td></tr><tr><td><code>lo</code></td><td>Large Object maintenance.</td><td><div><span>18.3</span><span>18</span><span>17.9</span><span>17</span><span>16.13</span><span>16</span><span>15.17</span><span>15</span><span>14.22</span><span>14</span><span>13.23</span><span>13</span><span>12.22</span><span>12</span><span>11.22</span><span>11</span><span>10.22</span><span>10</span><span>9.6</span><span>9.5</span><span>9.3</span></div></td></tr><tr><td><code>ltree</code></td><td>Data type for hierarchical tree-like structures.</td><td><div><span>18.3</span><span>18</span><span>17.9</span><span>17</span><span>16.13</span><span>16</span><span>15.17</span><span>15</span><span>14.22</span><span>14</span><span>13.23</span><span>13</span><span>12.22</span><span>12</span><span>11.22</span><span>11</span><span>10.22</span><span>10</span><span>9.6</span><span>9.5</span><span>9.3</span></div></td></tr><tr><td><code>moddatetime</code></td><td>Functions for tracking last modification time.</td><td><div><span>18.3</span><span>18</span><span>17.9</span><span>17</span><span>16.13</span><span>16</span><span>15.17</span><span>15</span><span>14.22</span><span>14</span><span>13.23</span><span>13</span><span>12.22</span><span>12</span><span>11.22</span><span>11</span><span>10.22</span><span>10</span><span>9.6</span><span>9.5</span><span>9.3</span></div></td></tr><tr><td><code>pageinspect</code></td><td>Inspect the contents of database pages at a low level.</td><td><div><span>18.3</span><span>18</span><span>17.9</span><span>17</span><span>16.13</span><span>16</span><span>15.17</span><span>15</span><span>14.22</span><span>14</span><span>13.23</span><span>13</span><span>12.22</span><span>12</span><span>11.22</span><span>11</span><span>10.22</span><span>10</span><span>9.6</span><span>9.5</span><span>9.3</span></div></td></tr><tr><td><code>pg\_buffercache</code></td><td>Examine the shared buffer cache.</td><td><div><span>18.3</span><span>18</span><span>17.9</span><span>17</span><span>16.13</span><span>16</span><span>15.17</span><span>15</span><span>14.22</span><span>14</span><span>13.23</span><span>13</span><span>12.22</span><span>12</span><span>11.22</span><span>11</span><span>10.22</span><span>10</span><span>9.6</span><span>9.5</span><span>9.3</span></div></td></tr><tr><td><code>pg\_freespacemap</code></td><td>Examine the free space map (FSM).</td><td><div><span>18.3</span><span>18</span><span>17.9</span><span>17</span><span>16.13</span><span>16</span><span>15.17</span><span>15</span><span>14.22</span><span>14</span><span>13.23</span><span>13</span><span>12.22</span><span>12</span><span>11.22</span><span>11</span><span>10.22</span><span>10</span><span>9.6</span><span>9.5</span><span>9.3</span></div></td></tr><tr><td><code>pg\_prewarm</code></td><td>Prewarm relation data (requires 9.6 or higher).</td><td><div><span>18.3</span><span>18</span><span>17.9</span><span>17</span><span>16.13</span><span>16</span><span>15.17</span><span>15</span><span>14.22</span><span>14</span><span>13.23</span><span>13</span><span>12.22</span><span>12</span><span>11.22</span><span>11</span><span>10.22</span><span>10</span><span>9.6</span><span>9.5</span><span>9.3</span></div></td></tr><tr><td><code>pg\_stat\_statements</code></td><td>Track execution statistics of all SQL statements executed.</td><td><div><span>18.3</span><span>18</span><span>17.9</span><span>17</span><span>16.13</span><span>16</span><span>15.17</span><span>15</span><span>14.22</span><span>14</span><span>13.23</span><span>13</span><span>12.22</span><span>12</span><span>11.22</span><span>11</span><span>10.22</span><span>10</span><span>9.6</span><span>9.5</span><span>9.3</span></div></td></tr><tr><td><code>pg\_trgm</code></td><td>Text similarity measurement and index searching based on trigrams.</td><td><div><span>18.3</span><span>18</span><span>17.9</span><span>17</span><span>16.13</span><span>16</span><span>15.17</span><span>15</span><span>14.22</span><span>14</span><span>13.23</span><span>13</span><span>12.22</span><span>12</span><span>11.22</span><span>11</span><span>10.22</span><span>10</span><span>9.6</span><span>9.5</span><span>9.3</span></div></td></tr><tr><td><code>pg\_visibility</code></td><td>Examine the visibility map (VM) and page-level visibility info (requires 9.6 or higher).</td><td><div><span>18.3</span><span>18</span><span>17.9</span><span>17</span><span>16.13</span><span>16</span><span>15.17</span><span>15</span><span>14.22</span><span>14</span><span>13.23</span><span>13</span><span>12.22</span><span>12</span><span>11.22</span><span>11</span><span>10.22</span><span>10</span><span>9.6</span><span>9.5</span><span>9.3</span></div></td></tr><tr><td><code>pgcrypto</code></td><td>Cryptographic functions.</td><td><div><span>18.3</span><span>18</span><span>17.9</span><span>17</span><span>16.13</span><span>16</span><span>15.17</span><span>15</span><span>14.22</span><span>14</span><span>13.23</span><span>13</span><span>12.22</span><span>12</span><span>11.22</span><span>11</span><span>10.22</span><span>10</span><span>9.6</span><span>9.5</span><span>9.3</span></div></td></tr><tr><td><code>pgrouting</code></td><td>pgRouting Extension (requires 9.6 or higher).</td><td><div><span>18.3</span><span>18</span><span>17.9</span><span>17</span><span>16.13</span><span>16</span><span>15.17</span><span>15</span><span>14.22</span><span>14</span><span>13.23</span><span>13</span><span>12.22</span><span>12</span><span>11.22</span><span>11</span><span>10.22</span><span>10</span><span>9.6</span><span>9.5</span><span>9.3</span></div></td></tr><tr><td><code>pgrowlocks</code></td><td>Show row-level locking information.</td><td><div><span>18.3</span><span>18</span><span>17.9</span><span>17</span><span>16.13</span><span>16</span><span>15.17</span><span>15</span><span>14.22</span><span>14</span><span>13.23</span><span>13</span><span>12.22</span><span>12</span><span>11.22</span><span>11</span><span>10.22</span><span>10</span><span>9.6</span><span>9.5</span><span>9.3</span></div></td></tr><tr><td><code>pgstattuple</code></td><td>Show tuple-level statistics.</td><td><div><span>18.3</span><span>18</span><span>17.9</span><span>17</span><span>16.13</span><span>16</span><span>15.17</span><span>15</span><span>14.22</span><span>14</span><span>13.23</span><span>13</span><span>12.22</span><span>12</span><span>11.22</span><span>11</span><span>10.22</span><span>10</span><span>9.6</span><span>9.5</span><span>9.3</span></div></td></tr><tr><td><code>plpgsql</code></td><td>PL/pgSQL procedural language.</td><td><div><span>18.3</span><span>18</span><span>17.9</span><span>17</span><span>16.13</span><span>16</span><span>15.17</span><span>15</span><span>14.22</span><span>14</span><span>13.23</span><span>13</span><span>12.22</span><span>12</span><span>11.22</span><span>11</span><span>10.22</span><span>10</span><span>9.6</span><span>9.5</span><span>9.3</span></div></td></tr><tr><td><code>postgis</code></td><td>PostGIS geometry, geography, and raster spatial types and functions.</td><td><div><span>18.3</span><span>18</span><span>17.9</span><span>17</span><span>16.13</span><span>16</span><span>15.17</span><span>15</span><span>14.22</span><span>14</span><span>13.23</span><span>13</span><span>12.22</span><span>12</span><span>11.22</span><span>11</span><span>10.22</span><span>10</span><span>9.6</span><span>9.5</span><span>9.3</span></div></td></tr><tr><td><code>postgis\_sfcgal</code></td><td>PostGIS SFCGAL functions.</td><td><div><span>18.3</span><span>18</span><span>17.9</span><span>17</span><span>16.13</span><span>16</span><span>15.17</span><span>15</span><span>14.22</span><span>14</span><span>13.23</span><span>13</span><span>12.22</span><span>12</span><span>11.22</span><span>11</span><span>10.22</span><span>10</span><span>9.6</span><span>9.5</span><span>9.3</span></div></td></tr><tr><td><code>postgis\_tiger\_geocoder</code></td><td>PostGIS tiger geocoder and reverse geocoder.</td><td><div><span>18.3</span><span>18</span><span>17.9</span><span>17</span><span>16.13</span><span>16</span><span>15.17</span><span>15</span><span>14.22</span><span>14</span><span>13.23</span><span>13</span><span>12.22</span><span>12</span><span>11.22</span><span>11</span><span>10.22</span><span>10</span><span>9.6</span><span>9.5</span><span>9.3</span></div></td></tr><tr><td><code>postgis\_topology</code></td><td>PostGIS topology spatial types and functions.</td><td><div><span>18.3</span><span>18</span><span>17.9</span><span>17</span><span>16.13</span><span>16</span><span>15.17</span><span>15</span><span>14.22</span><span>14</span><span>13.23</span><span>13</span><span>12.22</span><span>12</span><span>11.22</span><span>11</span><span>10.22</span><span>10</span><span>9.6</span><span>9.5</span><span>9.3</span></div></td></tr><tr><td><code>postgres\_fdw</code></td><td>Foreign-data wrapper for remote PostgreSQL servers.</td><td><div><span>18.3</span><span>18</span><span>17.9</span><span>17</span><span>16.13</span><span>16</span><span>15.17</span><span>15</span><span>14.22</span><span>14</span><span>13.23</span><span>13</span><span>12.22</span><span>12</span><span>11.22</span><span>11</span><span>10.22</span><span>10</span><span>9.6</span><span>9.5</span><span>9.3</span></div></td></tr><tr><td><code>refint</code></td><td>Functions for implementing referential integrity (obsolete).</td><td><div><span>18.3</span><span>18</span><span>17.9</span><span>17</span><span>16.13</span><span>16</span><span>15.17</span><span>15</span><span>14.22</span><span>14</span><span>13.23</span><span>13</span><span>12.22</span><span>12</span><span>11.22</span><span>11</span><span>10.22</span><span>10</span><span>9.6</span><span>9.5</span><span>9.3</span></div></td></tr><tr><td><code>seg</code></td><td>Data type for representing line segments or floating-point intervals.</td><td><div><span>18.3</span><span>18</span><span>17.9</span><span>17</span><span>16.13</span><span>16</span><span>15.17</span><span>15</span><span>14.22</span><span>14</span><span>13.23</span><span>13</span><span>12.22</span><span>12</span><span>11.22</span><span>11</span><span>10.22</span><span>10</span><span>9.6</span><span>9.5</span><span>9.3</span></div></td></tr><tr><td><code>sslinfo</code></td><td>Information about SSL certificates.</td><td><div><span>18.3</span><span>18</span><span>17.9</span><span>17</span><span>16.13</span><span>16</span><span>15.17</span><span>15</span><span>14.22</span><span>14</span><span>13.23</span><span>13</span><span>12.22</span><span>12</span><span>11.22</span><span>11</span><span>10.22</span><span>10</span><span>9.6</span><span>9.5</span><span>9.3</span></div></td></tr><tr><td><code>tablefunc</code></td><td>Functions that manipulate whole tables, including crosstab.</td><td><div><span>18.3</span><span>18</span><span>17.9</span><span>17</span><span>16.13</span><span>16</span><span>15.17</span><span>15</span><span>14.22</span><span>14</span><span>13.23</span><span>13</span><span>12.22</span><span>12</span><span>11.22</span><span>11</span><span>10.22</span><span>10</span><span>9.6</span><span>9.5</span><span>9.3</span></div></td></tr><tr><td><code>tcn</code></td><td>Triggered change notifications.</td><td><div><span>18.3</span><span>18</span><span>17.9</span><span>17</span><span>16.13</span><span>16</span><span>15.17</span><span>15</span><span>14.22</span><span>14</span><span>13.23</span><span>13</span><span>12.22</span><span>12</span><span>11.22</span><span>11</span><span>10.22</span><span>10</span><span>9.6</span><span>9.5</span><span>9.3</span></div></td></tr><tr><td><code>timetravel</code></td><td>Trigger-based functions to record and query the history of row changes over time.</td><td><div><span>18.3</span><span>18</span><span>17.9</span><span>17</span><span>16.13</span><span>16</span><span>15.17</span><span>15</span><span>14.22</span><span>14</span><span>13.23</span><span>13</span><span>12.22</span><span>12</span><span>11.22</span><span>11</span><span>10.22</span><span>10</span><span>9.6</span><span>9.5</span><span>9.3</span></div></td></tr><tr><td><code>tsearch2</code></td><td>Compatibility package for pre-8.3 text search functions (obsolete, only available for 9.6 and 9.3).</td><td><div><span>18.3</span><span>18</span><span>17.9</span><span>17</span><span>16.13</span><span>16</span><span>15.17</span><span>15</span><span>14.22</span><span>14</span><span>13.23</span><span>13</span><span>12.22</span><span>12</span><span>11.22</span><span>11</span><span>10.22</span><span>10</span><span>9.6</span><span>9.5</span><span>9.3</span></div></td></tr><tr><td><code>tsm\_system\_rows</code></td><td>TABLESAMPLE method which accepts number of rows as a limit (requires 9.6 or higher).</td><td><div><span>18.3</span><span>18</span><span>17.9</span><span>17</span><span>16.13</span><span>16</span><span>15.17</span><span>15</span><span>14.22</span><span>14</span><span>13.23</span><span>13</span><span>12.22</span><span>12</span><span>11.22</span><span>11</span><span>10.22</span><span>10</span><span>9.6</span><span>9.5</span><span>9.3</span></div></td></tr><tr><td><code>tsm\_system\_time</code></td><td>TABLESAMPLE method which accepts time in milliseconds as a limit (requires 9.6 or higher).</td><td><div><span>18.3</span><span>18</span><span>17.9</span><span>17</span><span>16.13</span><span>16</span><span>15.17</span><span>15</span><span>14.22</span><span>14</span><span>13.23</span><span>13</span><span>12.22</span><span>12</span><span>11.22</span><span>11</span><span>10.22</span><span>10</span><span>9.6</span><span>9.5</span><span>9.3</span></div></td></tr><tr><td><code>unaccent</code></td><td>Text search dictionary that removes accents.</td><td><div><span>18.3</span><span>18</span><span>17.9</span><span>17</span><span>16.13</span><span>16</span><span>15.17</span><span>15</span><span>14.22</span><span>14</span><span>13.23</span><span>13</span><span>12.22</span><span>12</span><span>11.22</span><span>11</span><span>10.22</span><span>10</span><span>9.6</span><span>9.5</span><span>9.3</span></div></td></tr><tr><td><code>uuid-ossp</code></td><td>Generate universally unique identifiers (UUIDs).</td><td><div><span>18.3</span><span>18</span><span>17.9</span><span>17</span><span>16.13</span><span>16</span><span>15.17</span><span>15</span><span>14.22</span><span>14</span><span>13.23</span><span>13</span><span>12.22</span><span>12</span><span>11.22</span><span>11</span><span>10.22</span><span>10</span><span>9.6</span><span>9.5</span><span>9.3</span></div></td></tr><tr><td><code>vector</code></td><td>Open-source vector similarity search for PostgreSQL 11+.</td><td><div><span>18.3</span><span>18</span><span>17.9</span><span>17</span><span>16.13</span><span>16</span><span>15.17</span><span>15</span><span>14.22</span><span>14</span><span>13.23</span><span>13</span><span>12.22</span><span>12</span><span>11.22</span><span>11</span><span>10.22</span><span>10</span><span>9.6</span><span>9.5</span><span>9.3</span></div></td></tr><tr><td><code>xml2</code></td><td>XPath querying and XSLT.</td><td><div><span>18.3</span><span>18</span><span>17.9</span><span>17</span><span>16.13</span><span>16</span><span>15.17</span><span>15</span><span>14.22</span><span>14</span><span>13.23</span><span>13</span><span>12.22</span><span>12</span><span>11.22</span><span>11</span><span>10.22</span><span>10</span><span>9.6</span><span>9.5</span><span>9.3</span></div></td></tr></tbody></table></div></div>
</div>

<PostgreSQLExtensionsTable />

<Note>
  You can't upgrade to PostgreSQL 12 with the `postgis` extension enabled.
  For more details, see how to [upgrade to PostgreSQL 12 with `postgis`](#upgrade-to-postgresql-12-with-the-postgis-extension).
</Note>

## Large databases

Upsun Cloud supports PostgreSQL databases of any size, including multi-terabyte deployments. The same service configuration applies whether your database holds gigabytes or tens of terabytes. Only the resources you allocate to it differ.

### Cloning at any size

When you create a [preview environment](/docs/environments), Upsun Cloud clones the entire parent environment (including its database) at the storage layer. The clone completes in seconds to under a minute regardless of database size. A 10 TB database clones in roughly the same time as a 10 GB one. Service start-up time also stays largely the same with larger datasets on PostgreSQL.

### What drives performance

Total disk size is rarely the limiting factor for query performance. What matters is the **active dataset** (or working set), the subset of rows, indexes, and pages your application actually reads and writes.

A 10 TB database that serves queries against 5 GB of hot data can outperform a 50 GB database. The smaller database performs worse if it scans entire tables on every request. As long as the active dataset fits in PostgreSQL's [shared buffers](https://www.postgresql.org/docs/current/runtime-config-resource.html#GUC-SHARED-BUFFERS) and the operating system's page cache, queries are served from memory without touching disk.

By contrast, queries that read most of a table become more expensive as the table grows. The same is true of indexes that effectively scan the whole table.

### Sizing for large datasets

Memory is the lever that keeps the active dataset hot. PostgreSQL containers use the [`HIGH_MEMORY` container profile](/docs/manage-resources/adjust-resources#advanced-container-profiles) by default. Combined with [Guaranteed CPU](/docs/manage-resources/guaranteed-resources), you can allocate up to **512 GB of RAM** to a single PostgreSQL container.

To work efficiently with a large database:

* Size memory to fit the active dataset in shared buffers and the OS page cache.
* Make sure queries hit indexes, and avoid sequential scans on large tables.
* Watch index selectivity. An index that scans most of a large table on each query loads gigabytes into memory, evicting the active dataset.
* Use [`EXPLAIN (ANALYZE, BUFFERS)`](https://www.postgresql.org/docs/current/sql-explain.html) to verify which indexes a query uses and how much memory it touches.
* Run [`ANALYZE`](https://www.postgresql.org/docs/current/sql-analyze.html) after large data imports to refresh the planner's statistics.

Disk size alone, even into the multi-terabyte range, does not determine database performance. It determines what data you can store. Memory and query patterns determine how fast you can serve it.

## Troubleshooting

### Could not find driver

If you see this error: `Fatal error: Uncaught exception 'PDOException' with message 'could not find driver'`, this means you are missing the `pdo_pgsql` PHP extension. You need to enable it in your `.upsun/config.yaml` ([see above](#1-configure-the-service)).

## Upgrading

PostgreSQL 10 and later include an upgrade utility that can convert databases from previous versions to version 10 or later. If you upgrade your service from a previous version of PostgreSQL to version 10 or above, it upgrades automatically.

The utility can't upgrade PostgreSQL 9 versions, so upgrades from PostgreSQL 9.3 to 9.6 aren't supported. Upgrade straight to version 11 instead.

<Note>
  Make sure you first test your migration on a separate branch.

  Also, be sure to take a backup of your production environment **before** you merge this change.
</Note>

<Warning>
  <h4>Warning</h4>
  Downgrading isn't supported. If you need to downgrade, dump to SQL, remove the service, recreate the service, and import your dump.
</Warning>

### Upgrade to PostgreSQL 12 with the `postgis` extension

You can't upgrade to PostgreSQL 12 with the `postgis` extension enabled.
It involves a change to a major version that results in a failed deployment that requires support intervention to fix.
Upgrading from 12 to a higher version is possible.

If you need to upgrade to version 12, follow the same steps recommended for downgrading:

1. Dump the database.
2. Remove the service.
3. Create a new service with PostgreSQL 12.
4. Import the dump to that service.


# PostgreSQL read-only replication
Source: https://developer.upsun.com/docs/add-services/postgresql/postgresql-readonly-replication

Configure and access read-only PostgreSQL replicas to ease the load on a primary database.

<Info>
  <h4>Horizontal autoscaling for replicas</h4>
  You can configure horizontal autoscaling for `postgresql-replica` services. The platform automatically adjusts the number of running replicas based on CPU and/or memory thresholds you define — no redeployment required.

  * Your application is responsible for directing read queries to the replica connection string, available via `PLATFORM_RELATIONSHIPS` under the replica relationship name (for example, `database-readonly` as defined in your app configuration).
  * Configure autoscaling in the [Console (on the Configure resources tab)](/docs/manage-resources/autoscaling#enable-autoscaling) or by using the [CLI](/cli/install).

  To learn more, see [Autoscaling](/docs/manage-resources/autoscaling).
</Info>

You can improve the performance of read-heavy applications by defining read-only replicas of your PostgreSQL database and then connecting your applications to those replicas.

Examples of read-heavy applications include:

* Listing pages or dashboards
* Reporting or analytics jobs
* Background jobs that frequently query data

<Info>
  <h4>Note</h4>

  * **Replication is asynchronous**: Delays of a few milliseconds might occur between writes on the primary database and reads on the replica database.
  * **Replicas are read-only**: This restriction ensures data consistency and integrity. Attempts to modify data will result in an SQL error.
</Info>

### Replica scope and sharing services

PostgreSQL services (which provide access to databases and replicas) defined in a project cannot be accessed by or shared with applications in other projects.

## 1. Configure the primary and replica services

The following code fragment defines two PostgreSQL services: a primary and a replica. You can use this fragment as a template by copying it into your `.upsun/config.yaml` file.

Be sure to:

* Replace `VERSION` with the [supported PostgreSQL version](/docs/add-services/postgresql#supported-versions) that you need.
* **Important:** Use `replicator` as the endpoint name when you define the replica service. This is a special endpoint name that the replica service uses to connect to the database.

<Warning>
  The primary and replica services must use the **same PostgreSQL version**. Mismatched versions between `postgresql` and `postgresql-replica` prevent replication from working.
</Warning>

### How it works

Using the sample code fragment above:

1. After you define the replicator endpoints, the primary service creates a `replicator` user that has permission to replicate the database. You must specify `replicator` as the endpoint name, as described at the start of this topic.

   ```yaml theme={null}
   endpoints:
     replicator:
       replication: true
   ```

2. In the replica services (in this example, `db-replica1` and `db-replica2`), defining the relationship `primary: db:replicator` ensures that the service can connect to the primary database as the `replicator` user.

   ```yaml theme={null}
   relationships:
     primary: db:replicator
   ```

The `db-replica1` and `db-replica2` replica services continuously stream data from the primary endpoint, maintaining a read-only copy of the primary database content. Write operations are not permitted on the replicas.

## 2. Define the relationship between the application and the replicas

Even if your application won't access the replication endpoint, you must expose the endpoint to an application as a relationship so that you can connect to it over SSH.

Add a new relationship to your application container, as shown below:

```yaml .upsun/config.yaml theme={null}
applications:
  myapp:
    #... other properties
    
    # Relationships enable an app container's access to a service.
    relationships:
      # More information: https://developer.upsun.com/docs/configure-apps/image-properties/relationships
      db:
        service: db
        endpoint: main
      db-replica1:
        service: db-replica1
        endpoint: replicator        
```

If your application's performance is still not what you expect, you can configure additional replicas as described above.


# RabbitMQ (message queue service)
Source: https://developer.upsun.com/docs/add-services/rabbitmq

See how to configure RabbitMQ for your messaging needs.

[RabbitMQ](https://www.rabbitmq.com/documentation.html) is a message broker
that supports multiple messaging protocols, such as the Advanced Message Queuing Protocol (AMQP).
It gives your apps a common platform to send and receive messages
and your messages a safe place to live until they're received.

## Supported versions

You can select the major and minor version.

Patch versions are applied periodically for bug fixes and other maintenance updates. By default, you get the latest available patches each time you deploy. If your project has a [maintenance window](/docs/core-concepts/build-deploy#maintenance-window) configured, Upsun Cloud applies patches only during that window. Upsun Cloud may still apply urgent or critical fixes outside of the maintenance window.

* <span>4.3</span>

## Deprecated versions

The following versions are still available in your projects,
but they're at their end of life and are no longer receiving security updates from upstream.

*No deprecated versions.*

To ensure your project remains stable in the future, switch to a [supported version](#supported-versions).

## Retired versions

The following versions have been retired and are no longer available.
If your project uses a retired version, you must update to a [supported version](#supported-versions).

* <span>4.2</span>
* <span>4.1</span>
* <span>4.0</span>
* <span>3.13</span>
* <span>3.12</span>
* <span>3.11</span>
* <span>3.10</span>
* <span>3.9</span>
* <span>3.8</span>
* <span>3.7</span>
* <span>3.6</span>
* <span>3.5</span>

## Relationship reference

For each service [defined via a relationship](#usage-example) to your application,
Upsun Cloud automatically generates corresponding environment variables within your application container,
in the `$<RELATIONSHIP-NAME>_<SERVICE-PROPERTY>` format.

Here is example information available through the [service environment variables](/docs/development/variables#service-environment-variables) themselves,
or through the [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables).

<Tabs>
  <Tab title="Service environment variables">
    You can obtain the complete list of available service environment variables in your app container by running `upsun ssh env`.

    Note that the information about the relationship can change when an app is redeployed or restarted or the relationship is changed. So your apps should only rely on the [service environment variables](/docs/development/variables#service-environment-variables) directly rather than hard coding any values.
  </Tab>

  <Tab title="`PLATFORM_RELATIONSHIPS` environment variable">
    For some advanced use cases, you can use the [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables).
    The structure of the `PLATFORM_RELATIONSHIPS` environment variable can be obtained by running `upsun relationships` in your terminal:

    Here is an example of how to gather [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables) information in a [`.environment` file](/docs/development/variables/set-variables#when-to-use-env-files):

    ```bash .environment theme={null}
    # Decode the built-in credentials object variable.
    export RELATIONSHIPS_JSON="$(echo "$PLATFORM_RELATIONSHIPS" | base64 --decode)"

    # Set environment variables for individual credentials.
    export APP_RABBITMQ_HOST="$(echo "$RELATIONSHIPS_JSON" | jq -r '.rabbitmq[0].host')"
    ```
  </Tab>
</Tabs>

## Usage example

### 1. Configure the service

To define the service, use the `rabbitmq` type:

Note that changing the name of the service replaces it with a brand new service and all existing data is lost. Back up your data before changing the service.

### 2. Define the relationship

To define the relationship, use the following configuration:

<Tabs>
  <Tab title="Using default endpoints">
    You can define `SERVICE_NAME` as you like, so long as it's unique between all defined services
    and matches in both the application and services configuration.

    The example above leverages [default endpoint](/docs/configure-apps/image-properties/relationships) configuration for relationships.
    That is, it uses default endpoints behind the scenes, providing a [relationship](/docs/configure-apps/image-properties/relationships)
    (the network address a service is accessible from) that is identical to the *name* of that service.

    Depending on your needs, instead of default endpoint configuration,
    you can use [explicit endpoint configuration](/docs/configure-apps/image-properties/relationships).

    With the above definition, the application container (`APP_NAME`) now has access to the service via the relationship `SERVICE_NAME` and its corresponding [service environment variables](/docs/development/variables#service-environment-variables).
  </Tab>

  <Tab title="Using explicit endpoints">
    You can define `SERVICE_NAME` and `<RELATIONSHIP_NAME>` as you like, so long as it's unique between all defined services and relationships
    and matches in both the application and services configuration.

    The example above leverages [explicit endpoint](/docs/configure-apps/image-properties/relationships) configuration for relationships.

    Depending on your needs, instead of explicit endpoint configuration,
    you can use [default endpoint configuration](/docs/configure-apps/image-properties/relationships).

    With the above definition, the application container now has [access to the service](#use-in-app) via the relationship `<RELATIONSHIP_NAME>` and its corresponding [service environment variables](/docs/development/variables#service-environment-variables).
  </Tab>
</Tabs>

### Example configuration

### Use in app

To use the configured service in your app, add a configuration file similar to the following to your project.

This configuration defines a single application (`myapp`), whose source code exists in the `<PROJECT_ROOT>/myapp` directory.<br />
`myapp` has access to the `rabbitmq` service, via a relationship whose name is [identical to the service name](#2-define-the-relationship)
(as per [default endpoint](/docs/configure-apps/image-properties/relationships) configuration for relationships).

From this, `myapp` can retrieve access credentials to the service through the [relationship environment variables](#relationship-reference).

```bash myapp/.environment theme={null}
# Set environment variables for individual credentials.
# For more information, please visit /docs/development/variables#service-environment-variables.
export QUEUE_SCHEME="${RABBITMQ_SCHEME}"
export QUEUE_USERNAME="${RABBITMQ_USERNAME}"
export QUEUE_PASSWORD="${RABBITMQ_PASSWORD}"
export QUEUE_HOST="${RABBITMQ_HOST}"
export QUEUE_PORT="${RABBITMQ_PORT}"

# Set a single RabbitMQ connection string variable for AMQP.
export AMQP_URL="${QUEUE_SCHEME}://${QUEUE_USERNAME}:${QUEUE_PASSWORD}@${QUEUE_HOST}:${QUEUE_PORT}/"
```

The above file — `.environment` in the `myapp` directory — is automatically sourced by Upsun Cloud into the runtime environment, so that the variable `AMQP_URL` can be used within the application to connect to the service.

Note that `AMQP_URL`, and all Upsun Cloud [service environment variables](/docs/development/variables#service-environment-variables) like `RABBITMQ_HOST`, are environment-dependent.
Unlike the build produced for a given commit,
they can’t be reused across environments and only allow your app to connect to a single service instance on a single environment.

A file very similar to this is generated automatically for your when using the `upsun ify` command to [migrate a codebase to Upsun Cloud](/docs/get-started).

## Connect to RabbitMQ

When debugging, you may want to connect directly to your RabbitMQ service.
You can connect in multiple ways:

* An [SSH tunnel](#via-ssh)
* A [web interface](#access-the-management-ui)

In each case, you need the login credentials that you can obtain from the [relationship](#relationship-reference).

### Via SSH

To connect directly to your RabbitMQ service in an environment,
open an SSH tunnel with the [Upsun Cloud CLI](/cli).

To open an SSH tunnel to your service with port forwarding,
run the following command:

```bash theme={null}
upsun tunnel:single --gateway-ports
```

Then configure a RabbitMQ client to connect to this tunnel using the credentials from the [relationship](#relationship-reference).
See a [list of RabbitMQ client libraries](https://www.rabbitmq.com/devtools.html).

### Access the management UI

RabbitMQ offers a [management plugin with a browser-based UI](https://www.rabbitmq.com/management.html).
You can access this UI with an SSH tunnel.

To open a tunnel, follow these steps.

1. SSH into your app container with a flag for local port forwarding:

2. ```bash theme={null}
   ssh $(upsun ssh --pipe) -L 15672:<RELATIONSHIP_NAME>.internal:15672
   ```

   `<RELATIONSHIP_NAME>` is the [name you defined](#2-define-the-relationship).

3. Open `http://localhost:15672` in your browser.
   Log in using the username and password from the [relationship](#relationship-reference).

## Configuration options

You can configure your RabbitMQ service in the [services configuration](#1-configure-the-service) with the following options:

| Name | Type | Required | Description |
| - | - | - | - |
| `vhosts` | List of `string`s | No | Virtual hosts used for logically grouping resources. |

You can configure additional [virtual hosts](https://www.rabbitmq.com/vhosts.html),
which can be useful for separating resources, such as exchanges, queues, and bindings, into their own namespaces.
To create virtual hosts, add them to your configuration as in the following example:

## Upgrading

When upgrading RabbitMQ, skipping major versions (e.g. 3.7 -> 3.11) [is not supported](https://www.rabbitmq.com/upgrade.html#rabbitmq-version-upgradability).
Make sure you upgrade sequentially (3.7 -> 3.8 -> 3.9 -> 3.10 -> 3.11) and that each upgrade commit translates into an actual deployment.

## Exporting Data

RabbitMQ stores durable queues, exchanges, bindings, users, virtual hosts, and policies on disk.
You can export the full definitions (schema + messages metadata) using the RabbitMQ management API.

1. Open an SSH tunnel:

```bash Terminal theme={null}
upsun tunnel:single --relationship <RELATIONSHIP_NAME>
```

2. Export definitions (topology: exchanges, queues, bindings, policies):

```bash Terminal theme={null}
curl -u guest:<RABBITMQ_PASSWORD> \
  http://127.0.0.1:15672/api/definitions \
  -o rabbitmq-definitions.json
```

The management API is available on port `15672`. The default username is `guest`.
Retrieve the password from the service environment variables:

```bash Terminal theme={null}
upsun ssh -- env | grep RABBITMQ_PASSWORD
```

3. To export messages from a specific queue:

```bash Terminal theme={null}
curl -u guest:<RABBITMQ_PASSWORD> \
  -X POST http://127.0.0.1:15672/api/queues/%2F/<QUEUE_NAME>/get \
  -H "Content-Type: application/json" \
  -d '{"count": 10000, "ackmode": "ack_requeue_true", "encoding": "auto"}' \
  -o rabbitmq-messages.json
```

The `definitions.json` file can later be imported into any RabbitMQ instance via:

```bash Terminal theme={null}
curl -u guest:<PASSWORD> \
  -X POST http://<HOST>:15672/api/definitions \
  -H "Content-Type: application/json" \
  -d @rabbitmq-definitions.json
```


# Redis (Object cache)
Source: https://developer.upsun.com/docs/add-services/redis



[Redis](https://redis.io/documentation) is a multi-model database that allows you to store data in memory
for high-performance data retrieval and key-value storage.
Upsun Cloud supports two different Redis configurations:

* [Persistent](#persistent-redis): to set up fast persistent storage for your application
* [Ephemeral](#ephemeral-redis): to set up a non-persistent cache for your application

## Active versions

See [Image statuses](/docs/core-concepts/upgrade-runtimes-services#image-statuses) for what Active means.

You can select the major and minor version.

Patch versions are applied periodically for bug fixes and other maintenance updates. By default, you get the latest available patches each time you deploy. If your project has a [maintenance window](/docs/core-concepts/build-deploy#maintenance-window) configured, Upsun Cloud applies patches only during that window. Upsun Cloud may still apply urgent or critical fixes outside of the maintenance window.

* <span>8.8</span>
* <span>8.0</span>
* <span>7.2</span>

## Sunset versions

The following versions are still available in your projects, including code pushes, but new projects can't use them.
These versions are decommissioned 180 calendar days after entering Sunset — the exact decommission date is shown on your project's Overview page and on the relevant activity in the **Activity** panel. See [Image statuses](/docs/core-concepts/upgrade-runtimes-services#image-statuses) for what each status means.

* <span>7.0</span>
* <span>6.2</span>
* <span>6.0</span>
* <span>5.0</span>
* <span>4.0</span>
* <span>3.2</span>
* <span>3.0</span>
* <span>2.8</span>

## Decommissioned versions

The following versions have been decommissioned and are no longer available. See [Image statuses](/docs/core-concepts/upgrade-runtimes-services#image-statuses) for what each status means.
If your project uses a decommissioned version, you must update to an [active version](#active-versions).

*No decommissioned versions.*

Note that versions 3.0 and higher support up to 64 different databases per instance of the service,
while Redis 2.8 only supports a single database.

## Service types

Depending on your needs,
you can set up Redis as [persistent](#persistent-redis) or [ephemeral](#ephemeral-redis).

## Relationship reference

For each service [defined via a relationship](#usage-example) to your application,
Upsun Cloud automatically generates corresponding environment variables within your application container,
in the `$<RELATIONSHIP-NAME>_<SERVICE-PROPERTY>` format.

Here is example information available through the [service environment variables](/docs/development/variables#service-environment-variables) themselves,
or through the [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables).

<Tabs>
  <Tab title="Service environment variables">
    You can obtain the complete list of available service environment variables in your app container by running `upsun ssh env`.

    Note that the information about the relationship can change when an app is redeployed or restarted or the relationship is changed. So your apps should only rely on the [service environment variables](/docs/development/variables#service-environment-variables) directly rather than hard coding any values.
  </Tab>

  <Tab title="`PLATFORM_RELATIONSHIPS` environment variable">
    For some advanced use cases, you can use the [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables).
    The structure of the `PLATFORM_RELATIONSHIPS` environment variable can be obtained by running `upsun relationships` in your terminal:

    Here is an example of how to gather [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables) information in a [`.environment` file](/docs/development/variables/set-variables#when-to-use-env-files):

    ```bash .environment theme={null}
    # Decode the built-in credentials object variable.
    export RELATIONSHIPS_JSON="$(echo "$PLATFORM_RELATIONSHIPS" | base64 --decode)"

    # Set environment variables for individual credentials.
    export APP_REDIS_HOST="$(echo "$RELATIONSHIPS_JSON" | jq -r '.redis[0].host')"
    ```
  </Tab>
</Tabs>

The format of the relationship is identical whether your Redis service is [ephemeral](#ephemeral-redis) or [persistent](#persistent-redis).

## Persistent Redis

By default, Redis is an ephemeral service that stores data in memory.
This allows for fast data retrieval,
but also means data can be lost when a container is moved or shut down.

To solve this issue, configure your Redis service as persistent.
Persistent Redis stores data on a disk,
restoring it if the container restarts.

To switch from persistent to ephemeral Redis,
set up a new service with a different name.

<Warning>
  <h4>Warning</h4>
  Upsun Cloud sets the maximum amount of memory (`maxmemory`) Redis can use for the data set,
  and it cannot be amended.
  It is defined by comparing the following values and keeping the lower of the two:

  * Disk size / 2
  * Container memory × 0.75

  For example:

  * 1024 MB disk, 1024 MB memory → `maxmemory` = 512 MB
    *(disk/2 = 512, lower than 1024 × 0.75 = 768)*
  * 6144 MB disk, 1024 MB memory → `maxmemory` = 768 MB
    *(memory × 0.75 = 768, lower than 6144/2 = 3072)*
</Warning>

### Usage example

#### 1. Configure the service

To define the service, use the `redis-persistent` endpoint:

Note that changing the name of the service replaces it with a brand new service and all existing data is lost.
Back up your data before changing the service.

#### 2. Define the relationship

To define the relationship, use the `redis` endpoint :

<Tabs>
  <Tab title="Using default endpoints">
    You can define `SERVICE_NAME` as you like, so long as it’s unique between all defined services and matches in both the application and services configuration.

    The example above leverages [default endpoint](/docs/configure-apps/image-properties/relationships) configuration for relationships. That is, it uses default endpoints behind the scenes, providing a [relationship](/docs/configure-apps/image-properties/relationships) (the network address a service is accessible from) that is identical to the name of that service.

    Depending on your needs, instead of default endpoint configuration, you can use [explicit endpoint configuration](/docs/configure-apps/image-properties/relationships).

    With the above definition, the application container now has [access to the service](#use-in-app) via the relationship `SERVICE_NAME` and its corresponding [service environment variables](/docs/development/variables#service-environment-variables).
  </Tab>

  <Tab title="Using explicit endpoints">
    You can define `SERVICE_NAME` and `<RELATIONSHIP_NAME>` as you like, so long as it's unique between all defined services and relationships
    and matches in both the application and services configuration.

    The example above leverages [explicit endpoint](/docs/configure-apps/image-properties/relationships) configuration for relationships.

    Depending on your needs, instead of explicit endpoint configuration,
    you can use [default endpoint configuration](/docs/configure-apps/image-properties/relationships).

    With the above definition, the application container now has [access to the service](#use-in-app) via the relationship `<RELATIONSHIP_NAME>` and its corresponding [service environment variables](/docs/development/variables#service-environment-variables).
  </Tab>
</Tabs>

For PHP, enable the [extension](/docs/languages/php/extensions) for the service:

### Configuration example

### Use in app

To use the configured service in your app, add a configuration file similar to the following to your project.

This configuration defines a single application (`myapp`), whose source code exists in the `<PROJECT_ROOT>/myapp` directory.<br />
`myapp` has access to the `redis` service, via a relationship whose name is [identical to the service name](#2-define-the-relationship)
(as per [default endpoint](/docs/configure-apps/image-properties/relationships) configuration for relationships).

From this, `myapp` can retrieve access credentials to the service through the [relationship environment variables](#relationship-reference).

```bash myapp/.environment theme={null}
# Set environment variables for individual credentials.
# For more information, please visit /docs/development/variables#service-environment-variables.
export CACHE_HOST="${REDIS_HOST}"
export CACHE_PORT="${REDIS_PORT}"
export CACHE_PASSWORD="${REDIS_PASSWORD}"
export CACHE_SCHEME="${REDIS_SCHEME}"

# Surface a Redis connection string for use in app.
export CACHE_URL="${CACHE_SCHEME}://${CACHE_PASSWORD}@${CACHE_HOST}:${CACHE_PORT}"
```

The above file — `.environment` in the `myapp` directory — is automatically sourced by Upsun Cloud into the runtime environment, so that the variable `CACHE_URL` can be used within the application to connect to the service.

Note that `CACHE_URL`, and all Upsun Cloud [service environment variables](/docs/development/variables#service-environment-variables) like `REDIS_HOST`,
are environment-dependent.
Unlike the build produced for a given commit,
they can’t be reused across environments and only allow your app to connect to a single service instance on a single environment.

A file very similar to this is generated automatically for your when using the `upsun ify` command to [migrate a codebase to Upsun Cloud](/docs/get-started).

## Ephemeral Redis

By default, Redis is an ephemeral service that serves as a non-persistent cache.
Ephemeral Redis stores data only in memory and requires no disk space.
When the service reaches its memory limit, it triggers a cache cleanup.
To customize those cache cleanups, set up an [eviction policy](#eviction-policy).

Make sure your app doesn't rely on ephemeral Redis for persistent storage as it can cause issues.
For example, if a container is moved during region maintenance,
the `deploy` and `post_deploy` hooks don't run and an app that treats the cache as permanent shows errors.

To prevent data from getting lost when a container is moved or shut down,
you can use the [persistent Redis](#persistent-redis) configuration.
Persistent Redis provides a cache with persistent storage.

### Usage example

#### 1. Configure the service

To define the service, use the `redis` endpoint:

Note that changing the name of the service replaces it with a brand new service and all existing data is lost.
Back up your data before changing the service.

#### 2. Define the relationship

To define the relationship, use the `redis` endpoint :

<Tabs>
  <Tab title="Using default endpoints">
    You can define `SERVICE_NAME` as you like, so long as it’s unique between all defined services and matches in both the application and services configuration.

    The example above leverages [default endpoint](/docs/configure-apps/image-properties/relationships) configuration for relationships. That is, it uses default endpoints behind the scenes, providing a [relationship](/docs/configure-apps/image-properties/relationships) (the network address a service is accessible from) that is identical to the name of that service.

    Depending on your needs, instead of default endpoint configuration, you can use [explicit endpoint configuration](/docs/configure-apps/image-properties/relationships).

    With the above definition, the application container now has [access to the service](#use-in-app) via the relationship `SERVICE_NAME` and its corresponding [service environment variables](/docs/development/variables#service-environment-variables).
  </Tab>

  <Tab title="Using explicit endpoints">
    You can define `SERVICE_NAME` and `<RELATIONSHIP_NAME>` as you like, so long as it's unique between all defined services and relationships
    and matches in both the application and services configuration.

    The example above leverages [explicit endpoint](/docs/configure-apps/image-properties/relationships) configuration for relationships.

    Depending on your needs, instead of explicit endpoint configuration,
    you can use [default endpoint configuration](/docs/configure-apps/image-properties/relationships).

    With the above definition, the application container now has [access to the service](#use-in-app) via the relationship `<RELATIONSHIP_NAME>` and its corresponding [service environment variables](/docs/development/variables#service-environment-variables).
  </Tab>
</Tabs>

For PHP, enable the [extension](/docs/languages/php/extensions) for the service:

### Configuration example

### Use in app

To use the configured service in your app, add a configuration file similar to the following to your project.

This configuration defines a single application (`myapp`), whose source code exists in the `<PROJECT_ROOT>/myapp` directory.<br />
`myapp` has access to the `redis` service, via a relationship whose name is [identical to the service name](#2-define-the-relationship)
(as per [default endpoint](/docs/configure-apps/image-properties/relationships) configuration for relationships).

From this, `myapp` can retrieve access credentials to the service through the [relationship environment variables](#relationship-reference).

```bash myapp/.environment theme={null}
# Set environment variables for individual credentials.
# For more information, please visit /docs/development/variables#service-environment-variables.
export CACHE_HOST="${REDIS_HOST}"
export CACHE_PORT="${REDIS_PORT}"
export CACHE_PASSWORD="${REDIS_PASSWORD}"
export CACHE_SCHEME="${REDIS_SCHEME}"

# Surface a Redis connection string for use in app.
export CACHE_URL="${CACHE_SCHEME}://${CACHE_PASSWORD}@${CACHE_HOST}:${CACHE_PORT}"
```

The above file — `.environment` in the `myapp` directory — is automatically sourced by Upsun Cloud into the runtime environment, so that the variable `CACHE_URL` can be used within the application to connect to the service.

Note that `CACHE_URL`, and all Upsun Cloud [service environment variables](/docs/development/variables#service-environment-variables) like `REDIS_HOST`,
are environment-dependent.
Unlike the build produced for a given commit,
they can’t be reused across environments and only allow your app to connect to a single service instance on a single environment.

A file very similar to this is generated automatically for your when using the `upsun ify` command to [migrate a codebase to Upsun Cloud](/docs/get-started).

## Multiple databases

Redis 3.0 and above support up to 64 databases.
But you can't set up different access rights to each database.
When you set up a relationship connection,
access to all of the databases is automatically granted.

The way to access a particular database depends on the [client library](https://redis.io/clients) you're using:

<Tabs>
  <Tab title="PHP">
    Use the Redis [`select` command](https://redis.io/commands/select):

    ```php theme={null}
    <?php
    $redis = new Redis();
    $redis->connect(getenv('REDIS_HOST'), getenv('REDIS_PORT'));

    $redis->select(0);       // switch to DB 0
    $redis->set('x', '42');  // write 42 to x
    $redis->move('x', 1);    // move to DB 1
    $redis->select(1);       // switch to DB 1
    $redis->get('x');        // returns 42
    ```
  </Tab>

  <Tab title="Python">
    To manage [thread safety](https://github.com/redis/redis-py/blob/master/docs/advanced_features.rst#user-content-a-note-about-threading),
    the Python library suggests using separate client instances for each database:

    ```python theme={null}
    import os
    from redis import Redis

    database0 = Redis(host=os.getenv('REDIS_HOST'), port=os.getenv('REDIS_PORT'), db=0)
    database1 = Redis(host=os.getenv('REDIS_HOST'), port=os.getenv('REDIS_PORT'), db=1)
    ```
  </Tab>

  <Tab title="Node.js">
    Use the Redis [`select` command](https://redis.io/commands/select):

    ```javascript theme={null}
    const redis = require('redis');

    const client = redis.createClient(process.env.REDIS_PORT, process.env.REDIS_HOST);

    await client.SELECT(0);                  // switch to DB 0
    await client.set('x', '42');             // write 42 to x
    await client.MOVE('x', 1);               // move to DB 1
    await client.SELECT(1);                  // switch to DB 1
    const value = await client.get('x');     // returns 42
    ```
  </Tab>
</Tabs>

## Eviction policy

When Redis reaches its memory limit,
it triggers a cache cleanup.
To customize those cache cleanups, set up an eviction policy such as the following:

The following table presents the possible values:

| Value | Policy description |
| - | - |
| `allkeys-lru` | Removes the oldest cache items first. This is the default policy when `maxmemory_policy` isn't set. |
| `noeviction` | New items aren’t saved when the memory limit is reached. |
| `allkeys-lfu` | Removes least frequently used cache items first. |
| `volatile-lru` | Removes least recently used cache items with the `expire` field set to `true`. |
| `volatile-lfu` | Removes least frequently used cache items with the `expire` field set to `true`. |
| `allkeys-random` | Randomly removes cache items to make room for new data. |
| `volatile-random` | Randomly removes cache items with the `expire` field set to `true`. |
| `volatile-ttl` | Removes cache items with the `expire` field set to `true` and the shortest remaining `time-to -live` value. |

For more information on the different policies,
see the official [Redis documentation](https://redis.io/docs/latest/operate/rs/databases/memory-performance/eviction-policy/).

## Access your Redis service

After you've [configured your Redis service](#usage-example),
you can access it using either the Upsun Cloud CLI
or through the [Redis CLI](https://redis.io/docs/latest/operate/rs/references/cli-utilities/).

### Upsun Cloud CLI

Unlike the Redis CLI, connecting via the Upsun Cloud CLI does not require additional authentication steps if you are already authenticated in your terminal.

Access your Redis service by running the command:

```bash theme={null}
upsun redis
```

### Redis CLI

Retrieve the hostname and port you can connect to
through the `PLATFORM_RELATIONSHIPS` [environment variable](/docs/development/variables/use-variables#use-provided-variables).
To do so, run the `upsun relationships` command.

After you've retrieved the hostname and port, [open an SSH session](/docs/development/ssh).
To access your Redis service, run the following command:

If you have a Grid project, note that the `CONFIG GET` and `CONFIG SET` admin commands are restricted.
To get the current configuration, run the following command:

## Use Redis as a handler for PHP sessions

A PHP session allows you to store different data for each user through a unique session ID.
By default, PHP handles sessions using files.
But you can use Redis as a session handler,
which means Redis stores and retrieves the data saved into sessions.

To set up Redis as your session handler, add a configuration similar to the following:

## Exporting Data Persistent

This section applies only to **persistent** Redis services configured with `type: redis-persistent`.
Ephemeral Redis (`type: redis`) stores data only in memory; its data does not need to be exported.

The recommended approach is to use the `BGSAVE` command to write a point-in-time RDB snapshot to disk,
then download it.

1. Open an SSH tunnel:

```bash Terminal theme={null}
upsun tunnel:single --relationship <RELATIONSHIP_NAME>
```

2. Trigger a background save and wait for it to complete:

```bash Terminal theme={null}
redis-cli -h 127.0.0.1 -p 30000 BGSAVE
# Poll until "Background saving terminated" appears:
redis-cli -h 127.0.0.1 -p 30000 LASTSAVE
```

3. Download the RDB dump file from the container:

```bash Terminal theme={null}
# Connect via SSH and locate the dump file
upsun ssh -- find / -name "dump.rdb" 2>/dev/null

# Copy it locally
upsun scp remote:/path/to/dump.rdb ./redis-dump.rdb
```

The `.rdb` file can be imported into any Redis or Valkey instance by placing it in the data directory
and restarting the service.


# Self-hosted services
Source: https://developer.upsun.com/docs/add-services/self-hosted

Deploy services that aren't available as managed Upsun Cloud services using composable images or public Docker images.


Some third-party services aren't available as managed Upsun Cloud services. You can self-host them by deploying them as applications in your project.

## Composable image services

Deploy and configure a service from scratch using the [Composable image](/docs/configure-apps/app-reference/composable-image). Use this approach when you need full control over the runtime environment.

<CardGroup>
  <Card title="Qdrant" icon="database" href="/tutorials/self-hosted/qdrant">
    Vector similarity search engine for AI and semantic matching applications.
  </Card>

  <Card title="Chroma" icon="database" href="/tutorials/self-hosted/chroma">
    Open-source vector database for AI applications with embedding storage and retrieval.
  </Card>
</CardGroup>

## Docker image services

Run a service directly from a public Docker image. Use this approach when the service already ships a production-ready image. Before deploying a specific service, read the [Self-hosted services from public Docker images](/docs/add-services/docker-images) topic for configuration requirements and known limitations.

<CardGroup>
  <Card title="Meilisearch" icon="magnifying-glass" href="/docs/add-services/docker-images/docker-meilisearch">
    Fast, self-hosted search engine with a clean API and instant results.
  </Card>
</CardGroup>


# Solr (Search service)
Source: https://developer.upsun.com/docs/add-services/solr



Apache Solr is a scalable and fault-tolerant search index.

Solr search with generic schemas provided, and a custom schema is also supported. See the [Solr documentation](https://lucene.apache.org/solr/6_3_0/index.html) for more information.

## Supported versions

You can select the major and minor version.

Patch versions are applied periodically for bug fixes and other maintenance updates. By default, you get the latest available patches each time you deploy. If your project has a [maintenance window](/docs/core-concepts/build-deploy#maintenance-window) configured, Upsun Cloud applies patches only during that window. Upsun Cloud may still apply urgent or critical fixes outside of the maintenance window.

* <span>10.0</span>
* <span>9.9</span>
* <span>9.6</span>
* <span>9.4</span>
* <span>9.2</span>
* <span>9.1</span>

## Deprecated versions

The following versions are still available in your projects,
but they're at their end of life and are no longer receiving security updates from upstream.

*No deprecated versions.*

To ensure your project remains stable in the future, switch to a [supported version](#supported-versions).

## Retired versions

The following versions have been retired and are no longer available.
If your project uses a retired version, you must update to a [supported version](#supported-versions).

* <span>9.0</span>
* <span>8.11</span>
* <span>8.0</span>
* <span>7.7</span>
* <span>7.6</span>
* <span>6.6</span>
* <span>6.3</span>
* <span>4.10</span>
* <span>3.6</span>

## Relationship reference

For each service [defined via a relationship](#usage-example) to your application,
Upsun Cloud automatically generates corresponding environment variables within your application container,
in the `$<RELATIONSHIP-NAME>_<SERVICE-PROPERTY>` format.

Here is example information available through the [service environment variables](/docs/development/variables#service-environment-variables) themselves,
or through the [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables).

<Tabs>
  <Tab title="Service environment variables">
    You can obtain the complete list of available service environment variables in your app container by running `upsun ssh env`.

    Note that the information about the relationship can change when an app is redeployed or restarted or the relationship is changed. So your apps should only rely on the [service environment variables](/docs/development/variables#service-environment-variables) directly rather than hard coding any values.
  </Tab>

  <Tab title="`PLATFORM_RELATIONSHIPS` environment variable">
    For some advanced use cases, you can use the [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables#service-environment-variables).
    The structure of the `PLATFORM_RELATIONSHIPS` environment variable can be obtained by running `upsun relationships` in your terminal:

    Here is an example of how to gather [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables) information in a [`.environment` file](/docs/development/variables/set-variables#when-to-use-env-files):

    ```bash .environment theme={null}
    # Decode the built-in credentials object variable.
    export RELATIONSHIPS_JSON="$(echo "$PLATFORM_RELATIONSHIPS" | base64 --decode)"

    # Set environment variables for individual credentials.
    export APP_SOLR_HOST="$(echo "$RELATIONSHIPS_JSON" | jq -r '.solr[0].host')"
    ```
  </Tab>
</Tabs>

## Usage example

### 1. Configure the service

To define the service, use the `solr` type:

Note that changing the name of the service replaces it with a brand new service and all existing data is lost. Back up your data before changing the service.

### 2. Define the relationship

To define the relationship, use the following configuration:

<Tabs>
  <Tab title="Using default endpoints">
    You can define `SERVICE_NAME` as you like, so long as it's unique between all defined services
    and matches in both the application and services configuration.

    The example above leverages [default endpoint](/docs/configure-apps/image-properties/relationships) configuration for relationships.
    That is, it uses default endpoints behind the scenes, providing a [relationship](/docs/configure-apps/image-properties/relationships)
    (the network address a service is accessible from) that is identical to the *name* of that service.

    Depending on your needs, instead of default endpoint configuration,
    you can use [explicit endpoint configuration](/docs/configure-apps/image-properties/relationships).

    With the above definition, the application container (`APP_NAME`) now has access to the service via the relationship `SERVICE_NAME` and its corresponding [service environment variables](/docs/development/variables#service-environment-variables).
  </Tab>

  <Tab title="Using explicit endpoints">
    You can define `SERVICE_NAME` and `<RELATIONSHIP_NAME>` as you like, so long as it's unique between all defined services and relationships
    and matches in both the application and services configuration.

    The example above leverages [explicit endpoint](/docs/configure-apps/image-properties/relationships) configuration for relationships.

    Depending on your needs, instead of explicit endpoint configuration,
    you can use [default endpoint configuration](/docs/configure-apps/image-properties/relationships).

    With the above definition, the application container now has [access to the service](#use-in-app) via the relationship `<RELATIONSHIP_NAME>` and its corresponding [service environment variables](/docs/development/variables#service-environment-variables).
  </Tab>
</Tabs>

### Example configuration

### Use in app

To use the configured service in your app, add a configuration file similar to the following to your project.

This configuration defines a single application (`myapp`), whose source code exists in the `<PROJECT_ROOT>/myapp` directory.<br />
`myapp` has access to the `solr` service, via a relationship whose name is [identical to the service name](#2-define-the-relationship)
(as per [default endpoint](/docs/configure-apps/image-properties/relationships) configuration for relationships).

From this, `myapp` can retrieve access credentials to the service through the [relationship environment variables](#relationship-reference).

```bash myapp/.environment theme={null}
# Set environment variables for individual credentials.
# For more information, please visit /docs/development/variables#service-environment-variables.
export QUEUE_SCHEME="${SOLR_SCHEME}"
export QUEUE_USERNAME="${SOLR_USERNAME}"
export QUEUE_PASSWORD="${SOLR_PASSWORD}"
export QUEUE_HOST="${SOLR_HOST}"
export QUEUE_PORT="${SOLR_PORT}"

# Set a single RabbitMQ connection string variable for AMQP.
export AMQP_URL="${QUEUE_SCHEME}://${QUEUE_USERNAME}:${QUEUE_PASSWORD}@${QUEUE_HOST}:${QUEUE_PORT}/"
```

The above file — `.environment` in the `myapp` directory — is automatically sourced by Upsun Cloud into the runtime environment, so that the variable `SEARCH_URL` can be used within the application to connect to the service.

Note that `SEARCH_URL`, and all Upsun Cloud [service environment variables](/docs/development/variables#service-environment-variables) like `SOLR_HOST`, are environment-dependent.
Unlike the build produced for a given commit,
they can’t be reused across environments and only allow your app to connect to a single service instance on a single environment.

A file very similar to this is generated automatically for your when using the `upsun ify` command to [migrate a codebase to Upsun Cloud](/docs/get-started).

## Solr 4

For Solr 4, Upsun Cloud supports only a single core per server called `collection1`.

You must provide your own Solr configuration via a `core_config` key in your `.upsun/config.yaml`:

`<DIRECTORY>` points to a directory in the Git repository, in or below the `.upsun/` folder. This directory needs to contain everything that Solr needs to start a core. At the minimum, `solrconfig.xml` and `schema.xml`.

For example, place them in `.upsun/solr/conf/` such that the `schema.xml` file is located at `.upsun/solr/conf/schema.xml`. You can then reference that path like this -

```yaml .upsun/config.yaml theme={null}
services:
  # The name of the service container. Must be unique within a project.
  solr:
    type: "solr:4.10"
    configuration:
      core_config: !archive "solr/conf/"
```

## Solr 6 and later

For Solr 6 and later Upsun Cloud supports multiple cores via different endpoints. Cores and endpoints are defined separately, with endpoints referencing cores. Each core may have its own configuration or share a configuration. It is best illustrated with an example.

The above definition defines a single Solr 10.0 server. That server has 2 cores defined:

* `mainindex` — the configuration for which is in the `.upsun/core1-conf` directory
* `extraindex` — the configuration for which is in the `.upsun/core2-conf` directory.

It then defines two endpoints: `main` is connected to the `mainindex` core while `extra` is connected to the `extraindex` core. Two endpoints may be connected to the same core but at this time there would be no reason to do so. Additional options may be defined in the future.

Each endpoint is then available in the relationships definition in `.upsun/config.yaml`. For example, to allow an application to talk to both of the cores defined above its configuration should contain the following:

That is, the application's environment would include a `solrsearch1` relationship that connects to the `main` endpoint, which is the `mainindex` core, and a `solrsearch2` relationship that connects to the `extra` endpoint, which is the `extraindex` core.

The relationships array would then look something like the following:

```json theme={null}
{
  "solrsearch1": [
    {
      "path": "solr/mainindex",
      "host": "248.0.65.197",
      "scheme": "solr",
      "port": 8080
    }
  ],
  "solrsearch2": [
    {
      "path": "solr/extraindex",
      "host": "248.0.65.197",
      "scheme": "solr",
      "port": 8080
    }
  ]
}
```

### Configsets

For even more customizability, it's also possible to define Solr configsets. For example, the following snippet would define one configset, which would be used by all cores. Specific details can then be overridden by individual cores using `core_properties`, which is equivalent to the Solr `core.properties` file.

In this example, `.upsun/configsets/solr8` contains the configuration definition for multiple cores. There are then two cores created:

* `english_index` uses the defined configset, but specifically the `.upsun/configsets/solr8/english/schema.xml` file
* `arabic_index` is identical except for using the `.upsun/configsets/solr8/arabic/schema.xml` file.

Each of those cores is then exposed as its own endpoint.

Note that not all core properties features make sense to specify in the `core_properties`. Some keys, such as `name` and `dataDir`, aren't supported, and may result in a `solrconfig` that fails to work as intended, or at all.

### Default configuration

#### Default for version 9+

If you don't specify any configuration, the following default is used:

The example configuration directory is equivalent to the [Solr example configuration set](https://github.com/apache/solr/tree/main/solr/server/solr/configsets/sample_techproducts_configs/conf).
This default configuration is designed only for testing.
You are strongly recommended to define your own configuration with a custom core and endpoint.

#### Default for versions below 9

If you don't specify any configuration, the following default is used:

```yaml .upsun/config.yaml theme={null}
services:
  # The name of the service container. Must be unique within a project.
  solr:
    type: solr:8.4
    configuration:
      cores:
        collection1: {}
      endpoints:
        solr:
          core: collection1
```

The default configuration is based on an older version of the Drupal 8 Search API Solr module that is no longer in use.
You are strongly recommended to define your own configuration with a custom core and endpoint.

### Limitations

The recommended maximum size for configuration directories (zipped) is 2MB. These need to be monitored to ensure they don't grow beyond that. If the zipped configuration directories grow beyond this, performance declines and deploys become longer. The directory archives are compressed and string encoded. You could use this bash pipeline

```bash theme={null}
echo $(($(tar czf - . | base64 | wc -c )/(1024*1024))) Megabytes
```

inside the directory to get an idea of the archive size.

The configuration directory is a collection of configuration data, like a data dictionary, e.g. small collections of key/value sets. The best way to keep the size small is to restrict the directory context to plain configurations. Including binary data like plugin `.jar` files inflates the archive size, and isn't recommended.

## Accessing the Solr server administrative interface

Because Solr uses HTTP for both its API and admin interface it's possible to access the admin interface over an SSH tunnel.

By default, this opens a tunnel at `127.0.0.1:30000`.

You can now open `http://localhost:30000/solr/` in a browser to access the Solr admin interface.
Note that you can't create indexes or users this way,
but you can browse the existing indexes and manipulate the stored data.

## Available plugins

This is the complete list of plugins that are available and loaded by default:

| Plugin | Description | 8.11 | 9.x |
| - | - | - | - |
| [JTS](https://solr.apache.org/guide/8_1/spatial-search.html#jts-and-polygons-flat) | Library for creating and manipulating vector geometry. | \* | \* |
| [ICU4J](https://solr.apache.org/guide/8_3/language-analysis.html) | Library providing Unicode and globalization support. | \* | \* |

## Available modules

The following is the complete list of supported Solr modules.

### Modules vs plugins

In Solr, a **module** is a packaged feature set that can be added to the classpath.
A **plugin** is a specific Solr component (for example a request handler, parser, or repository implementation) that may rely on a module.

In practice, you often enable modules first, then use plugins provided by those modules in your configset.

### When to enable modules

Enable modules only when your configset needs them:

* `extraction`: Tika-based document extraction
* `langid`: language detection
* `ltr`: learning-to-rank components
* `clustering`: result clustering features
* `sql`: SQL query endpoint support
* `analysis-extras`: additional analysis filters and tokenizers

Loading only the modules you need reduces startup overhead and avoids unnecessary classpath bloat.

### Example: enable modules in the service configuration

Use the `configuration.modules` key in your service definition:

```yaml .upsun/config.yaml theme={null}
services:
  solr:
    type: solr:9.9
    configuration:
      modules:
        - analysis-extras
        - langid
        - ltr
```

### Bundled modules (Solr 9.9+)

Solr 9.8 made [`<lib>` directives in `solrconfig.xml` opt-in](https://solr.apache.org/guide/solr/latest/upgrade-notes/major-changes-in-solr-9.html#solr-9-8), and Solr 10.0 ([SOLR-16781](https://issues.apache.org/jira/browse/SOLR-16781)) removed support for them entirely.
As a result, bundled modules shipped under `/opt/solr/<VERSION>/modules/` are no longer auto-loaded from `<lib>` references in your configset.
Instead, list the modules you need in `configuration.modules`.

By default, no bundled modules are loaded. Only the modules you explicitly request are added to the classpath.

If you're upgrading from Solr 9.6 or earlier and your configset relies on `<lib>` directives,
add the matching modules to `configuration.modules` when you upgrade:

```yaml .upsun/config.yaml theme={null}
services:
  solr:
    type: solr:9.9
    configuration:
      modules:
        - extraction
        - analysis-extras
        - langid
        - ltr
```

The `configuration.modules` field is supported only on Solr 9.9 and later.
On Solr 9.6 and earlier, modules continue to load from `<lib>` directives in your configset.

### Typical migration issues (9.9+)

If you upgraded from an older setup that used `<lib>` directives, add the matching modules in `configuration.modules`.

| Symptom | Likely missing module |
| - | - |
| ClassNotFound errors related to Tika extraction | `extraction` |
| Language detection handlers/fields fail to initialize | `langid` |
| LTR parser/components fail to load | `ltr` |
| SQL endpoint/features unavailable | `sql` |

### Validation checklist after enabling modules

After deployment, verify the following:

* Solr service starts successfully
* Core loading completes without classpath errors
* The feature tied to the module works (query/index/update path)
* Service logs contain no module-related `ClassNotFound`/initialization errors

### Supported modules matrix

<div>
  <div><div><table><thead><tr><th>Extension</th><th>Description</th><th>Supported versions</th></tr></thead><tbody><tr><td><code>analysis-extras</code></td><td>Extra analyzers and token filters for advanced text analysis use cases.</td><td><div><span>10.0</span><span>9.9</span></div></td></tr><tr><td><code>analytics</code></td><td>Streaming expressions and advanced analytics functions.</td><td><div><span>10.0</span><span>9.9</span></div></td></tr><tr><td><code>clustering</code></td><td>Result clustering capabilities for grouped search output.</td><td><div><span>10.0</span><span>9.9</span></div></td></tr><tr><td><code>cross-dc</code></td><td>Cross-data-center replication and failover tooling.</td><td><div><span>10.0</span><span>9.9</span></div></td></tr><tr><td><code>cuvs</code></td><td>Vector search acceleration module based on cuVS.</td><td><div><span>10.0</span><span>9.9</span></div></td></tr><tr><td><code>extraction</code></td><td>Tika-based extraction for PDF, Office, and other document formats.</td><td><div><span>10.0</span><span>9.9</span></div></td></tr><tr><td><code>gcs-repository</code></td><td>Repository plugin for backups and snapshots on Google Cloud Storage.</td><td><div><span>10.0</span><span>9.9</span></div></td></tr><tr><td><code>hadoop-auth</code></td><td>Hadoop-compatible authentication integrations.</td><td><div><span>10.0</span><span>9.9</span></div></td></tr><tr><td><code>hdfs</code></td><td>HDFS integration for repository and storage operations.</td><td><div><span>10.0</span><span>9.9</span></div></td></tr><tr><td><code>jaegertracer-configurator</code></td><td>Jaeger tracing configuration helpers.</td><td><div><span>10.0</span><span>9.9</span></div></td></tr><tr><td><code>jwt-auth</code></td><td>JWT authentication support for Solr APIs.</td><td><div><span>10.0</span><span>9.9</span></div></td></tr><tr><td><code>langid</code></td><td>Automatic language identification update processor.</td><td><div><span>10.0</span><span>9.9</span></div></td></tr><tr><td><code>language-models</code></td><td>Language model resources used by NLP-oriented features.</td><td><div><span>10.0</span><span>9.9</span></div></td></tr><tr><td><code>llm</code></td><td>Large language model integration components.</td><td><div><span>10.0</span><span>9.9</span></div></td></tr><tr><td><code>ltr</code></td><td>Learning To Rank query reranking framework.</td><td><div><span>10.0</span><span>9.9</span></div></td></tr><tr><td><code>opentelemetry</code></td><td>OpenTelemetry instrumentation for traces and metrics.</td><td><div><span>10.0</span><span>9.9</span></div></td></tr><tr><td><code>s3-repository</code></td><td>Repository plugin for backups and snapshots on S3-compatible storage.</td><td><div><span>10.0</span><span>9.9</span></div></td></tr><tr><td><code>scripting</code></td><td>Script engine integrations for custom processing.</td><td><div><span>10.0</span><span>9.9</span></div></td></tr><tr><td><code>sql</code></td><td>SQL query parser and SQL request handler support.</td><td><div><span>10.0</span><span>9.9</span></div></td></tr></tbody></table></div></div>
</div>

<SolrModulesTable />

## Upgrading

The Solr data format sometimes changes between versions in incompatible ways. Solr doesn't include a data upgrade mechanism as it is expected that all indexes can be regenerated from stable data if needed. To upgrade (or downgrade) Solr you need to use a new service from scratch.

There are two approaches.

### Destructive upgrade

In your `.upsun/config.yaml` file, change the version of your Solr service *and* its name.
Be sure to also update the reference to the now changed service name in it's corresponding application's `relationship` block.

When you push that to Upsun Cloud, the old service is deleted and a new one with the name is created, with no data. You can then have your application re-index data as appropriate.

This approach has the downside of temporarily having an empty Solr instance, which your application may or may not handle gracefully, and needing to rebuild your index afterward. Depending on the size of your data that could take a while.

### Transitional upgrade

For a transitional approach you temporarily have two Solr services. Add a second Solr service with the new version a new name and give it a new relationship in `.upsun/config.yaml`. You can optionally run in that configuration for a while to allow your application to populate indexes in the new service as well.

Once you're ready to cut over, remove the old Solr service and relationship. You may optionally have the new Solr service use the old relationship name if that's easier for your application to handle. Your application is now using the new Solr service.

This approach has the benefit of never being without a working Solr instance. On the downside, it requires two running Solr servers temporarily, each of which consumes resources and need adequate disk space. Depending on the size of your data that may be a lot of disk space.


# Valkey
Source: https://developer.upsun.com/docs/add-services/valkey



[Valkey](https://valkey.io/) is an open source datastore that can be used high-performance data retrieval and key-value storage.

Upsun Cloud supports two different Valkey configurations:

* [Persistent](#persistent-valkey): to set up fast persistent storage for your application
* [Ephemeral](#ephemeral-valkey): to set up a non-persistent cache for your application

## Supported versions

You can select the major and minor version.

Patch versions are applied periodically for bug fixes and other maintenance updates. By default, you get the latest available patches each time you deploy. If your project has a [maintenance window](/docs/core-concepts/build-deploy#maintenance-window) configured, Upsun Cloud applies patches only during that window. Upsun Cloud may still apply urgent or critical fixes outside of the maintenance window.

* <span>9.0</span>
* <span>8.1</span>
* <span>8.0</span>

<Note>
  These versions are not yet available but are expected to be released soon.

  * <span>9.1</span>
</Note>

## Deprecated versions

The following versions are still available in your projects,
but they're at their end of life and are no longer receiving security updates from upstream.

*No deprecated versions.*

To ensure your project remains stable in the future, switch to a [supported version](#supported-versions).

## Retired versions

The following versions have been retired and are no longer available.
If your project uses a retired version, you must update to a [supported version](#supported-versions).

*No retired versions.*

## Service types

Depending on your needs, you can set up Valkey as [persistent](#persistent-valkey) or [ephemeral](#ephemeral-valkey).

## Relationship reference

For each service [defined via a relationship](#usage-example) to your application,
Upsun Cloud automatically generates corresponding environment variables within your application container,
in the `$<RELATIONSHIP-NAME>_<SERVICE-PROPERTY>` format.

Here is example information available through the [service environment variables](/docs/development/variables#service-environment-variables) themselves,
or through the [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables).

<Tabs>
  <Tab title="Service environment variables">
    You can obtain the complete list of available service environment variables in your app container by running `upsun ssh env`.

    Note that the information about the relationship can change when an app is redeployed or restarted or the relationship is changed. So your apps should only rely on the [service environment variables](/docs/development/variables#service-environment-variables) directly rather than hard coding any values.
  </Tab>

  <Tab title="`PLATFORM_RELATIONSHIPS` environment variable">
    For some advanced use cases, you can use the [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables).
    The structure of the `PLATFORM_RELATIONSHIPS` environment variable can be obtained by running `upsun relationships` in your terminal:

    Here is an example of how to gather [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables) information in a [`.environment` file](/docs/development/variables/set-variables#when-to-use-env-files):

    ```bash .environment theme={null}
    # Decode the built-in credentials object variable.
    export RELATIONSHIPS_JSON="$(echo "$PLATFORM_RELATIONSHIPS" | base64 --decode)"

    # Set environment variables for individual credentials.
    export APP_VALKEY_HOST="$(echo "$RELATIONSHIPS_JSON" | jq -r '.valkey[0].host')"
    ```
  </Tab>
</Tabs>

The format of the relationship is identical whether your Valkey service is [ephemeral](#ephemeral-valkey) or [persistent](#persistent-valkey).

<Note>
  <h4>Database access</h4>
  It should be noted that when you set up a relationship connection, access to all of the databases is automatically granted.
</Note>

## Persistent Valkey

By default, Valkey is an ephemeral service that stores data in memory.
This allows for fast data retrieval,but also means data can be lost when a container is moved or shut down.

To solve this issue, configure your Valkey service as persistent.
Persistent Valkey stores data on a disk, restoring it if the container restarts.

To switch from persistent to ephemeral Valkey, set up a new service with a different name.

<Warning>
  <h4>Warning</h4>
  Upsun Cloud sets the maximum amount of memory (`maxmemory`) Valkey can use for the data set,
  and it cannot be amended.
  It is defined by comparing the following values and keeping the lower of the two:

  * Disk size / 2
  * Container memory × 0.75

  For example:

  * 1024 MB disk, 1024 MB memory → `maxmemory` = 512 MB
    *(disk/2 = 512, lower than 1024 × 0.75 = 768)*
  * 6144 MB disk, 1024 MB memory → `maxmemory` = 768 MB
    *(memory × 0.75 = 768, lower than 6144/2 = 3072)*
</Warning>

### Usage example

#### 1. Configure the service

To define the service, use the `valkey-persistent` endpoint:

Note that changing the name of the service replaces it with a brand new service and all existing data is lost.
Back up your data before changing the service.

#### 2. Define the relationship

To define the relationship, use the `valkey` endpoint :

<Tabs>
  <Tab title="Using default endpoints">
    You can define `SERVICE_NAME` as you like, so long as it’s unique between all defined services and matches in both the application and services configuration.

    The example above leverages [default endpoint](/docs/configure-apps/image-properties/relationships) configuration for relationships. That is, it uses default endpoints behind the scenes, providing a [relationship](/docs/configure-apps/image-properties/relationships) (the network address a service is accessible from) that is identical to the name of that service.

    Depending on your needs, instead of default endpoint configuration, you can use [explicit endpoint configuration](/docs/configure-apps/image-properties/relationships).

    With the above definition, the application container now has [access to the service](#use-in-app) via the relationship `SERVICE_NAME` and its corresponding [service environment variables](/docs/development/variables#service-environment-variables).
  </Tab>

  <Tab title="Using explicit endpoints">
    You can define `SERVICE_NAME` and `<RELATIONSHIP_NAME>` as you like, so long as it's unique between all defined services and relationships
    and matches in both the application and services configuration.

    The example above leverages [explicit endpoint](/docs/configure-apps/image-properties/relationships) configuration for relationships.

    Depending on your needs, instead of explicit endpoint configuration,
    you can use [default endpoint configuration](/docs/configure-apps/image-properties/relationships).

    With the above definition, the application container now has [access to the service](#use-in-app) via the relationship `<RELATIONSHIP_NAME>` and its corresponding [service environment variables](/docs/development/variables#service-environment-variables).
  </Tab>
</Tabs>

For PHP, enable the [extension](/docs/languages/php/extensions) for the service:

### Configuration example

## Ephemeral Valkey

By default, Valkey is an ephemeral service that serves as a non-persistent cache.
Ephemeral Valkey stores data only in memory and requires no disk space.
When the service reaches its memory limit, it triggers a cache cleanup.
To customize those cache cleanups, set up an [eviction policy](#eviction-policy).

Make sure your app doesn't rely on ephemeral Vedis for persistent storage as it can cause issues. For example, if a container is moved during region maintenance,the `deploy` and `post_deploy` hooks don't run and an app that treats the cache as permanent shows errors.

To prevent data from getting lost when a container is moved or shut down,
you can use the [persistent Valkey](#persistent-valkey) configuration.
Persistent Valkey provides a cache with persistent storage.

### Usage example

#### 1. Configure the service

To define the service, use the `valkey` endpoint:

Note that changing the name of the service replaces it with a brand new service and all existing data is lost. Back up your data before changing the service.

#### 2. Define the relationship

To define the relationship, use the `valkey` endpoint :

<Tabs>
  <Tab title="Using default endpoints">
    You can define `SERVICE_NAME` as you like, so long as it’s unique between all defined services and matches in both the application and services configuration.

    The example above leverages [default endpoint](/docs/configure-apps/image-properties/relationships) configuration for relationships. That is, it uses default endpoints behind the scenes, providing a [relationship](/docs/configure-apps/image-properties/relationships) (the network address a service is accessible from) that is identical to the name of that service.

    Depending on your needs, instead of default endpoint configuration, you can use [explicit endpoint configuration](/docs/configure-apps/image-properties/relationships).

    With the above definition, the application container now has [access to the service](#use-in-app) via the relationship `SERVICE_NAME` and its corresponding [service environment variables](/docs/development/variables#service-environment-variables).
  </Tab>

  <Tab title="Using explicit endpoints">
    You can define `SERVICE_NAME` and `<RELATIONSHIP_NAME>` as you like, so long as it's unique between all defined services and relationships
    and matches in both the application and services configuration.

    The example above leverages [explicit endpoint](/docs/configure-apps/image-properties/relationships) configuration for relationships.

    Depending on your needs, instead of explicit endpoint configuration,
    you can use [default endpoint configuration](/docs/configure-apps/image-properties/relationships).

    With the above definition, the application container now has [access to the service](#use-in-app) via the relationship `<RELATIONSHIP_NAME>` and its corresponding [service environment variables](/docs/development/variables#service-environment-variables).
  </Tab>
</Tabs>

For PHP, enable the [extension](/docs/languages/php/extensions) for the service:

### Configuration example

### Use in app

To use the configured service in your app, add a configuration file similar to the following to your project.

This configuration defines a single application (`myapp`), whose source code exists in the `<PROJECT_ROOT>/myapp` directory.<br />
`myapp` has access to the `valkey` service, via a relationship whose name is [identical to the service name](#2-define-the-relationship)
(as per [default endpoint](/docs/configure-apps/image-properties/relationships) configuration for relationships).

From this, `myapp` can retrieve access credentials to the service through the [relationship environment variables](#relationship-reference).

```bash myapp/.environment theme={null}
# Set environment variables for individual credentials.
# For more information, please visit /docs/development/variables#service-environment-variables.
export CACHE_HOST="${VALKEY_HOST}"
export CACHE_PORT="${VALKEY_PORT}"
export CACHE_PASSWORD="${VALKEY_PASSWORD}"
export CACHE_SCHEME="${VALKEY_SCHEME}"

# Surface a Valkey connection string for use in app.
export CACHE_URL="${CACHE_SCHEME}://${CACHE_PASSWORD}@${CACHE_HOST}:${CACHE_PORT}"
```

The above file — `.environment` in the `myapp` directory — is automatically sourced by Upsun Cloud into the runtime environment, so that the variable `CACHE_URL` can be used within the application to connect to the service.

Note that `CACHE_URL`, and all Upsun Cloud [service environment variables](/docs/development/variables#service-environment-variables) like `VALKEY_HOST`,
are environment-dependent.
Unlike the build produced for a given commit,
they can’t be reused across environments and only allow your app to connect to a single service instance on a single environment.

A file very similar to this is generated automatically for your when using the `upsun ify` command to [migrate a codebase to Upsun Cloud](/docs/get-started).

## Eviction policy

When Valkey reaches its memory limit,
it triggers a cache cleanup.
To customize those cache cleanups, set up an eviction policy such as the following:

The following table presents the possible values:

| Value | Policy description |
| - | - |
| `allkeys-lru` | Removes the oldest cache items first. This is the default policy when `maxmemory_policy` isn't set. |
| `noeviction` | New items aren’t saved when the memory limit is reached. |
| `allkeys-lfu` | Removes least frequently used cache items first. |
| `volatile-lru` | Removes least recently used cache items with the `expire` field set to `true`. |
| `volatile-lfu` | Removes least frequently used cache items with the `expire` field set to `true`. |
| `allkeys-random` | Randomly removes cache items to make room for new data. |
| `volatile-random` | Randomly removes cache items with the `expire` field set to `true`. |
| `volatile-ttl` | Removes cache items with the `expire` field set to `true` and the shortest remaining `time-to -live` value. |

For more information on the different policies,
see the official [Valkey documentation](https://valkey.io/topics/lru-cache/).

## Access your Valkey service

After you've [configured your Valkey service](#usage-example),
you can access it using either the Upsun Cloud CLI
or through the [Valkey CLI](https://valkey.io/topics/cli/).

### Upsun Cloud CLI

Unlike the Valkey CLI, connecting via the Upsun Cloud CLI does not require additional authentication steps if you are already authenticated in your terminal.

Access your Valkey service by running the command:

```bash theme={null}
upsun valkey
```

### Valkey CLI

Retrieve the hostname and port you can connect to
through the `PLATFORM_RELATIONSHIPS` [environment variable](/docs/development/variables/use-variables#use-provided-variables).
To do so, run the `upsun relationships` command.

After you've retrieved the hostname and port, [open an SSH session](/docs/development/ssh).
To access your Valkey service, run the following command:

To get the current configuration, run the following command:

## Use Valkey as a handler for PHP sessions

A PHP session allows you to store different data for each user through a unique session ID.
By default, PHP handles sessions using files.
But you can use Valkey as a session handler,
which means Valkey stores and retrieves the data saved into sessions.

To set up Valkey as your session handler, add a configuration similar to the following:

## Migrate from Redis to Valkey

It is possible for a user to switch from `redis-persistent` to `valkey-persistent` without losing data. To make this switch, change the type of the service from `redis-persistent` to `valkey-persistent` (also note the version change), while keeping the same service name. For example, replace this:

with the following:

## Exporting Data Persistent

This section applies only to **persistent** Valkey services configured with `type: valkey-persistent`.
Ephemeral Valkey (`type: valkey`) stores data only in memory and does not need to be exported.

The procedure is identical to [Redis (persistent)](#persistent-valkey), using the same `BGSAVE` / RDB approach:

1. Open an SSH tunnel:

```bash Terminal theme={null}
upsun tunnel:single --relationship <RELATIONSHIP_NAME>
```

2. Trigger a background save:

```bash Terminal theme={null}
redis-cli -h 127.0.0.1 -p 30000 BGSAVE
```

3. Download the `dump.rdb` file from the container as described in the [Redis section](#persistent-valkey).

## Further resources

### Documentation

* [Valkey documentation](https://valkey.io/topics/)


# Varnish
Source: https://developer.upsun.com/docs/add-services/varnish



Varnish is a popular HTTP proxy server, often used for caching.
You usually don't need it with Upsun Cloud as the standard router includes HTTP cache
and a CDN would cover more advanced uses.
But you can include Varnish as a service.

## Supported versions

You can select the major and minor version.

Patch versions are applied periodically for bug fixes and other maintenance updates. By default, you get the latest available patches each time you deploy. If your project has a [maintenance window](/docs/core-concepts/build-deploy#maintenance-window) configured, Upsun Cloud applies patches only during that window. Upsun Cloud may still apply urgent or critical fixes outside of the maintenance window.

* <span>9.0</span>
* <span>6.0</span>

## Deprecated versions

The following versions are still available in your projects,
but they're at their end of life and are no longer receiving security updates from upstream.

*No deprecated versions.*

To ensure your project remains stable in the future, switch to a [supported version](#supported-versions).

## Retired versions

The following versions have been retired and are no longer available.
If your project uses a retired version, you must update to a [supported version](#supported-versions).

* <span>7.6</span>
* <span>7.3</span>
* <span>7.2</span>
* <span>7.1</span>
* <span>6.3</span>

## How it works

All incoming requests go through the [standard router](/docs/routes).
The Varnish service sits between the router and all apps in the project.

```mermaid {no-copy="true"} theme={null}
graph LR
    A(Request) -->B(Router)
    B --> C{Varnish}
    C -->D[App 1]
    C -->E[App 2]
```

## Usage example

### 1. Configure the service

To define the service, use the `varnish` type:

Note that changing the name of the service replaces it with a brand new service and all existing data is lost.
Back up your data before changing the service.

The `relationships` block defines the connection between Varnish and your app.
You can define `RELATIONSHIP_NAME` as you like.
`APP_NAME` should match your app's `name` in the [app configuration](/docs/configure-apps/app-reference/single-runtime-image).

The `configuration` block must reference a VCL file inside the `.upsun/` directory.
The `path` defines the file relative to the `.upsun/` directory.

#### Example configuration

Notice the `relationship` (`application`) defined for the service `varnish` granting access to the application container `myapp`.

### 2. Create a VCL template

To tell Varnish how to handle traffic, in the `.upsun/` directory
add a [Varnish Configuration Language (VCL) template](https://www.varnish-software.com/developers/tutorials/example-vcl-template/).

This template is supplemented by automatic additions from Upsun Cloud.
So you MUST NOT include certain features that you might elsewhere:

* A `vcl_init()` function:
  The function is automatically generated based on the relationships you defined in Step 1.
  Each defined relationship results in a backend with the same name.
* The VCL version at the start:
  This is automatically generated.
* Imports for `std` or `directors`:
  These are already imported.
  You can import other [modules](#include-modules).

The file MUST include:

* A definition of which backend to use in a  `vcl_recv()` subroutine.

The logic varies based on whether you have one or more apps.

<Note>
  Misconfigured VCL files can result in incorrect and confusing behavior that's hard to debug.
  Upsun Cloud doesn't help with VCL configuration options beyond the basic connection logic documented here.

  You can see any compilation errors with the [stats endpoint](#stats-endpoint).
</Note>

#### Example VCL template with one app

To serve one app, your VCL template needs at least the following function:

Where `RELATIONSHIP_NAME` is the name of the relationship you defined in [Step 1](#1-configure-the-service).
With the [example configuration](#example-configuration), that would be the following:

#### Example VCL template with multiple apps

If you have multiple apps fronted by the same Varnish instance,
your VCL templates needs logic to determine where each request is forwarded.

For example, you might have the following configuration for two apps:

You could then define that all requests to `/blog/` go to the `blog` app and all other requests to the other app:

```bash {location="config.vcl" dir="true"} theme={null}
sub vcl_recv {
  if (req.url ~ "^/blog/") {
      set req.backend_hint = blog.backend();
  } else {
      set req.backend_hint = main.backend();
  }
}
```

### 3. Route incoming requests to Varnish

Edit your [route definitions](/docs/routes) to point to the Varnish service you just created.
Also disable the router cache as Varnish now provides caching.

To forward all incoming requests to Varnish rather than your app, you could have the following:

```yaml .upsun/config.yaml theme={null}
routes:
  "https://{default}/":
    type: upstream
    upstream: "varnish:http"
    cache:
      enabled: false
```

Varnish forwards requests to your app based on the specified VCL template.

## Include modules

You can include the following optional modules in your VCL templates to add additional features:

* `cookie`
* `header`
* `saintmode`
* `softpurge`
* `tcp`
* `var`
* `vsthrottle`
* `xkey`

To use them, add an import to your template such as the following:

```bash {location="config.vcl" dir="true"} theme={null}
import xkey;
```

## Circular relationships

At this time, Upsun Cloud doesn't support circular relationships between services and apps.
That means you can't add a relationship from an app fronted by Varnish to the Varnish service.
If you do so, then one of the relationships is skipped and the connection doesn't work.

## Rate limit connections

Sometimes you want to ensure that users, whether human or machine, can't overload your app with requests.
One tool to help is using Varnish to limit the rate at which connections can be made.

For example, say you want to make sure no one can make more than 20 requests within 10 seconds.
If they do, you want to block them from any more requests for 2 minutes.

To do so, [import the `vsthrottle` module](#include-modules)
and add logic similar to the following to your VCL template:

```bash {location="config.vcl" dir="true"} theme={null}
import vsthrottle;

sub vcl_recv {
  # The Upsun Cloud router provides the real client IP as X-Client-IP
  # This replaces client.identity in other implementations
  if (vsthrottle.is_denied(req.http.X-Client-IP, 20, 10s, 120s)) {
    # Client has exceeded 20 requests in 10 seconds.
    # When this happens, block that IP for the next 120 seconds.
    return (synth(429, "Too Many Requests"));
  }

  # Set the standard backend for handling requests that aren't limited
  set req.backend_hint = application.backend();
}
```

## Clear cache with a push

You may want at times to clear a specific part of your cache when you know the content is outdated.
With Varnish, you can clear the content with [purging and banning](https://varnish-cache.org/docs/trunk/users-guide/purging.html).

The following example shows how to set up purging.

1. Add an access control list to your VCL template:

   ```bash {location="config.vcl" dir="true"} theme={null}
   acl purge {
       "localhost";
       "192.0.2.0"/24;
   }
   ```

   This list ensures that only requests from the listed IPs are accepted.
   Choose which IPs to allow.
   If you are sending requests from an app, checkout the [outbound IPs for the region](/docs/development/regions#public-ip-addresses).

   Alternatively, you could code in a token that must be sent with the request.

2. Add purge handling:

   ```bash {location="config.vcl" dir="true"} theme={null}
   sub vcl_recv {
       if (req.method == "PURGE") {
           # The Upsun Cloud router provides the real client IP as X-Client-IP
           # Use std.ip to convert the string to an IP for comparison
           if (!std.ip(req.http.X-Client-IP, "0.0.0.0") ~ purge) {
               # Deny all purge requests not from the allowed IPs
               return(synth(403,"Not allowed."));
           }
           # Purge cache for allowed requests
           return (purge);
       }
       ...
   }
   ```

<Info>
  The snippet above has been produced for Varnish 7.x. If using a different version, consult the [Varnish documentation](https://varnish-cache.org/docs/) for potential differences in syntax and required parameters.
</Info>

3. Set up cache purging to suit your needs.
   The following cURL call gives an example of how this can work:

   Where `URL_TO_PURGE` is the URL of the content you want to purge.

## Stats endpoint

The Varnish service also offers an `http+stats` endpoint,
which provides access to some Varnish analysis and debugging tools.

You can't use it from an app fronted by Varnish because of the restriction with [circular relationships](#circular-relationships).
To access the stats, create a **separate app** (`stats-app`) with a relationship *to* Varnish, but not *from* it.
Define [app configuration](/docs/configure-apps/app-reference/single-runtime-image) similar to the following:

You choose any valid name and type.
When the app is deployed, the app can access the Varnish service over HTTP to get diagnostic information.
The following paths are available:

* `/`: returns any error logged when generating the VCL template failed
* `/config`: returns the generated VCL template
* `/stats`: returns the output of `varnishstat`
* `/logs`: returns a streaming response of `varnishlog`

To access the Varnish stats endpoint from the command line:

1. Connect to your stats app [using SSH](/docs/development/ssh): `upsun ssh --app stats-app`
   (replace `stats-app` with the name you gave the app).
2. Display the [relationships array](/docs/configure-apps/image-properties/relationships) with `echo $PLATFORM_RELATIONSHIPS | base64 -d | jq .`,
3. Query Varnish with `curl HOST:PORT/stats`, replacing `HOST` and `PATH` with the values from Step 2.


# Vault key management service
Source: https://developer.upsun.com/docs/add-services/vault



The Vault key management service (KMS) provides key management and access control for your secrets.
The Upsun Cloud Vault KMS offers the [transit secrets engine](https://developer.hashicorp.com/vault/docs/secrets/transit)
to sign, verify, encrypt, decrypt, and rewrap information.

Vault doesn't store the data sent to the transit secrets engine,
so it can be viewed as encryption as a service.
To store secrets such as API keys, create sensitive [environment variables](/docs/development/variables).

## Supported versions

You can select the major and minor version.

Patch versions are applied periodically for bug fixes and other maintenance updates. By default, you get the latest available patches each time you deploy. If your project has a [maintenance window](/docs/core-concepts/build-deploy#maintenance-window) configured, Upsun Cloud applies patches only during that window. Upsun Cloud may still apply urgent or critical fixes outside of the maintenance window.

* <span>1.12</span>

## Deprecated versions

The following versions are still available in your projects,
but they're at their end of life and are no longer receiving security updates from upstream.

*No deprecated versions.*

To ensure your project remains stable in the future,
switch to a [supported version](#supported-versions).

## Retired versions

The following versions have been retired and are no longer available.
If your project uses a retired version, you must update to a [supported version](#supported-versions).

*No retired versions.*

## Relationship reference

For each service [defined via a relationship](#usage-example) to your application,
Upsun Cloud automatically generates corresponding environment variables within your application container,
in the `$<RELATIONSHIP-NAME>_<SERVICE-PROPERTY>` format.

Here is example information available through the [service environment variables](/docs/development/variables#service-environment-variables) themselves,
or through the [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables).

<Tabs>
  <Tab title="Service environment variables">
    You can obtain the complete list of available service environment variables in your app container by running `upsun ssh env`.

    Note that the information about the relationship can change when an app is redeployed or restarted or the relationship is changed. So your apps should only rely on the [service environment variables](/docs/development/variables#service-environment-variables) directly rather than hard coding any values.
  </Tab>

  <Tab title="`PLATFORM_RELATIONSHIPS` environment variable">
    For some advanced use cases, you can use the [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables).
    The structure of the `PLATFORM_RELATIONSHIPS` environment variable can be obtained by running `upsun relationships` in your terminal:

    Here is an example of how to gather [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables) information in a [`.environment` file](/docs/development/variables/set-variables#when-to-use-env-files):

    ```bash .environment theme={null}
    # Decode the built-in credentials object variable.
    export RELATIONSHIPS_JSON="$(echo "$PLATFORM_RELATIONSHIPS" | base64 --decode)"

    # Set environment variables for individual credentials.
    export APP_VAULT_HOST=="$(echo "$RELATIONSHIPS_JSON" | jq -r '.vault_secret[0].host')"
    ```
  </Tab>
</Tabs>

## Usage example

### 1. Configure the service

To define the service, use the `vault-kms` type:

Note that changing the name of the service replaces it with a brand new service and all existing data is lost.
Back up your data before changing the service.

* `SERVICE_NAME` is the name you choose to identify the service.
* `VERSION` is a supported version of the service.
* `ENDPOINT_ID` is an identifier you choose for the endpoint.
* `KEY_NAME` is the name of the key to be stored in the Vault KMS.
* `POLICY` is one of the available [policies](#policies) based on what you want to accomplish.
* The `type` is one of:

  * `sign`: for signing payloads, with the type `ecdsa-p256`
  * `encrypt` (for encrypt`chacha20-poly1305`).

  The `type` can't be changed after creation.

You can create multiple endpoints, such as to have key management separate from key use.

512 MB is the minimum required disk space for the Vault KMS service.

### 2. Define the relationship

To define the relationship, use the following configuration:

You can define `SERVICE_NAME` as you like, so long as it's unique between all defined services
and matches in both the application and services configuration.

The example above leverages [default endpoint](/docs/configure-apps/image-properties/relationships) configuration for relationships.
That is, it uses default endpoints behind the scenes, providing a [relationship](/docs/configure-apps/image-properties/relationships)
(the network address a service is accessible from) that is identical to the *name* of that service.

Depending on your needs, instead of default endpoint configuration,
you can use [explicit endpoint configuration](/docs/configure-apps/image-properties/relationships).

With the above definition, the application container (`APP_NAME`) now has access to the service via the relationship `<RELATIONSHIP_NAME>` and its corresponding [service environment variables](/docs/development/variables#service-environment-variables).

If you split the service into multiple endpoints, define multiple relationships.

### Example configuration

```yaml .upsun/config.yaml theme={null}
applications:
  # The name of the app container. Must be unique within a project.
  myapp:
    relationships:
      vault_secret: "vault-kms:manage_keys"

services:
  # The name of the service container. Must be unique within a project.
  vault-kms:
    type: vault-kms:1.12
    configuration:
      endpoints:
        manage_keys:
          - policy: admin
            key: vault-sign
            type: sign
          - policy: sign
            key: vault-sign
            type: sign
          - policy: verify
            key: vault-sign
            type: sign
```

## Multiple endpoints example

```yaml .upsun/config.yaml theme={null}
applications:
  # The name of the app container. Must be unique within a project.
  myapp:
   relationships:
      vault_manage:
        service: vault-kms
        endpoint: management
      vault_sign:
        service: vault-kms
        endpoint: sign_and_verify

services:
  # The name of the service container. Must be unique within a project.
  vault-kms:
    type: vault-kms:1.12
    configuration:
      endpoints:
        management:
          - policy: admin
            key: admin-key
            type: sign
        sign_and_verify:
          - policy: sign
            key: signing-key
            type: sign
          - policy: verify
            key: signing-key
            type: sign
```

## Use Vault KMS

To connect your app to the Vault KMS, use a token that's defined in the [service environment variables](#relationship-reference).
With this token for authentication,
you can use any of the policies you [defined in your `.upsun/config.yaml` file](#1-configure-the-service).

You can obtain the complete list of available service environment variables in your app container by running `upsun ssh env`.

Note that the information about the relationship can change when an app is redeployed or restarted or the relationship is changed. So your apps should only rely on the [service environment variables](/docs/development/variables#service-environment-variables) directly rather than hard coding any values.

The following examples use cURL as an example, which you could do in a hook or after accessing your app with SSH.
Adapt the examples for your app's language.

### Get the token

To make any calls to the Vault KMS, you need your token. Get it from the [service environment variables](#relationship-reference):

```bash theme={null}
echo ${RELATIONSHIP_NAME_PASSWORD}"
```

`RELATIONSHIP_NAME` is the relationship name you [defined in your `.upsun/config.yaml` file](#2-define-the-relationship).

You can also store this as a variable:

```bash theme={null}
VAULT_TOKEN=${RELATIONSHIP_NAME_PASSWORD}
```

A given token is valid for one year from its creation.

### Get the right URL

The [service environment variable](#relationship-reference) also contains the information you need to construct a URL for contacting the Vault KMS: the `host` and `port`.

Assign it to a variable as follows:

```bash theme={null}
VAULT_URL=${RELATIONSHIP_NAME_HOST}:${RELATIONSHIP_NAME_PORT}
```

`RELATIONSHIP_NAME` is the name you [defined in your `.upsun/config.yaml` file](#2-define-the-relationship).

### Manage your keys

Your key names are [defined in your `.upsun/config.yaml` file](#1-configure-the-service). You can manage them if you've set an [admin policy](#policies) for them.

To get information on a key, such as its expiration date, run the following command:

```bash theme={null}
curl \
  --header "X-Vault-Token: $VAULT_TOKEN" \
  http://"$VAULT_URL"/v1/transit/keys/"$KEY_NAME" | jq .
```

`$KEY_NAME` is the name in your `.upsun/config.yaml` file.

To rotate the version of your key, run the following command:

```bash theme={null}
curl \
  --header "X-Vault-Token: $VAULT_TOKEN" \
  http://"$VAULT_URL"/v1/transit/keys/"$KEY_NAME">/rotate \
  --request POST
```

### Sign and verify payloads

If you've set [sign and verify policies](#policies), you can use your keys to sign and verify various payloads, such as a JSON Web Token (JWT) for authentication in your app. Note that all payloads (all plaintext data) must be base64-encoded.

To sign a specific payload, run the following command:

```bash theme={null}
curl \
  --header "X-Vault-Token: $VAULT_TOKEN" \
  http://$VAULT_URL/v1/transit/sign/"$KEY_NAME"/sha2-512 \
  --data "{\"input\": \"$(echo SECRET | base64)\"}"
```

The string at the end of the URL denotes the specific [hash algorithm used by the Vault KMS](https://www.vaultproject.io/api-docs/secret/transit#hash_algorithm).

You get back a JSON object that includes the signature for the payload:

```json theme={null}
{
  "request_id": "a58b549f-1356-4028-d191-4c9cd585ca25",
  ...
  "data": {
    "key_version": 1,
    "signature": "vault-kms:v1:MEUCIAiN4UtXh..."
  },
  ...
}
```

You can then use `data.signature` to sign things such as a JWT.

To verify a payload, run the following command:

```bash theme={null}
curl \
  --header "X-Vault-Token: $VAULT_TOKEN" \
  http://"$VAULT_URL"/v1/transit/verify/"$KEY_NAME"/sha2-512 \
  --data "
{
  \"input\": \"$(echo SECRET | base64)\",
  \"signature\": \"$SIGNATURE\"
}"
```

You get back a JSON object that includes whether or not the signature is valid:

```json theme={null}
{
  "request_id": "5b624718-fd9d-37f6-8b95-b387379d2648",
  ...
  "data": {
    "valid": true
  },
  ...
}
```

A `true` value means the signature matches and a `false` value means it doesn't.

### Encrypt and decrypt data

If you've set [encrypt and decrypt policies](#policies), you can use your keys to encrypt and decrypt any data you want. Note that all of plaintext data you work with must be base64-encoded.

To sign a specific payload, run the following command:

```bash theme={null}
curl \
  --header "X-Vault-Token: $VAULT_TOKEN" \
  http://$VAULT_URL/v1/transit/encrypt/"$KEY_NAME" \
  --data "{\"plaintext\": \"$(echo SECRET | base64)\"}"
```

You get back a JSON object that includes your encrypted data:

```json theme={null}
{
  "request_id": "690d634a-a4fb-bdd6-9947-e895578b79d5",
  ...
  "data": {
    "ciphertext": "vault-kms:v1:LEtOWSwh3N...",
    "key_version": 1
  },
  ...
}
```

To decrypt data that you've already encrypted, run the following command:

```bash theme={null}
curl \
  --header "X-Vault-Token: $VAULT_TOKEN" \
  http://"$VAULT_URL"/v1/transit/decrypt/"$KEY_NAME" \
  --data "
{
  \"ciphertext\": \"$CIPHERTEXT\"
}"
```

You get back a JSON object that your decrypted data base64-encoded:

```json theme={null}
{
  "request_id": "bbd411ca-6ed7-aa8b-8177-0f35055ce613",
  ...
  "data": {
    "plaintext": "U0VDUkVUCg=="
  },
  ...
}
```

To get the value un-encoded, add `| jq -r ".data.plaintext" | base64 -d` to the end of the `curl` command.

#### Rewrap encrypted data

If you have already encrypted data and you have [changed your key version](#manage-your-keys), you can rewrap the encrypted data with the new key.

Assuming `$CIPHERTEXT` stores your encrypted data (`vault:v1:LEtOWSwh3N...`), run the following command:

```bash theme={null}
curl \
  --header "X-Vault-Token: $VAULT_TOKEN" \
  http://"$VAULT_URL"/v1/transit/rewrap/"$KEY_NAME" \
  --data "
{
  \"ciphertext\": \"$CIPHERTEXT\"
}"
```

In the JSON object that's returned, you can notice that the `ciphertext` is different (and now includes the new key version as a prefix) as is the `key_version`:

```json theme={null}
{
  ...
  "data": {
    "ciphertext": "vault-kms:v2:ICRi0yAlH...",
    "key_version": 2
  },
  ...
}
```

## Policies

| Policy | Endpoint | Capabilities | Purpose |
| - | - | - | - |
| `admin` | `transit/keys/${KEY}` | `read` | Access to key properties and various functions performed on keys such as rotation and deletion |
| | `transit/keys/${KEY}/*` | `read`, `create`, `update`, `delete` | |
| `sign` | `transit/sign/${KEY}/${HASH_ALGORITHM}` | `read`, `update` | Signing payloads with an existing key |
| `verify` | `transit/verify/${KEY}/${HASH_ALGORITHM}` | `read`, `update` | Verifying already signed payloads |
| `encrypt` | `transit/encrypt/${KEY}` | `read`, `update` | Encrypting data with an existing key |
| `decrypt` | `transit/decrypt/${KEY}` | `read`, `update` | Decrypting data with an existing key |
| `rewrap` | `transit/rewrap/${KEY}` | `read`, `update` | Re-encrypting data with a new key version without revealing the secret |


# Subscribe to an add-on
Source: https://developer.upsun.com/docs/administration/billing/add-on-subscription

Subscribe to add-ons to enhance your user experience.

Depending on your needs, you may want to upgrade to the following Upsun Cloud add-ons.
You can do so directly from the Console.

## Advanced User Management add-on

### Included features

The Advanced User Management add-on gives you access to the following features:

* [Teams](/docs/administration/teams)
* [MFA enforcement](/docs/administration/security/mfa)
* [Single sign-on (SSO)](/docs/administration/security/sso)

<Info>
  Note that the minimum commitment for this add-on is **30 days** before any changes can be made.
</Info>

### Upgrade to the Advanced User Management add-on

To upgrade to the Advanced User Management add-on, follow these steps:

1. In the Console, navigate to your organization.
2. Open the user menu (your name or profile picture), then select **Billing**.
3. In the **Organization add-ons** section of the **Overview** tab,
   locate the **User management** panel and click **Upgrade**.
4. In the pop-up window, select **Advanced user management** and check the 30-day commitment box.
5. Click **Upgrade**.

After the add-on is added to your organization,
you can remove it from the same location in the **Overview** tab
by clicking **Downgrade**.
Once the minimum 30-day commitment period is over,
the add-on is removed from your organization and you are no longer billed for it.

## Continuous Profiling add-on

### Included features

By default, Upsun Cloud offers 15 minutes of continuous profiling per project and for free.
When you upgrade to the continuous profiling add-on,
you get 30 days of continuous profiling per project for a fixed fee.
For more information on incurred costs, see the [Upsun pricing page](https://upsun.com/pricing/).

The [Upsun Cloud performance agent](/docs/get-started/ai/upsun-cloud-performance-agent) can read this profiling data and return a ranked report of bottlenecks with recommended code changes. Each run bills the task container's compute per second, at the resources you allocate to it. You also bring your own model API key and set your own spend ceiling for that provider's charges.

### Upgrade to the Continuous Profiling add-on

To upgrade to this add-on, follow these steps:

1. In the Console, navigate to your organization.
2. Open the user menu (your name or profile picture), then select **Billing**.
3. In the **Overview** tab, find the project on which you want to activate full continuous profiling.
4. Click **<MoreIcon /> More** next to that project.
5. Click **Project billing**.
6. In the **Project add-ons** section,
   locate the **Continuous profiling** panel and click **Enable**.
7. To confirm, click **Enable**.

## Organization Support add-on

The Upsun Cloud Organization Support add-on provides tiered support options tailored to organizational needs. These tiers vary between Standard, Advanced and Premium.

<Tip>
  All organizations are automatically enrolled in the **Standard** support tier. This tier is the default and cannot be removed.
</Tip>

### Available tiers

| Tier | Cost (% of Org Spend) | Urgent SLA | High SLA | Normal SLA | Low SLA |
| - | - | - | - | - | - |
| **Standard** (Default) | 10% | 4h (24/7) | 24h (24/7) | 48h (24/7) | 72h (24/7) |
| **Advanced** | 15% | 1h (24/7) | 6h (24/7) | 12h (24/7) | 24h (24/7) |
| **Premium** | 19% | 30m (24/7) | 3h (24/7) | 8h (24/7) | 24h (24/7) |

<Info>
  <h4>Minimum requirements</h4>
  The Advanced and Premium tiers require a 12 month minimum time commitment (MTC).
</Info>

### Upgrade to the Organization Support add-on

To upgrade to either the Advanced or Premium tier, follow these steps:

1. Visit the **Organization Billing Overview** page in Console.
2. Navigate to the **Organization Add-ons** section.
3. Select your desired support tier.
4. Acknowledge and accept the 12 month MTC.
5. Confirm the upgrade. The new support level will be applied, and billing will be adjusted accordingly.

### Spend calculation

The Organization Support add-on fee is calculated as a percentage of your Organization's total recurring spend, including:

* Projects
* Sellables
* User licenses

For more information on incurred costs, see the [Upsun pricing page](https://upsun.com/pricing/).

<Warning>
  <h4>Exclusions</h4>
  One-time charges, taxes, discounts, and the support add-on itself are **not** included in the spend calculation.
</Warning>

### Downgrading tiers

Downgrades are permitted only after the 365 day MTC has been completed. Organizations may:

* Downgrade from Premium to Advanced
* Downgrade from Advanced or Premium to Standard

Downgrades are performed through the Console and take effect based on the Organization's billing cycle.


# Manage agency and multi-profile billing
Source: https://developer.upsun.com/docs/administration/billing/bp-agency

Understand and manage the agency billing structure — one billing account with multiple billing profiles, one per client.

Agency customers use a multi-profile billing structure: a single billing account that holds one billing profile per client organization. This lets you manage billing for multiple clients from one place while keeping each client's charges, invoices, and payment methods separate.

## Agency billing structure

| Level | Description |
| - | - |
| [Billing account](/docs/glossary#billing-account) | One per agency. Holds the name, country, and tax ID. |
| [Billing profile](/docs/glossary#billing-profile) | One per client. Defines the client's payment method, currency, and billing address. Receives its own invoices. |

## Add a billing profile for a new client

To create a billing profile for an additional client:

1. Complete one of the following steps:
   * From the organization menu (upper left), select an organization and then click **Billing**.
   * From the user menu (upper right), click **Billing** or a billing account.
2. Click **Add billing profile**.
3. Enter a name for the client's billing profile.
4. Select a contract type.
5. Click **Save**.

Once created, link the client's organizations and projects to the new profile and [add a payment method](/docs/administration/billing/bp-payment-method).

## Switch between billing profiles

To switch between client billing profiles:

1. Complete one of the following steps:
   * From the organization menu (upper left), select an organization and then click **Billing**.
   * From the user menu (upper right), click **Billing** or a billing account.
2. Select the billing profile you want to manage from the profile list.

All billing actions — viewing invoices, managing payment methods, setting alerts — apply to the selected profile only.


# View discounts and commitments
Source: https://developer.upsun.com/docs/administration/billing/bp-discounts

Access discount details and commitment values for your billing profile.

View details related to your contract on the **Discounts & commitments** page. Both active and expired commitments are shown.

A *commitment* is a minimum spend you agree to in your contract for a defined period. A *discount* is a reduction applied to your charges in return for meeting that commitment. Upsun determines discount eligibility at the billing profile level when you establish a contract, and applies discounts automatically each billing period.

The Discounts & commitments page uses the following terms:

* **Contract total**: A total of the committed spend and discounts for the entire duration of the contract.
* **Commitment details**: Details shown are determined by the commitment structure agreed upon in the contract.
* **Commitment period**: The duration in which the commitment must be reached.

## Prerequisites

* Familiarize yourself with the [billing account](/docs/glossary#billing-account) and [billing profile](/docs/glossary#billing-profile) concepts.
* A billing account and at least one billing profile must exist. If you have not set these up, see [Set up a billing account and billing profile](/docs/administration/billing/bp-setup).
* You must be a billing member. See [Manage billing members on a billing profile](/docs/administration/billing/bp-users).

## View discounts and commitments

1. Complete one of the following steps:
   * From the organization menu (upper left), select an organization and then click **Billing**.
   * From the user menu (upper right), click **Billing** or a billing account.
2. On the billing account page, select a billing profile.
3. Click **Discounts & commitments**.

The page displays your contract total, commitment details, and commitment period.

For questions about discounts and commitments for a billing profile, contact the Upsun Finance team using the email address listed on your invoice.


# Edit a billing profile
Source: https://developer.upsun.com/docs/administration/billing/bp-edit-billing-profile

Update the name, contact email, and billing address on an existing billing profile.

You can update a billing profile's name, contact email, and billing address at any time from the Console.

## Prerequisites

* Familiarize yourself with the [billing account](/docs/glossary#billing-account) and [billing profile](/docs/glossary#billing-profile) concepts.
* A billing account and at least one billing profile must exist. If you have not set these up, see [Set up a billing account and billing profile](/docs/administration/billing/bp-setup).
* You must be a billing member with `Manage billing` permission. See [Manage billing members on a billing profile](/docs/administration/billing/bp-users).

## Edit billing profile details

To edit a billing profile:

1. Complete one of the following steps:
   * From the organization menu (upper left), select an organization and then click **Billing**.
   * From the user menu (upper right), click **Billing** or a billing account.
2. On the billing account page, select a billing profile.
3. Click **Billing details**.
4. Update any of the following fields:
   * **Billing profile name**: The name as it appears on invoices.
   * **Billing contact email**: The email address that receives invoices.
   * **Billing address**: The address used for tax calculation and invoice display.
5. Click **Save**.

Your changes are saved and reflected on your next invoice.


# Billing FAQ
Source: https://developer.upsun.com/docs/administration/billing/bp-faq

Answers to common questions and known issues in the billing system.

## I can't create a second billing account

Each email address can only be associated with one billing account. Creating a second billing account with the same email is not permitted. If you need multiple billing accounts, use a different email address for each.

## My invoice is showing the wrong total, missing tax, or missing information

For questions about your invoice, contact the Upsun Finance team using the email address listed on your invoice.

## What happens if a payment fails on my billing profile?

If a payment fails, your billing profile enters a dunning state. The following states are surfaced in the Console:

| State | Description |
| - | - |
| Overdue | A payment attempt failed. Retry the payment or update your payment method to resolve. |
| Has dispute | A charge has been disputed. Contact support to resolve the dispute. |

When your profile is in a dunning state, the **Retry payment** and **Update payment method** actions appear alongside your payment method on the billing profile page.

Dunning restrictions apply at the project level, based on the payment status of each project's billing profile. Projects linked to a healthy billing profile are never affected, even if other projects in the same organization are in a dunning state.

While a billing profile is in a dunning state, projects linked to it can't:

* Be created under that billing profile.
* Be moved to a different billing profile.
* Have their resource allocation changed, whether through Git, the API, or an add-on purchase.


# View invoices
Source: https://developer.upsun.com/docs/administration/billing/bp-invoices

View current and past invoices for your billing profile, including invoice ID, amount, status, and line-item usage charges.

Invoices are generated at the end of each billing period and are available directly from your billing profile.
Each invoice includes line items showing the services and usage charged during that period.

## Prerequisites

* Familiarize yourself with the [billing account](/docs/glossary#billing-account) and [billing profile](/docs/glossary#billing-profile) concepts.
* A billing account and at least one billing profile must exist. If you have not set these up, see [Set up a billing account and billing profile](/docs/administration/billing/bp-setup).
* You must be a billing member. See [Manage billing members on a billing profile](/docs/administration/billing/bp-users).

## View billing profile invoices

To view a billing profile's invoices:

1. Complete one of the following steps:
   * From the organization menu (upper left), select an organization and then click **Billing**.
   * From the user menu (upper right), click **Billing** or a billing account.
2. On the billing account page, select a billing profile.
3. Click **Invoices**.

Each invoice is listed with its ID, date, and amount.

### Upcoming vs. past invoices

Upcoming invoices are prorated estimates for the current, open billing period, shown excluding tax, with viewable line-item details until they're charged at the end of the billing cycle.

Past invoices are finalized and closed, so you can only download them as a PDF rather than view interactive details.

In the Console, invoices with **Current** status appear in the **Upcoming** section, and invoices with **Closed** status appear under their billing year (for example, **2026**).

## Update your billing information

To update your billing information, [edit your billing profile](/docs/administration/billing/bp-edit-billing-profile).

For questions about an invoice, contact the Upsun Finance team using the email address listed on your invoice.


# Monitor spending and usage
Source: https://developer.upsun.com/docs/administration/billing/bp-monitor-billing

View monthly cost and usage estimates for your billing profile, and set billing and traffic alerts to catch spending increases early.

To help you manage costs related to projects linked to your billing profile,
you can view the projected total costs for the current month and the next month.

You can also set alerts to notify you when monthly cost or traffic thresholds are reached.

The Console shows the unit price used to calculate your estimated monthly projected totals. For additional pricing information, refer to the [Upsun pricing page](https://upsun.com/pricing/).

## Prerequisites

* Familiarize yourself with the [billing account](/docs/glossary#billing-account) and [billing profile](/docs/glossary#billing-profile) concepts.
* A billing account and at least one billing profile must exist. If you have not set these up, see [Set up a billing account and billing profile](/docs/administration/billing/bp-setup).

## View cost and usage estimates

You must be a billing member. See [Manage billing members on a billing profile](/docs/administration/billing/bp-users).

View summary and detailed cost and usage info on the **Cost & usage** page of your billing profile.

1. Complete one of the following steps:
   * From the organization menu (upper left), select an organization and then click **Billing**.
   * From the user menu (upper right), click **Billing** or a billing account.
2. On the billing account page, select a billing profile.
3. Click **Cost & usage**.
4. To view cost projections for individual projects, drill down by organization in the **Cost breakdown** section.

The [**Summary**](#view-the-monthly-projected-total-for-all-projects) and [**Cost breakdown**](#view-the-monthly-projected-cost-per-project) sections show **projected totals** based on the actual usage to date and an estimate of the rest of the month using the daily average.

To notify billing members before costs exceed your budget, [set a billing alert](#set-a-billing-alert).

### View the monthly projected total for all projects

In the **Summary** section of the **Cost & usage** page, view the current month's projected total cost (excluding tax).

The projected total combines your actual usage to date with an estimate for the rest of the month, based on your daily average usage. **It can't be 100% accurate, because it's impossible to know your exact future usage.**

The projected total is based on:

* Your organization settings (such as user management settings, number of projects, add-ons, and support SLA)
* Resource allocation of the projects included in this billing profile

To view the monthly cost breakdown by project, drill down to a project by organization in the [**Cost breakdown**](#view-the-monthly-projected-cost-per-project) section.

### View the monthly projected cost per project

In the **Cost breakdown** section of the **Cost & usage** page, view each project's projected total cost (excluding tax).

The current month's breakdown is calculated from:

* Resources used so far in the billing cycle
* Averages of previous resource usage, to estimate the remaining costs for the month

Click **Future** to view a projection of next month's costs. Like the current month total, this projection can't be 100% accurate, because it's impossible to know your exact future usage. It's based on the same factors described in [View the monthly projected total for all projects](#view-the-monthly-projected-total-for-all-projects).

To catch cost increases before they add up, [set a billing alert](#set-a-billing-alert).

## Alerts and notifications

### Billing event notifications

Upsun sends email notifications about the following events to billing members:

| Event | Description |
| - | - |
| Payment overdue | Sent when a payment attempt fails and your billing profile enters an overdue state. |
| Payment dispute | Sent when a charge on your billing profile is disputed. |
| Invoice available | Sent when a new invoice is generated at the end of the billing period. |

Notifications are sent to billing members. To manage who receives these notifications, see [Manage billing members on a billing profile](/docs/administration/billing/bp-users).

### Set a billing alert

You must be a billing member with `Manage billing` permission to set a billing alert. See [Manage billing members on a billing profile](/docs/administration/billing/bp-users).

To help you monitor your costs, determine a billing threshold that, when reached, triggers an email when the charges for all
organizations in this billing profile reach the defined threshold for the current month.

The alert is based on your actual usage, which Upsun updates daily.

Actual usage includes costs for allocated CPU, memory, storage, environments, and users.

To set a billing alert:

1. Complete one of the following steps:
   * From the organization menu (upper left), select an organization and then click **Billing**.
   * From the user menu (upper right), click **Billing** or a billing account.
2. On the billing account page, select a billing profile.
3. Click **Cost & usage**.
4. Click **Set alert**.
5. Enter a monthly threshold and click **Create alert**.

Upsun updates actual usage once daily. If your actual usage across all organizations and projects in the profile crosses the threshold you set, billing members receive one notification per day until you resolve the alert.

To edit or delete an alert, click the alert indicator, and adjust the threshold or delete the alert.

### Set a traffic alert on a project

You must be a billing member with `Manage billing` permission to set a traffic alert. See [Manage billing members on a billing profile](/docs/administration/billing/bp-users).

You can set consumption alerts for your resource usage on a project.

1. In the Console, navigate to a project: Select an organization from the **All projects** menu (upper right), then select a project.
2. In the **Traffic this month** block on the project landing page, click the **Alert** icon.
3. Configure usage thresholds for Origin bandwidth, Origin requests, CDN bandwidth and CDN requests (if applicable).
4. Save your changes.

When a threshold is reached during the month, billing members receive an email notification. To manage who receives these notifications, see [Manage billing members on a billing profile](/docs/administration/billing/bp-users).

#### About traffic alerts

If the actual usage to date for a project rises above its defined threshold, Upsun sends an email to billing members.

Upsun updates traffic and usage data once daily, and sends one alert per day for a maximum of 3 consecutive days after a threshold is crossed, then stops until the threshold resets.


# Add and manage payment methods
Source: https://developer.upsun.com/docs/administration/billing/bp-payment-method

Attach a payment method to your billing profile before you can be charged.

You must attach a payment method to your billing profile before any charges can be processed.

## Prerequisites

* Familiarize yourself with the [billing account](/docs/glossary#billing-account) and [billing profile](/docs/glossary#billing-profile) concepts.
* A billing account and at least one billing profile must exist. If you have not set these up, see [Set up a billing account and billing profile](/docs/administration/billing/bp-setup).
* You must be a billing member with `Manage billing` permission. See [Manage billing members on a billing profile](/docs/administration/billing/bp-users).

## Add or update a payment method

To add or update a payment method on your billing profile:

1. Complete one of the following steps:
   * From the organization menu (upper left), select an organization and then click **Billing**.
   * From the user menu (upper right), click **Billing** or a billing account.
2. On the billing account page, select a billing profile.
3. Click **Billing details**.
4. In the **Payment method** section, click **Add payment method** or **Update**.
5. Select a payment method type, enter your details, and complete payment workflows when prompted.
6. Agree to the payment terms and click **Save**.

Your payment method is saved and will be charged for future invoices.

View your upcoming invoices anytime on the **Invoices** page of your billing profile.


# Set up a billing account and billing profile
Source: https://developer.upsun.com/docs/administration/billing/bp-setup

To set up billing, start by creating a billing account, configuring a billing profile, and linking Upsun Cloud organizations to a billing profile.

Upsun Cloud’s billing system consolidates all charges — projects, add-ons, SLA commitments, and support plans — into a single place, giving you a unified view of consumption across your organizations.

Before you begin, familiarize yourself with the [billing account](/docs/glossary#billing-account) and [billing profile](/docs/glossary#billing-profile) concepts.

## Step 1: Create a billing account

To create a billing account:

1. In the Console, click the user menu near the upper right of the page and select **Billing**.
2. Complete one of the following steps.

   * **If you have a trial Upsun account**: Select the account type to create; then click **Save and continue**.
     * **Individual**: For individuals who use Upsun Cloud for personal use or who are Upsun trial account users.
     * **Company**: For incorporated companies or legal entities that have a tax ID for their country.
     * **Public sector**: For government owned or funded entities.
   * **If you don't have a trial account**: In the **Billing account** section on the **Details** page, click **Add new account**.
3. Enter the full name of the legal entity responsible for billing and the country in which the entity is located. Then click **Save and continue**.

To navigate to your billing information later, from the user menu (upper right), select **Billing**, or select a billing account if you have multiple.

## Step 2: Create a billing profile

To create a billing profile:

1. Enter the billing profile details; then, save your changes.
   * **Billing profile name**: The name as it should appear on the invoice. It also helps you identify this profile across invoices and billing settings.
   * **Billing contact email**: The email address of the invoice recipient.
   * **Organization type**: Choose which type of Upsun Cloud organization can be billed under this profile. **You cannot change this setting later.** Choose **Fixed** only when billing existing Upsun Fixed organizations.
2. Choose a payment method and add the payment method details as prompted.
3. Agree to the payment terms and save your changes.
4. Follow any additional instructions, if presented, for linking payment information to your Upsun account.

The organization owner who creates the billing profile automatically receives `Manage billing` permission for it. To invite other billing members afterward, see [Manage billing members on a billing profile](/docs/administration/billing/bp-users).

From the user menu (upper right), select **Billing** or a billing account; then, on the **Details** page, click a billing profile.


# Transfer an organization to a different billing profile
Source: https://developer.upsun.com/docs/administration/billing/bp-transfers

Move an organization to a different billing profile by contacting Support.

Transferring the billing ownership of an organization to a different billing profile currently requires manual intervention. There is no self-serve flow for these operations.

To transfer organization ownership instead, see [Transfer organization ownership](/docs/administration/organizations#transfer-organization-ownership).

## Prerequisites

* Familiarize yourself with the [billing account](/docs/glossary#billing-account) and [billing profile](/docs/glossary#billing-profile) concepts.
* A billing account and at least one billing profile must exist. If you have not set these up, see [Set up a billing account and billing profile](/docs/administration/billing/bp-setup).

## Request a transfer

To transfer an organization to a billing profile, [contact Support](/docs/core-concepts/get-support) with the following information:

* The name or ID of the organization to transfer.
* The destination billing profile.
* The reason for the transfer.

Support will process the transfer and confirm when it is complete.


# Manage billing members on a billing profile
Source: https://developer.upsun.com/docs/administration/billing/bp-users

Invite and manage billing members who can access and administer a billing profile.

You can invite other billing members to manage a billing profile alongside you.
Billing members can view invoices, manage payment methods, and update billing details.

When inviting a billing member, assign one of the following permissions:

| Permission | Description |
| - | - |
| Manage billing | Full access to manage the billing profile, including payment methods, invoices, and billing details. |
| View billing | Read-only access to billing information for the profile. |

<Note>
  Adding users with billing-only access is free and won't increase your monthly cost.
</Note>

## Prerequisites

* Familiarize yourself with the [billing account](/docs/glossary#billing-account) and [billing profile](/docs/glossary#billing-profile) concepts.
* A billing account and at least one billing profile must exist. If you have not set these up, see [Set up a billing account and billing profile](/docs/administration/billing/bp-setup).
* You must be a billing member with `Manage billing` permission to add other billing members.

## Add a billing member to a billing profile

To add a billing member to a billing profile:

1. Complete one of the following steps:
   * From the organization menu (upper left), select an organization and then click **Billing**.
   * From the user menu (upper right), click **Billing** or a billing account.
2. On the billing account page, select a billing profile.
3. Click **Billing details**.
4. In the **Billing access** section, click **Add user**.
5. Enter one or more email addresses (separated by commas) and click **Invite**. The billing members you invite must have an Upsun account.

The invited billing member receives an email invitation to access the billing profile.


# View vouchers
Source: https://developer.upsun.com/docs/administration/billing/bp-vouchers

View promotional credits applied to your billing profile.

Vouchers are promotional credits that reduce charges on your billing profile. Upsun assigns and applies vouchers to your billing profile automatically: no action is required on your part.

Each voucher has one of the following statuses:

| Status | Description |
| - | - |
| Scheduled | The voucher has been assigned but its period has not yet started. |
| In use | The voucher is active and currently being applied to your charges. |
| Completed | The voucher period has ended and the full credit has been used. |
| Expired | The voucher was not fully used before its expiry date. |

## Prerequisites

* Familiarize yourself with the [billing account](/docs/glossary#billing-account) and [billing profile](/docs/glossary#billing-profile) concepts.
* A billing account and at least one billing profile must exist. If you have not set these up, see [Set up a billing account and billing profile](/docs/administration/billing/bp-setup).
* You must be a billing member. See [Manage billing members on a billing profile](/docs/administration/billing/bp-users).

## View billing profile vouchers

To view all vouchers for a billing profile:

1. Complete one of the following steps:
   * From the organization menu (upper left), select an organization and then click **Billing**.
   * From the user menu (upper right), click **Billing** or a billing account.
2. On the billing account page, select a billing profile.
3. Click **Vouchers**.
4. Click a voucher to expand it and view its details, including which invoices it has been applied to.


# Billing
Source: https://developer.upsun.com/docs/administration/billing/index

Understand billing accounts and billing profiles, and manage your charges, invoices, and payment methods from the Console.

Upsun Cloud's billing system consolidates all charges — projects, add-ons, SLA commitments, and support plans — into a single place, giving you a unified view of consumption across your organizations.

Two key concepts to understand before you begin: the [billing account](/docs/glossary#billing-account) and the [billing profile](/docs/glossary#billing-profile).

Billing is calculated per billing profile and represents the aggregate of all projects in the organizations linked to that profile.

To get started, see the **Set up billing** card below.

<CardGroup>
  <Card title="Set up billing" icon="circle-play" href="/docs/administration/billing/bp-setup">
    Create a billing account and billing profile to start managing charges.
  </Card>

  <Card title="Add or update a payment method" icon="credit-card" href="/docs/administration/billing/bp-payment-method">
    Attach or replace the payment source on your billing profile.
  </Card>

  <Card title="View invoices" icon="receipt-text" href="/docs/administration/billing/bp-invoices">
    Access current and historical invoices and review line-item charge breakdowns.
  </Card>

  <Card title="Monitor spending and usage" icon="chart-line" href="/docs/administration/billing/bp-monitor-billing">
    View projected costs and set billing and traffic alerts for your billing profile.
  </Card>

  <Card title="Manage billing members" icon="users" href="/docs/administration/billing/bp-users">
    Invite and manage users who can access and administer a billing profile.
  </Card>
</CardGroup>


# Administration
Source: https://developer.upsun.com/docs/administration/index

Administration tasks for your Upsun Cloud projects is accessible from within the Console and through the CLI.


<CardGroup>
  <Card title="Console" icon="monitor" href="/docs/administration/web">
    Configure your projects and environments from the Upsun Cloud Console.
  </Card>

  <Card title="Organizations" icon="building" href="/docs/administration/organizations">
    Manage multiple Upsun Cloud projects at once through organizations.
  </Card>

  <Card title="Teams" icon="users" href="/docs/administration/teams">
    Manage team access and permissions across your projects.
  </Card>

  <Card title="Users" icon="user" href="/docs/administration/users">
    Manage user access and permissions across your projects.
  </Card>

  <Card title="Pricing" icon="credit-card" href="/docs/administration/pricing">
    Understand how Upsun Cloud pricing works.
  </Card>

  <Card title="Billing" icon="receipt" href="/docs/administration/billing">
    Keep your billing details up to date and manage costs.
  </Card>

  <Card title="Server upgrades" icon="server" href="/docs/administration/servers">
    Information about how Upsun Cloud updates servers.
  </Card>

  <Card title="Security" icon="shield" href="/docs/administration/security">
    Enable MFA or SSO for enhanced security.
  </Card>
</CardGroup>


# Organizations
Source: https://developer.upsun.com/docs/administration/organizations

See how to manage multiple Upsun Cloud projects at once through organizations.

Organizations allow you to manage your Upsun Cloud projects, users, and billing.
You can group multiple projects in one organization and manage them together.

To manage users within your organization, see how to [manage organization users](/docs/administration/users#manage-organization-users).

## Manage your organization settings

As an organization owner, you can manage the basic settings for your organization such as its name and URL.

<Tabs>
  <Tab title="Using the Console">
    1. Navigate to the organization you want to manage (or a project in it).
    2. Open the user menu (your name or profile picture).
    3. Click **Settings**.
    4. Click **Edit** to edit the label or click in the **Organization URL** field to edit the URL.
    5. Click **Save**.
  </Tab>

  <Tab title="Using the CLI">
    To change the name (URL) and label of the `acme` organization, run:

    ```bash theme={null}
    upsun organization:info --org acme label "Acme Corp" name acme-corp
    ```

    To verify the changes, run:

    ```bash theme={null}
    upsun organization:info --org acme-corp
    ```
  </Tab>
</Tabs>

## Manage your organization billing

As an organization owner or an organization user with the **Manage billing** permission,
you can access and download invoices and edit billing information such as the stored credit card and billing address.

<Tabs>
  <Tab title="Using the Console">
    1. Navigate to the organization you want to manage (or a project in it).
    2. Open the user menu (your name or profile picture).
    3. Click **Billing**.
  </Tab>
</Tabs>

## Create a new organization

You can create new organizations with different payment methods and billing addresses
and organize your projects as you want.

<Tabs>
  <Tab title="Using the Console">
    1. Navigate to your existing organization or a project in it.
    2. Open the user menu (your name or profile picture).
    3. Click **Create Organization**.
    4. Enter the required information (label, organization URL, company name, country, security contact).
    5. Click **Create organization**.
  </Tab>

  <Tab title="Using the CLI">
    To create an organization with the label `Acme` and the name (URL) `acme`, run:

    ```bash theme={null}
    upsun organization:create --label "Acme" --name acme --country "United States"
    ```

    To verify the changes, run:

    ```bash theme={null}
    upsun organization:info --org acme
    ```
  </Tab>
</Tabs>

<Note>
  To monitor your spend, you can [set billing alerts](/docs/administration/billing/bp-monitor-billing#set-a-billing-alert) on your new organization.
  When the cost of your actual usage (which Upsun Cloud updates daily) within your billing period reaches the defined threshold, members with `Manage billing` permission receive an email notification.
</Note>

## Delete an existing organization

As an organization owner, you can delete your own organization.

Note that if your organization owns projects or owes remaining invoices, you can not delete it yourself.
To have it deleted, [contact support](/docs/core-concepts/get-support).

<Tabs>
  <Tab title="Using the Console">
    1. Navigate to your existing organization or a project in it.
    2. Open the user menu (your name or profile picture).
    3. Click **Settings**.
    4. Click **Delete Organization**.
    5. Confirm your decision by clicking **Delete**.
  </Tab>

  <Tab title="Using the CLI">
    To delete the organization `acme`, run:

    ```bash theme={null}
    upsun organization:delete --org acme
    ```
  </Tab>
</Tabs>

## Transfer project ownership

You can transfer your project ownership to a different organization at anytime.
To do this, you must be an organization owner or have the [manage billing permission](/docs/administration/users#organization-permissions).

1. Make the new organization owner a [project admin](/docs/administration/users)
   for the project you want to transfer.
2. To ask for the transfer, from your organization account open a [support ticket](/docs/core-concepts/get-support).

<Note>
  Once the project transfer is completed, the new organization can administer all project settings and billing and receives future invoices. Subscription charges are automatically transferred to the new organization.
</Note>

## Transfer organization ownership

To transfer an organization to a different owner, first make sure that user is part of the organization.
If they aren't yet, [add them](/docs/administration/users#add-a-user-to-an-organization). Then open a [support ticket](/docs/core-concepts/get-support) from the current organization to ask for the transfer.

<Note>
  Once the organization transfer is completed, the new organization owner can administer all organization and project settings, including billing. Note that transferring organization ownership does not automatically update the organization's payment method. The existing payment method remains on file until the new owner replaces it. The new owner should review and update the payment details at the time of transfer to avoid unintended charges to the previous payment method.
</Note>

## Upsun Fixed and Upsun Cloud organizations

### What is an Upsun Fixed organization?

<Warning>
  Upsun Fixed is no longer available as a new offering and has been removed from the product catalog.

  Existing Upsun Fixed customers can continue to manage their organizations as before and can create new
  organizations by [contacting Support](https://fixed.docs.upsun.com/administration/organizations.html#create-a-fixed-organization).

  [Upsun Cloud](#what-is-an-upsun-cloud-organization) is the default for new customers.
</Warning>

Upsun Fixed is designed for workloads with consistent, predictable resource requirements. With a Fixed organization, you select a plan with predefined CPU and memory resources. You cannot adjust these resources or scale them automatically. To increase capacity, you must upgrade to a higher plan.

<Info>
  **Fixed:** Resources from the plan are applied to the production environment. For preview environments, the default small size is used for all containers.
</Info>

### What is an Upsun Cloud organization?

Upsun Cloud is designed for workloads that evolve over time or have dynamic resource requirements, and suits most use cases.
With an Upsun Cloud organization, you allocate the exact CPU and memory resources your applications and services need. You can adjust these resources at any time or configure automatic scaling. You are charged based on the resources you allocate.

By default, all new organizations are Upsun Cloud organizations.

<Info>
  **Upsun Cloud:** You can customize resources per container (per app or service) for **all** environments.
</Info>

### Feature differences

If you are an existing Upsun Fixed customer, you can use the information in this section to help you
decide whether to [convert](/tutorials/migration/from-fixed) your existing Upsun Fixed projects to Upsun Cloud.

#### Developer experience

| **Feature** | **Upsun Fixed** | **Upsun Cloud** |
| - | - | - |
| Manual backups | Yes | Yes |
| Health notifications | Yes | Yes |
| Preview environments | Yes | Yes |
| Free SSL certificates | Yes | Yes |
| Source integrations (GitHub, GitLab, Bitbucket) | Yes | Yes |
| Runtime operations | Yes | Yes |
| Custom # of preview environments | No (3 small included, purchase by bulk of 3) | Yes |
| Custom size of preview environments | No | Yes |
| Resource allocation | Project Level Plans | Container Level |
| Custom build resources | No | Yes |
| Autoscaling | No | Yes |
| Horizontal scaling of apps | No | Yes |
| Guaranteed CPU | No | Yes |
| Dedicated architecture | Yes | No |
| Custom domains on preview environments | Enterprise and Elite only | Yes |
| Automated code updates | Enterprise and Elite only | Yes |
| Manual deployment | Enterprise and Elite only | Yes |
| Zero downtime deployment | Enterprise and Elite only | Yes |
| Custom backup retention policies | Different packages | Unlimited (pay for storage) |
| Email SMTP server | Yes | Yes |
| Email validation (DKIM) | Enterprise and Elite only | Yes |
| ElasticSearch (Premium containers) | Enterprise and Elite only | No |
| MongoDB (Premium containers) | Enterprise and Elite only | No |

#### Observability tools

| **Feature** | **Upsun Fixed** | **Upsun Cloud** |
| - | - | - |
| Logs forwarding | Enterprise and Elite only | Yes |
| Upsun Blackfire | Enterprise and Elite only (or self-service add-on) | Yes |
| HTTP Traffic | Yes (but longer timeframe with Enterprise) | Yes |
| Continuous profiling | Enterprise and Elite only | Yes |
| Resources | Yes (but longer timeframe with Enterprise) | Yes |

#### User management

| **Feature** | **Upsun Fixed** | **Upsun Cloud** |
| - | - | - |
| Google SSO | Enterprise and Elite only | Yes, with add-on |
| OpenID Connect | Elite only | Yes, with add-on |
| Multifactor Authentication | Enterprise and Elite only | Yes, with add-on |
| Teams | Enterprise and Elite only | Yes, with add-on |

#### Support and SLAs

| **Feature** | **Upsun Fixed** | **Upsun Cloud** |
| - | - | - |
| Support SLA | Enterprise and Elite only | Yes, with add-on |
| Uptime SLA | Enterprise and Elite only (Architecture based) | Yes, with add-on |
| CDN | Enterprise and Elite only | Yes |
| Fastly WAF | Enterprise & Elite only as add-on | Yes, with add-on |
| Upsun WAF | Enterprise and Elite only | Yes |

#### Billing

| **Feature** | **Upsun Fixed** | **Upsun Cloud** |
| - | - | - |
| Pay as you go (Monthly) | Yes | Yes |
| Pay with credit card | Yes | Yes |
| Pay with SEPA | Enterprise and Elite only | Yes |
| Volume discounts | No | Yes |

#### Security and Compliance

| **Feature** | **Upsun Fixed** | **Upsun Cloud** |
| - | - | - |
| Privacy regulations | Yes | Yes |
| SOC 2 | Yes | Yes |
| PCI DSS Level 1-compatible | Yes | Yes |
| HIPAA | Enterprise and Elite only in specific regions | Coming soon |

### Upsun Fixed and Upsun Cloud FAQs

#### What happens to my URL?

* `https://auth.api.platform.sh/` will become `https://auth.upsun.com/`.

#### If I had a Fixed organization (previously Platform.sh), will I be redirected to my organizations?

* Yes. You will be automatically redirected to the new Console and can log in using the same credentials.

#### Will I be able to switch if I have both Upsun Fixed and Upsun Cloud organizations?

* Yes. If you already have both organization types, you can navigate between them from a drop-down list in the Console.

#### How will Upsun Fixed vs Upsun Cloud be identifiable in the Console?

* Organizations will have tags next to their names in the Console.
* Organizations will also be categorized by organization type in the Console.

#### Will I be able to access Upsun Fixed projects via the Upsun Cloud CLI?

* Correct.

#### Will I still use the same configuration files for Fixed projects?

* Correct. The same configuration file structures remain (`.platform.app.yaml`, `.platform/services.yaml`, `.platform/routes.yaml`, etc).

#### Besides the name "Platform.sh" going away, will there be visual changes in the Console?

Yes.

* Ability to navigate between organization types.
* <a href="https://auth.upsun.com/register/">**15-day free trial**</a> for users creating Upsun Cloud organizations.

#### With a unified CLI, will there be a way to identify Upsun Fixed vs Upsun Cloud in the project list?

* You will see a list of all organizations.
* There is no field in the CLI that explicitly identifies Upsun Fixed vs Upsun Cloud.

#### Do Upsun Cloud projects run in the same regions as Platform.sh projects?

Correct.

#### How can I anticipate my monthly invoice with usage-based pricing?

Upsun Cloud gives a monthly price estimation for the current and next full month based on current usage pattern.

#### Can I use the same credentials / SSO / 2FA on Platform and Upsun Cloud?

Yes.

#### Can I use Upsun Blackfire for my Upsun Cloud applications?

Upsun Cloud includes Upsun Blackfire by default.

#### Will Upsun Cloud be delivered entirely on a “self service” model?

Yes. Additionally, Upsun offers discounts based on volume commitment that is contracted for 1+ Year.

#### Can I try Upsun Cloud before buying?

Yes, you can <a href="https://auth.upsun.com/register/">sign-up for the 15-day trial</a> for users creating Upsun Cloud organizations.


# Pricing
Source: https://developer.upsun.com/docs/administration/pricing

Understand how Upsun Cloud pricing works.

Upsun offers flexible, predictable [pricing](https://upsun.com/pricing/) for organizations and projects.

<Info>
  This page is meant to provide some context for how the pricing model relates to technical work on Upsun Cloud.
  It is *not* meant to be your primary resource for the exact costs of certain features.

  The official Upsun [pricing page](https://upsun.com/pricing/) should always be considered the primary source of pricing details.
</Info>

In general, there are four main dimensions that determine the cost of work on Upsun Cloud.

| Pricing dimension | Details |
| - | - |
| Project fees | An individual project on Upsun Cloud comes with a consistent monthly cost. The cost includes all of the orchestration and provisioning characteristics that define the Upsun Cloud platform.<br /><br />It comes with some baseline features and feature limits, such as infrastructure metrics and a certain number of build minutes. Individual preview environments do not come with their own associated creation cost - you are charged only for the resources those preview environments use during their lifespan (see next row). |
| [Project resources](/docs/manage-resources) | Deploying on Upsun Cloud allows you fine-grained control over the amount of resources allocated for your application and service containers. CPU, memory, and disk (including backup disk) are calculated across each organization, project, and environment to determine your overall usage for a billing period. |
| [User licenses](/docs/administration/users) | Each organization user comes with a license fee. Users can be given different levels of access to singular projects within an organization, or to multiple projects, without changing that license fee. There are two exceptions which are not charged the license fee: Viewers and Viewers who Manage Billing. There are no limits to the number of users you can have in an organization. |
| Feature add-ons | There are additional features that can be added to the organization that come with their own cost. Few of these are available immediately during the Beta phase, but more will be added. |

A given organization's monthly billing is then made up of the sum of each of these dimensions.

You can monitor your spend from the Console by viewing [projected cost estimates for the current and next month](/docs/administration/billing/bp-monitor-billing#view-the-monthly-projected-cost-per-project).
You can also [set billing alerts](/docs/administration/billing/bp-monitor-billing#set-a-billing-alert) to notify team members with `Manage billing` permissions when your actual usage for the current month reaches a defined threshold.

For questions about what happens if a payment fails, see [our billing FAQ](/docs/administration/billing/bp-faq#what-happens-if-a-payment-fails-on-my-billing-profile).

Be sure to visit the [Pricing page](https://upsun.com/pricing/) for exact details related to Upsun Cloud pricing.


# Security
Source: https://developer.upsun.com/docs/administration/security/index

For enhanced security, enable Multifactor Authentication (MFA) or Single Sign-On (SSO).

<CardGroup>
  <Card title="Multifactor Authentication (MFA)" icon="shield-check" href="/docs/administration/security/mfa">
    Enhance your organization's security with Multifactor Authentication.
  </Card>

  <Card title="Single Sign-On (SSO)" icon="key" href="/docs/administration/security/sso">
    Configure Single Sign-On for your organization.
  </Card>
</CardGroup>


# Multifactor Authentication (MFA)
Source: https://developer.upsun.com/docs/administration/security/mfa

Enhance your organizations' security with Multifactor Authentication (MFA).

<Info>
  **Feature Availability**

  This feature is available as part of the Advanced User Management add-on. You can [upgrade your organization to this add-on](/docs/administration/billing/add-on-subscription#upgrade-to-the-advanced-user-management-add-on) in the Console.

  For details about the other features included in this add-on, see the [Advanced User Management add-on](/docs/administration/billing/add-on-subscription#advanced-user-management-add-on) help topic section; for pricing information, see the [Upsun pricing](https://upsun.com/pricing/) page.
</Info>

Multifactor Authentication (MFA) enhances security by protecting both your organization and every user account that interacts with it
through SSH or the Upsun Cloud API.

When MFA is enforced within an organization, every project contributor **must** enable MFA on their user account so they can run Git commands,
SSH into an environment, or trigger actions through the Upsun Cloud API.

## Enable MFA on your user account

To access an organization that enforces MFA or any of its projects,
you **must** enable MFA on your user account.
Failure to do so results in forbidden access to the organization from the Console or API,
and an [error message](/docs/development/ssh/troubleshoot-ssh#mfa-related-error-message) when trying to SSH into its environments.

To enable MFA on your user account, follow these steps:

1. In the Console, open the user menu (your name or profile picture).
2. Click **My profile**.
3. On the **Authentication Settings** tab, click **Set up application**.
4. Follow the instructions for the chosen authentication app.
5. Click **Verify & save**.
6. Refresh your SSH credentials by running `upsun login -f` in the CLI.

## Enforce MFA within your organization

Prerequisites:

* You must be an **organization owner** or **admin user**.
* Your organization must have the [Advanced User Management add-on](/docs/administration/billing/add-on-subscription#advanced-user-management-add-on).
* You must first [enable MFA on *your own* user account](#enable-mfa-on-your-user-account) as described above.

To enforce MFA within your organization, follow these steps:

1. In the Console, select an organization from the organization menu in the upper left of the page.

2. Click the organization name again, and from the expanded menu, click **Security**.

   On the **Security** tab, in the **User security settings** section, you can see which users in your organization have [activated MFA for their user accounts](#enable-mfa-on-your-user-account).

3. In the **MFA required** section, click the **Enable MFA** toggle to the on position.

### Send email reminders

To send email reminders to users who haven't enabled MFA on their account:

1. In the Console, select an organization from the organization menu in the upper left of the page.
2. Click the organization name again, and from the expanded menu, click **Security**.
3. On the **Security** tab, in the **User security settings** section, complete the steps below based on the action you want to take.<br /><br />

   * To send an email reminder to an individual user, click **<MoreIcon /> More** beside the user's name and then click **Remind**.<br />

   * To send an email reminder to multiple users at once, select the checkbox beside the names of the users you want to remind. To remind *all* of the users who do not have MFA enabled, select the **Name** checkbox at the top of the list. Then, near the **Name** checkbox, click **Remind**.

An email is sent to the user with instructions on how to enable MFA on their user account.


# Single Sign-On (SSO)
Source: https://developer.upsun.com/docs/administration/security/sso

Upsun Cloud enables you to set up mandatory SSO with a third-party identity provider (IdP) for all your users.


<Info>
  **Feature Availability**

  This feature is available as part of the Advanced User Management add-on. You can [upgrade your organization to this add-on](/docs/administration/billing/add-on-subscription#upgrade-to-the-advanced-user-management-add-on) in the Console.

  For details about the other features included in this add-on, see the [Advanced User Management add-on](/docs/administration/billing/add-on-subscription#advanced-user-management-add-on) help topic section; for pricing information, see the [Upsun pricing](https://upsun.com/pricing/) page.
</Info>

Your SSO provider can be enabled for a specific email domain, for example `@example.com`. Every user with a matching email address needs to log in or register on Upsun Cloud using your SSO provider. Such users can't use an alternative provider, or register a password, or change their email address.

## Mitigation controls

If you deactivate a user on your identity provider, they can't log in or register on Upsun Cloud.

If the user is already logged in to Upsun Cloud, they are automatically deactivated after their access token has expired (generally after 1 hour).

A deactivated user can no longer use SSH, Git, or other Upsun Cloud APIs.

## Service users

If you have a service user with an email address under your SSO domain, such as `machine-user@example.com`, you can exclude that user from the SSO enforcement rule so they aren't required to authenticate through your identity provider.

Please open a [support ticket](/docs/core-concepts/get-support) if you need to exclude a service user.

## SSO providers

### Google

Enforce your users to authenticate with Google. To enable Google SSO, please open a [support ticket](/docs/core-concepts/get-support).

#### Issue with re-authenticating every 15 minutes

If your organization has Google SSO enabled on Upsun Cloud, you may be required to re-authenticate with Google every 15 minutes. This happens when Upsun Cloud doesn't possess a valid refresh token from your Google account.

To resolve this issue:

1. Go to [https://myaccount.google.com/permissions](https://myaccount.google.com/permissions) and revoke the access from the `Upsun` application that has `Access given to auth.api.platform.sh`.
2. Go to [https://auth.upsun.com/auth/authorize/google?prompt=consent](https://auth.upsun.com/auth/authorize/google?prompt=consent) for the system to obtain a valid refresh token for your Google account.

### OpenId Connect

Enforce your users to authenticate with your OpenID Connect (OIDC) provider,
such as Microsoft (Entra ID), Okta, Ory, or Ping Identity.
To enable SSO with your OIDC provider, please
[create a support ticket](https://support.upsun.com/hc/en-us/requests/new?ticket_form_id=35294051960082).


# Server upgrades
Source: https://developer.upsun.com/docs/administration/servers

Information about how Upsun Cloud updates servers

To ensure your projects get the latest features, improvements, and bug fixes, Upsun Cloud updates the servers that deliver services.

No action is needed on your part, and no downtime occurs for your projects.

These upgrades are scheduled ahead of time, and you can reschedule one to another weekday if needed. This is separate from your project's [maintenance window](/docs/core-concepts/build-deploy#maintenance-window), which controls patch updates to your services' container images rather than these servers.

To view these server upgrade events, go to the [activity logs](/docs/observability/logs/access-logs#activity-logs) for any project or environment and then select **Upgrade** from the **Filter** list.

## Affected servers

### Project API server

The project API server responds to API calls to make the CLI and Console work for your project.
It acts as the Git server, mirroring the source repository in the case of [source integrations](/docs/integrations/source).

It stores your app code and project configuration, provides API interfaces,
and orchestrates the build and deploy process and other tasks for your environments.

### Project metrics server

The project metrics server retrieves information about your environments' use of RAM, CPU, and disk.
You can view this information as part of [environment metrics](/docs/observability/metrics).


# Administer teams
Source: https://developer.upsun.com/docs/administration/teams

Manage team access and permissions across all your projects and organizations.

<Info>
  **Feature Availability**

  This feature is available as part of the Advanced User Management add-on. You can [upgrade your organization to this add-on](/docs/administration/billing/add-on-subscription#upgrade-to-the-advanced-user-management-add-on) in the Console.

  For details about the other features included in this add-on, see the [Advanced User Management add-on](/docs/administration/billing/add-on-subscription#advanced-user-management-add-on) help topic section; for pricing information, see the [Upsun pricing](https://upsun.com/pricing/) page.
</Info>

Organizations on Upsun Cloud are made up of both [projects](/docs/projects/) and [users](/docs/administration/users).
While organizations by themselves allow you to assign project and environment type permissions to individual users on individual projects,
having many users and many projects calls for another method to group common access control settings.

**Teams** provide a grouping that connects a subset of an organization's users to another subset of that organization's projects.
That relationship enables organization owners to set default project and environment type access settings for each user and project from one place.

There is no limit to the number of teams that can be defined within a single organization.

## Create a new team

As an organization owner or member with **Manage users** permissions,
you can create new teams.

Teams must belong to an organization, so [create one](/docs/administration/organizations) first.
You can create new organizations with different payment methods and billing addresses
and organize your projects as you want, but keep in mind that both users and teams are restricted to single organizations.

<Tabs>
  <Tab title="Using the Console">
    1. Navigate to your existing organization.
    2. Open the user menu (your name or profile picture).
    3. Select **Teams** from the dropdown.
    4. Click **+ Create team**.
    5. Enter the information for your team. Only the team name is required at this point, but you can define environment type permissions now if you'd like.
    6. Click **Create team**.
  </Tab>

  <Tab title="Using the CLI">
    1. Run the following command:

       ```bash theme={null}
       upsun team:create -o <ORGANIZATION_NAME>
       ```
    2. Enter a team name.
    3. Define your team's project role (admin or viewer).
    4. If your team has viewer rights on the project, define its role on each type of environment.
    5. Enter `Y` to confirm.

    <Note>
      To view a list of all the existing teams in your organization, run the following command:

      ```bash theme={null}
      upsun team:list -o <ORGANIZATION_NAME>
      ```
    </Note>
  </Tab>
</Tabs>

## Delete an existing team

As an organization owner or member with **Manage users** permissions,
you can delete existing teams.

Note that deleting teams and deleting users are not equivalent.
Deleting a team will remove member access permissions to projects described by the team,
but it will *not* [remove users from the organization](/docs/administration/users#remove-a-user-from-an-organization) (or your billing).

<Tabs>
  <Tab title="Using the Console">
    1. Navigate to your existing organization
    2. Open the user menu (your name or profile picture).
    3. Select **Teams** from the dropdown.
    4. Find the team you want to delete under the **Manage teams** list,
       then click **<MoreIcon /> More**.
    5. Click **Delete team**.
    6. Click **Yes** to confirm.
  </Tab>

  <Tab title="Using the CLI">
    1. Run the following command:

       ```bash theme={null}
       upsun team:delete -o <ORGANIZATION_NAME>
       ```
    2. Select the team you want to delete.
    3. Enter `Y` to confirm.
  </Tab>
</Tabs>

## Manage team settings

As an organization owner or member with **Manage users** permissions,
you can manage the settings of existing teams such as:

* [Team name](#team-name)
* [Environment type permissions granted to members on individual projects](#project--environment-type-permissions)
* [Team members](#team-members)
* [Project access](#team-access-to-projects)

### Team name

<Tabs>
  <Tab title="Using the Console">
    1. In the upper left of the Console, navigate to your existing organization.
    2. Click the organization name again and select **Teams** from the menu.
    3. Find the team you want to rename under the **Manage teams** list,
       then click **<MoreIcon /> More**.
    4. Click **Edit team**.
    5. In the sidebar, click **Edit** and edit the team name.
    6. Click **Save**.
  </Tab>

  <Tab title="Using the CLI">
    1. Run the following command:

       ```bash theme={null}
       upsun team:update -o <ORGANIZATION_NAME>
       ```
    2. Select the team you want to rename.
    3. Enter the new name.
    4. Confirm or adjust the team permissions.
    5. Enter `Y` to confirm.
  </Tab>
</Tabs>

### Project and environment type permissions

The primary purpose of teams is to allow organizations to quickly apply, audit, and update project and environment type permissions for groups of users.

<Tabs>
  <Tab title="Using the Console">
    1. In the upper left of the Console, navigate to your existing organization.

    2. Click the organization name again and select **Teams** from the menu.

    3. Find the team you want to modify under the **Manage teams** list,
       then click **<MoreIcon /> More**.

    4. Click **Edit team**.

    5. In the sidebar, you can:

       * Assign **Project permissions** by selecting the check box to make team members *Project admins* of every project added to the team.
       * Assign **Environment type permissions** by using the dropdowns to grant *No access*, *Viewer*, *Contributor*, or *Admin* rights to team members for *Production*, *Staging*, and *Development* project environment types.

    6. Click **Save**.
  </Tab>

  <Tab title="Using the CLI">
    1. Run the following command:

       ```bash theme={null}
       upsun team:update -o <ORGANIZATION_NAME>
       ```
    2. Select the team whose permissions you want to update.
    3. Confirm or adjust the team name.
    4. Adjust the team permissions.
    5. Enter `Y` to confirm.
  </Tab>
</Tabs>

### Team members

#### Add users to a team

To join a team, a user must already have been added [to the organization](/docs/administration/users#manage-organization-access),
where their [organization permissions](/docs/administration/users#organization-permissions) are defined.

<Tabs>
  <Tab title="Using the Console">
    1. In the upper left of the Console, navigate to your existing organization.
    2. Click the organization name again and select **Teams** from the menu.
    3. Find the team you want to modify under the **Manage teams** list,
       then click **<MoreIcon /> More**.
    4. Click **Add user**.
    5. Locate and select organization users from the dropdown.
    6. In the sidebar click the **Edit** link, and edit the team name.
    7. Click **Add users**.
  </Tab>

  <Tab title="Using the CLI">
    1. Run the following command:

       ```bash theme={null}
       upsun team:user:add -o <ORGANIZATION_NAME>
       ```
    2. Select the team you want to add a user to.
    3. Enter the user's email address.
    4. Enter `Y` to confirm.

    <Note>
      To view a list of all the users on a team, follow these steps:

      1. Run the following command:

         ```bash theme={null}
         upsun team:user:list -o <ORGANIZATION_NAME>
         ```

      2. Select the team whose users you want to display.
    </Note>
  </Tab>
</Tabs>

#### Remove users from a team

Note that deleting users from teams and deleting users from organizations are not equivalent.
Deleting users from a team will remove member access permissions to projects described by the team,
but it will *not* [remove users from the organization](/docs/administration/users#remove-a-user-from-an-organization) (or your billing).

<Tabs>
  <Tab title="Using the Console">
    1. In the upper left of the Console, navigate to your existing organization.
    2. Click the organization name again and select **Teams** from the menu.
    3. Find the team you want to modify under the **Manage teams** list,
       then click **<MoreIcon /> More**.
    4. Click **Edit team**.
    5. Find the user you want to remove under the **USERS** tab view,
       then click **<MoreIcon /> More**.
    6. Click **Remove user**.
    7. Click **Yes** to confirm.
  </Tab>

  <Tab title="Using the CLI">
    1. Run the following command:

       ```bash theme={null}
       upsun team:user:delete -o <ORGANIZATION_NAME>
       ```
    2. Select a team.
    3. Select the user you want to remove from the team.
    4. Enter `Y` to confirm.
  </Tab>
</Tabs>

### Team access to projects

#### Adding projects to a team's access

<Tabs>
  <Tab title="Using the Console">
    **Option 1: Add projects to team with from Team settings**

    1. In the upper left of the Console, navigate to your existing organization.
    2. Click the organization name again and select **Teams** from the menu.
    3. Find the team you want to modify under the **Manage teams** list,
       then click **<MoreIcon /> More**.
    4. Click **Edit team**.
    5. Click **+ Add projects**.
    6. Select **All projects**, or choose individual projects from the dropdown.
       <Note>
         **All projects** refers to all existing projects.
         Any future project you create will need to be added to the team manually.
       </Note>
    7. Click **Add to team**.

    <br />

    **Option 2: Add teams to project from project's Access settings**

    1. Navigate to your existing organization.
    2. Select the project you want to add to the existing team.
    3. Navigate to the project's settings by clicking the **<SettingsIcon /> Settings** icon.
    4. Click **Access** settings under **Project settings** in the sidebar.
    5. Select the **TEAMS** tab in the **Access** list view.
    6. Click **+Add to projects**.
    7. Select **All teams**, or choose individual teams from the dropdown.
       <Note>
         **All teams** refers to all existing teams.
         Any future team you create will need to be added to the project manually.
       </Note>
    8. Click **Add to team**.
  </Tab>

  <Tab title="Using the CLI">
    1. Run the following command:

       ```bash theme={null}
       upsun team:project:add -o <ORGANIZATION_NAME>
       ```
    2. Select a team.
    3. Select the project you want the team to access.
    4. Enter `Y` to confirm.

    <Note>
      To view a list of all the projects added to a team, follow these steps:

      1. Run the following command:

         ```bash theme={null}
         upsun team:project:list -o <ORGANIZATION_NAME>
         ```
      2. Select the team whose projects you want to display.
    </Note>
  </Tab>
</Tabs>

#### Remove project from team's access

<Tabs>
  <Tab title="Using the Console">
    **Option 1: Remove projects from a team with from Team settings**

    1. Navigate to your existing organization.
    2. Open the user menu (your name or profile picture).
    3. Select **Teams** from the dropdown.
    4. Find the team you want to modify under the **Manage teams** list,
       then click **<MoreIcon /> More**.
    5. Click **Edit team**.
    6. Find the project you want to modify under the **PROJECTS** tab view,
       then click **<MoreIcon /> More**.
    7. Click **Remove project**.
    8. Select **All projects**, or choose individual projects from the dropdown.
    9. Click **Yes** to confirm.

    <br />

    **Option 2: Remove teams from a project from project's Access settings**

    1. Navigate to your existing organization.
    2. Select the project you want to add to the existing team.
    3. Navigate to the project's settings by clicking the **<SettingsIcon /> Settings** icon.
    4. Click **Access** settings under **Project settings** in the sidebar.
    5. Find the team under the **TEAMS** tab view,
       then click **<MoreIcon /> More**.
    6. Click **Remove team**.
    7. Click **Yes** to confirm.
  </Tab>

  <Tab title="Using the CLI">
    1. Run the following command:

       ```bash theme={null}
       upsun team:project:delete -o <ORGANIZATION_NAME>
       ```
    2. Select a team.
    3. Select the project whose access you want to revoke for the team.
    4. Enter `Y` to confirm.
  </Tab>
</Tabs>


# Administer users
Source: https://developer.upsun.com/docs/administration/users

Manage user access and permissions across all your projects and organizations.

Upsun Cloud offers fine-grained and flexible user permissions across projects and organizations.
When a user is added to a project, they are automatically added to your organization.

<Note>
  <h4>Available add-on</h4>
  The Advanced User Management add-on offers [teams](/docs/administration/teams), [MFA enforcement within an organization](/docs/administration/security/mfa) and [single sign-on](/docs/administration/security/sso). See how to [subscribe to this add-on](/docs/administration/billing/add-on-subscription#advanced-user-management-add-on).
</Note>

## Manage project access

If you have set up an external integration to GitHub, GitLab, or Bitbucket and your users can't clone the project locally,
see how to [troubleshoot source integrations](/docs/integrations/source/troubleshoot).

### Project roles

A user can have one of the following roles to control their access at project level:

| Role | View environment | Push code | Manage user access | Change settings | Execute actions on all environments |
| - | - | - | - | - | - |
| Project admin | Yes | Yes | Yes | Yes | Yes |
| Project viewer | Yes | No | No | No | No |

By default, organization owners have **Project admin** access on all of the projects within their organization.

### Environment type roles

An environment type (Production, Staging, and Development) groups one or more environments together so that you can manage access for all environments of that type:

* A role assigned to an environment type applies to all environments of that type.
* Only one environment per project can be of the type: Production.
  It is set automatically as the default branch and can't be overridden separately.
* You can change an environment's type (except for the Production environment).
* You can have multiple preview (staging and development) environments.

A user can have one of the following roles on an environment type which grants them permissions on all environments of this type:

| Role | View environment | Force push | Push code | Branch environment | SSH access | Change settings | Execute actions |
| - | - | - | - | - | - | - | - |
| Admin | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| Contributor | Yes | No | Yes | Yes | Yes | No | No |
| Viewer | Yes | No | No | Yes | No | No | No |

To customize which roles can use SSH, set [`access` in your app configuration](/docs/configure-apps/image-properties/access).

### View a user's permissions across all of the projects in your organization

For each user, you can view a summary of their roles and permissions
across all projects in your organization.

<Tabs>
  <Tab title="Using the CLI">
    This feature is available for **v4.1.2+** of the CLI.

    Run a command similar to the following,
    using the email address of the user whose permissions you want to view:

    ```bash theme={null}
    upsun organization:user:projects --org <ORGANIZATION_NAME> <EMAIL_ADDRESS>
    ```
  </Tab>

  <Tab title="In the Console">
    1. Open the organization menu (your organization name in the upper-left).
    2. Click **Users**.
    3. For the user whose user permissions you want to view, click **<MoreIcon /> More**.
    4. Click **Edit user**.
  </Tab>
</Tabs>

### Add a user to a project

To invite a user, you need to be a [project admin](#project-roles).

To add a user, follow these steps:

<Tabs>
  <Tab title="Using the CLI">
    To add a user, run the following command:

    ```bash theme={null}
    upsun user:add <EMAIL_ADDRESS> -r <PERMISSIONS_TO_GRANT>
    ```

    For example, if you want to add `user1@example.com` to the project as a project admin,
    run the following command:

    ```bash theme={null}
    upsun user:add user1@example.com -r admin
    ```

    If you want to add `user2@example.com` to the project as a contributor for Development environments
    and a viewer for Staging environments,
    run the following command:

    ```bash theme={null}
    upsun user:add user2@example.com -r development:contributor -r staging:viewer
    ```
  </Tab>

  <Tab title="In the Console">
    1. Select the project where you want to add a new user.
    2. Click <SettingsIcon /> **Settings**.
    3. Click **Access**.
    4. Click **+ Add**.
    5. Add the user's details and choose their permissions.
    6. Click **Save**.
  </Tab>
</Tabs>

The user has to create an account before they can access the project.
Once you add a user to a project, they receive an invitation email with instructions.

To apply SSH access changes after you add a user to a project,
[trigger a redeploy](/docs/troubleshooting/general#force-a-redeploy).

### Manage project users

To manage user permissions on a project, you need to be a [project admin](#project-roles),
be an organization owner, or have the [**Manage users** permission for the organization](#organization-permissions).

To change user permissions, follow these steps:

<Tabs>
  <Tab title="Using the CLI">
    To update an existing user's permissions, run the following command:

    ```bash theme={null}
    upsun user:update <EMAIL_ADDRESS> -r <PERMISSIONS_TO_GRANT>
    ```

    If you want `user1@example.com` to be a viewer for Production environments
    and a contributor for Development environments,
    run the following command:

    ```bash theme={null}
    upsun user:update user1@example.com -r production:viewer,development:contributor
    ```
  </Tab>

  <Tab title="In the Console">
    1. Select the project where you want to update user access.
    2. Click <SettingsIcon /> **Settings**.
    3. Click **Access**.
    4. Click the user you want to update permissions for.
    5. Update environment type permissions, or click **Remove user**.
    6. Click **Accept**.
  </Tab>
</Tabs>

To apply SSH access changes after you add a remove a user from a project or environment type,
[trigger a redeploy](/docs/troubleshooting/general#force-a-redeploy).

### Remove a user from a project

To remove a user from a project, you need to be a [project admin](#project-roles),
be an organization owner, or have the [**Manage users** permission for the organization](#organization-permissions).

To remove a user, follow these steps:

<Tabs>
  <Tab title="Using the CLI">
    Run the following command:

    ```bash theme={null}
    upsun user:delete user1@example.com
    ```
  </Tab>

  <Tab title="In the Console">
    1. Open the organization menu (your organization name in the upper-left).
    2. Click **Users**.
    3. For the user you want to remove, click **<MoreIcon /> More**.
    4. Click on the **Projects** tab
    5. For the project you want to remove them from, click **<MoreIcon /> More**.
    6. Click **Remove from project**.
    7. Click **Yes**.
  </Tab>
</Tabs>

To apply SSH access changes after changing a user's permissions for an environment type,
[trigger a redeploy](/docs/troubleshooting/general#force-a-redeploy).

## Manage organization access

All users who are added to any project within an organization become members of that organization.
By default, such users have no [organization permissions](#organization-permissions).
You can also have organization users who aren't part of any projects.

Users who are a part of an organization with the **List projects** permission can see all projects in that organization at the organization's URL,
which takes the form `https://console.upsun.com/<ORGANIZATION_NAME>`.
They can only access projects they've been explicitly invited to.
For more information on project access control, see how to [manage project users](#manage-project-users).

### Organization permissions

As an organization owner or an organization user with the **Manage users** permission, you can invite other users to your organization and grant them the following permissions:

* **Admin** (`owner`):
  Manage the organization and access all organization permissions, including all listed below.
* **Manage billing** (`billing`):
  Add, remove, and edit billing information.
  Access invoices and vouchers.
  Users with this permission receive monthly invoices by email.
* **Manage users** (`members`):
  Add, remove, and edit organization-level users and permissions, except their own.
  Users with this permission can't grant other users permissions that they themselves don't have.
* **Create projects** (`projects:create`):
  Create new projects within the organization.
* **List projects** (`projects:list`):
  See all projects in an organization, even those the user can't access.

<Note>
  Users with the **Manage users** (`members`) permission can add, edit, or remove *any* user's permissions except their own.

  Users with the **Manage billing** (`billing`) permission automatically are granted **List projects** (`projects:list`) permission.
  That is, they are able to see all organization projects once given billing rights.
</Note>

Users without any of these permissions can only access [projects where they're users](#project-roles).
They can't access or manage the rest of the organization.

Organization owners have all permissions within their organization.
Their permission level can't be edited.
Organization owners can't be removed from their organization,
except through an [ownership transfer](/docs/administration/organizations#transfer-project-ownership).

#### Viewer permissions

A user is considered a viewer only if **all** of the following are true:

* Their organization-level permissions are limited to **view**, `project:list`, or **billing**
* They are **not** an admin or contributor on any project
* They do **not** have team-level access that grants admin permissions

<Note>
  If any of these conditions are not met, the user is counted as an **admin** for billing.
</Note>

### Add a user to an organization

<Tabs>
  <Tab title="Using the CLI">
    To invite a user to your organization, run the following command:

    ```bash theme={null}
    upsun organization:user:add <EMAIL_ADDRESS> --org <ORGANIZATION_NAME> --permission <PERMISSIONS>
    ```

    For example, to invite `alice@example.com` to the `acme` organization
    with the **Manage billing** and **Create projects** permissions, run the following command:

    ```bash theme={null}
    upsun organization:user:add alice@example.com --org acme --permission billing,projects:create
    ```
  </Tab>

  <Tab title="Using the Console">
    1. Open the organization menu (your organization name in the upper-left).
    2. Click **Users**.
    3. Click **+ Invite users**.
    4. Enter the users' email addresses separated by commas.
    5. Select which organization-wide permissions they should have.
    6. Click **Invite**.
  </Tab>
</Tabs>

All users you invite receive an invitation email with instructions.

### Manage organization users

<Tabs>
  <Tab title="Using the CLI">
    To update permissions for a user in your organization, run the following command:

    ```bash theme={null}
    upsun organization:user:update <EMAIL_ADDRESS> --org <ORGANIZATION_NAME> --permission <PERMISSIONS>
    ```

    For example, to update the permissions for `alice@example.com` in your `acme` organization
    so that she has only the **Manage billing** permission, run the following command:

    ```bash theme={null}
    upsun organization:user:update alice@example.com --org acme --permission billing
    ```
  </Tab>

  <Tab title="Using the Console">
    1. Open the organization menu (your organization name in the upper-left).
    2. Click **Users**.
    3. Next to the user you want to manage, click **<MoreIcon /> More**.
    4. Click **Edit user**.

    You see all the projects the user is a part of and their permissions in those projects.
    You also see their permissions across the organization.

    To edit their organization permissions, follow these steps:

    1. Select or clear the checkboxes for the relevant permissions.
    2. Click **Save**.
    3. Click **Yes**.
  </Tab>
</Tabs>

### Remove a user from an organization

<Tabs>
  <Tab title="Using the CLI">
    To update remove a user from your organization, run the following command:

    ```bash theme={null}
    upsun organization:user:delete <EMAIL_ADDRESS> --org <ORGANIZATION_NAME>
    ```

    For example, to remove `alice@example.com` from your `acme` organization, run the following command:

    ```bash theme={null}
    upsun organization:user:delete alice@example.com --org acme
    ```
  </Tab>

  <Tab title="Using the Console">
    1. Open the organization menu (your organization name in the upper-left).
    2. Click **Users**.
    3. Next to the user you want to remove, click **<MoreIcon /> More**.
    4. Click **Remove from organization**.

    To delete users in bulk, select the users to remove and click **Remove users from organization**.
  </Tab>
</Tabs>

Remove a user from an organization will remove them from all projects they were a member of.


# Configure environments
Source: https://developer.upsun.com/docs/administration/web/configure-environment

Configure your environments including their name, status, and visibility.

From your project's main page in the Console, you can see all your environments as a list or a project tree:

<img alt="List of all environments as a tree" />

In this overview, the names of inactive environments are lighter.
Selecting an environment allows you to see details about it,
such as its [activity feed](#activity-feed), [services](#service-information),
[metrics](/docs/observability/metrics), and [backups](/docs/environments/backup).

## Activity Feed

When you access an environment in the Console, you can see its [activity feed](/docs/observability/logs/access-logs#activity-logs).
This allows you to check which activities have happened or are currently happening on the selected environment:

<img alt="Environment activity list" />

You can filter activities by type (such as merge, sync, or redeploy).

## Actions on environments

Each environment offers ways to keep environments up to date with one another:

* [<BranchIcon /> **Branch**](/docs/glossary#branch) to create a new child environment.
* [<MergeIcon /> **Merge**](/docs/glossary#merge) to copy the current environment into its parent.
* [<SyncIcon /> **Sync**](/docs/glossary#sync)
  to copy changes from its parent environment into the current environment.

There are also additional options:

* <SettingsIcon /> **Settings** to [configure the environment](#environment-settings).
* <MoreIcon /> **More** to get more options.
* **URLs** to access the deployed environment from the web.
* **SSH** to access your project using SSH.
* **Code**
  * **CLI** for the command to get your project set up locally with the [Upsun Cloud CLI](/cli).
  * **Git** for the command to clone the codebase via Git.

    If you're using Upsun Cloud as your primary remote repository, the command clones from the project.
    If you have set up an [external integration](/docs/integrations/source),
    the command clones directly from the integrated remote repository.

    If the project uses an external integration to a repository that you haven't been given access to,
    you can't clone until your access has been updated.
    See how to [troubleshoot source integrations](/docs/integrations/source/troubleshoot).

## Environment URL

When you access an environment in the Console, you can view its URL. While the environment is loading in the Console, a `Waiting for URL...` message is displayed instead of the URL. If this message isn't updated once your [default environment](/docs/environments#default-environment)'s information is loaded, follow these steps:

1. Check that [you have defined routes](/docs/routes) for your default environment.
2. Verify that your [application](/docs/configure-apps/app-reference/single-runtime-image), [services](/docs/add-services), and [routes](/docs/routes) configurations are correct.
3. Check that your default environment is [active](/docs/environments/deactivate-environment#reactivate-an-environment).

## Environment settings

To access the settings of an environment, click <SettingsIcon /> **Settings** within that environment.

<img alt="Settings for an environment" />

### Environment name

Under **Environment name**, you can edit the name and type of your environment and view its parent environment:

<img alt="Environment status" />

### Status

Under **Status**, you can check whether or not your environment is [active](/docs/glossary#active-environment).

<img alt="Environment status" />

For preview environments, you can [change their status](/docs/environments/deactivate-environment).

### Outgoing emails

Under **Outgoing emails**, you can allow your environment to [send emails](/docs/development/email):

<img alt="Environment email" />

### Hide from search engines

Under **Hide from search engines**, you can tell [search engines to ignore the site](/docs/environments/search-engine-visibility):

<img alt="Environment search" />

### HTTP access control

Under **HTTP access control**, you can [control access to your environment using HTTP methods](/docs/environments/http-access-control):

<img alt="Settings control access with password and by IP" />

### Variables

Under **Variables**, you can define [environment variables](/docs/development/variables):

<img alt="Configure Upsun Cloud environment variables" />

## Service information

For each environment, you can view information about how your routes, services, and apps are currently configured.

To do so, click **Services**.
By default, you see configured routes.

### Routes

The **Router** section shows a list of all the [routes configured on your environment](/docs/routes).
You can see each route's type and check if caching and server side includes have been enabled for it.

To view the configuration file where your routes are set up, click **Configuration**.

### Applications

To see detailed information about an app container,
select it in the tree or list on the left-hand side:

<img alt="Services: app overview" />

The **Overview** tab gives you information about your app.
You can see:

* The language version, the container size, the amount of persistent disk,
  the number of cron jobs, and the command to SSH into the container.
* A summary of [metrics for the environment](/docs/observability/metrics).
* All cron jobs with their name, frequency, and command.
* All workers with their name, size, amount of persistent disk, and command to SSH into the container.

To view [the configuration file where your app is set up](/docs/configure-apps/), click **Configuration**.

### Services

To see detailed information about a [running service](/docs/add-services),
select it in the tree or list on the left-hand side:

<img alt="Services: service overview" />

The **Overview** gives you information about the selected service.
You can see the service version, the container size, and the disk size, if you've configured a persistent disk.
You can also see a summary of [metrics for the environment](/docs/observability/metrics).

To view the configuration file where your services are set up, click **Configuration**.


# Configure a project
Source: https://developer.upsun.com/docs/administration/web/configure-project

Configure settings that apply across a project, such as the name, access, and domain.

Each project has settings that apply to everything within that project, including all its environments.
You can only see and update settings for projects where you are a [Project Admin](/docs/administration/users).
To access the settings, click <SettingsIcon /> **Settings** from the main project page.

The settings are divided into several sections.

## General

The **General** section shows you the project's region and allows you to update the project name and [timezone](/docs/projects/change-project-timezone).

<img alt="configure project" />

## Access

The **Access** section allows you to [manage user access to the project](/docs/administration/users).

<img alt="Project configure icon" />

## Certificates

The **Certificates** section shows a list of your project's TLS certificates.
To see details about a certificate or delete one, click **Edit <ChevronIcon />**.
See how to [add custom certificates](/docs/domains/steps/tls).

<img alt="A list of certificates in a project" />

## Domains

The **Domains** section allows you to manage the domains where your project is accessible.
See how to [set up your domain](/docs/domains/steps).

<img alt="project domain" />

## Deploy Key

The **Deploy Key** section shows you the public SSH key you can add to your private repositories.
Adding it lets Upsun Cloud access the repositories during the build process.
This is useful if you want to reuse some code components across multiple projects and manage those components as dependencies of your project.

<img alt="Project deploy key" />

## Integrations

The **Integrations** section allows you to manage all of your [integrations](/docs/integrations).

<img alt="Integrations" />

## Variables

The **Variables** section allows you to manage all project-wide [variables](/docs/development/variables).

<img alt="Project variables" />

## Maintenance window

The **Maintenance window** section lets you schedule when Upsun Cloud applies patch updates to your services' container images. See [Maintenance window](/docs/core-concepts/build-deploy#maintenance-window).

<img alt="Maintenance window in Project settings" />


# Console
Source: https://developer.upsun.com/docs/administration/web/index

Upsun Cloud provides a web Console so you can interact with your projects and manage your environments.


<img alt="Overview of projects in the Console" />

This Console offers you ways to manage projects and environments other than the [command line interface (CLI)](/cli).

## Project list

Opening the [Console](https://console.upsun.com) takes you to the first organization you joined  as a
Upsun Cloud user.
You get an overview of all your projects within that organization.
You can narrow the list down by searching for specific projects,
or switch to a different organization from the menu in the top left-hand corner.

Once you select a project, you can [configure the project settings](/docs/administration/web/configure-project).
You can also choose individual environments within the project and [configure each environment](/docs/administration/web/configure-environment).

You can also create a new project by clicking **+ Create project**.

## Display settings

You can personalize the display settings for the Console.
To do so:

1. Open the user menu (your name or profile picture).
2. Click **My Profile**.
3. Choose the mode you want.
4. Click **Save**.

The Console can be displayed in three ways:

* Light mode (default)
* High contrast mode
* Dark mode

To meet our [commitment to accessibility](https://upsun.com/trust-center/legal/),
all three options are compliant with level AA of the Web Content Accessibility Guidelines 2.0.


# Composable image
Source: https://developer.upsun.com/docs/configure-apps/app-reference/composable-image

Use the Upsun Cloud composable image to build and deploy your app.

The Upsun Cloud composable image provides enhanced flexibility when defining your app.
It enables you to install several runtimes and tools in your application container,
in a **"one image to rule them all"** approach.

The composable image is built on [Nix](https://nix.dev), which offers the following benefits:

* You can add as many packages to your application container as you need,
  choosing from over 120,000 packages from [the Nixpkgs collection](https://search.nixos.org/packages).
* The packages you add are built in isolation, enabling you to install different versions of the same package.
* With [Nix](https://nix.dev/reference/glossary#term-Nix), there are no undeclared dependencies in your source code.
  What works on your local machine is guaranteed to work on any other machine.

This page introduces all the settings available to configure your composable image from your `.upsun/config.yaml` file
(usually located at the root of your Git repository).<br />
Note that multi-app projects can be [set in various ways](/docs/configure-apps/multi-app).

You can also skip directly to this [comprehensive example](/docs/configure-apps#comprehensive-example) of a composable image configuration in the "Configure apps" topic. This example includes all of the primary application properties listed in the table in the next section.

## Primary application properties

In the `.upsun/config.yaml` file, configure each application as a unique key beneath the top-level `applications` key.

In a composable image, you can add multiple runtimes to a single application container by defining them in the [`.applications.<APP_NAME>:.stack`](/docs/configure-apps/app-reference/composable-image#example-stack-configuration) key, described later in this topic.

The following table presents all of the properties available to each unique application.

The **Set in instance** column defines whether the given property can be overridden within a `web` or `workers` instance.
To override any part of a property, you must provide the entire property.

<Info>
  * The `type` and `stack` properties are unique to the composable image type and are described later in this topic. All other properties are available in both single-runtime and composable images — click a property name to view its details in a separate topic.
  * The `stack` key replaces the `build`, `dependencies`, and `runtime` keys that are available in the [single-runtime image](/docs/configure-apps/app-reference/single-runtime-image).
</Info>

<div>
  | Name | Type | Required | Set in instance? | Description |
  | - | - | - | - | - |
  | [`type`](#type) | A type | Yes | No | [Defines the version of the Nix channel](#supported-nix-channels). Mandatory in each application that uses the composable image. Example: <code>type: "composable:26.05"</code>. |
  | [`stack`](#stack) | `runtimes` and/or  `packages` arrays | Yes | No | Specifies [Upsun Cloud-supported `runtimes`](#upsun-supported-nix-runtimes) and extra [Nixpkgs `packages`](https://search.nixos.org/packages) beyond those in the `type` channel. |
  | [`container_profile`](/docs/configure-apps/image-properties/container_profile) | A container profile | | Yes | Determines which combinations of CPU and RAM an app or service container can use. Default value is `HIGH_CPU`; see [Resources](#resources-cpu-memory-disk-space) if using multiple runtimes. |
  | [`relationships`](/docs/configure-apps/image-properties/relationships) | A dictionary of relationships | | Yes | Connections to other services and apps. |
  | [`mounts`](/docs/configure-apps/image-properties/mounts) | A dictionary of mounts | | Yes | Directories that are writable even after the app is built. Allocated disk for mounts is defined with a separate resource configuration call using `upsun resources:set`. |
  | [`web`](/docs/configure-apps/image-properties/web) | A web instance | | N/A | How the web application is served. |
  | [`workers`](/docs/configure-apps/image-properties/workers) | A worker instance | | N/A | Alternate copies of the application to run as background processes. |
  | `timezone` | `string` | | No | The timezone for crons to run. Format: a [TZ database name](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). Defaults to `UTC`, which is the timezone used for all logs no matter the value here. See also [app runtime timezones](/docs/projects/change-project-timezone). |
  | [`access`](/docs/configure-apps/image-properties/access) | An access dictionary | | Yes | Access control for roles accessing app environments. |
  | [`variables`](/docs/configure-apps/image-properties/variables) | A variables dictionary | | Yes | Variables to control the environment. |
  | [`hooks`](/docs/configure-apps/image-properties/hooks) | A hooks dictionary | | No | Specifies commands and/or scripts to run in the `build`, `deploy`, and `post_deploy` phases. |
  | [`crons`](/docs/configure-apps/image-properties/crons) | A cron dictionary | | No | Scheduled tasks for the app. |
  | [`source`](/docs/configure-apps/image-properties/source) | A source dictionary | | No | Details about the app’s source code and available operations. |
  | [`additional_hosts`](/docs/configure-apps/image-properties/additional_hosts) | An additional hosts dictionary | | Yes | Mappings of hostnames to IP addresses. |
  | [`authorizations`](/docs/configure-apps/image-properties/authorizations) | | An authorizations dictionary | Yes | An authorizations list that grants applications and tasks narrowly-scoped access to the environment API and task operations. |
  | [`operations`](/docs/configure-apps/runtime-operations) | A dictionary of runtime operations | | No | Runtime operations for the application. |
</div>

## `type`

Required for all applications that use the composable image. Defines the version of the Nix channel that application uses.

For example, to specify the Nix channel `26.05` for `<APP_NAME>`, use the following syntax:

### Supported Nix channels

Upsun Cloud supports the following Nix channel versions:

* 26.05

<Warning>
  <h4>Channel bumps can break your build</h4>
  Upgrading channels (e.g. `25.11` → `26.05`) can break your build even if the runtime version stays supported. Package and extension availability varies per channel: upstream maintainers can drop or alter support without notice, and Upsun Cloud doesn't track per-channel compatibility.

  For example, `openswoole` on `26.05` dropped support for PHP 8.2. A project using that combination on `25.11` will fail to build after a channel bump, even though PHP 8.2 itself remains supported.

  Before bumping a channel, check the [Nixpkgs entry](https://search.nixos.org/packages) for each runtime, extension, and package you rely on, and test in a preview environment first.
</Warning>

View the list of [supported Nix runtimes](#upsun-supported-nix-runtimes) in the `stack` section below.

### Deprecated Nix channels

The following channels are still available in your projects,
but they're at their end of life and are no longer receiving security updates from upstream.

*No deprecated channels.*

To ensure your project remains stable in the future,
switch to a [supported Nix channel](#supported-versions).

### Retired Nix channels

The following channels have been retired and are no longer available.
If your project uses a retired channel, you must update to a [supported Nix channel](#supported-versions).

* 25.11
* 25.05
* 24.11
* 24.05

## `stack`

You must define the `stack` element by using distinct `runtimes` and `packages` keys, as described in the following table.

See the [example `stack` configuration](#example-stack-configuration) that follows this table.

<div>
  | Name | Type | Required | Additional keys | Description |
  | - | - | - | - | - |
  | `runtimes` | array | No | `extensions`, `disabled_extensions`, and related subkeys | An array of 1+ language runtimes specified as `"<nixruntime@version>"` or `<nixruntime>`.<br />The first declared runtime (or *[primary runtime](#working-with-multiple-runtimes-primary-runtime)*) is started automatically.<br />See the complete list of [supported runtimes](#upsun-supported-nix-runtimes) below. |
  | `packages` | array | No | `package`, `channel`, additional keys to demonstrate passthrough flexibility | Additional Nix tools/libraries, using the channel from `type` unless overridden locally by specifying the `package` and its `channel`. Format: `<nixpackage>` |
</div>

<Note>
  <h4>Runtimes extensions or packages?</h4>
  Be sure you understand where to specify a runtime's additional components. For example:

  * **PHP**: Manage extensions by using the `stack.runtimes.extensions` and `stack.runtimes.disabled_extensions` keys.<br />
    * Note: In some scenarios, you might [add PHP settings](/docs/languages/php#customize-php-settings) via environment variables or `php.ini`.

  * **Python**: Install extra packages via the `stack.packages` key.<br />

  See the [example `stack` configuration](#example-stack-configuration) below.<br />
  For other runtimes, see the [Languages](/docs/languages) section.
</Note>

### Example: `stack` configuration

The `config.yaml` file excerpt below shows the following `stack` configuration:

* **Primary runtime:** `php@8.4` with additional extensions and one disabled extension
* **Secondary runtimes:** <code>nodejs\@26</code> and <code>python\@3.14</code>
* **Nix packages:**
  * `yarn` and `python313Packages.yq` from the channel defined in `type`
  * `python313Packages.jupyterlab` (with config) and `wkhtmltopdf` from the `unstable` channel

<Note>
  <h4>Warning</h4>
  Although `nix` commands are available during the build phase, they are not supported at runtime because the final image is read-only.

  When you use the Upsun Cloud composable image, you don't need `nix` commands.
  Anything you declare under the `stack` key is automatically installed and the binaries are included in your `$PATH`, making them immediately available to use.

  For example, to [start a secondary runtime](#working-with-multiple-runtimes-primary-runtime),
  you can run it directly in your [`start` command](/docs/configure-apps/image-properties/web#web-commands) without using `nix run`.
</Note>

### Working with multiple runtimes: primary runtime

If you add multiple runtimes to your application container,
the first declared runtime becomes the primary runtime.
The primary runtime is the one that is automatically started.

To start other declared runtimes (or *secondary* runtimes), you need to start them manually by using [web commands](/docs/configure-apps/image-properties/web#web-commands).
To find out which start command to use, go to the [Languages](/docs/languages) section
and visit the documentation page dedicated to your runtime.

Containers that define multiple runtimes typically require some resource sizing adjustments. For details, see the [Resources](#resources-cpu-memory-disk-space) section of this topic.

See the [`stack` configuration example](#example-stack-configuration) above, which declares multiple runtimes.

### PHP as a primary runtime

If a PHP runtime is the first declared (or *primary*) runtime in the app:

* The PHP-FPM service starts automatically.
* You can configure the PHP-FPMP service by using `request_terminate_timeout` and `sizing_hints` keys in the app's `stack.runtimes` key.

  The [`stack` configuration example](#example-stack-configuration) above declares PHP as a primary runtime but does not show these additional keys.

For the complete list of PHP extension keys and PHP-FPM sizing hints, see [Modify your PHP runtime when using the composable image](/docs/languages/php#modify-your-php-runtime-when-using-the-composable-image) section in the "PHP" topic.

Related resource: [When php-fpm runs out of workers: a 502 error field guide](https://devcenter.upsun.com/posts/when-php-fpm-runs-out-of-workers-a-502-error-field-guide/) (Dev Center article)

### Upsun Cloud-supported Nix runtimes

<Note>
  Upsun Cloud officially supports the Nix runtimes listed below. To use them in your container, add them to the `stack.runtimes` array.<br />
  Runtimes **not** listed below are supported only by Nix as Nixpkgs *packages*, not as Upsun Cloud runtimes. In those cases, add them to `stack.packages`. <br />For example, if your app requires the [FrankenPHP](https://search.nixos.org/packages?channel=unstable\&show=frankenphp\&from=0\&size=50\&sort=relevance\&type=packages\&query=frankenphp) runtime from the `unstable` channel, you would add `frankenphp` to `stack.packages`. See the [`stack` configuration example](#example-stack-configuration) above for a similar addition.
</Note>

For some runtimes (such as Clojure), you can specify only a major version.

For other runtimes (such as Elixir), you can specify a major or a major.minor version.
Security and other patches are applied automatically.

<div>
  <div><div><table><thead><tr><th>Language</th><th>Nix package</th><th>Version</th><th>Supported Nix channels</th></tr><tr><th><span>26.05</span></th><th><span>25.11</span></th></tr></thead><tbody><tr><td><a href="https://clojure.org/">Clojure</a></td><td><a href="https://search.nixos.org/packages?channel=26.05&query=clojure"><code>clojure</code></a></td><td><code>1</code></td><td><span>✓</span></td><td><span>✓</span></td></tr><tr><td><a href="http://www.list-lang.org/">Common List/SBCL</a></td><td><a href="https://search.nixos.org/packages?channel=26.05&query=sbcl"><code>sbcl</code></a></td><td><code>2</code></td><td><span>✓</span></td><td><span>✓</span></td></tr><tr><td><a href="/docs/languages/elixir">Elixir</a></td><td><a href="https://search.nixos.org/packages?channel=26.05&query=elixir"><code>elixir</code></a></td><td><code>1.20</code></td><td><span>✓</span></td><td /></tr><tr><td><code>1.19</code></td><td><span>✓</span></td><td><span>✓</span></td></tr><tr><td><code>1.18</code></td><td><span>✓</span></td><td><span>✓</span></td></tr><tr><td><code>1.17</code></td><td><span>✓</span></td><td><span>✓</span></td></tr><tr><td><a href="/docs/languages/go">Go</a></td><td><a href="https://search.nixos.org/packages?channel=26.05&query=golang"><code>golang</code></a></td><td><code>1.26</code></td><td><span>✓</span></td><td /></tr><tr><td><code>1.25</code></td><td><span>✓</span></td><td><span>✓</span></td></tr><tr><td><code>1.24</code></td><td /><td><span>✓</span></td></tr><tr><td><a href="/docs/languages/java">Java</a></td><td><a href="https://search.nixos.org/packages?channel=26.05&query=java"><code>java</code></a></td><td><code>25</code></td><td><span>✓</span></td><td><span>✓</span></td></tr><tr><td><code>21</code></td><td><span>✓</span></td><td><span>✓</span></td></tr><tr><td><a href="https://bun.sh/">Javascript/Bun</a></td><td><a href="https://search.nixos.org/packages?channel=26.05&query=bun"><code>bun</code></a></td><td><code>1</code></td><td><span>✓</span></td><td><span>✓</span></td></tr><tr><td><a href="/docs/languages/nodejs">Javascript/Node.js</a></td><td><a href="https://search.nixos.org/packages?channel=26.05&query=nodejs"><code>nodejs</code></a></td><td><code>26</code></td><td><span>✓</span></td><td /></tr><tr><td><code>24</code></td><td><span>✓</span></td><td><span>✓</span></td></tr><tr><td><code>22</code></td><td><span>✓</span></td><td><span>✓</span></td></tr><tr><td><code>20</code></td><td /><td><span>✓</span></td></tr><tr><td><a href="https://www.perl.org/">Perl</a></td><td><a href="https://search.nixos.org/packages?channel=26.05&query=perl"><code>perl</code></a></td><td><code>5</code></td><td><span>✓</span></td><td><span>✓</span></td></tr><tr><td><a href="/docs/languages/php">PHP</a></td><td><a href="https://search.nixos.org/packages?channel=26.05&query=php"><code>php</code></a></td><td><code>8.5</code></td><td><span>✓</span></td><td><span>✓</span></td></tr><tr><td><code>8.4</code></td><td><span>✓</span></td><td><span>✓</span></td></tr><tr><td><code>8.3</code></td><td><span>✓</span></td><td><span>✓</span></td></tr><tr><td><code>8.2</code></td><td><span>✓</span></td><td><span>✓</span></td></tr><tr><td><a href="/docs/languages/python">Python</a></td><td><a href="https://search.nixos.org/packages?channel=26.05&query=python"><code>python</code></a></td><td><code>3.14</code></td><td><span>✓</span></td><td /></tr><tr><td><code>3.13</code></td><td><span>✓</span></td><td><span>✓</span></td></tr><tr><td><code>3.12</code></td><td><span>✓</span></td><td><span>✓</span></td></tr><tr><td><code>3.11</code></td><td /><td><span>✓</span></td></tr><tr><td><a href="/docs/languages/ruby">Ruby</a></td><td><a href="https://search.nixos.org/packages?channel=26.05&query=ruby"><code>ruby</code></a></td><td><code>4.0</code></td><td><span>✓</span></td><td><span>✓</span></td></tr><tr><td><code>3.4</code></td><td><span>✓</span></td><td><span>✓</span></td></tr><tr><td><code>3.3</code></td><td><span>✓</span></td><td><span>✓</span></td></tr></tbody></table></div><div><span>Channels:</span><span><span>26.05</span><span>Supported</span></span><span><span>25.11</span><span>Retired</span></span></div></div>
</div>

<NixRuntimesTable />

### PHP extensions and Python packages

To discover which PHP extensions and Python packages are available for these runtimes:

1. Go to the [NixOS search](https://search.nixos.org/).
2. Enter a runtime and click **Search**.
3. In the **Package sets** side bar, select the right set of extensions/packages for your runtime version.<br />
   You can choose the desired extensions/packages from the filtered results.

<img alt="Screenshot of the Nix package sets selection for PHP@8.3" />

<Note>
  <h4>Note: PHP extension names</h4>
  To help you find PHP extension names,
  some maintainers provide a `PHP upstream extension` value in the [NixOS search engine](https://search.nixos.org/packages?channel=unstable\&show=php82Extensions.gd).

  <img alt="Screenshot of an upstream extension value shown in the NixOS search" />

  If this information is not provided, copy the `<EXTENSION-NAME>` extension name from the appropriate `<PHP><VERSION>Extensions.<EXTENSION-NAME>` search result and add it to `stack.runtimes.extensions` as shown in the [`stack` configuration example](#example-stack-configuration) above.
</Note>

4. Add extensions to `stack.runtimes.extensions` and packages to `stack.packages` as described in the [`stack`](#stack) section above.

## Resources (CPU, memory, disk space)

By default, Upsun Cloud assigns a container profile and container size to each application and service on the first deployment of a project. <br />

The container *profile* defines and enforces a specific CPU-to-memory ratio. The default container profile for an app or service in a composable image is `HIGH_CPU`.

Use the Upsun Cloud CLI or Console to manually adjust the allocated container *size* (CPU and memory resources)—that is, to perform a **vertical‑scaling** action. When you redeploy, the container runs with the CPU‑to‑memory ratio defined by its profile, so it enforces the size you specified.

If you define **multiple runtimes** in an application's `.applications.<app_name>.stack.runtimes` key, you need to do one of the following:

* Change the [`.applications.<app_name>.container_profile`](/docs/configure-apps/image-properties/container_profile) to a profile that uses a larger container size.<br />

* Change the [resource initialization policy](/docs/manage-resources/resource-init) (the default CPU and RAM ratio) by running this command:

  ```bash theme={null}
  upsun push --resources-init=manual
  ```

Related topics:

* For detailed steps for changing the container size, see the [Vertical scaling](/docs/manage-resources/adjust-resources#vertical-scaling) section of the "Resource configuration topic.
* For details about container sizes for each resource allocation strategy (shared CPU, guaranteed CPU, and initial allocation), see the [Advanced: Container profiles](/docs/manage-resources/adjust-resources#advanced-container-profiles) section of the "Resource configuration" topic.
* To learn more about general resource management in Upsun Cloud, see the topics in the [Manage resources](/docs/manage-resources) section.

### Downsize a disk

You can reduce the target disk size of an app. Keep in mind:

* Backups created before the downsize are incompatible and cannot be used; you must [create new backups](/docs/environments/backup).
* The downsize will fail if the disk contains more data than the target size.

## Combine single-runtime and composable images

In a [multiple application context](/docs/configure-apps/multi-app),
you can use a mix of [single-runtime images](/docs/configure-apps/app-reference/single-runtime-image)
and composable images.

The following sample configuration includes two applications:

* `frontend` – uses a single-runtime image
* `backend` – uses a composable image<br />
  In this app, PHP is the primary runtime and is started automatically (PHP-FPM also starts automatically when PHP is the primary runtime). For details, see the [PHP as a primary runtime](#php-as-a-primary-runtime) section in this topic.


# Choose an image type
Source: https://developer.upsun.com/docs/configure-apps/app-reference/index

Configure your app and control how it's built and deployed on Upsun Cloud.

An *image* represents the configuration of the container that contains the application (or service) that you want to deploy.

Choosing the image type for the container that best suits your application is the first and most important decision in configuring how your application is deployed.

Upsun Cloud offers two image types for applications — [single-runtime](/docs/configure-apps/app-reference/single-runtime-image) and [composable](/docs/configure-apps/app-reference/composable-image) — plus support for running [self-hosted services from public Docker images](/docs/add-services/docker-images).

You define all of these options as `applications` in your `.upsun/config.yaml` file.

## Which image type should you choose?

| **Criteria / Use‑case** | **Single‑runtime image** | **Composable image** | **Docker image** |
| - | - | - | - |
| **When it’s best used (typical use case)** | Good for simple applications that need only one runtime. | Best for applications needing custom secondary runtimes, static assets, or custom binaries/tools. | Best when you already build and ship container images outside Upsun Cloud and want to deploy them as is. |
| **# of runtimes per container** | One — a single runtime per container. | Zero or more — you can define multiple runtimes (or none) per container. | Defined entirely by the image itself. |
| **Packages permitted / how dependencies are managed** | Only the base runtime and its extensions are permitted directly. To add non-runtime packages, you must use build-phase installation via hooks or dependencies. See [Keys used](#keys-used-in-each-image-type) below. | Supports multiple runtimes, extensions, packages and services. You define everything in the `stack` key (runtimes + Nix packages). See [Keys used](#keys-used-in-each-image-type) below. | All dependencies are bundled inside the image. Upsun Cloud does not add or modify packages. |
| **Manual configuration / setup burden** | Lower: using a supported runtime means less manual setup; adding downloads, dependencies, and packages might require use of build hooks, which might complicate configuration. | Higher: you manually define the composition of the container or  `stack` (runtimes + packages) of Nix packages. More flexible but requires more setup. | Low on the Upsun Cloud side — see [Configure an app](/docs/add-services/docker-images#configure-an-app) in the "Self-hosted services from public Docker images" topic. Image preparation and maintenance happen in your own build pipeline. |
| **Maintenance & updates (patches, upgrades)** | Upsun Cloud handles image updates (minor and patch updates; security patches) automatically on deployment | You need to redeploy often to apply Nix package updates; update cadence depends on package maintainers.<br />Your team must be comfortable with upgrading, testing, and refactoring images promptly when Nix a channel becomes deprecated (every six months). | **You are responsible for security patches.** Upsun Cloud does not patch public Docker image runtimes. You must rebuild and redeploy the image to apply updates. |
| **Flexibility (versions, custom binaries, tools)** | Limited to supported runtimes + permitted extensions. If you require combinations not supported by Upsun Cloud, you may hit limits (e.g. certain PHP + Node.js/Python combos). | High — you can mix runtimes, pick specific package versions, and include custom binaries/tools via Nix. | Highest — full control over the image contents, runtime, and tooling. You can use any Docker image from a public registry. |
| **When to reconsider / migrate** | If you need many packages (beyond runtime extensions), complex dependencies, multiple runtimes, or custom tools, consider migrating to composable. | If you don’t need the complexity (just a simple runtime and minimal packages), composable may be unnecessary overhead. | If patch responsibility or storage cost is a concern. Images must be under 4 GB; larger images require a [support ticket](/docs/get-started/here/support#create-a-support-ticket). Build hooks are not supported. |

## Keys used in each image type

The single-runtime and composable image types share many configuration keys. Differences in syntax or meaning are noted as needed in [Image properties](/docs/configure-apps/image-properties).

* Single-runtime image: Use the
  [`build`](/docs/configure-apps/app-reference/single-runtime-image#build), [`dependencies`](/docs/configure-apps/app-reference/single-runtime-image#dependencies), and [`runtime`](/docs/configure-apps/app-reference/single-runtime-image#runtime) keys
* Composable image: Use the [`stack.runtimes` and `stack.packages`](/docs/configure-apps/app-reference/composable-image#stack) keys
* Docker image (for deploying self-hosted services): Use the [`type`](/docs/add-services/docker-images/index#configure-an-app) key and the `image.name` key
  (see [Configure an app](/docs/add-services/docker-images/index#configure-an-app)). The `build`, `dependencies`, `runtime`, and `stack` keys do not apply. Build hooks are not supported.

## Multi-app projects

In a multiple application context, you can use a mix of single-runtime images, composable images, and Docker images. See the examples in the [single-runtime image](/docs/configure-apps/app-reference/single-runtime-image#combine-single-runtime-and-composable-images) topic and [composable image](/docs/configure-apps/app-reference/composable-image#combine-single-runtime-and-composable-images) topic. For a sample Docker image app, see the [Docker image](/docs/add-services/docker-images) topic.


# Single-runtime image
Source: https://developer.upsun.com/docs/configure-apps/app-reference/single-runtime-image

See all of the options for controlling your apps and how they're built and deployed on Upsun Cloud.

Use the `.upsun/config.yaml` file,
located at the root of your Git repository, to configure the apps in a single-runtime image.

See a [comprehensive example](/docs/configure-apps#comprehensive-example) of a configuration in
a `.upsun/config.yaml` file.

[Multi-app projects](/docs/configure-apps/multi-app) can be set up in various ways.

## Primary application properties

In the `.upsun/config.yaml` file, configure each application as a unique key beneath the top-level `applications` key.

For example, if your deployed site requires a Javascript `frontend` application container and a Python `backend` application container, the `.upsun/config.yaml` file would start to look something like this:

The following table presents all of the properties available to each unique app beneath the `applications` key.

The **Set in instance** column defines whether the given property can be overridden within a `web` or `workers` instance.
To override any part of a property, you have to provide the entire property.

<Info>
  The `build`, `dependencies`, and `runtime` properties are unique to this image type and are described later in this topic. All other properties are available in both single-runtime and composable images — click a property name to view its details in a separate topic.
</Info>

| Name | Type | Required | Set in instance? | Description |
| - | - | - | - | - |
| [`type`](#type) | A type | Yes | No | The base image to use with a specific app language. Format: `runtime:version`. |
| [`container_profile`](/docs/configure-apps/image-properties/container_profile) | A container profile | | Yes | Determines which combinations of CPU and RAM a container can use. |
| [`relationships`](/docs/configure-apps/image-properties/relationships) | A dictionary of relationships | | Yes | Connections to other services and apps. |
| [`mounts`](/docs/configure-apps/image-properties/mounts) | A dictionary of mounts | | Yes | Directories that are writable even after the app is built. Allocated disk for mounts is defined with a separate resource configuration call using `upsun resources:set`. |
| [`web`](/docs/configure-apps/image-properties/web) | A web instance | | N/A | How the web application is served. |
| [`workers`](/docs/configure-apps/image-properties/workers) | A worker instance | | N/A | Alternate copies of the application to run as background processes. |
| [`timezone`](/docs/configure-apps/timezone) | `string` | | No | The timezone for crons to run. Format: a [TZ database name](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). Defaults to `UTC`, which is the timezone used for all logs no matter the value here. See also [app runtime timezones](/docs/projects/change-project-timezone) |
| [`access`](/docs/configure-apps/image-properties/access) | An access dictionary | | Yes | Access control for roles accessing app environments. |
| [`variables`](/docs/configure-apps/image-properties/variables) | A variables dictionary | | Yes | Variables to control the environment. |
| [`build`](#build) | A build dictionary | | No | What happens when the app is built. |
| [`dependencies`](#dependencies) | A dependencies dictionary | | No | What global dependencies to install before the `build` hook runs. |
| [`hooks`](/docs/configure-apps/image-properties/hooks) | A hooks dictionary | | No | What commands run at different stages in the `build`, `deploy`, and `post_deploy` phases. |
| [`crons`](/docs/configure-apps/image-properties/crons) | A cron dictionary | | No | Scheduled tasks for the app. |
| [`source`](/docs/configure-apps/image-properties/source) | A source dictionary | | No | Details about the app’s source code and available operations. |
| [`runtime`](#runtime) | A runtime dictionary | | No | Customizations to your PHP runtime. |
| [`additional_hosts`](/docs/configure-apps/image-properties/additional_hosts) | An additional hosts dictionary | | Yes | Mappings of hostnames to IP addresses. |
| [`authorizations`](/docs/configure-apps/image-properties/authorizations) | | An authorizations dictionary | Yes | An authorizations list that grants applications and tasks narrowly-scoped access to the environment API and task operations. |
| [`operations`](/docs/configure-apps/runtime-operations) | A dictionary of runtime operations | | No | Runtime operations for the application. |

## Root directory

Some of the properties you can define are relative to your app's root directory.
The root defaults to the root of the repository.

That is, if a custom value for `source.root` is not provided in your configuration, the default behavior is equivalent
to the above.

To specify another directory, for example for a [multi-app project](/docs/configure-apps/multi-app),
use the [`source.root` property](/docs/configure-apps/image-properties/source).

## `type`

<Info>
  To install *multiple* runtimes and tools in your application container, use the Upsun Cloud composable image.<br />
  If you arrived here from another page, you may want to review the supported `stack` key where `type` was referenced.<br />
  For details, see the list of [supported Nix runtimes](/docs/configure-apps/app-reference/composable-image#upsun-supported-nix-runtimes) that you can define in a composable image `stack`.
</Info>

The `type` defines the base container image used to run the application.
The version is the major (`X`) and sometimes minor (`X.Y`) version numbers,
depending on the service, as in the following table.
Security and other patches are taken care of for you automatically.

Available languages and their supported versions:

| Language | Type key | Supported versions |
| - | - | - |
| [C#/.Net Core](/docs/languages/dotnet) | `dotnet` | <span>10.0</span> <span>8.0</span> |
| [Elixir](/docs/languages/elixir) | `elixir` | <span>1.20</span> <span>1.19</span> <span>1.18</span> |
| [Go](/docs/languages/go) | `golang` | <span>1.27</span> <span>1.26</span> |
| [Java](/docs/languages/java) | `java` | <span>25</span> <span>21</span> |
| [JavaScript/Node.js](/docs/languages/nodejs) | `nodejs` | <span>26</span> <span>24</span> <span>22</span> |
| [PHP](/docs/languages/php) | `php` | <span>8.5</span> <span>8.4</span> <span>8.3</span> <span>8.2</span> |
| [Python](/docs/languages/python) | `python` | <span>3.14</span> <span>3.13</span> <span>3.12</span> <span>3.11</span> |
| [Ruby](/docs/languages/ruby) | `ruby` | <span>4.0</span> <span>3.4</span> <span>3.3</span> |
| [Rust](/docs/languages/rust) | `rust` | <span>1</span> |

### Example configuration

These are used in the format `runtime:version`:

## `build`

The only property of the `build` dictionary is `flavor`, which specifies a default set of build tasks to run.
Flavors are language-specific.

See what the build flavor is for your language:

* [Node.js](/docs/languages/nodejs#dependencies)
* [PHP](/docs/languages/php#dependencies)

In all languages, you can also specify a flavor of `none` to take no action at all
(which is the default for any language other than PHP and Node.js).

## `dependencies`

Installs global dependencies as part of the build process.
They're independent of the code dependencies of your application
and are available in the `PATH` during the build process and in the runtime environment.
They're installed before the `build` hook runs using a package manager for the language.

| Language | Key name | Package manager |
| - | - | - |
| PHP | `php` | [Composer](https://getcomposer.org/) |
| Python 2 | `python` or `python2` | [Pip 2](https://packaging.python.org/tutorials/installing-packages/) |
| Python 3 | `python3` | [Pip 3](https://packaging.python.org/tutorials/installing-packages/) |
| Ruby | `ruby` | [Bundler](https://bundler.io/) |
| Node.js | `nodejs` | [npm](https://www.npmjs.com/) (see [how to use yarn](/docs/languages/nodejs#use-yarn-as-a-package-manager)) |

The format for package names and version constraints are defined by the specific package manager.

An example of dependencies in multiple languages:

## `runtime`

This applies to PHP only.

The following table lists the various possible modifications to your PHP runtime:

| Name | Type | Language | Description |
| - | - | - | - |
| `extensions` | List of `string`s OR [extensions definitions](#extensions) | PHP | [PHP extensions](/docs/languages/php/extensions) to enable. |
| `disabled_extensions` | List of `string`s | PHP | [PHP extensions](/docs/languages/php/extensions) to disable. |
| `request_terminate_timeout` | `integer` | PHP | The timeout (in seconds) for serving a single request after which the PHP-FPM worker process is killed. |
| `sizing_hints` | A [sizing hints definition](#sizing-hints) | PHP | The assumptions for setting the number of workers in your PHP-FPM runtime. |
| `xdebug` | An Xdebug definition | PHP | The setting to turn on [Xdebug](/docs/languages/php/xdebug). |

You can also set your [app's runtime timezone](/docs/configure-apps/timezone).

### Extensions

<Info>
  To install multiple runtimes and tools in your application container, use the Upsun Cloud composable image.<br />
  If you arrived here from another page and you are using the composable image, you enable and disable extensions by using the `stack.runtimes.extensions`/`stack.runtimes.disabled_extensions` keys.<br />
  For details and an example, see the [`stack`](/docs/configure-apps/app-reference/composable-image#stack) section in the "Composable image" topic.
</Info>

You can enable [PHP extensions](/docs/languages/php/extensions) just with a list of extensions:

Alternatively, if you need to include configuration options, use a dictionary for that extension:

In this case, the `name` property is required.

### Sizing hints

The following table shows the properties that can be set in `sizing_hints`:

| Name | Type | Default | Minimum | Description |
| - | - | - | - | - |
| `request_memory` | `integer` | 45 | 10 | The average memory consumed per request in MB. |
| `reserved_memory` | `integer` | 70 | 70 | The amount of memory reserved in MB. |

See more about [PHP-FPM workers and sizing](/docs/languages/php/fpm).

## Resources (CPU, memory, and disk space)

By default, Upsun Cloud assigns a container profile and container size to each application and service on the first deployment of a project. <br />

The container *profile* defines and enforces a specific CPU-to-memory ratio. The default container profile for an app or service in a composable image is `HIGH_CPU`.

Use the Upsun Cloud CLI or Console to manually adjust the allocated container *size* (CPU and memory resources)—that is, to perform a **vertical‑scaling** action. When you redeploy, the container runs with the CPU‑to‑memory ratio defined by its profile, so it enforces the size you specified.

Related topics:

* For detailed steps for changing the container size, see the [Vertical scaling](/docs/manage-resources/adjust-resources#vertical-scaling) section of the "Resource configuration topic.
* For details about container sizes for each resource allocation strategy (shared CPU, guaranteed CPU, and initial allocation), see the [Advanced: Container profiles](/docs/manage-resources/adjust-resources#advanced-container-profiles) section of the "Resource configuration" topic.
* To learn more about general resource management in Upsun Cloud, see the topics in the [Manage resources](/docs/manage-resources) section.

### Downsize a disk

You can reduce the target disk size of an app. Keep in mind:

* Backups created before the downsize are incompatible and cannot be used; you must [create new backups](/docs/environments/backup).
* The downsize will fail if the disk contains more data than the target size.

### Combine single-runtime and composable images

In a [multiple application context](/docs/configure-apps/multi-app),
you can use a mix of single-runtime images
and [composable images](/docs/configure-apps/app-reference/composable-image).

The following sample configuration includes two applications:

* `frontend` – uses a single-runtime image
* `backend` – uses a composable image<br />
  In this app, PHP is the primary runtime and is started automatically (PHP-FPM also starts automatically when PHP is the primary runtime). For details, see the [PHP as a primary runtime](/docs/configure-apps/app-reference/composable-image#php-as-a-primary-runtime) section in the Composable image topic.


# Use hooks with dependencies
Source: https://developer.upsun.com/docs/configure-apps/hooks/hooks-and-dependencies

Manage dependencies for your hooks, such as compiling Sass files as part of your build.

If you use a specific package in a hook, you may want to manage dependencies for it.
For example, you may want to compile Sass files as part of your build process.
You can set dependencies along with hooks in your [app configuration](/docs/configure-apps/app-reference/single-runtime-image#dependencies).

The following example assumes you have some Sass source files, such as a `index.scss` file.
You also need a script to compile the files, such as the following:

```json package.json theme={null}
{
  "scripts": {
    "build-css": "sass index.scss css/index.css"
  },
}
```

Set your app configuration to have Sass available globally and use it:

```yaml .upsun/config.yaml theme={null}
applications:
  myapp:
    # Ensure sass is available globally
    dependencies:
      nodejs:
        sass: "^1.47.0"

    hooks:
      # Run the script defined in package.json
      build: |
        npm run build-css
```


# Comparison of hooks
Source: https://developer.upsun.com/docs/configure-apps/hooks/hooks-comparison

What hooks are available in the build and deploy process and how to choose which to use.

The following table presents the main differences among the three available hooks:

| Hook name | Failures stop build | Variables available | Services available | Timeout | Run on `worker` instances | Writable directories | Blocks requests | Runs on all redeploys\* |
| - | - | - | - | - | - | - | - | - |
| `build` | Yes | Build variables | No | 1 hour | Yes | `$PLATFORM_APP_DIR`, `$PLATFORM_CACHE_DIR`, and `/tmp` | No | No |
| `deploy` | No | Runtime variables | Yes | None | No | [Mounts](/docs/configure-apps/image-properties/mounts) | Yes | No |
| `post_deploy` | No | Runtime variables | Yes | None | No | [Mounts](/docs/configure-apps/image-properties/mounts) | No | Yes |

\* All of the hooks run with changes to the code or environment.
This column indicates which hooks run on a redeploy without any code changes.

## Build hook

The `build` hook is run after any [build flavor](/docs/configure-apps/app-reference/single-runtime-image#build).
During this hook, no services (such as a database) or any persistent file mounts are available
as the application hasn't yet been deployed.

The `build` hook can access only the variables that are available at build time:

* Variables provided by Upsun Cloud, as listed in [this table](/docs/development/variables/use-variables#use-provided-variables) (see the **Build** column)
* User-defined project-level or environment-specific build-time variables (**Available during buildtime** is set in the Console or the `--visible-build=true` option was set by using the CLI)

During the `build` hook, there are three writeable directories:

* `$PLATFORM_APP_DIR`:
  This is where your code is checked out and is the working directory when the `build` hook starts.
  The contents of this directory after the build hook is the application that gets deployed.
* `$PLATFORM_CACHE_DIR`:
  This directory persists between builds, but isn't deployed as part of your application.
  It's a good place for temporary build artifacts that can be reused between builds.
  It's shared by all builds on all branches.
* `/tmp`:
  The temp directory is also useful for writing files that aren't needed in the final application,
  but it's wiped between each build.
  Note that `$PLATFORM_CACHE_DIR` is mapped to `/tmp`
  and together they offer about 8 GB of free space.

The only constraint on what can be downloaded during a `build` hook is the disk space available for builds.

This is *not* the disk specified by your [resources configuration](/docs/manage-resources).

If you exceed this limit, you receive a `No space left on device` error.
See how to [troubleshoot this error](/docs/troubleshooting/disks#no-space-left-on-device).

The `build` hook runs only when the app or its runtime (variables and such) have changed.
Redeploys with no changes trigger only the `post_deploy` hook.
If you need the `build` hook to run, [manually trigger a build](/docs/troubleshooting/general#manually-trigger-builds).

Each hook is executed as a single script, so they're considered to have failed only if the final command in them fails.
To cause them to fail on the first failed command, add `set -e` to the beginning of the hook.
If a `build` hook fails for any reason, the build is aborted and the deploy doesn't happen.
Note that this only works for `build` hooks.
If other hooks fail, the deploy still happens.

### Timeout

Build hooks automatically time out if they run for 1 hour.
So if you accidentally add an unbroken loop, it gets cut off and you can continue with other activities.

## Deploy hook

The `deploy` hook is run after the app container has been started but before it has started accepting requests.
Note that the deploy hook only runs on [`web` instances](/docs/configure-apps/image-properties/mounts),
not [`worker` instances](/docs/configure-apps/image-properties/mounts).

You can access other services at this stage (such as MySQL, Solr, Redis).
The disk where the application lives is read-only at this point.

This hook should be used when something needs to run once when new code is deployed.
It isn't run when a host is restarted (such as during region maintenance),
so anything that needs to run each time an instance of an app starts (regardless of whether there's new code)
should go in the `pre_start` key in [your `web` configuration](/docs/configure-apps/image-properties/web#web-commands).
For example, clearing the cache.

Be aware: The deploy hook blocks the site accepting new requests.
If your `deploy` hook is only a few seconds,
incoming requests in that time are paused and continue when the hook is finished.
So it effectively appears as if the site just took a few extra seconds to respond.
If the hook takes too long, requests can't be held and appear as dropped connections.
Only run tasks in your deploy hook that have to be run exclusively,
such as database schema updates or some types of cache clear (those where the code must match what's on the disk).
A task that can safely run concurrently with new incoming requests should be run as a `post_deploy` hook instead.

After a Git push, in addition to the log shown in the activity log,
the execution of the `deploy` hook is logged in the [deploy log](/docs/observability/logs/access-logs#container-logs).
For example:

```bash theme={null}
[2026-03-01 08:27:25.495579] Launching command 'bash export-config.sh'.

🔥 Successfully cleared configuration
🚀 Added new configuration details
```

Your `deploy` hook is tied to commits in the same way as your builds.
Once a commit has been pushed and a new build image has been created,
the result of both the `build` and `deploy` hooks are reused until there is a new git commit.
Redeploys with no changes trigger only the `post_deploy` hook.
If you need the `deploy` hook to run, [manually trigger a build](/docs/troubleshooting/general#manually-trigger-builds).

## Post-deploy hook

The `post_deploy` hook functions exactly the same as the `deploy` hook,
but after the container is accepting connections.
It runs concurrently with normal incoming traffic.
That makes it well suited to any updates that don't require exclusive database access.

What's "safe" to run in a `post_deploy` hook vs. in a `deploy` hook varies by the application.
Often times content imports, some types of cache warmups, and other such tasks are good candidates for a `post_deploy` hook.

In addition to the activity log, the `post_deploy` hook logs to the [post-deploy log](/docs/observability/logs/access-logs#container-logs).

The `post_deploy` hook is the only hook that runs during a redeploy. **Make sure the scripts in your `post_deploy` hook are written to be idempotent** (safe to run multiple times) or have checks against duplication.


# Use build and deploy hooks
Source: https://developer.upsun.com/docs/configure-apps/hooks/index

Add custom scripts at different stages in the build and deploy process.

As your app goes through the [build and deploy process](/docs/core-concepts/build-deploy),
you might want to run custom commands.
These might include compiling the app, setting the configuration for services based on variables, and rebuilding search indexes.
Do these tasks using one of [three hooks](/docs/configure-apps/hooks/hooks-comparison).

The following example goes through each of these hooks for a multi-app project

* Next.js acts as the frontend container, `client`
* Drupal serves data as the backend container, `api`

Configuration for [both applications](/docs/configure-apps/multi-app) resides in a single [`.upsun/config.yaml` configuration file](/docs/configure-apps).
Be sure to notice the `source.root` property for each.

## Build dependencies

The Next.js app uses Yarn for dependencies, which need to be installed.
Installing dependencies requires writing to disk and doesn't need any relationships with other services.
This makes it perfect for a `build` hook.

In this case, the app has two sets of dependencies:

* For the main app
* For a script to test connections between the apps

Create your `build` hook to install them all:

1. Create a `build` hook in your [app configuration](/docs/configure-apps/app-reference/single-runtime-image):

The hook has two parts so far:

* The `|` means the lines that follow can contain a series of commands.
  They aren't interpreted as new YAML properties.
* Adding `set -e` means that the hook fails if *any* of the commands in it fails.
  Without this setting, the hook fails only if its *final* command fails.

  If a `build` hook fails for any reason, the build is aborted and the deploy doesn't happen.
  Note that this only works for `build` hooks.
  If other hooks fail, the deploy still happens.

2. Install your top-level dependencies inside this `build` hook:

This installs all the dependencies for the main app.

## Configure Drush and Drupal

The example uses [Drush](https://www.drush.org/latest/) to handle routine tasks.
For its configuration, Drush needs the URL of the site.
That means the configuration can't be done in the `build` hook.
During the `build` hook, the site isn't yet deployed and so there is no URL to use in the configuration.
(The [`PLATFORM_ROUTES` variable](/docs/development/variables/use-variables#use-provided-variables) isn't available.)

Add the configuration during the `deploy` hook.
This way you can access the URL before the site accepts requests (unlike in the `post_deploy` hook).

The script also prepares your environment to handle requests,
such as by [rebuilding the cache](https://www.drush.org/latest/commands/cache_rebuild/)
and [updating the database](https://www.drush.org/latest/commands/updatedb/).
Because these steps should be done before the site accepts request, they should be in the `deploy` hook.

All of this configuration and preparation can be handled in a bash script.

1. Copy the [preparation script from the Upsun Fixed template](https://github.com/platformsh-templates/nextjs-drupal/blob/master/api/platformsh-scripts/hooks.deploy.sh)
   into a file called `hooks.deploy.sh` in a `api/platformsh-scripts` directory.
   Note that hooks are executed using the dash shell, not the bash shell used by SSH logins.
2. Copy the [Drush configuration script from the template](https://github.com/platformsh-templates/nextjs-drupal/blob/master/api/drush/platformsh_generate_drush_yml.php)
   into a `drush/platformsh_generate_drush_yml.php` file.
3. Set a [mount](/docs/configure-apps/image-properties/mounts).
   Unlike in the `build` hook, in the `deploy` hook the system is generally read-only.
   So create a mount where you can write the Drush configuration:

4) Add a `deploy` hook that runs the preparation script:

This `!include` syntax tells the hook to process the script as if it were included in the YAML file directly.
This helps with longer and more complicated scripts.

## Get data from Drupal to Next.js

This Next.js app generates a static site.
Often, you would generate the site for Next.js in a `build` hook.
In this case, you first need to get data from Drupal to Next.js.

This means you need to wait until Drupal is accepting requests
and there is a relationship between the two apps.
So the `post_deploy` hook is the perfect place to build your Next.js site.

You can also redeploy the site every time content changes in Drupal.
On redeploys, only the `post_deploy` hook runs,
meaning the Drupal build is reused and Next.js is built again.
So you don't have to rebuild Drupal but you still get fresh content.

1. Set a relationship for Next.js with Drupal.
   This allows the Next.js app to make requests and receive data from the Drupal app.

2) Set [mounts](/docs/configure-apps/image-properties/workers).
   Like the [`deploy` hook](#configure-drush-and-drupal), the `post_deploy` hook has a read-only file system.
   Create mounts for your Next.js files:

3. Add a `post_deploy` hook that first tests the connection between the apps:

Note that you could add `set -e` here, but even if the job fails, the build/deployment itself can still be counted as successful.

4. Then build the Next.js site:

The `$PLATFORM_APP_DIR` variable represents the app root and can always get you back there.

## Final hooks


# Change hooks in different environments
Source: https://developer.upsun.com/docs/configure-apps/hooks/vary-hooks-by-environment

Change what runs in your hooks depending on the current environment type.

You might have certain commands you want to run only in certain environments.
For example enabling detailed logging in preview environments
or purging your CDN cache for production environments.

The `deploy` and `post_deploy` hooks can access all [runtime environment variables](/docs/development/variables/use-variables#use-provided-variables).
Use this to vary those hooks based on the environment.

Check the `PLATFORM_ENVIRONMENT_TYPE` variable to see if it's in a production environment:

```yaml .upsun/config.yaml theme={null}
applications:
  myapp:
    hooks:
      deploy: |
        if [ "$PLATFORM_ENVIRONMENT_TYPE" = production ]; then
          # Run commands only when deploying to production
        else
          # Run commands only when deploying to development or staging environments
        fi
        # Commands to run regardless of the environment
```


# Access
Source: https://developer.upsun.com/docs/configure-apps/image-properties/access

An access dictionary that defines the access control for roles accessing app environments.

Optional in [single-runtime](/docs/configure-apps/app-reference/single-runtime-image#primary-application-properties) and [composable](/docs/configure-apps/app-reference/composable-image#primary-application-properties) images.

The `access` dictionary has one allowed key:

| Name | Allowed values | Default | Description |
| - | - | - | - |
| `ssh` | `admin`, `contributor`, or `viewer` | `contributor` | Defines the minimum role required to access app environments via SSH. |

In the following example, only users with `admin` permissions for the
given [environment type](/docs/administration/users#environment-type-roles)
can access the deployed environment via SSH:


# Additional hosts
Source: https://developer.upsun.com/docs/configure-apps/image-properties/additional_hosts

An additional hosts dictionary that maps hostnames to IP addresses.

Optional in [single-runtime](/docs/configure-apps/app-reference/single-runtime-image#primary-application-properties) and [composable](/docs/configure-apps/app-reference/composable-image#primary-application-properties) images.

If you’re using a private network with specific IP addresses you need to connect to, you might want to map those addresses to hostnames to better remember and organize them. In such cases, you can add a map of those IP addresses to whatever hostnames you like. Then when your app tries to access the hostname, it’s sent to the proper IP address.

So in the following example, if your app tries to access api.example.com, it’s sent to 192.0.2.23.

This is equivalent to adding the mapping to the `/etc/hosts` file for the container.


# Workload authorizations
Source: https://developer.upsun.com/docs/configure-apps/image-properties/authorizations

An authorizations list that grants applications and tasks narrowly-scoped access to the environment API and task operations.

Upsun Cloud runs several types of workloads — applications, workers, crons, and tasks. The `authorizations` key enables a workload to call the
Upsun Cloud API at runtime using short-lived, narrowly-scoped tokens, with no long-lived credentials required.
This key can be declared on both applications and tasks, but serves a different purpose depending on where it's declared:

* On an **application**: grants permission to trigger tasks and call the environment API.
* On a [**task**](/docs/configure-apps/tasks): grants the task permission to call the environment API from inside its container. A task can also trigger another task.
* On a [**worker**](/docs/configure-apps/image-properties/workers): inherits the application's `authorizations` by default, or overrides them — the same as other application properties
  that can be set in a web or worker instance (such as `relationships`, `mounts`; for a complete list, refer to the **Set in instance** column of the
  **Primary applicaton properties** table in the [single-runtime](/docs/configure-apps/app-reference/single-runtime-image#primary-application-properties)
  and [composable image](/docs/configure-apps/app-reference/composable-image#primary-application-properties) topics).
* On a **cron**: crons run inside the application container and inherit its `authorizations` automatically. You cannot grant different authorizations to individual crons.

The `authorizations` key grants an application or task permission to make specific calls to the Upsun Cloud API from inside its container.
Each authorization defines a `type` and an `action`, and optionally a `resource` to scope the permission.

No user API token or long-lived credential is required.
The platform injects a short-lived bearer token at runtime, scoped to the permissions declared here.

## How it works

Instead of storing a long-lived API token in your environment, every application and task container has a local auth proxy running at `http://localhost:8200`.
The proxy issues short-lived tokens scoped to the permissions you declared — so there are no credentials to rotate, and a token issued in one environment cannot act on another.

When your code needs to call the Upsun Cloud API:

1. Your app sends a token request to `http://localhost:8200/oauth2/token`.
2. The proxy returns a bearer token scoped to those declared permissions.
3. Your app uses that token to call the Upsun Cloud API.

## Parameters

| Parameter | Values | Description |
| :- | :- | :- |
| `type` | `task`, `env` | The type of resource to access: `task` — a task defined in your project. `env` — the environment API. |
| `resource` | Task name | The name of the task. Required when `type` is `task`. |
| `action` | `operate`, `view` | `operate` allows triggering and managing a task. `view` grants read-only access to the environment API. |

### Valid combinations

| `type` | `action` | `resource` | What it grants |
| :- | :- | :- | :- |
| `task` | `operate` | Task name | Trigger and manage the named task |
| `env` | `view` | — | Read-only access to the environment API |

## Examples

Allow an application to trigger a task and read the environment API:

Allow a task to read the environment API:


# Container profile
Source: https://developer.upsun.com/docs/configure-apps/image-properties/container_profile

Defines the container profile of the application.

Optional in [single-runtime](/docs/configure-apps/app-reference/single-runtime-image#primary-application-properties) and [composable](/docs/configure-apps/app-reference/composable-image#primary-application-properties) images.

A *container profile* is a CPU-to-memory ratio that defines how much CPU and RAM a container can use. Four container profiles are available: `HIGH_CPU`, `BALANCED`, `HIGH_MEMORY`, and `HIGHER_MEMORY`.

By default, Upsun Cloud assigns a container *profile* and container *size* to each application and service upon the first deployment of a project. You can configure this *resource initialization strategy*- for details, see the [Resource initialization](/docs/manage-resources/resource-init) topic.

When you change the container *size* assigned to an app or service (by using the CLI or Console; see [below](#changing-the-container-size)), the profile enforces the CPU-to-RAM ratio, ensuring your container is sized correctly.

To choose a different CPU-to-memory *ratio*, change the `container_profile` key. See [Adjust a container profile](/docs/manage-resources/adjust-resources#adjust-a-container-profile) in the "Resource configuration" topic.

### Single-runtime images

In a single-runtime image, you typically don't need to change the `container_profile` key of any of the apps and services. For the default profile values assigned for each runtime and service, refer to the [Default container profiles](/docs/manage-resources/adjust-resources#default-container-profiles) table in the "Resource configuration" topic.

### Composable images

The default container profile for an app or service in a composable image is `HIGH_CPU`.<br />
<br />If your `.applications.<app_name>.stack.runtimes` key defines multiple runtimes, you need to do one of the following:

* Change
  the `.applications.<app_name>.container_profile `[default container\_profile](/docs/manage-resources/adjust-resources#advanced-container-profiles)
* Change [default CPU and RAM ratio](/docs/manage-resources/resource-init) on first deployment using the following
  commands:

  ```bash theme={null}
  upsun push --resources-init=manual
  ```

### Changing the container size

You can change the container *size* assigned to an app or service by using the Upsun Cloud CLI or Console:

* For detailed steps, see the [Resource configuration](/docs/manage-resources/adjust-resources) topic.
* For details about container sizes for each resource allocation strategy (shared CPU, guaranteed CPU, and initial allocation), see the [Advanced: Container profiles](/docs/manage-resources/adjust-resources#advanced-container-profiles) section of the "Resource configuration" topic.


# Crons
Source: https://developer.upsun.com/docs/configure-apps/image-properties/crons

A cron dictionary that defines scheduled tasks for the app.

Optional in [single-runtime](/docs/configure-apps/app-reference/single-runtime-image#primary-application-properties) and [composable](/docs/configure-apps/app-reference/composable-image#primary-application-properties) images.

The keys of the `crons` definition are the names of the cron jobs.
The names must be unique.

If an application defines both a `web` instance and `worker` instances, cron jobs run only on the `web` instance.

See how to [get cron logs](/docs/observability/logs/access-logs#container-logs).

The following table shows the properties for each job:

| Name | Type | Required | Description |
| - | - | - | - |
| `spec` | `string` | Yes | The [cron specification](https://en.wikipedia.org/wiki/Cron#Cron_expression). To prevent competition for resources that might hurt performance, use `H` in definitions to indicate an unspecified but invariant time. For example, instead of using `0 * * * *` to indicate the cron job runs at the start of every hour, you can use `H * * * *` to indicate it runs every hour, but not necessarily at the start. This prevents multiple cron jobs from trying to start at the same time. |
| `commands` | A [cron commands dictionary](#cron-commands) | Yes | A definition of what commands to run when starting and stopping the cron job. |
| `shutdown_timeout` | `integer` | No | When a cron is canceled, this represents the number of seconds after which a `SIGKILL` signal is sent to the process to force terminate it. The default is `10` seconds. |
| `timeout` | `integer` | No | The maximum amount of time a cron can run before it's terminated. Defaults to the maximum allowed value of `86400` seconds (24 hours). |

Note that you can [cancel pending or running crons](/docs/environments/cancel-activity).

### Cron commands

| Name | Type | Required | Description |
| - | - | - | - |
| `start` | `string` | Yes | The command that's run. It's run in [Dash](https://en.wikipedia.org/wiki/Almquist_shell). |
| `stop` | `string` | No | The command that's issued to give the cron command a chance to shutdown gracefully, such as to finish an active item in a list of tasks. Issued when a cron task is interrupted by a user through the CLI or Console. If not specified, a `SIGTERM` signal is sent to the process. |

In this example configuration, the crons `spec` key uses the `H` syntax.

### Single-runtime image: Example cron jobs

### Composable image: Example cron jobs

### Conditional crons

If you want to set up customized cron schedules depending on the environment type,
define conditional crons.
To do so, use a configuration similar to the following:

### Cron job timing

The minimum time between cron jobs being triggered is 5 minutes.

For each app container, only one cron job can run at a time.
If a new job is triggered while another is running, the new job is paused until the other completes.

To minimize conflicts, a random offset is applied to all triggers.
The offset is a random number of seconds up to 20 minutes or the cron frequency, whichever is smaller.

Crons are also paused while activities such as [backups](/docs/environments/backup) are running.
The crons are queued to run after the other activity finishes.

To run cron jobs in a timezone other than UTC, set the `timezone` property property as described for the image type ([single-runtime image](/docs/configure-apps/app-reference/single-runtime-image#primary-application-properties) or
[composable image](/docs/configure-apps/app-reference/composable-image#primary-application-properties)).

To run cron jobs in a timezone other than UTC, set the [timezone property](/docs/configure-apps/timezone).

### Paused crons

[Preview environments](/docs/glossary#preview-environment) are often used for a limited time and then abandoned.
While it's useful for environments under active development to have scheduled tasks,
unused environments don't need to run cron jobs.
To minimize unnecessary resource use,
crons on environments with no deployments are paused.

This affects all preview environments *and* production environments that do not yet have a domain attached to them.

Such environments with deployments within 14 days have crons with the status `running`.
If there haven't been any deployments within 14 days, the status is `paused`.

You can see the status in the Console
or using the CLI by running `upsun environment:info` and looking under `deployment_state`.

#### Restarting paused crons

If the crons on your preview environment are paused but you're still using them,
you can push changes to the environment or redeploy it.

To restart crons without changing anything:

<Tabs>
  <Tab title="In the Console">
    1. In the Console, navigate to your project.
    2. Open the environment where you'd like the crons to run.
    3. Click `Redeploy` next to the cron status of `Paused`.
  </Tab>

  <Tab title="Using the CLI">
    Run the following command:

    ```bash theme={null}
    upsun redeploy
    ```
  </Tab>
</Tabs>


# Hooks
Source: https://developer.upsun.com/docs/configure-apps/image-properties/hooks

A hooks dictionary that defines which commands run at different stages in the build and deploy process.

Optional in [single-runtime](/docs/configure-apps/app-reference/single-runtime-image#primary-application-properties) and [composable](/docs/configure-apps/app-reference/composable-image#primary-application-properties) images.

There are three different hooks that run as part of the process of building and deploying your app.
These are places where you can run custom scripts.
They are: the `build` hook, the `deploy` hook, and the `post_deploy` hook.
Only the `build` hook is run for [worker instances](/docs/configure-apps/image-properties/workers), while [web instances](/docs/configure-apps/image-properties/web) run all three.

The process is ordered as:

<Tabs>
  <Tab title="Single-runtime image">
    1. Variables accessible at build time become available.
    2. [Build flavor](/docs/configure-apps/app-reference/single-runtime-image#build) runs if applicable.
    3. Any [dependencies](/docs/configure-apps/app-reference/single-runtime-image#dependencies) are installed.
    4. The `build` hook is run.
    5. The file system is changed to read only, except for any [mounts](/docs/configure-apps/image-properties/mounts).
    6. The app container starts. Variables accessible at runtime and services become available.
    7. The `deploy` hook is run.
    8. The app container begins accepting requests.
    9. The `post_deploy` hook is run.
  </Tab>

  <Tab title="Composable image">
    1. Variables accessible at build time become available.
    2. The `build` hook is run.
    3. The file system is changed to read only, except for any [mounts](/docs/configure-apps/image-properties/mounts).
    4. The app container starts. Variables accessible at runtime and services become available.
    5. The `deploy` hook is run.
    6. The app container begins accepting requests.
    7. The `post_deploy` hook is run.
  </Tab>
</Tabs>

Note that if an environment changes by no code changes, only the last step is run.
If you want the entire process to run, see how
to [manually trigger builds](/docs/troubleshooting/general#manually-trigger-builds).

### Writable directories during build

During the `build` hook, there are three writeable directories:

* `PLATFORM_APP_DIR`:
  Where your code is checked out and the working directory when the `build` hook starts.
  Becomes the app that gets deployed.
* `PLATFORM_CACHE_DIR`:
  Persists between builds, but isn't deployed.
  Shared by all builds on all branches.
* `/tmp`:
  Isn't deployed and is wiped between each build.
  Note that `PLATFORM_CACHE_DIR` is mapped to `/tmp`
  and together they offer about 8 GB of free space.

### Hook failure

Each hook is executed as a single script, so they're considered to have failed only if the final command in them fails.
To cause them to fail on the first failed command, add `set -e` to the beginning of the hook.

If a `build` hook fails for any reason, the build is aborted and the deploy doesn't happen.
Note that this only works for `build` hooks --
if other hooks fail, the app is still deployed.

#### Automated testing

It’s preferable that you set up and run automated tests in a dedicated CI/CD tool.
Relying on Upsun Cloud hooks for such tasks can prove difficult.

During the `build` hook, you can halt the deployment on a test failure but the following limitations apply:

* Access to services such as databases, Redis, Vault KMS, and even writable mounts is disabled.
  So any testing that relies on it is sure to fail.
* If you haven’t made changes to your app, an existing build image is reused and the build hook isn’t run.
* Test results are written into your app container, so they might get exposed to a third party.

During the `deploy` hook, you can access services but **you can’t halt the deployment based on a test failure**.
Note that there are other downsides:

* Your app container is read-only during the deploy hook,
  so if your tests need to write reports and other information, you need to create a file mount for them.
* Your app can only be deployed once the deploy hook has been completed.
  Therefore, running automated testing via the deploy hook generates slower deployments.
* Your environment isn’t available externally during the deploy hook.
  Unit and integration testing might work without the environment being available,
  but you can’t typically perform end-to-end testing until after the environment is up and available.


# Image properties
Source: https://developer.upsun.com/docs/configure-apps/image-properties/index

Details about image properties in the Upsun Cloud config.yaml file

**Note:** The properties below are available in **both** [single-runtime image](/docs/configure-apps/app-reference/single-runtime-image) and [composable image](/docs/configure-apps/app-reference/composable-image) types.

For most of these properties, the syntax and details are the same for both image types. Differences in meaning and syntax are noted as needed for each property.

<Note>
  To learn about the properties that are **unique to each image type**, refer to the top-level properties described in the [single-runtime image](/docs/configure-apps/app-reference/single-runtime-image) topic or the primary application properties described in the [composable image](/docs/configure-apps/app-reference/composable-image) topic.
</Note>

Pick a property to jump to its reference:

<CardGroup>
  <Card title="access" icon="user-lock" href="/docs/configure-apps/image-properties/access">Access & Security</Card>
  <Card title="additional_hosts" icon="globe" href="/docs/configure-apps/image-properties/additional_hosts">Networking</Card>
  <Card title="authorizations" icon="key" href="/docs/configure-apps/image-properties/authorizations">Access & Security</Card>
  <Card title="container_profile" icon="server" href="/docs/configure-apps/image-properties/container_profile">Networking</Card>
  <Card title="crons" icon="clock" href="/docs/configure-apps/image-properties/crons">Runtime</Card>
  <Card title="hooks" icon="terminal" href="/docs/configure-apps/image-properties/hooks">Build & Deploy</Card>
  <Card title="mounts" icon="hard-drive" href="/docs/configure-apps/image-properties/mounts">Storage & Data</Card>
  <Card title="relationships" icon="link" href="/docs/configure-apps/image-properties/relationships">Relationships</Card>
  <Card title="source" icon="code" href="/docs/configure-apps/image-properties/source">Build & Deploy</Card>
  <Card title="variables" icon="list" href="/docs/configure-apps/image-properties/variables">Storage & Data</Card>
  <Card title="web" icon="globe" href="/docs/configure-apps/image-properties/web">Runtime</Card>
  <Card title="workers" icon="users" href="/docs/configure-apps/image-properties/workers">Runtime</Card>
</CardGroup>


# Mounts
Source: https://developer.upsun.com/docs/configure-apps/image-properties/mounts

Directories that are writable even after the app is built.

Directories that are writable even after the app is built. Allocated disk for mounts is defined with a separate resource configuration call using `upsun resources:set`.

Optional in [single-runtime](/docs/configure-apps/app-reference/single-runtime-image#primary-application-properties) and [composable](/docs/configure-apps/app-reference/composable-image#primary-application-properties) images.

After your app is built, its file system is read-only.
To make changes to your app's code, you need to use Git.

For enhanced flexibility, Upsun Cloud allows you to define and use writable directories called "mounts".
Mounts give you write access to files generated by your app (such as cache and log files)
and uploaded files without going through Git.

When you define a mount, you are mounting an external directory to your app container,
much like you would plug a hard drive into your computer to transfer data.

<Note>
  * Mounts aren't available during the build.
  * When you [back up an environment](/docs/environments/backup), the mounts on that environment are also backed up.
</Note>

### Define a mount

To define a mount, use the following configuration:

`<MOUNT_PATH>` is the path to your mount **within the app container** (relative to the app's root).
If you already have a directory with that name, you get a warning that it isn't accessible after the build.
See how to [troubleshoot the warning](/docs/troubleshooting/mounts#overlapping-folders).

| Name | Type | Required | Description |
| - | - | - | - |
| `source` | `storage`, `instance`, `tmp` (also called `temporary`), or `service` | Yes | Specifies the type of the mount:<br /><br />- By design, `storage` mounts can be shared between instances of the same app. You can also configure them so they are [shared between different apps](#share-a-mount-between-several-apps).<br /><br />-`instance` mounts are local mounts; set to 8 GB. Unique to your app, they are useful to store files that remain local to the app instance, such as application logs.<br /><br />- `tmp` (or `temporary`) mounts are local ephemeral mounts, where an external directory is mounted to the `/tmp` directory of your app.<br />The content of a `tmp` mount **may be removed during infrastructure maintenance operations**. Therefore, `tmp` mounts allow you to **store files that you’re not afraid to lose**, such as your application cache that can be seamlessly rebuilt.<br />Note that the `/tmp` directory has **a maximum allocation of 8 GB**.<br /><br />- `service` mounts can be useful if you want to explicitly define and use a [Network Storage](/docs/add-services/network-storage) service to share data between different apps (instead of using a `storage` mount). |
| `source_path` | `string` | No | Specifies where the mount points **inside the external directory**.<br /><br /> - If you explicitly set a `source_path`, your mount points to a specific subdirectory in the external directory. <br /><br /> - If the `source_path` is an empty string (`""`), your mount points to the entire external directory.<br /><br /> - If you don't define a `source_path`, Upsun Cloud uses the `<MOUNT_PATH>` as default value, without leading or trailing slashes.<br />For example, if your mount lives in the `/web/uploads/` directory in your app container, it will point to a directory named `web/uploads` in the external directory.  <br /><br /> **WARNING:** Changing the name of your mount affects the `source_path` when it's undefined. See [how to ensure continuity](#ensure-continuity-when-changing-the-name-of-your-mount) and maintain access to your files. |
| `service` | `string` | | The purpose of the `service` key depends on your use case.<br /><br /> In a multi-app context where a `storage` mount is shared between apps, `service` is required. Its value is the name of the app whose mount you want to share. See how to [share a mount between several apps](#share-a-mount-between-several-apps).<br /><br /> In a multi-app context where a [Network Storage service](/docs/add-services/network-storage) (`service` mount) is shared between apps, `service` is required and specifies the name of that Network Storage. |

The accessibility to the web of a mounted directory depends on the [`web.locations` configuration](/docs/configure-apps/image-properties/web).
Files can be all public, all private, or with different rules for different paths and file types.

Note that when you remove a `tmp` mount from your `.upsun/config.yaml` file,
the mounted directory isn't deleted.
The files still exist on disk until manually removed,
or until the app container is moved to another host during a maintenance operation.

### Example configuration

### Ensure continuity when changing the name of your mount

Changing the name of your mount affects the default `source_path`.

Suppose you have a `/my/cache/` mount with an undefined `source_path`:

If you rename the mount to `/cache/files/`, it will point to a new, empty `/cache/files/` directory.

To ensure continuity, you must explicitly define the `source_path` as the previous name of the mount, without leading
or trailing slashes:

The `/cache/files/` mount now points to the original `/my/cache/` directory, maintaining access to all your existing
files in that directory.

### Share a mount between several apps

By design, [`storage` mounts](/docs/configure-apps/image-properties/mounts) are shared **between different instances of the same app**,
which enables [horizontal scaling](/docs/manage-resources).

In a [multi-application context](/docs/configure-apps/multi-app),
you can even share a `storage` mount **between different applications** in the same project.

To do so, you need to define a `storage` mount in each of your app containers,
and point each of those mounts to the same shared external network directory.

Use the following configuration:

* `<MOUNT_PATH_1>` and `<MOUNT_PATH_2>` are the paths to each mount **within their
  respective app container** (relative to the app's root).
* When configuring the first `storage` mount, you don't need to include the `service` key.
  The first mount implicitly points to an external network directory.
  The `service` key is required for subsequent mounts, to ensure they use the same external network directory as the
  first mount.
* The `source_path` allows you to point each mount to the same subdirectory **within the shared external network
  directory**.

#### Example

Suppose you have a `backend` app and a `frontend` app, and you want both apps to share data from the same mount.<br />
To achieve this, complete the following steps:

1. In your `backend` app configuration, define a `storage` mount:

This creates a `storage` mount named `var/uploads` in the `backend` app container.
The mount points to the `backend/uploads` directory within an external network directory.

2. In your `frontend` app configuration, define another `storage` mount:

This creates another `storage` mount named `web/uploads` in the `frontend` app container.

The `service` key allows you to specify that the `web/uploads` mount should use the same external network directory
as the mount previously defined in the `backend` app container.

The `source_path` key specifies which subdirectory within the external network directory both mounts should share (
here, the `backend/uploads` directory).

Note that another way to share data between apps through a mount is by
explicitly [defining a Network Storage service](/docs/add-services/network-storage).

### Composable image only: Local mounts

If you need a local mount (i.e. unique per container),
Upsun Cloud allows you to mount a directory within the `/tmp` directory of your app.
However, the following limitations apply:

* Content from `tmp` mounts is removed when your app container is moved to another host during an infrastructure
  maintenance operation
* The `/tmp` directory has a [maximum allocation of 8 GB](/docs/troubleshooting/disks#no-space-left-on-device)

Therefore, `tmp` mounts are ideal to store non-critical data, such as your application cache which can be seamlessly
rebuilt,
but aren't suitable for storing files that are necessary for your app to run smoothly.

Note that Upsun Cloud will provide new local mounts in the near future.

### Overlapping mounts

The locations of mounts as they are visible to application containers can overlap somewhat.
For example:

In this case, it does not matter that each mount is of a different `source` type.
Each mount is restricted to a subfolder within `var`, and all is well.

The following, however, is not allowed and will result in a failure:

The `storage` mount type specifically exists to share data between instances of the same application, whereas `tmp` and `instance` are meant to restrict data to build time and runtime of a single application instance, respectively.
These allowances are not compatible, and will result in an error if pushed.


# Relationships
Source: https://developer.upsun.com/docs/configure-apps/image-properties/relationships

A dictionary of relationships that defines the connections to other services and apps.

Optional in [single-runtime](/docs/configure-apps/app-reference/single-runtime-image#primary-application-properties) and [composable](/docs/configure-apps/app-reference/composable-image#primary-application-properties) images.

To allow containers in your project to communicate with one another,
you need to define relationships between them.
You can define a relationship between an app and a service, or [between two apps](/docs/configure-apps/multi-app/relationships).

The quickest way to define a relationship between your app and a service
is to use the service's default endpoint.<br />
However, some services allow you to define multiple databases, cores, and/or permissions.
In these cases, you can't rely on default endpoints.
Instead, you can explicitly define multiple endpoints when setting up your relationships.

<Note>
  App containers don't have a default endpoint like services.
  To connect your app to another app in your project,
  you need to explicitly define the `http` endpoint as the endpoint to connect both apps.<br />
  For more information, see how to [define relationships between your apps](/docs/configure-apps/multi-app/relationships).
</Note>

<Info>
  <h4>Availability</h4>
  New syntax (default and explicit endpoints) described below is supported by most, but not all, image types
  (`Relationship 'SERVICE_NAME' of application 'app' ... targets a service without a valid default endpoint configuration.`).
  This syntax is currently being rolled out for all images.
  If you encounter this error, use the "legacy" Upsun Cloud configuration noted at the bottom of this section.
</Info>

To define a relationship between your app and a service:

<Tabs>
  <Tab title="Using default endpoints">
    Use the following configuration:

    The `SERVICE_NAME` is the name of the service as defined in its [configuration](/docs/add-services).
    It is used as the relationship name, and associated with a `null` value.
    This instructs Upsun Cloud to use the service's default endpoint to connect your app to the service.

    For example, if you define the following configuration:

    Upsun Cloud looks for a service named `mariadb` in your `.upsun/config.yaml` file,
    and connects your app to it through the service's default endpoint.

    For reference, the equivalent configuration using explicit endpoints would be the following:

    You can define any number of relationships in this way:

    <Info>
      <h4>Tip</h4>
      An even quicker way to define many relationships is to use the following single-line configuration:
    </Info>
  </Tab>

  <Tab title="Using explicit endpoints">
    Use the following configuration:

    * `RELATIONSHIP_NAME` is the name you want to give to the relationship.
    * `SERVICE_NAME` is the name of the service as defined in its [configuration](/docs/add-services).
    * `ENDPOINT_NAME` is the endpoint your app will use to connect to the service (refer to the service reference to know which value to use).

    For example, to define a relationship named `database` that connects your app to a service called `mariadb` through the `db1` endpoint,
    use the following configuration:

    For more information on how to handle multiple databases, multiple cores,
    and/or different permissions with services that support such features,
    see each service's dedicated page:

    * [MariaDB/MySQL](/docs/add-services/mysql#multiple-databases) (multiple databases and permissions)
    * [PostgreSQL](/docs/add-services/postgresql#multiple-databases) (multiple databases and permissions)
    * [Redis](/docs/add-services/redis#multiple-databases) (multiple databases)
    * [Solr](/docs/add-services/solr#solr-6-and-later) (multiple cores)
    * [Vault KMS](/docs/add-services/vault#multiple-endpoints-example) (multiple permissions)

    You can add as many relationships as you want to your app configuration,
    using both default and explicit endpoints according to your needs:
  </Tab>
</Tabs>

<Info>
  <h4>Legacy</h4>
  The following legacy syntax for specifying relationships is still supported by Upsun Cloud:

  For example:

  Feel free to use this until the default and explicit endpoint syntax is supported on all images.
</Info>


# Source
Source: https://developer.upsun.com/docs/configure-apps/image-properties/source

Contains information about the app’s source code and operations that can be run on it.

Optional in [single-runtime](/docs/configure-apps/app-reference/single-runtime-image#primary-application-properties) and [composable](/docs/configure-apps/app-reference/composable-image#primary-application-properties) images.

The following table shows the properties that can be set in `source`:

| Name | Type | Required | Description |
| - | - | - | - |
| `operations` | An operations dictionary | | Operations that can be applied to the source code. See [source operations](/docs/configure-apps/source-operations). |
| `root` | `string` | | The path where the app code lives. Useful for [multi-app setups](/docs/configure-apps/multi-app). <br />**Single-runtime image**: Defaults to the directory of the `.upsun/config.yaml` file. <br />**Composable image**: Defaults to the root project directory. |


# Variables
Source: https://developer.upsun.com/docs/configure-apps/image-properties/variables

A variables dictionary that defines variables to control the environment.

Optional in [single-runtime](/docs/configure-apps/app-reference/single-runtime-image#primary-application-properties) and [composable](/docs/configure-apps/app-reference/composable-image#primary-application-properties) images.

Upsun Cloud provides a number of ways to set [variables](/docs/development/variables).
Variables set in your app configuration have the lowest precedence,
meaning they're overridden by any conflicting values provided elsewhere.

All variables set in your app configuration must have a prefix.
Some [prefixes have specific meanings](/docs/development/variables#variable-prefixes).

Variables with the prefix `env` are available as a separate environment variable.
All other variables are available in
the [`PLATFORM_VARIABLES` environment variable](/docs/development/variables/use-variables#use-provided-variables).

The following example sets two variables:

* A variable named `env:AUTHOR` with the value `Juan` that's available in the environment as `AUTHOR`
* A variable named `d8config:system.site:name` with the value `My site rocks`
  that's available in the `PLATFORM_VARIABLES` environment variable

You can also define and access more [complex values](/docs/development/variables/use-variables#access-complex-values).


# Web
Source: https://developer.upsun.com/docs/configure-apps/image-properties/web

A web instance that defines how the web application is served.

Optional in [single-runtime](/docs/configure-apps/app-reference/single-runtime-image#primary-application-properties) and [composable](/docs/configure-apps/app-reference/composable-image#primary-application-properties) images.

Use the `web` key to configure the web server running in front of your app.

For **single-runtime images**, default values might vary based on the image [`type`](/docs/configure-apps/app-reference/single-runtime-image#type), which defines the base container used to run the application.

| Name | Type | Required | Description |
| - | - | - | - |
| `commands` | A [web commands dictionary](#web-commands) | See [`start`](#start-command) | The command to launch your app. |
| `upstream` | An [upstream dictionary](#upstream) | | How the front server connects to your app. |
| `locations` | A [locations dictionary](#locations) | | How the app container responds to incoming requests. |

See some [examples of how to configure what's served](/docs/configure-apps/web).

### Web commands

| Name | Type | Required | Description |
| - | - | - | - |
| [`pre_start`](#pre_start-command) | `string` | | Command run just prior to `start`, which can be useful when you need to run *per-instance* actions. Non-blocking. |
| [`start`](#start-command) | `string` | Typically, except for PHP; see [`start`](#start-command). | The command to launch your app. If it terminates, it's restarted immediately. |
| [`post_start`](#post_start-command) | `string` | | Command runs **after** the `start` command and **before** adding the container to the router. Can be used to ensure app is active before routing traffic to it. |

### `pre_start` command

The `pre_start` command is **not blocking**, which means the `deploy` hook may start running **before** the `pre_start` command finishes. This can lead to unexpected behavior if `pre_start` performs setup tasks that `deploy` depends on.<br />
To avoid issues, make sure any critical initialization in `pre_start` can complete quickly or is safe to run concurrently with `deploy`.

### `start` command

On all containers other than PHP, it's a best practice to include a `start` command. This command runs every time your app is restarted, regardless of whether new code is deployed.

On PHP containers, `start` is optional and defaults to starting PHP-FPM (`/usr/bin/start-php-app`).
You can set it explicitly on a PHP container to run a dedicated process,
such as [React PHP](https://github.com/platformsh-examples/platformsh-example-reactphp)
or [Amp](https://github.com/platformsh-examples/platformsh-example-amphp).
See [Alternate start commands](/docs/languages/php#alternate-start-commands) in the PHP topic.

<Note>
  Do not run a `start` process in the background by using `&` syntax.
  The Upsun Cloud supervisor interprets that syntax as the command terminating and starts another copy, creating a loop that continues until the container crashes.
  Run the command as usual and allow the Upsun Cloud supervisor to manage it.
</Note>

### `post_start` command

You can use the `post_start` command to ensure your app is fully active before traffic is routed to it. This command can perform checks or wait until your application starts listening on the expected port.

For example, if your framework needs several seconds to initialize (for example, to build caches or establish database connections), `post_start` can help coordinate the handover to ensure that the app receives traffic only after it is initialized.

#### Example:

This example contains two web commands:

* A `start` command that starts the application every time, whether or not new code is deployed.
* A `post_start` command that repeatedly checks whether a service on `localhost` is responding.

### `upstream`

<Tabs>
  <Tab title="Single-runtime image">
    | Name | Type | Required | Description | Default |
    | - | - | - | - | - |
    | `socket_family` | `tcp` or `unix` | | Whether your app listens on a Unix or TCP socket. | Defaults to `tcp` for all [image types](/docs/configure-apps/app-reference/single-runtime-image#type) except PHP; for PHP image types the default is `unix`. |
    | `protocol` | `http` or `fastcgi` | | Whether your app receives incoming requests over HTTP or FastCGI. | Default varies based on [image `type`](/docs/configure-apps/app-reference/single-runtime-image#type). |

    For PHP, the defaults are configured for PHP-FPM and shouldn't need adjustment.
    For all other containers, the default for `protocol` is `http`.

    The following example is the default on non-PHP containers:
  </Tab>

  <Tab title="Composable image">
    | Name | Type | Required | Description | Default |
    | - | - | - | - | - |
    | `socket_family` | `tcp` or `unix` | | Whether your app listens on a Unix or TCP socket. | Defaults to `tcp` for all [primary runtimes](/docs/configure-apps/app-reference/composable-image#working-with-multiple-runtimes-primary-runtime) except PHP; for PHP the default is `unix`. |
    | `protocol` | `http` or `fastcgi` | | Whether your app receives incoming requests over HTTP or FastCGI. | Default varies based on the [primary runtimes](/docs/configure-apps/app-reference/composable-image#working-with-multiple-runtimes-primary-runtime). |

    For PHP, the defaults are configured for PHP-FPM and shouldn't need adjustment.
    For all other containers, the default for `protocol` is `http`.

    The following example is the default on non-PHP containers:
  </Tab>
</Tabs>

#### Where to listen

Where to listen depends on your setting for `web.upstream.socket_family` (defaults to `tcp`).

| `socket_family` | Where to listen |
| - | - |
| `tcp` | The port specified by the [`PORT` environment variable](/docs/development/variables/use-variables#use-provided-variables) |
| `unix` | The Unix socket file specified by the [`SOCKET` environment variable](/docs/development/variables/use-variables#use-provided-variables) |

If your application isn't listening at the same place that the runtime is sending requests,
you see `502 Bad Gateway` errors when you try to connect to your website.

### `locations`

Each key in the `locations` dictionary is a path on your site with a leading `/`.
For `example.com`, a `/` matches `example.com/` and `/admin` matches `example.com/admin`.
When multiple keys match an incoming request, the most-specific applies.

The following table presents possible properties for each location:

<Tabs>
  <Tab title="Single-runtime image">
    | Name | Type | Default | Description |
    | - | - | - | - |
    | `root` | `string` | | The directory to serve static assets for this location relative to the [app's root directory](/docs/configure-apps/app-reference/single-runtime-image#root-directory). Must be an actual directory inside the root directory. |
    | `passthru` | `boolean` or  `string` | `false` | Whether to forward disallowed and missing resources from this location to the app. A string is a path with a leading `/` to the controller, such as `/index.php`. <br /> <br /> If your app is in PHP, when setting `passthru` to `true`, you might want to set `scripts` to `false` for enhanced security. This prevents PHP scripts from being executed from the specified location. You might also want to set `allow` to `false` so that not only PHP scripts can't be executed, but their source code also can't be delivered. |
    | `index` | `string` array or `null` | | Files to consider when serving a request for a directory. When set, requires access to the files through the `allow` or `rules` keys. |
    | `expires` | `string` | `-1` | How long static assets are cached. The default means no caching. Setting it to a value enables the `Cache-Control` and `Expires` headers. Times can be suffixed with `ms` = milliseconds, `s` = seconds, `m` = minutes, `h` = hours, `d` = days, `w` = weeks, `M` = months/30d, or `y` = years/365d. If a `Cache-Control` appears on the `headers` configuration, `expires`, if set, will be ignored. Thus, make sure to set the `Cache-Control`'s `max-age` value when specifying a header. |
    | `allow` | `boolean` | `true` | Whether to allow serving files which don't match a rule. |
    | `scripts` | `boolean` | | Whether to allow scripts to run. Doesn't apply to paths specified in `passthru`. Meaningful only on PHP containers. |
    | `headers` | A headers dictionary | | Any additional headers to apply to static assets, mapping header names to values (see [Set custom headers on static content](/docs/configure-apps/web/custom-headers)). Responses from the app aren't affected. |
    | `request_buffering` | A [request buffering dictionary](#request-buffering) | See below | Handling for chunked requests. |
    | `dynamic_compression` | `boolean` | `false` | Whether to compress dynamic responses from your app. See [dynamic response compression](#dynamic-response-compression). |
    | `rules` | A [rules dictionary](#rules) | | Specific overrides for specific locations. |
  </Tab>

  <Tab title="Composable image">
    | Name | Type | Default | Description |
    | - | - | - | - |
    | `root` | `string` | | The directory to serve static assets for this location relative to the app's root directory ([see `source.root`](/docs/configure-apps/image-properties/source)). Must be an actual directory inside the root directory. |
    | `passthru` | `boolean` or  `string` | `false` | Whether to forward disallowed and missing resources from this location to the app. A string is a path with a leading `/` to the controller, such as `/index.php`. <br /> <br /> If your app is in PHP, when setting `passthru` to `true`, you might want to set `scripts` to `false` for enhanced security. This prevents PHP scripts from being executed from the specified location. You might also want to set `allow` to `false` so that not only PHP scripts can't be executed, but their source code also can't be delivered. |
    | `index` | `string` array or `null` | | Files to consider when serving a request for a directory. When set, requires access to the files through the `allow` or `rules` keys. |
    | `expires` | `string` | `-1` | How long static assets are cached. The default means no caching. Setting it to a value enables the `Cache-Control` and `Expires` headers. Times can be suffixed with `ms` = milliseconds, `s` = seconds, `m` = minutes, `h` = hours, `d` = days, `w` = weeks, `M` = months/30d, or `y` = years/365d. |
    | `allow` | `boolean` | `true` | Whether to allow serving files which don't match a rule. |
    | `scripts` | `boolean` | | Whether to allow scripts to run. Doesn't apply to paths specified in `passthru`. Meaningful only on PHP containers. |
    | `headers` | A headers dictionary | | Any additional headers to apply to static assets, mapping header names to values (see [Set custom headers on static content](/docs/configure-apps/web/custom-headers)). Responses from the app aren't affected. |
    | `request_buffering` | A [request buffering dictionary](#request-buffering) | See below | Handling for chunked requests. |
    | `dynamic_compression` | `boolean` | `false` | Whether to compress dynamic responses from your app. See [dynamic response compression](#dynamic-response-compression). |
    | `rules` | A [rules dictionary](#rules) | | Specific overrides for specific locations. |
  </Tab>
</Tabs>

#### Rules

The rules dictionary can override most other keys according to a regular expression.
The key of each item is a regular expression to match paths exactly.
If an incoming request matches the rule, it's handled by the properties under the rule,
overriding any conflicting rules from the rest of the `locations` dictionary.

Under `rules`, you can set all the other possible [`locations` properties](#locations)
except `root`, `index`, `rules` and `request_buffering`.

In the following example, the `allow` key disallows requests for static files anywhere in the site.
This is overridden by a rule that explicitly allows common image file formats.

#### Dynamic response compression

Static files are compressed automatically, but responses generated by your app aren't.
Set `dynamic_compression` to `true` on a location to compress them:

The algorithm is chosen based on the request's `Accept-Encoding` header, with Brotli preferred and gzip as the fallback.
Requests without that header get an uncompressed response.
Compressed responses carry a `Vary: Accept-Encoding` header.
Responses that already have a `Content-Encoding` header are left alone,
so an app that compresses its own output isn't compressed twice.

Compression starts at 256 bytes, on a best-effort basis:
the web server can only check the size of responses that declare a `Content-Length`,
which means chunked responses are compressed whatever their size.

To keep some paths uncompressed, turn the setting on for the location and off in a [rule](#rules):

Enable compression on the location and opt out per rule, not the other way around.
A rule that turns compression on inside a location where it's off doesn't survive the `passthru` rewrite,
which leaves the traffic uncompressed on a typical PHP app.
A rule that turns compression off applies to both direct hits and requests served through `passthru`.

<Warning>
  Compressing dynamic responses reintroduces the theoretical [BREACH](https://en.wikipedia.org/wiki/BREACH) attack surface over HTTPS.
  BREACH needs a secret and attacker-controlled input in the same response,
  so only enable `dynamic_compression` when your framework mitigates it,
  through Cross-Site Request Forgery (CSRF) token masking or a similar technique.
  Most frameworks do by default.
  Turn the setting off with a rule on authenticated areas,
  and on any path that reflects user input into a response that also carries a secret.
</Warning>

Apps serving large volumes of public, cacheable HTML from the origin get the most out of the setting,
especially behind a content delivery network (CDN) that can't compress what the origin sends it.

#### Request buffering

Request buffering is enabled by default to handle chunked requests as most app servers don't support them.
The following table shows the keys in the `request_buffering` dictionary:

| Name | Type | Required | Default | Description |
| - | - | - | - | - |
| `enabled` | `boolean` | Yes | `true` | Whether request buffering is enabled. |
| `max_request_size` | `string` | | `250m` | The maximum size to allow in one request. |

The default configuration would look like this:


# Workers
Source: https://developer.upsun.com/docs/configure-apps/image-properties/workers

Defines the list of worker names, which are alternate copies of the application to run as background processes.

Optional in [single-runtime](/docs/configure-apps/app-reference/single-runtime-image#primary-application-properties) and [composable](/docs/configure-apps/app-reference/composable-image#primary-application-properties) images.

Workers require resource definition using `upsun resources:set`, same as application containers.
For more information, see how to [manage resources](/docs/manage-resources).

Workers are exact copies of the code and compilation output as a `web` instance after a [`build` hook](/docs/configure-apps/image-properties/hooks).
They use the same container image.

Workers can't accept public requests and so are suitable only for background tasks.
If they exit, they're automatically restarted.

<Tabs>
  <Tab title="Single-runtime image">
    The keys of the `workers` definition are the names of the workers.
    You can then define how each worker differs from the `web` instance using
    the [primary application properties](/docs/configure-apps/app-reference/single-runtime-image#primary-application-properties).

    Each worker can differ from the `web` instance in all properties *except* for:

    * `build` and `dependencies` properties, which must be the same
    * `crons` as cron jobs don't run on workers
    * `hooks` as the `build` hook must be the same
      and the `deploy` and `post_deploy` hooks don't run on workers.

    A worker named `queue` that was small and had a different start command could look like this:
  </Tab>

  <Tab title="Composable image">
    The keys of the `workers` definition are the names of the workers.
    You can then define how each worker differs from the `web` instance using
    the [primary application properties](/docs/configure-apps/app-reference/composable-image#primary-application-properties).

    Each worker can differ from the `web` instance in all properties *except* for:

    * `crons` as cron jobs don't run on workers
    * `hooks` as the `build` hook must be the same
      and the `deploy` and `post_deploy` hooks don't run on workers.

    A worker named `queue` that was small and had a different start command could look like this:
  </Tab>
</Tabs>


# Configure apps
Source: https://developer.upsun.com/docs/configure-apps/index

Control your apps and how they're built and deployed on Upsun Cloud with YAML configuration.


Within a single project, you can have one or more apps and each app can have multiple instances.
Instances are where the same code can be run with different configurations,
such as one for external communication and one for background processes.
Apps and instances use similar properties, with minor differences depending on the image type that you choose:

* [Single-runtime image](/docs/configure-apps/app-reference/single-runtime-image)
* [Composable image](/docs/configure-apps/app-reference/composable-image)

Not sure which image type to use? See [choosing an image type](/docs/configure-apps/app-reference).

## A minimal application

To create a very basic app (for this example, using a single-runtime image), you need a few things:

* A unique name not shared by any other app in the project.
* The runtime `type` defining what language it uses.
* A definition of how to handle requests from the outside `web`.

The following example shows such a basic setup for Node.js:

## Use multiple apps

You might have multiple apps you want to run from a single Git repository,
such as a RESTful web service and a front-end or a main website and a blog.
In such cases, you configure each app separately and define the relationships among them.
See the various ways to set up a [multi-app project](/docs/configure-apps/multi-app).

## Connect to services

If you want to use one of the [databases or other services Upsun Cloud provides](/docs/add-services),
set it up by following these steps:

1. Configure the service based on the documentation for that service.
2. Use the information from that service inside your app's [`relationships` definition](/docs/configure-apps/image-properties/relationships)
   to configure how your app communicates with the service.

## Control the build and deploy process

Your app generally needs to undergo some steps to be turned from the code in your Git repository into a running app.
If you're running a PHP or Node.js app, this starts with the [build flavor](/docs/configure-apps/app-reference/single-runtime-image#build),
which runs a default set of tasks.
Then any [global dependencies](/docs/configure-apps/app-reference/single-runtime-image#dependencies) can be installed.

Once these optional tasks are done, you can run [hooks](/docs/configure-apps/hooks) at various points in the process.
Hooks are places for your custom scripts to control how your app is built and deployed.

## Configure what's served

Once your app is built, it needs a defined way to communicate with the outside world.
Define its behavior with a [`web` instance](/docs/configure-apps/image-properties/web).
There you can set what command runs every time your app is restarted,
how dynamic requests are handled, and how to respond with static files.

## Response compression

Response compression reduces payload sizes and generally increases your app's response times.
Requests for static files that are served directly by Upsun Cloud are compressed automatically
using either gzip or Brotli compression if:

* The request headers for the file support gzip or Brotli compression.
* The file is served directly from disk by Upsun Cloud and not passed through your application.
* The file would be served with a cache expiration time in the future.
* The file type is one of: HTML, JavaScript, JSON, PDF, PostScript, SVG, CSS, CSV, plain text, or XML.

Also, if there is a request for a file and another file exists with the same name plus a `.gz` or `.br` extension,
the compressed file is served regardless of the original file type.
So a request for `styles.css` that accepts a gzipped file (according to the request headers)
automatically returns a `styles.css.gz` file if it exists.
This approach supports any file type and offers some CPU optimization, especially if the cache lifetime is short.

Dynamic responses generated by your app aren't compressed by default,
because compressing them reintroduces the theoretical [BREACH](https://en.wikipedia.org/wiki/BREACH) attack surface.
If your framework mitigates BREACH, which most do by default,
you can opt in per location with the
[`dynamic_compression` setting](/docs/configure-apps/image-properties/web#dynamic-response-compression).

## Comprehensive example

<Info>
  <h4>PHP specifics</h4>
  Unlike other runtimes, most PHP applications do not have a start command. There is a daemon running configured to work automatically with the web server. More often than not there will be a single entry-point a "front-controller". In the case of PHP the `passthru` property is a string with the location of the front-controller rather than a boolean.
</Info>

The following example shows a setup for a PHP app with comments to explain the settings.


# Set up multiple apps in a single project
Source: https://developer.upsun.com/docs/configure-apps/multi-app/index

Create multiple apps within a single project, such as a CMS backend connected to a frontend to display it.

You can create multiple apps within a single project so they can share data.
This can be useful if you have several apps that are closely related,
such as a backend-only CMS and a frontend system for content delivery and display.

No matter how many apps you have in one project, they're all served by a single [router for the project](/docs/configure-apps/multi-app/routes).
To allow your apps to communicate with each other, [create relationships](/docs/configure-apps/multi-app/relationships).
Each app separately defines its relationships to [services](/docs/add-services),
so apps can share services or have their own.


# Choose a project structure
Source: https://developer.upsun.com/docs/configure-apps/multi-app/project-structure

Explore possible code structures you can apply to your multiple application projects.

How you structure a project with multiple apps depends on how your code is organized
and what you want to accomplish.
For example, there are various ways you could set up the following multiple apps:

Here are some example use cases and potential ways to organize the project:

| Use case | Structure |
| - | - |
| Separate basic apps that are worked on together. | [Unified app configuration](#unified-app-configuration) |
| One app depends on code from another app. | [Nested directories](#nested-directories) |
| You want to keep configuration separate from code, such as through Git submodules. | [Configuration separate from code](#split-your-code-source-into-multiple-git-submodule-repositories) |
| You want multiple apps from the same source code. | [Unified app configuration](#unified-app-configuration) |
| You want to control all apps in a single location. | [Unified app configuration](#unified-app-configuration) |

## Unified app configuration

You can configure all your apps from a single file.
To do so, create a `.upsun/config.yaml` and define each app as a key.

For example, if you have an API Platform backend with a Symfony API,
a Mercure Rocks server, and a Gatsby frontend,
you can organize your repository like this:

```text theme={null}
├── .upsun/
│   ├── config.yaml   <- Unified configuration
├── admin
│   └── ...                 <- API Platform Admin app code
├── api-app
│   └── ...                 <- Bigfoot app code
├── gatsby
│   └── ...                 <- Gatsby app code
└── mercure
    └── ...                 <- Mercure Rocks app code
```

The `api` app is built from the `api-app` directory.<br />
The `admin` app is built from the `admin` directory.<br />
The `gatsby` app is built from the `gatsby` directory.<br />
The `mercure` app is built from the `mercure` directory.<br />
They all have different configurations for how they serve the files. For more details, see the [complete example file](https://github.com/platformsh-templates/bigfoot-multiapp/blob/multiapp-monolith/.platform/applications.yaml).

<Note>
  The `.upsun/` directory is located at the root, separate from your apps.
  It contains all the needed configuration files to set up the routing, services and behavior of each app.
  Since the code bases of your apps live in a different directory,
  you need to [change the source root of each app](#change-the-source-root-of-your-app).

  To build multiple apps from the repository root, set `source.root` to `/`.
  This allows you to control all your apps in one place and even build multiple apps from the same source code.
</Note>

To allow your apps to communicate with each other, define [relationships](/docs/configure-apps/multi-app/relationships).

Note that with this setup, when you amend the code of one of your apps,
the build image for your other apps can still be reused.

Once your repository is organized, you can use a configuration similar to the following:

## Nested directories

When code bases are separate, changes to one app don't necessarily mean that the other apps in the project get rebuilt.
You might have a situation where app `main` depends on app `languagetool`, but `languagetool` doesn't depend on `main`.

In such cases, you can nest the dependency so the parent (`main`) gets rebuilt on changes to it or its children,
but the child (`languagetool`) is only rebuilt on changes to itself.

For example, you might have a Python app (`main`) that runs a script that requires Java code to be up to date.
But the Java app (`languagetool`) doesn't require updating when the Python app (`main`) is updated.
In that case, you can nest the Java app within the Python app:

```text theme={null}
├── .upsun/
│   ├── .upsun/config.yaml
├── languagetool
│   └── main.java           <- Java app code
└── main.py                 <- Python app code
```

The Python app's code base includes all of the files at the top level (excluding the `.upsun/` directory)
*and* all of the files within the `languagetool` directory.
The Java app's code base includes only the files within the `languagetool` directory.

In this case, your `.upsun/config.yaml` file must contain 2 entries, one for the `main` app and second one for the `languagetool` app.

<Note>
  The `.upsun/` directory is located at the root, separate from your apps.
  It contains all the needed configuration files to set up the routing, services and behavior of each app.
  Since the code base of the `languagetool` app lives in a different directory (`languagetool/`),
  you need to [change the source root](#change-the-source-root-of-your-app) of the `languagetool` app.
</Note>

Once your repository is organized, you can use a configuration similar to the following:

## Split your code source into multiple Git submodule repositories

If you have different teams working on different code with different processes,
you might want each app to have its own repository.
Then you can build them together in another repository using [Git submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules).

With this setup, your apps are kept separate from the top application.
Each app has its own [Git submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules) containing its code base.
All your apps are configured in a single `.upsun/config.yaml` file.
So you could organize your [project repository](https://github.com/platformsh-templates/bigfoot-multiapp/tree/submodules-root-app-yaml) like this:

```text {no-copy="true"} theme={null}
├── .upsun/
│   ├── config.yaml
├── @admin      <-- API Platform Admin submodule
├── @api        <-- Bigfoot submodule
├── @gatsby     <-- Gatsby submodule
├── @mercure    <-- Mercure rocks submodule
└── .gitmodules
```

[Add the submodules using the Git CLI](/docs/development/submodules#clone-submodules-during-deployment).

Your `.gitmodules` file would define all the submodules like this:

```txt .gitmodules theme={null}
[submodule "admin"]
	path = admin
	url = https://github.com/platformsh-templates/bigfoot-multiapp-admin.git
[submodule "api"]
	path = api
	url = https://github.com/platformsh-templates/bigfoot-multiapp-api.git
[submodule "gatsby"]
	path = gatsby
	url = https://github.com/platformsh-templates/bigfoot-multiapp-gatsby.git
[submodule "mercure"]
	path = mercure
	url = https://github.com/platformsh-templates/bigfoot-multiapp-mercure.git
```

<Note>
  In this case, and any other case where your app configuration files are kept outside of the app directory,
  make sure you [change the source root](#change-the-source-root-of-your-app) for each of your apps.
</Note>

## Change the source root of your app

When your app's code base and configuration file aren't located at the same directory level in your project repository,
you need to [define a root directory](/docs/configure-apps/app-reference/single-runtime-image#root-directory) for your app.

To do so, add a new `source.root` property in your app configuration.

For example, to change the source root of the `admin` app
from the [unified app configuration](#unified-app-configuration) example project,
you could add the following configuration:

```yaml .upsun/config.yaml theme={null}
applications:
  admin:
    source:
      root: admin
```

The `source.root` path is relative to the repository root.
In this example, the `admin` app now treats the `admin` directory as its root when building.

If `source.root` isn't specified, it defaults to the project root directory, that is `"/"`.


# Define relationships between your multiple apps
Source: https://developer.upsun.com/docs/configure-apps/multi-app/relationships

Find out how relationships are managed between your apps.

When you set up a project containing multiple applications,
by default your apps can't communicate with each other.
To enable connections, define relationships between apps using the `http` endpoint.

You can't define circular relationships.
If `app1` has a relationship to `app2`, then `app2` can't have a relationship to `app1`.
If you need data to go both ways, consider coordinating through a shared data store,
like a database or [RabbitMQ server](/docs/add-services/rabbitmq).

Relationships between apps use HTTP, not HTTPS.
This is still secure because they're internal and not exposed to the outside world.

## Relationships example

You have two apps, `app1` and `app2`, and `app1` needs data from `app2`.

In your app configuration for `app1`, define a relationship to `app2`:

```yaml .upsun/config.yaml theme={null}
applications:
  app1:
    relationships:
      api:
        service: "app2"
        endpoint: "http"
```

Once they're both built, `app1` can access `app2` at the following URL: `http://api.internal`.<br />
The specific URL is always available through the [service environment variables](/docs/development/variables#service-environment-variables),
or through the [`PLATFORM_RELATIONSHIPS` variable](/docs/development/variables/use-variables#use-provided-variables):

<Tabs>
  <Tab title="Service environment variables">
    ```bash {location="Terminal on app1 container", no-copy="true"} theme={null}
    $ echo $API_HOST
    api.internal
    ```
  </Tab>

  <Tab title="`PLATFORM_RELATIONSHIPS` environment variable">
    It uses the `jq` library, which is included in all app containers for this purpose.

    ```bash {location="Terminal on app1 container", no-copy="true"} theme={null}
    $ echo $PLATFORM_RELATIONSHIPS | base64 --decode | jq '.api[0].host'
    api.internal
    ```
  </Tab>
</Tabs>


# Define routes for your multiple apps
Source: https://developer.upsun.com/docs/configure-apps/multi-app/routes

Learn about the many ways you can define routes between your apps.

When you set up a project containing multiple applications,
all of your apps are served by a single [router for the project](/docs/routes).
Each of your apps must have a `name` that's unique within the project.
To define specific routes for one of your apps, use this `name`.

There are various ways you can define routes for multiple app projects.

In this project, you have a CMS app, two frontend apps (one using Symfony and another using Gatsby),
and a Mercure Rocks server app, defined as follows:

<Note>
  You don't need to define a route for each app in the repository.
  If an app isn't specified, then it isn't accessible to the web.
  One good example of defining an app with no route is when you [use Git submodules](/docs/configure-apps/multi-app/project-structure#split-your-code-source-into-multiple-git-submodule-repositories) and want to [use a source operation to update your submodules](/docs/development/submodules#update-submodules).

  You can also achieve the same thing by defining the app as a [`worker`](/docs/configure-apps/image-properties/workers).
</Note>

Depending on your needs, you could configure the router container
[using subdomains](#define-routes-using-subdomains) or using [subdirectories](#define-routes-using-subdirectories).

### Define routes using subdomains

You could define routes for your apps as follows:

```yaml .upsun/config.yaml theme={null}
routes:
  "https://mercure.{default}/":
    type: upstream
    upstream: "mercure:http"
  "https://{default}/":
    type: upstream
    upstream: "api:http"
```

So if your default domain is `example.com`, that means:

* `https://mercure.example.com/` is served by your Mercure Rocks app (`mercure`).
* `https://example.com/` is served by your Symfony frontend app (`api`).

<Note>
  Using a subdomain might [double your network traffic](https://www.nickolinger.com/blog/2021-08-04-you-dont-need-that-cors-request/),
  so consider using a path like `https://{default}/api` instead.
</Note>

### Define routes using subdirectories

Alternatively, you could define your routes as follows:

```yaml .upsun/config.yaml theme={null}
routes:
  "https://{default}/":
    type: upstream
    upstream: "api:http"
  "https://{default}/admin":
    type: upstream
    upstream: "admin:http"
```

Then you would need to configure each app's `web.locations` property to match these paths:

So if your default domain is `example.com`, that means:

* `https://example.com/` is served by your Symfony frontend app (`api`).
* `https://example.com/admin` is served by your Admin app (`admin`).

Note that in this example, for the configuration of your `admin` app,
you need to add the URL suffix `/admin` as both an index in the `web.locations` and a value for the `passhtru` setting.

For a complete example, [go to this project on GitHub](https://github.com/platformsh-templates/bigfoot-multiapp/tree/submodules-root-subfolders-applications).


# Runtime operations
Source: https://developer.upsun.com/docs/configure-apps/runtime-operations

Set up runtime operations to run one-off commands on your project through the Upsun Cloud CLI.

Runtime operations allow you to trigger one-off commands or scripts on your project.
Similar to [crons](/docs/configure-apps/image-properties/crons), they run in the app container but not on a specific schedule.
You can [define runtime operations](#define-a-runtime-operation) in your [app configuration](/docs/configure-apps/app-reference/single-runtime-image)
and [trigger them](#run-a-runtime-operation) at any time through the Upsun Cloud CLI.

For example, if you have a static website,
you may want to set up a runtime operation to occasionally fetch content from a backend system
without having to rebuild your whole app.

## Define a runtime operation

To define a runtime operation, add a configuration similar to the following:

When you define a runtime operation,
you can specify which users can trigger it according to their user `role`:

* `viewer`
* `contributor`
* `admin`

If you don't set the `role` option when configuring your runtime operation,
by default all users with the `contributor` role can trigger it.

For example, to allow admin users to clear the cache of a Drupal site,
you could define an operation like the following:

The name of the runtime operation in this case is `clear-rebuild`.

For more possibilities, see other [runtime operation examples](#runtime-operation-examples).

## Run a runtime operation

<Tabs>
  <Tab title="In the Console">
    First, make sure that you have [defined a runtime operation](#define-a-runtime-operation). Then:

    1. Navigate to the environment where you want to run the operation.
    2. Click <MoreIcon /> **More**.
    3. Click **Run runtime operation**.
    4. Select the operation you want to run.
    5. Click **Run**.
  </Tab>

  <Tab title="Using the CLI">
    A runtime operation can be triggered through the Upsun Cloud CLI once it has been [defined](#define-a-runtime-operation).

    Run the following command:

    ```bash theme={null}
    upsun operation:run <RUNTIME_OPERATION_NAME> --project <PROJECT_ID> --environment <ENVIRONMENT_NAME>
    ```

    You can only trigger a runtime operation if you have permission to do so.
    Permissions are granted through the `role` option specified in the [runtime operation configuration](#define-a-runtime-operation). This can only be done if a [runtime operation has been defined](#define-a-runtime-operation).

    For example, to trigger the runtime operation [defined previously](#define-a-runtime-operation),
    you could run the following command:

    ```bash theme={null}
    upsun operation:run clear-rebuild --project <PROJECT_ID> --environment <ENVIRONMENT_NAME>
    ```
  </Tab>
</Tabs>

## List your runtime operations

To list all the runtime operations available on an environment,
run the following command:

```bash theme={null}
upsun operation:list --project <PROJECT_ID> --environment <ENVIRONMENT_NAME>
```

## Runtime operation examples

### Build your app when using a static site generator

During every Upsun Cloud deployment, a standard [`build` step](/docs/core-concepts/build-deploy#the-build) is run.
When you use a static site generator like Gatsby
or Next.js with a headless backend
you need to run a second `build` step to get your app ready for production.

This is because, as its framework is being built,
your frontend needs to pull content-related data from your backend’s API
(to generate all the static HTML pages your site is to serve).
To accomplish this on Upsun Cloud, where each app goes through a build-deploy pipeline in parallel,
your frontend’s build must be delayed *until after* your backend has fully deployed.
It's often delayed up until the [`post_deploy` hook](/docs/configure-apps/hooks/hooks-comparison#post-deploy-hook) stage,
when the filesystem is read-only.

You can use a runtime operation to trigger the second `build` step
after the initial deployment of your app or after a redeployment.
You can also trigger it when you need to fetch content from your backend
but want to avoid going through the whole Upsun Cloud [build and deploy processes](/docs/core-concepts/build-deploy) again.

<Note>
  The following examples assume that the frontend and backend containers are included in the same environment.
  This isn’t necessary for the commands to run successfully.<br />
  What *is* necessary is that the build destination for your frontend **is  writable at runtime**
  (meaning, you must [define a mount](/docs/configure-apps/image-properties/mounts) for it).
  If you don’t want to include a build within a mount (especially if your data source **isn’t** on Upsun Cloud),
  you can use [source operations](/docs/configure-apps/source-operations) to achieve a similar effect,
  but through generating a new commit.
</Note>

<Tabs>
  <Tab title="Gatsby">
    To run the [Gatsby build](https://www.gatsbyjs.com/docs/conceptual/overview-of-the-gatsby-build-process/#understanding-gatsby-build-build-time) step,
    define a runtime operation similar to the following:

    ```yaml .upsun/config.yaml theme={null}
    applications:
      # The name of the app container. Must be unique within a project.
      myapp:
        # The location of the application's code.

        operations:
          gatsby-build:
            role: viewer
            commands:
              start: gatsby build
    ```

    To trigger your runtime operation, run a command similar to the following:

    ```bash theme={null}
    upsun operation:run gatsby-build --project <PROJECT_ID> --environment <ENVIRONMENT_NAME>
    ```
  </Tab>

  <Tab title="Next.js">
    To run the [Next.js build](https://nextjs.org/docs/deployment#nextjs-build-api) step,
    define a runtime operation similar to the following:

    ```yaml .upsun/config.yaml theme={null}
    applications:
      # The name of the app container. Must be unique within a project.
      myapp:
        # The location of the application's code.

        operations:
          next-build:
            role: admin
            commands:
              # All below are valid, depending on your setup
              start: next build
              # start: npx next build
              # start: npm run build
    ```

    To trigger your runtime operation, run a command similar to the following:

    ```bash theme={null}
    upsun operation:run next-build --project <PROJECT_ID> --environment <ENVIRONMENT_NAME>
    ```
  </Tab>
</Tabs>

### Execute actions on your Node.js app

You can define runtime operations for common [pm2](https://pm2.io/docs/runtime/overview/) process manager tasks.

<Tabs>
  <Tab title="Ping your app">
    To ping your Node.js app, define a runtime operation similar to the following:

    ```yaml .upsun/config.yaml theme={null}
    applications:
      # The name of the app container. Must be unique within a project.
      myapp:
        # The location of the application's code.

        operations:
          pm2-ping:
            role: admin
            commands:
              start: |
                # Assuming pm2 start npm --no-daemon --watch --name $APP -- start -- -p $PORT
                APP=$(cat package.json | jq -r '.name')
                pm2 ping $APP
    ```

    To trigger your runtime operation, run a command similar to the following:

    ```bash theme={null}
    upsun operation:run pm2-ping --project <PROJECT_ID> --environment <ENVIRONMENT_NAME>
    ```
  </Tab>

  <Tab title="Reload your app">
    To reload your Node.js app, define a runtime operation similar to the following:

    ```yaml .upsun/config.yaml theme={null}
    applications:
      # The name of the app container. Must be unique within a project.
      myapp:
        # The location of the application's code.

        operations:
          pm2-reload:
            role: admin
            commands:
              start: |
                # Assuming pm2 start npm --no-daemon --watch --name $APP -- start -- -p $PORT
                APP=$(cat package.json | jq -r '.name')
                pm2 reload $APP
    ```

    To trigger your runtime operation, run a command similar to the following:

    ```bash theme={null}
    upsun operation:run pm2-reload --project <PROJECT_ID> --environment <ENVIRONMENT_NAME>
    ```
  </Tab>

  <Tab title="Restart your app">
    To restart your Node.js app, define a runtime operation similar to the following:

    ```yaml .upsun/config.yaml theme={null}
    applications:
      # The name of the app container. Must be unique within a project.
      myapp:
        # The location of the application's code.

        operations:
          pm2-restart:
            role: admin
            commands:
              start: |
                # Assuming pm2 start npm --no-daemon --watch --name $APP -- start -- -p $PORT
                APP=$(cat package.json | jq -r '.name')
                pm2 restart $APP
    ```

    To trigger your runtime operation, run a command similar to the following:

    ```bash theme={null}
    upsun operation:run pm2-restart --project <PROJECT_ID> --environment <ENVIRONMENT_NAME>
    ```
  </Tab>
</Tabs>

### Define management commands on your Django project

On a Django project, you can [define custom `django-admin` commands](https://docs.djangoproject.com/en/4.2/howto/custom-management-commands/), for example to run a one-off management command (`manual migration` in the example above) outside of the Django ORM migration framework.
To do so, define a runtime operation similar to the following:

To trigger your runtime operation, run a command similar to the following:

```bash theme={null}
upsun operation:run manual-migration --project <PROJECT_ID> --environment <ENVIRONMENT_NAME>
```


# Source operations
Source: https://developer.upsun.com/docs/configure-apps/source-operations

Run automated code updates via source operations.

On Upsun Cloud, you can run automated code updates through a feature called **source operations**.
Defined in your [app configuration](/docs/configure-apps), source operations let you specify commands
that can commit changes to your project's repository when called.

For example, you can set up a source operation to [automatically update your application dependencies](/docs/core-concepts/common-tasks/dependency-updates),
[update a site from an upstream repository](#update-a-site-from-an-upstream-repository-or-template),
or [revert to the last commit](#revert-to-the-last-commit) pushed to your Git repository.

To run your source operations, you can use the [Upsun Cloud CLI](/cli) or the [Console](https://console.upsun.com).
If you want to run your source operations and update your code automatically,
you can also define [cron jobs](/docs/configure-apps/image-properties/crons).

## How source operations work

When you trigger a source operation, the following happens in order:

1. The current environment HEAD commit is checked out in Git.
   It doesn't have any remotes or tags defined in the project.
   It only has the current environment branch.

2. Sequentially, for each app that has an operation bearing [the name](#define-a-source-operation)
   of the triggered source operation in its configuration,
   the operation command is run in the app container.
   The container isn't part of the environment's runtime cluster
   and doesn't require that the environment is running.

   The environment has all of the variables normally available during the build phase.
   These may be optionally overridden by the variables specified when the operation is run.

3. If any new commits were created, they're pushed to the repository and the normal build process is triggered.

   If multiple apps in a single project both result in a new commit,
   there are two distinct commits in the Git history but only a single new build process.

## Define a source operation

A source operation requires two things:

* A name that must be unique within the application.
  The name is the key of the block defined under `source.operations` in your [app configuration](/docs/configure-apps/image-properties/source).

* A `command` that defines what's run when the operation is triggered.

The syntax is similar to the following:

For example, to update a file from a remote location, you could define an operation like this:

The name of the source operation in this case is `update-file`.

For more possibilities, see other [source operation examples](#source-operation-examples).

## Run a source operation

<Tabs>
  <Tab title="In the Console">
    1. Navigate to the environment where you want to run the operation.
    2. Click <MoreIcon /> **More**.
    3. Click **Run source operation**.
    4. Select the operation you want to run.
    5. Optional: Add the [variables](#use-variables-in-your-source-operations) required by your source operation.
    6. Click **Run**.
  </Tab>

  <Tab title="Using the CLI">
    Run the following command:

    ```bash theme={null}
    upsun source-operation:run <SOURCE_OPERATION_NAME>
    ```

    Replace `<SOURCE_OPERATION_NAME>` with the name of your operation, such as `update-file` in the [example above](#define-a-source-operation).
  </Tab>
</Tabs>

After running a source operation,
to apply the changes to your local development environment run the `git pull` command.

Note that you can [cancel pending or running source operations](/docs/environments/cancel-activity).

## Use variables in your source operations

You can add [variables](/docs/development/variables) to the environment of the source operation.

Use the `env:` prefix to expose each of those variables as a Unix environment variable.
In this way, they're referenced by the source operation
and interpreted the same way as any other variable set in your project.

For example, you might want to have a `FILE` variable available with the value `example.txt`
to pass to a source operation similar to the following:

Follow these steps to run the source operation:

<Tabs>
  <Tab title="From the CLI">
    ```bash Using the CLI theme={null}
    upsun source-operation:run update-file --variable env:FILE="example.txt"
    ```
  </Tab>

  <Tab title="From the Console">
    1. Navigate to the environment where you want to run the operation.
    2. Click <MoreIcon /> **More**.
    3. Click **Run source operation**.
    4. Select the operation you want to run.
    5. Under **Add/override variables**, put `FILE` as the **Variable name** and `example.txt` as the **Value**.
       The variable is automatically prefixed with `env:`.
    6. Click **Run**.
  </Tab>
</Tabs>

## Source integrations

If your project is using a [source integration](/docs/integrations/source),
any new commits resulting from a source operation are first pushed to your external Git repository.
Then the source integration pushes those commits to Upsun Cloud and redeploys the environment.

When using a source integration,
you can't run source operations on environments created from pull or merge requests created on the external repository.

If you try running a source operation on a non-supported environment, you see the following error:

```text {no-copy="true"} theme={null}
[ApiFeatureMissingException]
This project doesn't support source operations.
```

## Automated source operations using a cron job

You can use a cron to automatically run your source operations.

Note that it’s best not to run source operations on your production environment,
but rather on a dedicated environment where you can test changes.

Make sure you have the [Upsun Cloud CLI](/cli) installed
and [an API token](/cli/api-tokens#2-create-an-api-token)
so you can run a cron job in your app container.

1. Set your API token as a top-level environment variable:

<Tabs>
  <Tab title="From the CLI">
    Run the following command:

    ```bash theme={null}
    upsun variable:create --environment main --level environment --prefix 'env' --name UPSUN_CLI_TOKEN --sensitive true --value 'YOUR_UPSUN_CLI_TOKEN' --inheritable false --visible-build true --json false --enabled true --visible-runtime true
    ```
  </Tab>

  <Tab title="From the Console">
    1. Open the environment where you want to add the variable.
    2. Click <SettingsIcon /> **Settings**.
    3. Click **Variables**.
    4. Click **+ Add variable**.
    5. In the **Variable name** field, enter `env:UPSUN_CLI_TOKEN`.
    6. In the **Value** field, enter your API token.
    7. Make sure the **Available at runtime** and **Sensitive variable** options are selected.
    8. Click **Add variable**.
  </Tab>
</Tabs>

<Warning>
  Once you add the API token as an environment variable,
  anyone with [SSH access](/docs/development/ssh) can read its value.
  Make sure you carefully check your [user access on this project](/docs/administration/users#manage-project-users).
</Warning>

2. Add a build hook to your app configuration to install the CLI as part of the build process:

```yaml .upsun/config.yaml theme={null}
applications:
  myapp:
    hooks:
      build: |
        set -e
        echo "Installing Upsun Cloud CLI"
        curl -fsSL https://raw.githubusercontent.com/upsun/cli/main/installer.sh | bash

        echo "Testing Upsun Cloud CLI"
        upsun
```

3. Then, to configure a cron job to automatically run a source operation once a day,
   use a configuration similar to the following:

The example above synchronizes the `development` environment with its parent
and then runs the `update-file` source operation defined [previously](#define-a-source-operation).

## Source operation examples

### Update your application dependencies

You can set up a source operation and a cron job to [automate your dependency updates](/docs/core-concepts/common-tasks/dependency-updates).

### Update a site from an upstream repository or template

The following source operation syncronizes your branch with an upstream Git repository.

1. [Add a project-level variable](/docs/development/variables/set-variables#create-project-variables)
   named `env:UPSTREAM_REMOTE` with the Git URL of the upstream repository.
   That makes that repository available as a Unix environment variable in all environments,
   including in the source operation's environment.

   * Variable name: `env:UPSTREAM_REMOTE`
   * Variable example value: `https://github.com/platformsh/platformsh-docs`

2. In your app configuration, define a source operation to fetch from that upstream repository:

3) Now every time you run the `upstream-update` operation on a given branch,
   the branch fetches all changes from the upstream git repository
   and then merges the latest changes from the default branch in the upstream repository.
   If there’s a conflict merging from the upstream repository,
   the source operation fails and doesn't update from the upstream repository.

Run the `upstream-update` operation on a preview environment rather than directly on Production.

### Revert to the last commit

The following source operation reverts the last commit pushed to the Git repository.
This can be useful if you didn't properly test the changes of another operation
and you need to quickly revert to the previous state.

Now every time you run the `revert` operation on a given branch,
the operation reverts to the last commit pushed to that branch.

### Update Drupal Core

The following source operation uses Composer to update Drupal Core:

`--with-dependencies` is used to also update Drupal Core dependencies.
Read more on how to [update Drupal Core via Composer on Drupal.org](https://www.drupal.org/docs/updating-drupal/updating-drupal-core-via-composer).

Now every time you run the `update-drupal-core` operation, it updates Drupal Core.

### Download a Drupal extension

The following source operation downloads a Drupal extension.
You can define the Drupal extension by setting an `EXTENSION` variable
or [overriding it](#use-variables-in-your-source-operations) when running the source operation.

Now every time you run the `download-drupal-extension` operation, it downloads the defined extension.

If it's a new extension, after the source operation finishes,
you need to enable the new extension via the Drupal management interface or using Drush.

### Update Git submodules

The following source operation updates all Git submodules recursively:

Now every time you run the `rebuild` operation, it updates the Git submodules.


# Configure tasks to run on-demand workloads and AI agents
Source: https://developer.upsun.com/docs/configure-apps/tasks

Run on-demand workloads like AI agents and batch jobs alongside your apps and services, triggered from the Console or through the API.

A **task** is an on-demand, run-to-completion workload defined alongside your applications and services in `.upsun/config.yaml`.
When triggered, a task container is injected into your environment's cluster, runs a single command, and is removed when the command exits.

## When to use a task

A task is the right choice when you need:

* **A background AI agent session** — for example, an agent that reads your codebase, calls tools such as shell commands or database queries, and writes the results back to your project.
* **A one-time job that needs service access:** database maintenance, a data export, a report.
* **A batch job triggered from your application** rather than on a schedule.

For a working example, see the [Upsun Cloud performance agent](/docs/get-started/ai/upsun-cloud-performance-agent), which runs as a task to analyze observability data and generate a report.

A task is *not* the right choice for:

* **A long-running daemon**: use a [worker](/docs/configure-apps/image-properties/workers#workers).
* **A scheduled job**: use a [cron](/docs/configure-apps/image-properties/crons).
* **Serving HTTP traffic**: tasks are not routable and cannot be used as an upstream in `routes:`.

## How tasks compare to other workloads

| | Application | Worker | Cron | Task |
| :- | :- | :- | :- | :- |
| Lifecycle | Always running | Always running | Scheduled, run-to-completion | On-demand, run-to-completion |
| HTTP exposure | Yes | No | No | No |
| Has its own image/build | Yes | No (shares app slug) | No (shares app slug) | Yes |
| Triggered by | Deploy | Deploy | Schedule | API call |
| Blocks deployments | N/A | N/A | Cancelled on deploy | Cancelled on deploy |

## Define a task

Tasks are declared at the top level of `.upsun/config.yaml`, alongside `applications:` and `services:`.

### Required fields

| Field | Description |
| :- | :- |
| `type` | The runtime image; same syntax as an application and the `type` in the preceding example. |
| `run.command` | The command to execute. Runs to completion, not as a daemon. To run initialization steps that need service access, place them at the start of this command — for example: `node setup.js && node agent.js`. |

### Common optional fields

| Field | Description |
| :- | :- |
| [`source.root`](/docs/configure-apps/image-properties/source) | Subdirectory containing the task's code. Defaults to `/`. |
| `run.timeout` | Maximum duration in seconds. Defaults to `3600` (one hour); max value `86400` (one day). On timeout, the platform sends `SIGTERM`, then `SIGKILL` after a grace period. |
| [`authorizations`](/docs/configure-apps/image-properties/authorizations) | Declared on a **task**: API permissions granted to the task container at runtime. Declared on an **application**: grants the app permission to trigger tasks and call the environment API. |
| [`hooks.build`](/docs/configure-apps/image-properties/hooks) | Command run during the environment build phase, producing a slug reused across runs. |
| [`relationships`](/docs/configure-apps/image-properties/relationships) | Connections to services and applications in the same cluster. |
| [`mounts`](/docs/configure-apps/image-properties/mounts) | Writable directories. `instance` and `tmp` mounts are reset between runs; use a `storage` or `service` mount to persist data across runs. |
| [`variables`](/docs/configure-apps/image-properties/variables) | Environment variables defined in your config file. Only use this for non-sensitive values — set secrets such as passwords and API keys using the [API or CLI](/docs/development/variables/set-variables) to keep them out of version control, for example: `upsun variable:create --name MY_SECRET --sensitive 1`. |

### Fields that don't apply

[`web`](/docs/configure-apps/image-properties/web), [`workers`](/docs/configure-apps/image-properties/workers), and [`crons`](/docs/configure-apps/image-properties/crons) have no meaning for tasks. Tasks have no HTTP router, are not long-running, and are not scheduled.

## Relationships

A task can declare relationships to applications and services in the same environment:

Inside the task container, these relationships appear in `PLATFORM_RELATIONSHIPS` exactly as they do for applications.
The task can read from the database, write to the cache, and POST results back to the app over HTTP.

**Relationship direction is one-way.**
Applications and other tasks cannot declare a relationship *to* a task, because a task exists in the cluster only while a task is running.
If you need the app to receive results from a task, the task should push them to the app, for example by using the <code>app: "myapp:http"</code> relationship.

## Trigger a task

You can trigger a task from the Console, the Upsun Cloud CLI, or through the Upsun Cloud API.

### From the Console

1. Open your project or environment overview page.
2. Find the **Tasks** card, below **Apps & Services**.
3. Hover over the task you want to run to open its detail popover.
4. Click **Run task**, optionally provide runtime variables as JSON, and confirm.

The task's status changes to **Running**, then back to **Idle** when it completes.

### From the CLI

Run a task using `upsun task:run`:

```bash theme={null}
upsun task:run myagent
```

If you omit the task name, you're prompted to choose one interactively. This fails in non-interactive mode (for example, in a CI pipeline), so always pass the task name explicitly there.

To pass run-time variables, use `--variable` in the format `<type>:<name>=<value>` (repeatable):

```bash theme={null}
upsun task:run myagent --variable env:BATCH_SIZE=100 --variable env:TARGET=prod
```

By default, the command returns as soon as the task starts. Add `--wait` to block until it completes:

```bash theme={null}
upsun task:run myagent --wait
```

To see the tasks defined on an environment, run `upsun task:list` (alias: `upsun tasks`):

```bash theme={null}
upsun task:list
```

This lists each task's name, type, command, and timeout.

See the [Upsun Cloud CLI reference](/cli/reference) for the full list of commands and options.

### From the API

To trigger a task through the API, see the [task run endpoint reference](https://developer.upsun.com/api-reference/task/post-projects-environments-tasks-run):

```bash theme={null}
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  https://api.upsun.com/projects/{project}/environments/{env}/tasks/myagent/run
```

To pass run-time variables to the task, include a `variables` object in the request body:

```bash theme={null}
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"variables": {"env": {"BATCH_SIZE": "100", "TARGET": "prod"}}}' \
  https://api.upsun.com/projects/{project}/environments/{env}/tasks/myagent/run
```

`$TOKEN` is a short-lived access token obtained from your API token. See [Authentication](/api/rest/authentication) for the exchange process and [API tokens](/cli/api-tokens) for the steps to create one.

Each invocation creates an **activity** (the same mechanism used for deploys, backups, and crons) that gives you:

* A unique activity ID.
* Live status (`pending`, `in_progress`, `complete`, `cancelled`).
* Streamed logs through the existing activity logs endpoint.
* Cancellation through the `/cancel` endpoint on the activity.

## Trigger from application code

Declare which tasks the app is allowed to trigger using [**workload authorizations**](/docs/configure-apps/image-properties/authorizations) (the `authorizations` key), then request a short-lived token at runtime — no long-lived credentials required.

Steps 1–3 break down each part individually. For a complete implementation combining token retrieval, caching, and triggering, see [Sample implementation](#sample-implementation).

### 1. Declare the authorization

### 2. Request a token and trigger the task

```bash theme={null}
token=$(curl http://localhost:8200/oauth2/token -d grant_type=client_credentials | jq -r .access_token)

curl -X POST -H "Authorization: Bearer $token" \
  "https://api.upsun.com/projects/$PLATFORM_PROJECT/environments/$PLATFORM_BRANCH/tasks/myagent/run"
```

### 3. Cache the token

Token caching is highly recommended if your application triggers tasks repeatedly. Without token caching,
every trigger makes a round-trip to the auth proxy. Request a new token only when the current one is about to expire.

By default, tokens expire after 60 seconds. The `x-token-ttl` header extends the lifetime up to 900 seconds (15 minutes) — set it to match your expected time between task triggers. For example, if your app triggers a task every 5 minutes (300 seconds), set `x-token-ttl` to slightly more than the trigger interval to account for network delays.

### Sample implementation

The following examples combine steps 1–3 into a single helper that handles authorization declaration, token retrieval, caching, and task triggering.

<CodeGroup>
  ```python title="Python" theme={null}
  import os
  import time
  import requests

  _cache = {}

  def _get_token():
      if _cache.get("expires_at", 0) - 30 > time.time():
          return _cache["token"]
      r = requests.post("http://localhost:8200/oauth2/token",
                        data={"grant_type": "client_credentials"},
                        headers={"x-token-ttl": "900"})  # 60–900 seconds
      r.raise_for_status()
      data = r.json()
      _cache["token"] = data["access_token"]
      _cache["expires_at"] = time.time() + data.get("expires_in", 900)
      return _cache["token"]

  def trigger_task(task_name, variables=None):
      token = _get_token()
      project = os.environ["PLATFORM_PROJECT"]
      branch  = os.environ["PLATFORM_BRANCH"]
      r = requests.post(
          f"https://api.upsun.com/projects/{project}/environments/{branch}/tasks/{task_name}/run",
          headers={"Authorization": f"Bearer {token}"},
          json={"variables": variables} if variables else None,
      )
      r.raise_for_status()
      return r.json()

  # Example: pass run-time variables
  trigger_task("myagent", variables={"env": {"BATCH_SIZE": "100", "TARGET": "prod"}})
  ```

  ```javascript title="Node.js" theme={null}
  const cache = {};

  async function getToken() {
    if (cache.expiresAt - 30_000 > Date.now()) return cache.token;
    const res = await fetch('http://localhost:8200/oauth2/token', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded',
        'x-token-ttl': '900', // 60–900 seconds
      },
      body: 'grant_type=client_credentials',
    });
    const data = await res.json();
    cache.token = data.access_token;
    cache.expiresAt = Date.now() + (data.expires_in ?? 900) * 1000;
    return cache.token;
  }

  export async function triggerTask(taskName, variables = {}) {
    const token = await getToken();
    const { PLATFORM_PROJECT, PLATFORM_BRANCH } = process.env;
    const url = `https://api.upsun.com/projects/${PLATFORM_PROJECT}/environments/${PLATFORM_BRANCH}/tasks/${taskName}/run`;
    const hasVars = Object.keys(variables).length > 0;
    const res = await fetch(url, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${token}`,
        ...(hasVars ? { 'Content-Type': 'application/json' } : {}),
      },
      body: hasVars ? JSON.stringify({ variables }) : undefined,
    });
    return res.json();
  }

  // Example: pass run-time variables
  await triggerTask('myagent', { env: { BATCH_SIZE: '100', TARGET: 'prod' } });
  ```
</CodeGroup>

## Resources, variables, and access

Tasks follow the same model as applications:

* **Resources** (CPU, memory): configured by using `upsun resources:set` against the task name, or in the Console on the **Configure resources** page.
* **Billing**: Per-second for the duration of each run. CPU and memory cost the same as an application; see the [Upsun pricing page](https://upsun.com/pricing/) for rates. Usage is accounted for within the application's resources; there is no separate usage group for tasks on the billing page.
* **Variables and secrets**: configured with `upsun variable:create --level environment` or by using the API. Sensitive variables are injected as environment variables at run time.
* **Access**: standard project roles apply. Project admins and contributors can change task definitions, trigger tasks, and view runs.

## Security

Tasks run in the same Linux Containers (LXC) as applications, with the same namespace isolation, capability dropping (removing unnecessary Linux process privileges), seccomp profile, cgroup limits, and network isolation.
Cross-project isolation and relationship-based access control apply unchanged. For details, see the [Project isolation](/docs/security/project-isolation) topic.

For tasks that run untrusted code (for example, an LLM-driven agent), consider pairing with [bubblewrap](https://github.com/containers/bubblewrap) inside the task container to restrict filesystem access, environment variables, and syscalls visible to the agent process.

## Known limitations

* **Cancelled on deploy.** A running task receives `SIGTERM` before any deploy on the same environment, followed by `SIGKILL` after a grace period of a few seconds. Catch `SIGTERM`, persist state to a service, and exit cleanly. The caller is responsible for retrying.
* **Concurrency cap.** Multiple task runs can execute in parallel up to a default limit of 3. Further triggers queue behind running ones. During a [trial](/docs/glossary#trial), this limit is lower.
* **No task-to-task relationships.** Nothing can declare a relationship *to* a task. An app and a task can share a relationship to the same service or a network file mount.
* **Fresh filesystem every run.** `instance` and `tmp` mounts are reset between runs. Use a `storage` or `service` mount for files that must survive across runs.
* **Requires at least one application.** An Upsun Cloud project configuration requires at least one application container to run code, handle routing, and connect to managed services.


# Timezones
Source: https://developer.upsun.com/docs/configure-apps/timezone

Learn more about the different timezones on Upsun Cloud and when you can customize them.

On Upsun Cloud, there are several timezones you might want to keep in mind.
All timezones default to UTC time.
You can customize some of them, but in most cases,
it's best if you leave them in UTC
and store user data with an associated timezone instead.

The different timezones on Upsun Cloud are the following:

| Timezone | Description | Customizable |
| - | - | - |
| Container timezone | The timezone for all Upsun Cloud containers (UTC). | No |
| App runtime timezone | [Set an app runtime timezone](#set-an-app-runtime-timezone) if you want your app runtime to use a specific timezone instead of the container timezone.<br />The app runtime timezone only affects your app itself. | Yes |
| Cron timezone | [Set a cron timezone](#set-a-cron-timezone) if you want your crons to run in a specific timezone instead of the app runtime timezone (or instead of the container timezone if no app runtime timezone is set on your project). <br />The cron timezone only affects your cron jobs. | Yes |
| Log timezone | The timezone for all Upsun Cloud logs (UTC). | No |

<Note>
  Each Upsun Cloud project also has a **project timezone** that only affects [automated backups](/docs/environments/backup#automated-backups).
  By default, the project timezone is based on the [region](/docs/development/regions) where your project is hosted.
  You can [change it from the Console](/docs/projects/change-project-timezone) at any time.
</Note>

## Set an app runtime timezone

How you can set an app runtime timezone depends on your actual app runtime:

<Tabs>
  <Tab title="PHP">
    Add the following to your app configuration:

    ```yaml .upsun/config.yaml theme={null}
    applications:
      # The name of the app container. Must be unique within a project.
      myapp:
        # The location of the application's code.
        variables:
          php:
            "date.timezone": "Europe/Paris"
    ```
  </Tab>

  <Tab title="Node.js">
    Start the server with `env TZ='<TIMEZONE>' node server.js`.
  </Tab>

  <Tab title="Python">
    Start the server with `env TZ='<TIMEZONE>' python server.py`.
  </Tab>

  <Tab title="Java">
    Start the server with `env TZ='<TIMEZONE>' java -jar ...` OR set the Java virtual machine argument `user.timezone`.
    This Java virtual machine argument takes precedence over the environment variable TZ.
    For example, you can use the flag `-D` when running the application:
    `java -jar -D user.timezone=GMT` or `java -jar -D user.timezone="Asia/Kolkata"`
  </Tab>
</Tabs>

## Set a cron timezone

You can set a specific timezone for your crons so they don't run in your app runtime timezone (or container timezone if no app runtime timezone is set on your project).
To do so, [set the `timezone` top-level property](/docs/configure-apps/app-reference/single-runtime-image#primary-application-properties) in your app configuration.


# Set custom headers on static content
Source: https://developer.upsun.com/docs/configure-apps/web/custom-headers

Set custom headers for your static content such as custom content-types or limits to cross-origin usage.

When your app responds to dynamic requests, it can generate headers on the fly.
To set headers for static content, add them in [your `web` configuration](/docs/configure-apps/image-properties/web).

You might want to do so to add custom content-type headers, limit what other sites can embed your content,
or allow cross origin requests.

Say you want to limit most files to be embedded only on your site, but you want an exception for Markdown files.
And you want to serve both Markdown and [AAC](https://en.wikipedia.org/wiki/Advanced_Audio_Coding) files with the
correct content types to avoid
[MIME sniffing](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types#mime_sniffing).

Start by defining a header for files in general:

This sets the `X-Frame-Options` header to `SAMEORIGIN` for all static files.
Now your files can only be embedded within your site.

Now set up an exception for Markdown (`*.md`) using a [rule](/docs/configure-apps/image-properties/web#rules):

This rule sets an explicit content type for files that end in `.md`. Because specific rules override the general
heading configuration, Markdown files don't get the `X-Frame-Options` header set before.

<Info>
  <h4>Setting charset</h4>
  By default, [HTTP charset parameters](https://www.w3.org/International/articles/http-charset/index.en) are not sent to the response.
  If not set, modern browsers will detect `ISO-8859-1` and likely default to `windows-1252` as this has 32 more international characters.

  To set the HTTP charset parameters to your desired charset, you can add `; charset=UTF-8` in the `Content-Type` parameters.
</Info>

Now set a rule for AAC files.

This rule sets an explicit content type for files that end in `.aac`. It repeats the rule for `X-Frame-Options` because
the `headers` block here overrides the more general configuration.

So now you have three header configurations:

* `X-Frame-Options: SAMEORIGIN` **and** `Content-Type: audio/aac` for AAC files
* Only `Content-Type: text/markdown` for Markdown files
* Only `X-Frame-Options: SAMEORIGIN` for everything else

## Cross origin requests

To allow cross origin requests, add a `Access-Control-Allow-Origin` header to responses.
You can do so for specific origins or for all origins with a wildcard.

If you use the wildcard value, the headers are modified for each request in the following ways:

* The value of the `Access-Control-Allow-Origin` header is set to the value of the `Origin` request header.
* The `Vary` header is included with a value of `Origin`. See why in the [MDN web docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#access-control-allow-origin).

This is done so that credentialed requests can be supported.
They would otherwise fail CORS checks if the wildcard value is used.

## `Strict_Transport_Security` header

The `Strict_Transport_Security` header returns a value of `max-age=0`
unless you enable [HTTP Strict Transport Security (HSTS)](/docs/routes/https#enable-http-strict-transport-security-hsts)
in your [routes configuration](/docs/routes).

Note that once HSTS is enabled, configuration capabilities depend
on the [HSTS properties](/docs/routes/https#enable-http-strict-transport-security-hsts)
set in your routes configuration.
For example, the `max-age` value is set to `31536000` by Upsun Cloud and can't be customized.


# Configure what's served
Source: https://developer.upsun.com/docs/configure-apps/web/index



How you should configure your web server depends a lot on what you want to serve.
The following examples show how in specific scenarios you might define [your web server](/docs/configure-apps/image-properties/web).


# Create a basic PHP app with a front controller
Source: https://developer.upsun.com/docs/configure-apps/web/php-basic

Start with a basic PHP app with a front controller for dynamic requests.

To handle dynamic requests to your PHP app, you might want to use a [front controller](https://en.wikipedia.org/wiki/Front_controller).
The following example shows how for such an app you might start defining [your web server](/docs/configure-apps/image-properties/web).

## Define a document root

Start by defining your document root (where all your publicly visible pages are).

## Define a front controller

Define where all requests that don't match a file in the document root are sent.

In this case, `/index.php` acts as a front controller and handles dynamic requests.

Because it handles dynamic requests, you want to ensure that scripts are enabled
and responses aren't cached.

## Define rules

You might want to define specific rules for the location.
For example, you might want to allow all kinds of files except mp4 files.

## Set different rules for specific locations

You might want to set specific rules for specific locations.
For example, you might have files in your `/public/images` directory that are served at `/images`.
You could define a specific cache time for them and limit them to only static image files.

## Complete example


# Rewrite requests without redirects
Source: https://developer.upsun.com/docs/configure-apps/web/rewrite-requests

Rewrite requests to be served by other parts of your app without directing users.

You might want to rewrite requests so they're served by specific sections of your app
without having to redirect users.
For example, you might want to make URLs seem semantic to users without having to rewrite your app architecture.

In such a case, you might want requests to `/shoes/great-shoe/` to be served
as if they were requests to `/?category=shoes&product=great-shoe`.
If so, add a [rule](/docs/configure-apps/image-properties/web#rules) similar to the following:

```yaml .upsun/config.yaml theme={null}
applications:
  myapp:
    source:
      root: "/"
    web:
      locations:
        '/':
          ...
          rules:
            '^/(?<category>[^/]+)/(?<product>[^/]+)/$':
              passthru: '/?category=$category&product=$product'
```

Or you might organize your images by file type, but don't want to expose the organization externally.
You could rewrite requests to do that behind the scenes:

```yaml .upsun/config.yaml theme={null}
applications:
  myapp:
    source:
      root: "/"
    web:
      locations:
        '/':
          ...
          rules:
            '^/img/(?<name>.*)\.(?<type>.*)$':
              passthru: '/$type/$name.$type'
```

Now a request to `/img/image.png` returns the file found at `/png/image.png`.

## Query parameters

Query parameters in the request are untouched by rules and will be passed to the app.
For example, if you have the category and product rule from previously, a request to `/shoes/great-shoe/?product=terrible-shoe`
is rewritten to `?category=shoes&product=great-shoe&product=terrible-shoe`.
In that case, the `product` query parameter sent to the app will contain the value `terrible-shoe`.


# Serve directories at different paths
Source: https://developer.upsun.com/docs/configure-apps/web/serve-different-directories

Serve directories at different places than where they are in your app.

In some cases you might want to depart from the common practice of serving directories directly.
You might want to create a URL structure different than the structure on your disk.

For example, in Git you might have a folder for your app and another folder that builds your documentation.
Your entire Git repository might look like the following:

```text {no-copy="true"} theme={null}
.upsun/
    config.yaml
application/
    [app-code-files]
docs-src/
    [docs-code-files]
```

And your build process might build the documentation with an output folder such as `docs-public`.

If so, you can serve all requests by your app code except for those that start with `/docs`,
which you serve with your generated docs.
Use a [`web` configuration](/docs/configure-apps/image-properties/web) similar to the following:

```yaml .upsun/config.yaml theme={null}
applications:
  docs:
    source:
      root: "/"
      web:
        locations:
          '/':
            passthru: true
          '/docs':
            root: 'docs-public'
            index:
              - "index.html"
            expires: 24h
            scripts: false
            allow: true
```

This way, your app can safely coexist with static files as if it were a single site hierarchy.
And you can keep the static pages separate from your app code.


# Serve static sites
Source: https://developer.upsun.com/docs/configure-apps/web/static

Serve completely static sites

Static site generators are a popular way to create fast sites.
Because there's no need to wait for responses from servers, the sites may load faster.

To learn how to serve your static site using Upsun Cloud,
you can start with the required [minimal app configuration](#minimal-app-configuration) and build on it,
or jump straight to an [example of a complete configuration](#complete-example-configuration).

## Minimal app configuration

To successfully serve a static site using Upsun Cloud,
you need to set up a minimal app configuration similar to the following:

See more information on the required minimal settings:

* [Top-level properties](/docs/configure-apps/app-reference/single-runtime-image#primary-application-properties).
* [`web` property](/docs/configure-apps/image-properties/web).
* [`locations` properties](/docs/configure-apps/image-properties/web#locations).

## Add more features

### Allow static files but not dynamic files on PHP containers

If you have a PHP container,
you might want to enable client-side scripts but disable server-side scripts.

To enable static files that don't match any rule while disabling server-side scripts on a PHP container,
use the following configuration:

See more information on [`locations` properties](/docs/configure-apps/image-properties/web#locations).

### Create cache rules

You can create sensible cache rules to improve performance.
For example, if you publish new content regularly without updating images or site files much,
you might want to cache text files for a day but all image files for longer.

To do so, use a configuration similar to the following:

You can also set a `Cache-Control` header in your rules.

If `expires` and a `Cache-Control` header are set, the rule ignores the `expires` and sets only the `Cache-Control` header. For this reason, make sure
to add a `max-age` value, in seconds, for the `Cache-Control` header.

### Conserve the server

Because your site is completely static, it doesn't need the server to be running.
To set a background process that blocks the server and conserves resources,
use the following configuration:

You can also use this place to start small programs,
such as a [script to handle 404 errors](https://support.platform.sh/hc/en-us/community/posts/16439636723474).

## Complete example configuration


# Work with workers
Source: https://developer.upsun.com/docs/configure-apps/workers

Interact with your worker instances to handle background tasks for your apps.

Workers are instances of your code that aren't open to connections from other apps or services or the outside world.
They're good for handling background tasks.
See how to [configure a worker](/docs/configure-apps/image-properties/workers) for your app.

## Access the worker container

Like with any other application container,
Upsun Cloud allows you to connect to the worker instance through SSH to inspect logs and interact with it.

Use the `--worker` switch in the Upsun Cloud CLI, like so:

```bash theme={null}
upsun ssh --worker=queue
```

## Stopping a worker

If a worker instance needs to be updated during a new deployment,
a `SIGTERM` signal is first sent to the worker process to allow it to shut down gracefully.
If your worker process can't be interrupted mid-task, make sure it reacts to `SIGTERM` to pause its work gracefully.

If the process is still running after 15 seconds, a `SIGKILL` message is sent that force-terminates the worker process,
allowing the container to be shut down and restarted.

To restart a worker manually, [access the container](#access-the-worker-container) and run the following commands:

```bash theme={null}
sv stop app
sv start app
```

## Workers vs cron jobs

Worker instances don't run cron jobs.
Instead, both worker instances and cron tasks address similar use cases.
They both address out-of-band work that an application needs to do
but that shouldn't or can't be done as part of a normal web request.
They do so in different ways and so are fit for different use cases.

A cron job is well suited for tasks when:

* They need to happen on a fixed schedule, not continually.
* The task itself isn't especially long, as a running cron job blocks a new deployment.
* It's long but can be divided into many small queued tasks.
* A delay between when a task is registered and when it actually happens is acceptable.

A dedicated worker instance is a better fit if:

* Tasks should happen "now", but not block a web request.
* Tasks are large enough that they risk blocking a deploy, even if they're subdivided.
* The task in question is a continually running process rather than a stream of discrete units of work.

The appropriateness of one approach over the other also varies by language;
single-threaded languages would benefit more from either cron or workers than a language with native multi-threading, for instance.
If a given task seems like it would run equally well as a worker or as a cron,
cron is generally more efficient as it doesn't require its own container.

## Commands

The `commands` key defines the command to launch the worker application.
For now there is only a single command, `start`, but more will be added in the future.
The `commands.start` property is required.

The `start` key specifies the command to use to launch your worker application.
It may be any valid shell command, although most often it runs a command in your application in the language of your application.
If the command specified by the `start` key terminates, it's restarted automatically.

Note that [`deploy` and `post_deploy` hooks](/docs/configure-apps/hooks) as well as [`cron` commands](/docs/configure-apps/image-properties/crons)
run only on the [`web`](/docs/configure-apps/image-properties/web) container, not on workers.

## Inheritance

Workers inherit and can override several primary application properties, including `access`, `authorizations`, `mounts`, and `relationships`.
For a complete list, refer to the **Set in instance** column of the **Primary applicaton properties** table
in the [single-runtime](/docs/configure-apps/app-reference/single-runtime-image#primary-application-properties)
and [composable image](/docs/configure-apps/app-reference/composable-image#primary-application-properties) topics.

Likewise [resources defined for the application container](/docs/manage-resources) are inherited by every worker, unless overridden explicitly.

That means, for example, that the following two `.upsun/config.yaml` definitions produce identical workers.

In both cases, there are two worker instances named `queue` and `mail`.
Both have access to a MySQL/MariaDB service defined in `.upsun/config.yaml`,
through a [relationship](/docs/configure-apps/image-properties/relationships) that is identical to the *name* of that service (`mysql`).
Both also have their own separate [`storage` mount](/docs/configure-apps/image-properties/mounts).

## Customizing a worker

The most common properties to set in a worker to override the top-level settings are `variables` and its resources.
`variables` lets you instruct the application to run differently as a worker than as a web site,
whereas you can allocate [fewer worker-specific resources](/docs/manage-resources) for a container that is running only a single background process
(unlike the web site which is handling many requests at once).

For example, consider the following configuration:

There's a lot going on here, but it's all reasonably straightforward.
The configuration in `.upsun/config.yaml` takes a single Python 3.14 code base from your repository,
downloads all dependencies in `requirements.txt`, and then installs Gunicorn.
That artifact (your code plus the downloaded dependencies) is deployed as three separate container instances, all running Python 3.14.

The `web` instance starts a Gunicorn process to serve a web application.

* It runs the Gunicorn process to serve web requests, defined by the `project/wsgi.py` file which contains an `application` definition.
* It has an environment variable named `TYPE` with value `web`.
* It has a writable mount at `/app/uploads`.
* It has access to both a MySQL database and a RabbitMQ server, both of which are defined in `.upsun/config.yaml`.

The `queue` instance is a worker that isn't web-accessible.

* It runs the `queue-worker.py` script, and restart it automatically if it ever terminates.
* It has an environment variable named `TYPE` with value `worker`.
* It has a writable mount at `/app/scratch`.
* It has access to both a MySQL database and a RabbitMQ server,
  both of which are defined in `.upsun/config.yaml` (because it doesn't specify otherwise).

The `mail` instance is a worker that isn't web-accessible.

* It runs the `mail-worker.py` script, and restart it automatically if it ever terminates.
* It has an environment variable named `TYPE` with value `worker`.
* It has no writable file mounts at all.
* It has access only to the RabbitMQ server, through a different relationship name than on the `web` instance.
  It has no access to MySQL.

<Note>
  Upsun Cloud automatically allocates [default resources](/docs/manage-resources/resource-init) to each instance,
  unless you [define a different resource initialization strategy](/docs/manage-resources/resource-init#specify-a-resource-initialization-strategy).
  You can also [adjust resources](/docs/manage-resources/adjust-resources) after your project has been deployed.
</Note>

For example, if you want the `web` instance to have a large upload space
and the `queue` instance to have a small amount of scratch space for temporary files,
you can allocate more CPU and RAM to the `web` instance than to the `queue` instance.

The `mail` instance has no persistent writable disk space at all, as it doesn't need it.
The `mail` instance also doesn't need any access to the SQL database, so for security reasons it has none.

Each instance can also check the `TYPE` environment variable to detect how it's running
and, if appropriate, adjust its behavior accordingly.

## Mounts

When defining a [worker](/docs/configure-apps/image-properties/workers) instance,
keep in mind what mount behavior you want.

`tmp` and `instance` local mounts are a separate storage area for each instance,
while `storage` mounts can be shared between instances.

For example, you can define a `storage` mount (called `shared_dir`) to be used by a `web` instance,
and a `tmp` mount (called `local_dir`) to be used by a `queue` worker instance:

Both the `web` instance and `queue` worker have their own, dedicated `local_dir` mount.
Note that:

* Each `local_dir` mount is a [`tmp` mount](/docs/configure-apps/image-properties/mounts) with a **maximum allocation of 8 GB**.<br />
* `tmp` mounts **may be removed** during infrastructure maintenance operations.

Both the `web` instance and `queue` worker also have a `shared_dir` mount pointing to the same network storage space.
They can both read and write to it simultaneously.


# Keep your Git repository clean
Source: https://developer.upsun.com/docs/core-concepts/best-practices/clean-repository

To avoid performance issues, prevent your Git repository from becoming too large.

When a Git repository contains a high number of references and files, the performance of Git can decrease.
This is why most Git providers have repository size limits in place (for more information, see the [GitHub](https://docs.github.com/en/repositories/working-with-files/managing-large-files/about-large-files-on-github), [GitLab](https://docs.gitlab.com/ee/user/gitlab_com/index.html#account-and-limit-settings)
and [Bitbucket](https://support.atlassian.com/bitbucket-cloud/docs/reduce-repository-size/) documentation).

The Upsun Cloud API and [Console](/docs/administration/web) are closely tied to Git.
When the performance of Git decreases, Upsun Cloud API servers also become slower.
As a user, you can then experience significant latencies.
If your repository becomes too large, your Console may even become unresponsive,
leaving you unable to access your project.

To avoid such issues, make sure you keep your Git repository clean by following the instructions on this page.

If you're already facing performance issues and suspect they might be related to the size of your Git repository,
see how you can [troubleshoot a sizeable Git repository](#troubleshoot-a-sizeable-git-repository).

## Enable the automated pruning of old branches in your project

To keep your repository size to a minimum,
make sure that branches that don't exist anymore in your repository have also been deleted from Upsun Cloud.

To automate this process, when setting up a [source integration](/docs/integrations),
enable the `prune-branches` option.

If you already have a source integration set up and want to enable the `prune-branches` option,
follow these steps:

<Tabs>
  <Tab title="Using the CLI">
    1. To enable the `prune-branches` option, you must first enable the `fetch-branches` option.
       To do so, run the following command:

       ```bash theme={null}
       upsun integration:update --project <PROJECT_ID> <SOURCE_INTEGRATION_ID> --fetch-branches true
       ```

    2. Then, to enable the `prune-branches` option, run the following command:

       ```bash theme={null}
       upsun integration:update --project <PROJECT_ID> <SOURCE_INTEGRATION_ID> --prune-branches true
       ```
  </Tab>

  <Tab title="In the Console">
    1. Navigate to your project.
    2. Click <SettingsIcon /> **Settings**.
    3. Click **Project Settings**.
    4. Click **Integrations** and select your source integration.
    5. Click **Edit**.
    6. Enter your access token and click **Continue**.
    7. Select your repository and check the following boxes:
       * **Fetch branches from the remote repository to your project** (`fetch-branches` option, mandatory to enable `prune-branches`).
       * **Remove branches from your project that have disappeared remotely (requires the fetch branches option to be enabled)** (`prune-branches` option).
    8. Click **Save**.
  </Tab>
</Tabs>

## Upload your files through mounts

Keeping too many files, especially large binary files, in your Git repository can cause performance and stability issues.
Therefore, Upsun recommends that you only commit your source code in Git.

To upload any other files to your app, [create mounts](/docs/configure-apps/image-properties/mounts)
and [transfer your files directly to them](/docs/development/file-transfer#transfer-a-file-to-a-mount).

<Warning>
  Upsun Cloud does not currently support [Git Large File Storage](https://git-lfs.com/).

  There is a **100MB default file size limit** for direct Git pushes to Upsun Cloud. Pushing files larger than the limit will result in rejecting the push, so please keep this in mind. If you'd like to request a custom limit, please [contact Support](/docs/core-concepts/get-support).
</Warning>

## Troubleshoot a sizeable Git repository

If you're experiencing latencies or can't access your Console anymore,
your Git repository may have become too large and may need to be cleaned up.
To do so, follow these instructions:

1. Remove old, unwanted files from your repository (especially large files).
   You can do it manually, or use a tool such as [BFG Repo-Cleaner](https://rtyley.github.io/bfg-repo-cleaner/).
2. Remove stale branches from your repository and Upsun Cloud project.
3. Rebase and/or squash commits to clean up your history.
4. Make sure you [enable the automated pruning of old branches in your project](#enable-the-automated-pruning-of-old-branches-in-your-project)
   and [upload your files through mounts](#upload-your-files-through-mounts) to avoid facing the same situation in the future.


# HTTP caching
Source: https://developer.upsun.com/docs/core-concepts/best-practices/http-caching

See your options for HTTP caching with Upsun Cloud.

You can configure HTTP caching for your site on Upsun Cloud in several ways.
Which one you should use depends on your specific use case.

You should use only one of these at a time and disable any others.
Mixing them together most likely results in stale cache that can't be cleared.

## The Upsun Cloud router cache

Every project includes a router instance that includes [optional HTTP caching](/docs/routes/cache).
It's reasonably configurable and obeys HTTP cache directives, but doesn't support push-based clearing.

If you're uncertain what caching tool to use, start with this one.
It's enough for most uses.

## A Content Delivery Network (CDN)

Upsun Cloud is compatible with most commercial CDNs.

CDNs generally offer the best performance as they're the only option that includes multiple geographic locations.
But they do tend to be the most expensive option.

See more on setting up [Fastly](/docs/domains/cdn/fastly) and [Cloudflare](/docs/domains/cdn/cloudflare).
The methods for other CDNs are similar.

## Varnish

Upsun Cloud offers a [Varnish service](/docs/add-services/varnish) that you can insert between the router and your app.

It has roughly the same performance as the router cache.
Varnish is more configurable, but it requires you to be comfortable with Varnish Configuration Language (VCL).
Upsun Cloud doesn't help with VCL configuration and a misconfiguration may be difficult to debug.

Varnish supports [clearing cache with a push](/docs/add-services/varnish#clear-cache-with-a-push),
but access control is complicated by the inability to have [circular relationships](/docs/add-services/varnish#circular-relationships).

Generally speaking, you should use Varnish only if your application requires push-based clearing or relies on Varnish-specific business logic.

## App-specific caching

Many web apps and frameworks include a built-in web cache layer that mimics what Varnish or the Router cache would do.
Most of the time they're slower than a dedicated caching service as they still require invoking the app server
and only serve as a fallback for users that don't have a dedicated caching service available.
Generally speaking, use app-specific web cache only when it includes app-specific business logic you depend on,
such as app-sensitive selective cache clearing or partial page caching.

Note that this refers only to HTTP caching.
Many apps have an internal app cache for data objects and similar information.
That should remain active regardless of the HTTP cache in use.

## Cookies and caching

HTTP-based caching systems generally default to including cookie values in cache keys
to avoid serving authenticated content to the wrong user.
While this is a safe default, it means that *any* cookie effectively disables the cache,
including mundane cookies like analytics.

The solution is to set which cookies should impact the cache and limit them to session cookies.
For the router cache, see [cookies in HTTP caching](/docs/routes/cache#cookies).
For other cache systems, consult their documentation.


# Using Upsun Cloud Effectively
Source: https://developer.upsun.com/docs/core-concepts/best-practices/index

Here are some tips for getting the most out of Upsun Cloud's many features.

<CardGroup>
  <Card title="HTTP caching" icon="bolt" href="/docs/core-concepts/best-practices/http-caching">
    See your options for HTTP caching with Upsun Cloud.
  </Card>

  <Card title="From monoliths to microservices" icon="blocks" href="/docs/core-concepts/best-practices/oneormany">
    Choose the best app topology depending on your needs.
  </Card>

  <Card title="Keep your repository clean" icon="trash-2" href="/docs/core-concepts/best-practices/clean-repository">
    Prevent your Git repository from becoming too large to avoid performance issues.
  </Card>
</CardGroup>


# From monoliths through headless to microservices
Source: https://developer.upsun.com/docs/core-concepts/best-practices/oneormany

Choose the best app topology depending on your needs.

With Upsun Cloud, you can run multiple application containers in a single environment.
This gives you access to a large variety of setups and allows you to seamlessly upgrade your app
from a monolith with a single application server to a more elaborate and effective topology.

You can set up multiple apps to achieve the following:

* Keep your backend and frontend systems separate
* Run workers alongside your main app
* Or even go for a full microservices architecture

Upsun Cloud makes implementing such setups and switching from one to the other pain-free.

The same flexibility applies to any supported services, from relational databases to search engines and message queues.
Depending on your specific use case, you can run a single database,
multiple databases inside a single instance, or multiple databases in multiple versions...
It's up to you!

Whether you embrace a mono-repo approach with a single Git repository describing your entire setup,
or divide your project into multiple repositories, Upsun Cloud allows you to build the best architecture for your needs.

But while the possibilities are endless, making the right choice between creating one big project with multiple apps
or keeping each app in its own project can be a tough formula to crack.
So read on for guidance!

## Separate projects

If you have multiple apps sharing the same code but each of them has its own data,
keep your apps in separate projects.
Upsun Cloud provides the automation to deploy multiple projects from the same code base,
which makes their maintenance effortless.

<Note>
  By design, Upsun Cloud doesn't allow your app to access services in another project through HTTP.
</Note>

So separate projects are appropriate in the following cases:

* Your apps are for different customers/clients
* Your apps don't need to directly connect to the same database
* Different teams are working on different apps
* You want to develop true microservices, where each microservice is a fully standalone process with its own data

When in doubt over your own needs,
it's better to keep separate projects than build an architecture that may prove difficult for you to maintain.

## Clustered applications

A clustered application is one where your project requires multiple *app services* that are all part of the same conceptual project.

Clustered applications can range from a straightforward headless architecture, where frontend and backend systems are separated,
to micro-services with dozens of apps in multiple runtimes and frameworks forming a consistent whole.
Meaning, removing one of the app services would break the others.

Upsun Cloud allows you to configure access from one service to another
without having to worry about service discovery or complex *ingress controllers*.
[Configuring incoming routes](/docs/routes) is straightforward.
You can have services that are only exposed to another service as well as services that are exposed to the internet.

In a clustered application, you can have one of the following configurations:

* Multiple [applications](/docs/configure-apps/multi-app), often in different directories or with separate code bases that deploy separately
* A single app that spawns one or more [worker instances](/docs/configure-apps/image-properties/workers) that run background processes

With a clustered application, you often don't need multiple service instances.
The [MySQL, MariaDB](/docs/add-services/mysql),
and [Solr](/docs/add-services/solr) services support defining multiple databases on a single service,
which is significantly more efficient than defining multiple services.
[Redis](/docs/add-services/redis), [Memcached](/docs/add-services/memcached),
[Elasticsearch](/docs/add-services/elasticsearch), and [RabbitMQ](/docs/add-services/rabbitmq)
natively support multiple bins (also called *queues* or *indexes*) defined by the client application as part of the request.
Therefore, they don't need additional configuration on Upsun Cloud.

Clustered applications are appropriate in the following cases:

* You want one user-facing app and an entirely separate admin-facing app that are both operating on the same data
* You want to have a user-facing app and a separate worker process (either the same code or separate) that handles background tasks
* You want a single conceptual app written in multiple programming languages

## A note on "multi-site" applications

Some Content Management Systems or other applications support running multiple logical "sites" off of a single code base.
This approach isn't recommended on Upsun Cloud.

This multi-site logic is often dependent on the domain name of the incoming request, which on Upsun Cloud varies by branch.
Running multiple databases, as is often recommended with this approach,
is supported on Upsun Cloud but makes the setup process for each site more difficult.

Leveraging the multi-site capabilities of an app are appropriate only in the following cases:

* There is only a single team working on all of the "sites" involved
* All "sites" should be updated simultaneously as a single unit
* Each individual site is relatively low traffic. This means that the total traffic for all sites is appropriate for the resources that have been allocated.
  [allocated resources](/docs/manage-resources)
* All sites really do use the same codebase with no variation, just different data

Otherwise, [separate projects](#separate-projects) are a better long-term plan.


# Build and deploy
Source: https://developer.upsun.com/docs/core-concepts/build-deploy

See how applications get built and deployed with Upsun Cloud.

Each time you push a change to your app through Git or activate an [environment](/docs/environments),
your app goes through a process to be built and deployed.
If your app is redeployed with no changes to its codebase, the output of the previous build and deploy process is reused.

The build process looks through the configuration files in your repository and assembles the necessary containers.
The deploy process makes those containers live, replacing any previous versions, with minimal interruption in service.

<div>
  ```mermaid theme={null}
  ---
  config:
    theme: base
    themeVariables:
      primaryColor: '#F7F8F8'
      primaryTextColor: '#0E1113'
      primaryBorderColor: '#6046FF'
      lineColor: '#6046FF'
      secondaryColor: '#F7F8F8'
      tertiaryColor: '#F7F8F8'
      background: 'transparent'
      mainBkg: '#F7F8F8'
      nodeBorder: '#6046FF'
      nodeTextColor: '#0E1113'
      clusterBkg: '#FFFFFF'
      clusterBorder: '#6046FF'
      titleColor: '#0E1113'
      edgeLabelBackground: 'transparent'
      transitionColor: '#6046FF'
    look: neo
    fontSize: 18
  ---
  stateDiagram
    direction LR
    state Build {
      direction TB
      GitPush --> ValidateConfig
      ValidateConfig --> PullImage
      PullImage --> InstallDeps
      InstallDeps --> BuildFlavor
      BuildFlavor --> BuildHook
      BuildHook --> FreezeContainer
      GitPush
      ValidateConfig
      PullImage
      InstallDeps
      BuildFlavor
      BuildHook
      FreezeContainer
    }
    state Deploy {
      direction TB
      HoldRequests --> UnmountContainers
      UnmountContainers --> MountFS
      MountFS --> ExposeServices
      ExposeServices --> StartCommand
      StartCommand --> DeployHook
      DeployHook --> ServeRequests
      HoldRequests
      UnmountContainers
      MountFS
      ExposeServices
      StartCommand
      DeployHook
      ServeRequests
    }
    Build --> Deploy
    Build:BUILD PHASE
    GitPush:Git push or activation
    ValidateConfig:Validate configuration
    PullImage:Pull container image
    InstallDeps:Install dependencies
    BuildFlavor:Run build flavor commands
    BuildHook:Run build hook
    FreezeContainer:Freeze app container
    Deploy:DEPLOY PHASE
    HoldRequests:Hold requests
    UnmountContainers:Unmount current containers
    MountFS:Mount file systems
    ExposeServices:Expose services
    StartCommand:Run start command
    DeployHook:Run deploy hook
    ServeRequests:Serve requests

    style Build fill:#FFFFFF,stroke:#6046FF
    style Deploy fill:#FFFFFF,stroke:#6046FF
  ```
</div>

<div>
  ```mermaid theme={null}
  ---
  config:
    theme: base
    themeVariables:
      primaryColor: '#2B3134'
      primaryTextColor: '#FFFFFF'
      primaryBorderColor: '#BFB5FF'
      lineColor: '#BFB5FF'
      secondaryColor: '#2B3134'
      tertiaryColor: '#2B3134'
      background: 'transparent'
      mainBkg: '#2B3134'
      nodeBorder: '#BFB5FF'
      nodeTextColor: '#FFFFFF'
      clusterBkg: '#191C1E'
      clusterBorder: '#BFB5FF'
      titleColor: '#BFB5FF'
      edgeLabelBackground: 'transparent'
      transitionColor: '#BFB5FF'
    look: neo
    fontSize: 18
  ---
  stateDiagram
    direction LR
    state Build {
      direction TB
      GitPush --> ValidateConfig
      ValidateConfig --> PullImage
      PullImage --> InstallDeps
      InstallDeps --> BuildFlavor
      BuildFlavor --> BuildHook
      BuildHook --> FreezeContainer
      GitPush
      ValidateConfig
      PullImage
      InstallDeps
      BuildFlavor
      BuildHook
      FreezeContainer
    }
    state Deploy {
      direction TB
      HoldRequests --> UnmountContainers
      UnmountContainers --> MountFS
      MountFS --> ExposeServices
      ExposeServices --> StartCommand
      StartCommand --> DeployHook
      DeployHook --> ServeRequests
      HoldRequests
      UnmountContainers
      MountFS
      ExposeServices
      StartCommand
      DeployHook
      ServeRequests
    }
    Build --> Deploy
    Build:BUILD PHASE
    GitPush:Git push or activation
    ValidateConfig:Validate configuration
    PullImage:Pull container image
    InstallDeps:Install dependencies
    BuildFlavor:Run build flavor commands
    BuildHook:Run build hook
    FreezeContainer:Freeze app container
    Deploy:DEPLOY PHASE
    HoldRequests:Hold requests
    UnmountContainers:Unmount current containers
    MountFS:Mount file systems
    ExposeServices:Expose services
    StartCommand:Run start command
    DeployHook:Run deploy hook
    ServeRequests:Serve requests

    style Build fill:#191C1E,stroke:#BFB5FF
    style Deploy fill:#191C1E,stroke:#BFB5FF
  ```
</div>

Hooks are points in the build and deploy process where you can inject a custom script.

## The build

The outcome of the build process is designed to be repeatable and reusable.
Each app in a project is built separately.

Container configuration depends exclusively on your configuration files.
So each container is tied to a specific Git commit.
If there are no new changes for a given container, the existing container can be reused.
This saves you the time the build step would take.

This means the build is independent of the given environment and preview environments are perfect copies of production.
If you use environment variables to set up different build configuration options for different environments,
your build step isn't reused and your preview environments may differ from production.

You can't connect to services (like databases) during the build step.
Once the app has gone through all of the build steps, it can connect to services in the deploy process.

### Build steps

<Steps>
  <Step title="Validate configuration">
    The configuration is checked by validating the `.upsun/` directory and scanning the repository for any app configuration to validate.
  </Step>

  <Step title="Pull container images">
    Any container images that have been built before and that don't have any changes are pulled to be reused.
  </Step>

  <Step title="Install dependencies">
    If you have specified additional global dependencies, they're downloaded during this step.
    This is useful for commands you may need in the build hook.
  </Step>

  <Step title="Run build flavor commands">
    For some languages (NodeJS, PHP), a series of standard commands are run based on the build flavor.
    You can change the flavor or skip the commands by specifying it in your `.upsun/config.yaml` file.
  </Step>

  <Step title="Run build hook">
    The `build` hook comprises one or more shell commands that you write to finish creating your production code base: for example, compiling Sass files, running a bundler, rearranging files on disk, or compiling.
    The committed build hook runs in the build container.
    During this time, commands have write access to the file system, but there aren't connections to other containers (services and other apps).

    For automated builds, you can use the [`CI` environment variable](/docs/development/variables/use-variables#use-provided-variables) in build scripts and tooling to modify build behavior (for example, to disable attempts to connect to other containers during the build phase, or to disable interactivity). These modifications can help to prevent build failures.

    You can also manually [cancel deployments stuck on the build hook](/docs/environments/cancel-activity).
  </Step>

  <Step title="Freeze app container">
    The file system is frozen and produces a read-only container image, which is the final build artifact.
  </Step>
</Steps>

## The deploy

The deploy process connects each container from the build process and any services.
The connections are defined in your app and services configuration.

So unlike the build process, you can now access other containers,
but the file system is read-only.

### Deploy steps

<Steps>
  <Step title="Hold requests">
    Incoming [idempotent requests](https://www.iana.org/assignments/http-methods/http-methods.xhtml) (like `GET`, `PUT`, `DELETE` but **not** `POST`, `PATCH` etc.) are held.
  </Step>

  <Step title="Unmount current containers">
    Any previous containers are disconnected from their file system mounts.
  </Step>

  <Step title="Mount file systems">
    The file system is connected to the new containers.
    New branches have file systems cloned from their parent.
  </Step>

  <Step title="Expose services">
    Networking connections are opened between any containers specified in your app and services configurations.
  </Step>

  <Step title="Run (pre-) start commands">
    The [commands](/docs/configure-apps/image-properties/web#web-commands) necessary to start your app are run.
    Often this stage will only include a start command, which is restarted if ever terminated going forward.
    You may also, however, define a `pre_start` command, when you need to run *per-instance* actions.
    In this case, as you might expect, the `pre_start` command is run, then the `start` command.
  </Step>

  <Step title="Run deploy hook">
    The `deploy` hook is any number of shell commands you can run to finish your deployment.
    This can include clearing caches, running database migrations, and setting configuration that requires relationship information.
  </Step>

  <Step title="Serve requests">
    Incoming requests to your newly deployed application are allowed.
  </Step>
</Steps>

After the deploy process is over, any commands in your `post_deploy` hook are run.

## Deployment types

Upsun Cloud supports two deployment types - automatic and manual. These types help to provide control over when changes are applied to development, staging and production environments.

### Automatic deployment (default)

This is the default behavior for all environments. With automatic deployment, changes like code pushes and variable updates are deployed immediately. This type of deployment is best suited for rapid iteration during development.

### Manual deployment

You can deploy applications manually in any environment type (development/preview, staging, and production). When [enabled](#change-deployment-type), manual deployment lets you control when deployments happen: changes are staged but not deployed until you explicitly trigger a deployment. Manual deployment is ideal for teams that want to bundle multiple changes and deploy them together in a controlled manner.

When manual deployment is enabled in an environment, the following actions are queued until deployment is triggered:

| Category | Staged Activities |
| - | - |
| **Code** | `environment.push`, `environment.merge`, `environment.merge-pr` |
| **Variables** | `environment.variable.create`, `update`, `delete` |
| **Resources** | `environment.resources.update` |
| **Domains & Routes** | `environment.domain.*`, `environment.route.*` |
| **Subscription** | `environment.subscription.update ` |
| **Environment Settings** | `environment.update.http_access`, `smtp`, `restrict_robots` |

<Info>
  To restart your application without applying staged changes, run `upsun redeploy` or click **Redeploy** in the Console.
</Info>

### Change deployment type

You can adjust deployment behavior in your environment.

<Tabs>
  <Tab title="Using the CLI">
    Use the following command in the CLI to view or change the deployment type:

    ```bash theme={null}
    upsun environment:deploy:type
    ```

    The output should look similar to the example below:

    ```bash theme={null}
    Selected project: [my-project (ID)]
    Selected environment: main (type: production)
    Deployment type: manual
    ```
  </Tab>

  <Tab title="Using the Console">
    To switch to manual, navigate to the environment settings in the Console and select the manual deployments option.
  </Tab>
</Tabs>

### Trigger deployment manually

Once manual deployment is enabled, eligible changes are staged. You can deploy them in the following ways:

<Tabs>
  <Tab title="Using the CLI">
    Deploy staged changes to your chosen environment using the following command:

    ```bash theme={null}
    upsun environment:deploy
    ```

    The output should look similar to the example below:

    ```bash theme={null}
    Deploying staged changes:
    +---------------+---------------------------+-----------------------------------------------------------+---------+
    | ID            | Created                   | Description                                               | Result  |
    +---------------+---------------------------+-----------------------------------------------------------+---------+
    | 5uh3xwmkh5boq | 2026-01-01T14:01:10+00:00 | Patrick pushed to main                                    | failure |
    | fno2qiodq7e3c | 2026-01-01T13:06:18+00:00 | Arseni updated resource allocation on main                | success |
    | xzvcazrtoafeu | 2026-01-01T13:01:10+00:00 | Pilar added variable HELLO_WORLD to main                  | success |
    | fq73u53ruwloq | 2026-01-01T12:06:17+00:00 | Pilar pushed to main                                      | success |
    +---------------+---------------------------+-----------------------------------------------------------+---------+
    ```
  </Tab>

  <Tab title="Using the Console">
    In the Console, a deploy button will be visible in the environment whenever changes are staged. Click this button to deploy your staged changes.
  </Tab>

  <Tab title="Using the API">
    Trigger the deployment of staged changes with the following:

    ```bash theme={null}
    POST /projects/{projectId}/environments/{environmentId}/deploy
    ```
  </Tab>
</Tabs>

<Tip>
  As soon as your deployment type is switched from manual to automatic, all currently staged changes are deployed immediately and the environment resumes its default automatic deployment behavior.
</Tip>

## Maintenance window

A maintenance window is a recurring time slot when Upsun Cloud applies patch updates to your services' container images, such as bug and security fixes, keeping them up to date on a predictable schedule.

Some of these updates can cause brief downtime. Instead of Upsun Cloud running them at any time, you choose when they happen (for example, at a time that works best for your application and users). You set how often the window repeats (every 2 or 4 weeks), the day, and the time.

You configure one maintenance window per project. Upsun Cloud may still apply urgent or critical fixes outside of the project's maintenance window.

### Maintenance windows and zero-downtime deployments

[Zero-downtime deployments](#zero-downtime-deployments) use a rolling strategy, which keeps your app running on a temporary copy while the original updates. Some platform updates can't be applied that way, such as a restart of a database service onto a new version. A maintenance window gives those updates a scheduled time to run, so your regular deployments can stay zero-downtime.

Without a maintenance window, rolling deployments aren't available: requesting one is rejected until a project admin sets a maintenance window. Deployments that don't request the rolling strategy are unaffected and continue to use the default stop-start strategy.

Maintenance windows run only against active environments; [paused or inactive environments](/docs/environments/deactivate-environment) are skipped, even if the project has a maintenance window configured.

### What happens during a maintenance window

During your scheduled maintenance window, Upsun Cloud redeploys your environment to apply any pending patch updates to your services' container images, which can cause brief downtime.

Maintenance redeployments and your regular deployments stay separate: a maintenance redeployment skips your own staged or pending activities, and a regular deployment doesn't apply pending patch updates. A code push won't unexpectedly restart a service onto a new version, except for urgent or critical fixes, which Upsun Cloud may still apply outside of the maintenance window.

After the redeployment on your production environment succeeds, Upsun Cloud schedules the same redeployment on your non-production environments, staggered roughly 15 minutes apart so they don't all redeploy at once.

If no updates are pending, nothing runs.

### Configure a maintenance window

A project's maintenance window is not enabled by default.

<Warning>
  Once enabled, a maintenance window can't be turned off from the Console or CLI. [Contact support](/docs/core-concepts/get-support) to turn one off.
</Warning>

To configure one:

1. In the [Console](https://console.upsun.com), open your project and click **<SettingsIcon />**.
2. Click **Project Settings <ChevronIcon />** and then click **Maintenance window**.
3. Choose the recurrence (2 or 4 weeks), weekday, and time (in your project's [timezone](/docs/projects/change-project-timezone)). Click **Save**.

<img alt="Maintenance window in Project settings" />

Based on your recurrence settings, Upsun Cloud calculates the next maintenance date. The Console displays the next scheduled event, and the run itself appears as pending in the [activity log](/docs/observability/logs/access-logs#activity-logs) about 5 days ahead of time.

You can change the recurrence at any time. The new schedule applies from the next maintenance cycle, so a run that's already scheduled keeps its date.

### Reschedule a maintenance window

You can postpone a scheduled maintenance event multiple times within a seven-day window. The new date must fall within the allowable range shown in the Console.

### Turn off a maintenance window

A maintenance window can't be turned off from the Console or CLI. [Contact support](/docs/core-concepts/get-support) to turn one off.

## Zero Downtime Deployments

## What is Zero Downtime?

By default, deployments use a stop-start [deployment strategy](#deployment-strategies) (services stop, then restart with updates). Zero Downtime Deployments use a *rolling* deployment strategy, enabling you to deploy changes to your environment without taking your app offline and without interrupting live traffic.

<Info>
  Before using zero-downtime deployments, you must configure a [maintenance window](#maintenance-window). A rolling deployment updates your application, but some service updates, like restarting a database service onto a new version, can't happen during one, since your backing services must keep running the whole time to serve both the original app and its clone. A maintenance window gives Upsun Cloud a separate, scheduled time to apply those service updates instead.
</Info>

## How Zero Downtime works

Instead of stopping services before updating, a temporary copy of your application is created and prepared behind the scenes during the deployment process. Your services work with both the original application and the temporary copy during the whole deployment process, which means that any changes you make to your services during deployment will be applied to the original application. Here's the step-by-step process:

<Steps>
  <Step title="A temporary clone of your application is created">
    * Upsun Cloud starts a temporary container that runs a cloned version of your app.
    * The clone handles all live traffic during this time.
    * Services (for example, Redis) serve both the original app *and* the clone.

      <img alt="A duplicate is made of your current application" />
  </Step>

  <Step title="The original application is updated">
    * The original app is updated with the new code and configuration.
    * The deploy hook is run on the original app.
  </Step>

  <Step title="The clone is removed after deployment">
    * When deployment of the original app is complete, the clone (the temporary container) is shut down and removed.
    * All traffic and services are now applied to the original app only.

      <img alt="The duplicate of your original application is removed" />
  </Step>
</Steps>

<Warning>
  During a zero-downtime deployment, the original app and its clone run simultaneously short period (a few seconds to a couple of minutes).

  **You are billed for extra resources while both app versions active.** If your app’s deployment phase takes longer and uses more resources, expect proportionally higher costs.
</Warning>

### Deployment strategies

#### Stop-start (default)

* Services stop first then restart with the new version
* Deployment is fast but may cause temporary downtime or freezing depending on the application

#### Rolling (ZDD)

* Creates a temporary copy of your services
* Routes traffic to the temporary copy while updating the original services
* Removes the temporary copy once the deployment is complete
* No downtime for users
* Deployment may take longer and use slightly more resources temporarily

### Stop-start vs Rolling (ZDD)

| Feature | Stop-start (default) | Rolling (ZDD) |
| - | - | - |
| **User impact** | Services may be unavailable briefly | Users experience no downtime |
| **Deployment speed** | Fast | Slightly longer |
| **Resource usage** | Standard | Higher temporarily (due to parallel services) |
| **Process** | Stop services → deploy updates → start services | Deploy temporary services → switch traffic → update original services → remove temporary services |
| **Best for** | Small apps, quick updates | Apps requiring uninterrupted availability |
| **Limitations** | Causes downtime/freezetime | Longer deploy time, higher temporary resource use |

### Use cases

| Use Case | Recommendation |
| - | - |
| Code pushes | Suitable |
| Config or environment variable changes | Suitable |
| Stateful service updates (databases, caches) | Not suitable |
| Database schema migrations | Not suitable (unless updates are both backward **and** forward compatible) |

## How to use Zero Downtime Deployments

Before you can run zero-downtime deployments, a project admin needs to [set a maintenance window](#maintenance-window) for the project. We also recommend enabling [manual deployment](#manual-deployment) so you control when each deployment runs.

<Info>
  If you're not a project admin, ask one to set the maintenance window. In the Console, the deployment modal shows when a window hasn't been set yet.
</Info>

<Tabs>
  <Tab title="Using the CLI">
    **On code push**

    ```bash theme={null}
    upsun push --deploy-strategy rolling
    ```

    **With Manual Deployments**

    ```bash theme={null}
    upsun environment:deploy --strategy rolling
    ```
  </Tab>

  <Tab title="Using the Console">
    In the Console, navigate to the environment settings and trigger a deployment from the deployment modal. Select Zero Downtime as a deployment strategy.

    If the project doesn't have a maintenance window yet, you're asked to set one before you can select Zero Downtime.
  </Tab>

  <Tab title="Using the API">
    ```
    POST /projects/{projectId}/environments/{environmentId}/deploy

    {
    "strategy": "rolling"
    }
    ```
  </Tab>
</Tabs>

## Connection handling

During any deployment, long-lived connections like WebSockets or Server-Sent Events (SSE) are dropped.

With ZDD, you can plan for smooth reconnection:

* SSE supports automatic [retry logic](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#retry).

* WebSocket clients should implement reconnect logic.

## Zero Downtime Troubleshooting

This section covers two common scenarios and how to resolve them.

<Info>
  Rolling deployments require a maintenance window. If you get an error saying a maintenance window is required, [set one](#maintenance-window) in **Project settings → Maintenance window**, then deploy again.
</Info>

### Application is slow to start

If your application takes longer to become responsive, traffic might be [switched back to your original application](#how-zero-downtime-works) before it’s fully ready. This can cause temporary errors immediately after deployment.

**Use a post\_start command**

You can use the `post_start` command to ensure your app is fully active before traffic is routed to it. This command can perform checks or wait until your application starts listening on the expected port.

For example, if your framework needs several seconds to initialize (e.g. building caches or database connections), `post_start` can help coordinate the handover so the app receives traffic only when it's ready.

This `post_start` command waits for your application to respond before serving traffic:

```yaml .upsun/config.yaml theme={null}
applications:
  <APP_NAME>:
    web:
      commands:
        post_start: |
          date
          curl -sS --retry 20 --retry-delay 1 --retry-connrefused localhost -o /dev/null
```

For more information about the `post_start` command, visit [web commands](/docs/configure-apps/image-properties/web#post_start-command).

### Deployment fails midway

If deployment fails partway through, one of the applications (either the original or the clone) may remain active in the background while the other continues to serve traffic. This can lead to an increase in resource usage and costs.

To troubleshoot a failure, try one or both of the following:

* [Enable manual deployments](#change-deployment-type) if not already enabled; then, try to manually redeploy the application.
* Deploy the environment using the stop-start strategy to ensure no clones remain active.

<Info>
  If the most recent deployment failed, you can only use the default stop-start strategy.
</Info>

If you still experience issues, [contact support](/docs/core-concepts/get-support).

## Deployment philosophy

Upsun Cloud values consistency over availability, acknowledging that it's nearly impossible to have both.
During a deployment, the [deploy hook](/docs/configure-apps/hooks/hooks-comparison#deploy-hook) may make database changes
that are incompatible with the previous code version.
Having both old and new code running in parallel on different servers could therefore result in data loss.

Upsun believes that a minute of planned downtime for authenticated users is preferable to a risk of race conditions
resulting in data corruption, especially with a CDN continuing to serve anonymous traffic uninterrupted.

This brief downtime affects only the environment being updated.
Deployments to a staging or development branch have no impact on the production environment and cause no downtime.

## What's next

* See how to [configure your app](/docs/configure-apps) for the entire process.
* Learn more about [using build and deploy hooks](/docs/configure-apps/hooks).


# Automate your code updates
Source: https://developer.upsun.com/docs/core-concepts/common-tasks/dependency-updates

Learn how to automate your dependency updates through a source operation.

Upsun Cloud allows you to update your dependencies through [source operations](/docs/configure-apps/source-operations).

## Before you start

You need:

* The [Upsun Cloud CLI](/cli)
* An [API token](/cli/api-tokens#2-create-an-api-token)

## 1. Define a source operation to update your dependencies

To facilitate updating your dependencies in your project,
define a source operation in your `.upsun/config.yaml` file
depending on your dependency manager:

<Tabs>
  <Tab title="Composer">
    ```yaml .upsun/config.yaml theme={null}
    applications:
      # The name of the app container. Must be unique within a project.
      myapp:
        # The location of the application's code.
        source:
          operations:
            update:
              command: |
                set -e
                composer update
                git add composer.lock
                git add -A
                git diff-index --quiet HEAD || git commit --allow-empty -m "Update Composer dependencies"
    ```
  </Tab>

  <Tab title="npm">
    ```yaml .upsun/config.yaml theme={null}
    applications:
      # The name of the app container. Must be unique within a project.
      myapp:
        # The location of the application's code.
        source:
          operations:
            update:
              command: |
                set -e
                npm update
                git add package.json package-lock.json
                git add -A
                git diff-index --quiet HEAD || git commit --allow-empty -m "Update npm dependencies"
    ```
  </Tab>

  <Tab title="Yarn">
    ```yaml .upsun/config.yaml theme={null}
    applications:
      # The name of the app container. Must be unique within a project.
      myapp:
        # The location of the application's code.
        source:
          operations:
            update:
              command: |
                set -e
                yarn upgrade
                git add yarn.lock
                git add -A
                git diff-index --quiet HEAD || git commit --allow-empty -m "Update yarn dependencies"
    ```
  </Tab>

  <Tab title="Go">
    ```yaml .upsun/config.yaml theme={null}
    applications:
      # The name of the app container. Must be unique within a project.
      myapp:
        # The location of the application's code.
        source:
          operations:
            update:
              command: |
                set -e
                go get -u
                go mod tidy
                git add go.mod go.sum
                git add -A
                git diff-index --quiet HEAD || git commit --allow-empty -m "Update Go dependencies"
    ```
  </Tab>

  <Tab title="Pipenv">
    ```yaml .upsun/config.yaml theme={null}
    applications:
      # The name of the app container. Must be unique within a project.
      myapp:
        # The location of the application's code.
        source:
          operations:
            update:
              command: |
                set -e
                pipenv update
                git add Pipfile Pipfile.lock
                git add -A
                git diff-index --quiet HEAD || git commit --allow-empty -m "Update Python dependencies"
    ```
  </Tab>

  <Tab title="Bundler">
    ```yaml .upsun/config.yaml theme={null}
    applications:
      # The name of the app container. Must be unique within a project.
      myapp:
        # The location of the application's code.
        source:
          operations:
            update:
              command: |
                set -e
                bundle update --all
                git add Gemfile Gemfile.lock
                git add -A
                git diff-index --quiet HEAD || git commit --allow-empty -m "Update Ruby dependencies"
    ```
  </Tab>
</Tabs>

## 2. Automate your dependency updates with a cron job

After you've defined a source operation to [update your dependencies on your project](#1-define-a-source-operation-to-update-your-dependencies),
you can automate it using a cron job.

Note that it’s best not to run source operations on your production environment,
but rather on a dedicated environment where you can test changes.

Make sure you have the [Upsun Cloud CLI](/cli) installed
and [an API token](/cli/api-tokens#2-create-an-api-token)
so you can run a cron job in your app container.

1. Set your API token as a top-level environment variable:

<Tabs>
  <Tab title="From the CLI">
    Run the following command:

    ```bash theme={null}
    upsun variable:create --environment main --level environment --prefix 'env' --name UPSUN_CLI_TOKEN --sensitive true --value 'YOUR_UPSUN_CLI_TOKEN' --inheritable false --visible-build true --json false --enabled true --visible-runtime true
    ```
  </Tab>

  <Tab title="From the Console">
    1. Open the environment where you want to add the variable.
    2. Click <SettingsIcon /> **Settings**.
    3. Click **Variables**.
    4. Click **+ Add variable**.
    5. In the **Variable name** field, enter `env:UPSUN_CLI_TOKEN`.
    6. In the **Value** field, enter your API token.
    7. Make sure the **Available at runtime** and **Sensitive variable** options are selected.
    8. Click **Add variable**.
  </Tab>
</Tabs>

<Warning>
  Once you add the API token as an environment variable,
  anyone with [SSH access](/docs/development/ssh) can read its value.
  Make sure you carefully check your [user access on this project](/docs/administration/users#manage-project-users).
</Warning>

2. Add a build hook to your app configuration to install the CLI as part of the build process:

```yaml .upsun/config.yaml theme={null}
applications:
  myapp:
    hooks:
      build: |
        set -e
        echo "Installing Upsun Cloud CLI"
        curl -fsSL https://raw.githubusercontent.com/upsun/cli/main/installer.sh | bash

        echo "Testing Upsun Cloud CLI"
        upsun
```

3. Then, to configure a cron job to automatically update your dependencies once a day,
   use a configuration similar to the following:

```yaml .upsun/config.yaml theme={null}
applications:
  myapp:
    # ...
    crons:
      update:
        # Run the code below every day at midnight.
        spec: '0 0 * * *'
        commands:
          start: |
            set -e
            upsun sync -e development code data --no-wait --yes
            upsun source-operation:run update --no-wait --yes
```

The example above synchronizes the `development` environment with its parent
and then runs the `update` source operation defined [previously](#1-define-a-source-operation-to-update-your-dependencies).

<Warning>
  If you have enabled a [source integration](/docs/integrations/source), and have enabled `--fetch-branches` on that
  integration, merging on Upsun Cloud is not possible. Therefore, the `sync` command in the example above would
  fail.
</Warning>

## 3. Configure notifications about dependency updates

To get notified every time a source operation is triggered and therefore every time a dependency is updated,
you can configure activity scripts or webhooks.

### Notifications through an activity script

After you've defined a source operation to [update your dependencies on your project](#1-define-a-source-operation-to-update-your-dependencies),
you can configure an activity script
to receive notifications every time a dependency update is triggered.

<Note>
  <h4>Example</h4>
  You want to get notified of every dependency update
  through a message posted on a Slack channel.
  To do so, follow these steps:

  1. In your Slack administrative interface, [create a new Slack webhook](https://api.slack.com/messaging/webhooks).
     You get a URL starting with `https://hooks.slack.com/`.

  2. Replace `SLACK_URL` in the following `.js` script with your webhook URL.

  3. Add the following code to a `.js` file:

     ```javascript theme={null}
     /**
      * Sends a color-coded formatted message to Slack.
      *
      * To control what events trigger it, use the --events switch in
      * the Upsun Cloud CLI.
      *
      * Replace SLACK_URL in the following script with your Slack webhook URL.
      * Get one here: https://api.slack.com/messaging/webhooks
      * You should get something like: const url = 'https://hooks.slack.com/...';
      *
      * activity.text: a brief, one-line statement of what happened.
      * activity.log: the complete build and deploy log output, as it would be seen in the Console log screen.
      */
     function sendSlackMessage(title, message) {
       const url = 'SLACK_URL';
       const messageTitle = title;
       const color = activity.result === "success" ? "#66c000" : "#ff0000";
       const body = {
         attachments: [
           {
             title: messageTitle,
             text: message,
             color: color,
           },
         ],
       };
       const resp = fetch(url, {
         method: "POST",
         headers: {
           "Content-Type": "application/json",
         },
         body: JSON.stringify(body),
       });
       if (!resp.ok) {
         console.log("Sending slack message failed: " + resp.body.text());
       }
     }
     sendSlackMessage(activity.text, activity.log);
     ```

  4. Run the following [Upsun Cloud CLI](/cli) command:

     ```bash theme={null}
     upsun integration:add --type script --file ./my_script.js --events=environment.source-operation
     ```

     Optional: to only get notifications about specific environments,
     add the following flag to the command: `--environments=your_environment_name`.

  Anytime a dependency is updated via a source operation,
  the activity script now reports it to Slack.
</Note>

### Notifications through a webhook

After you've defined a source operation to [update your dependencies on your project](#1-define-a-source-operation-to-update-your-dependencies),
you can configure a webhook to receive notifications every time a dependency update is triggered.

[Webhooks](/docs/integrations/activity/webhooks) allow you to host a script yourself externally.
This script receives the same payload as an activity script and responds to the same events,
but can be hosted on your own server and in your own language.

To configure the integration between your webhook and your source operation,
run the following [Upsun Cloud CLI](/cli) command:

```bash theme={null}
upsun integration:add --type=webhook --url=URL_TO_RECEIVE_JSON --events=environment.source-operation
```

Optional: to only get notifications about specific environments,
add the following flag to the command: `--environments=your_environment_name`.

To test the integration and the JSON response,
you can generate a URL from a service such as [webhook.site](https://webhook.site)
and use the generated URL as `URL_TO_RECEIVE_JSON`.
This URL then receives the JSON response when a source operation is triggered.

Anytime a dependency is updated via a source operation,
the webhook now receives a POST message.
This POST message contains complete information about the entire state of the project at that time.


# Exporting data
Source: https://developer.upsun.com/docs/core-concepts/common-tasks/exporting

See how to export your code, files and service data.

As an Upsun user, your code and data belong to you.
At any time, you can download your site's data for local development, to back up your data, or to change provider.

For a full overview of all data categories, classifications, and export methods, see the [Data Register](/docs/registry).

## Before you begin

You need:

* [Git](https://git-scm.com/downloads)
* An Upsun account
* Code in your project
* Optional: the [Upsun CLI](/cli)

## 1. Download your app's code

Your app's code is maintained through the Git version control system.

To download your entire app's code history:

<Tabs>
  <Tab title="Using the CLI">
    1. List all your projects by running the following command:

       ```bash theme={null}
       upsun projects
       ```

    2. Retrieve the project you want to back up by running the following command:

       ```bash theme={null}
       upsun get <PROJECT_ID>
       ```
  </Tab>

  <Tab title="Using Git">
    1. In the [Console](https://console.platformsh.site/), open your project and click **Code <ChevronIcon />**.
    2. Click **Git**.
    3. To copy the command, click **<CopyIcon /> Copy**.
       The command is similar to the following:

       ```bash theme={null}
       git clone abcdefgh1234567@git.eu.platformsh.site:abcdefgh1234567.git project-name
       ```
  </Tab>
</Tabs>

## 2. Download your files

Some files might not be stored in Git,
such as data your app writes [in mounts](/docs/configure-apps/image-properties/mounts).

You can download your files [using the CLI](/docs/development/file-transfer#transfer-files-using-the-cli) or [using SSH](/docs/development/file-transfer#transfer-files-using-an-ssh-client).

### Network Storage mounts

If your project uses a [Network Storage service](/docs/add-services/network-storage)
(mounts with `source: service`), the data lives in a dedicated service container rather than in the app container itself.
The download process is the same as for local mounts — use the CLI or rsync over SSH — but you need to target the path
as it is mounted inside the app container.

For example, to download a `web/uploads` network mount using the CLI:

```bash Terminal theme={null}
upsun mount:download --mount web/uploads --target ./local-uploads
```

## 3. Download data from services

<Note title="Technical restrictions and known limitations">
  While Upsun Cloud supports customer data portability, certain technical characteristics of cloud-native platforms may affect migration workflows.

  <Accordion title="Volume limits">
    Upsun Cloud does not impose platform-specific restrictions on the volume of customer data that can be exported. However, exports may be subject to:

    * Network bandwidth limitations
    * Resource constraints of the originating environment
    * Service-specific export mechanisms
  </Accordion>

  <Accordion title="Transformation requirements">
    Some exported data may require reconfiguration before being used in another environment. Examples include:

    * Environment-specific configuration values
    * Infrastructure definitions referencing Upsun Cloud-specific services
    * Deployment configuration files tailored to Upsun Cloud's build and runtime model
  </Accordion>

  <Accordion title="Compatibility">
    Upsun Cloud supports widely adopted open formats and standards to maximize portability. However:

    * Infrastructure definitions written for Upsun Cloud may require adaptation when deployed on other cloud providers
    * Service configuration may need adjustment depending on the destination platform's capabilities
    * Some operational metadata used internally by Upsun Cloud is platform-specific and may not be applicable in external environments
  </Accordion>

  These limitations are typical for platform-as-a-service environments and do not prevent customers from exporting their application data and code.
</Note>

The mechanism for downloading from each service varies.

For services designed to hold non-persistent data in memory only — such as [ephemeral Redis](/docs/add-services/redis#ephemeral-redis),
[ephemeral Valkey](/docs/add-services/valkey), [Memcached](/docs/add-services/memcached),
or [Solr](/docs/add-services/solr) —
it's generally not necessary to download data as it can be rebuilt from the primary data store.

For services designed to hold persistent data, see the instructions for each service below.

### Relational databases

* [MySQL / MariaDB](/docs/add-services/mysql#exporting-data)
* [PostgreSQL](/docs/add-services/postgresql#exporting-data)

### Document and time-series databases

* [MongoDB](/docs/add-services/mongodb#exporting-data)
* [InfluxDB](/docs/add-services/influxdb#export-data)
* [ClickHouse](/docs/add-services/clickhouse#exporting-data)

### Search engines

* [Elasticsearch](/docs/add-services/elasticsearch#exporting-data)
* [OpenSearch](/docs/add-services/opensearch#exporting-data)

### Key-value stores (persistent)

* [Redis (persistent)](/docs/add-services/redis#exporting-data-persistent)
* [Valkey (persistent)](/docs/add-services/valkey#exporting-data-persistent)

### Message brokers

* [RabbitMQ](/docs/add-services/rabbitmq#exporting-data)
* [Kafka](/docs/add-services/kafka#exporting-data)

### Vector databases

* [Qdrant](/tutorials/self-hosted/qdrant#exporting-data)
* [Chroma](/tutorials/self-hosted/chroma#exporting-data)

## 4. Get environment variables

Environment variables can contain critical information such as tokens or additional configuration options for your app.

Environment variables can have different prefixes:

* Variables beginning with `env:` are exposed [as Unix environment variables](/docs/development/variables#top-level-environment-variables).
* Variables beginning with `php:` are interpreted [as `php.ini` directives](/docs/development/variables#php-specific-variables).

All other variables are [part of `$PLATFORM_VARIABLES`](/docs/development/variables/use-variables#use-provided-variables).

To back up your environment variables:

<Tabs>
  <Tab title="Using the CLI">
    1. Get the variable's values by running the following command:

       ```bash theme={null}
       upsun ssh -- 'echo $PLATFORM_VARIABLES | base64 -d | jq'
       ```

       Note that you can also get all the environment variable values by running the following command:

       ```bash theme={null}
       upsun ssh -- env
       ```

    2. Store the data somewhere secure on your computer.
  </Tab>

  <Tab title="In the Console">
    1. In the [Console](https://console.platformsh.site/), open your project and click **<SettingsIcon />**.
    2. Click **Project Settings <ChevronIcon />**.
    3. Click **Variables** and access your variable's values and settings.
    4. Store the data somewhere secure on your computer.

    Note that in the Console, you can't access the value of variables that have been [marked as sensitive](/docs/development/variables/set-variables#variable-options).
    Use the CLI to retrieve these values.
  </Tab>
</Tabs>

## What's next

* Migrate data from elsewhere [into Upsun](/tutorials/migration).
* Migrate to [another region](/docs/projects/region-migration).
* To use data from an environment locally, export your data and set up your [local development environment](/docs/development/local).


# Export data
Source: https://developer.upsun.com/docs/core-concepts/common-tasks/exporting_old

See how to export your code, files and service data.

As an Upsun Cloud user, your code and data belong to you.
At any time, you can download your site's data for local development, to back up your data, or to change provider.

## Before you begin

You need:

* [Git](https://git-scm.com/downloads)
* An Upsun account
* Code in your project
* Optional: the [Upsun Cloud CLI](/cli)

## 1. Download your app's code

Your app's code is maintained through the Git version control system.

To download your entire app's code history:

<Tabs>
  <Tab title="Using the CLI">
    1. List all your projects by running the following command:

       ```bash theme={null}
       upsun projects
       ```

    2. Retrieve the project you want to back up by running the following command:

       ```bash theme={null}
       upsun get <PROJECT_ID>
       ```
  </Tab>

  <Tab title="Using Git">
    1. In the [Console](https://console.upsun.com/), open your project and click **Code <ChevronIcon />**.
    2. Click **Git**.
    3. To copy the command, click **<CopyIcon /> Copy**.
       The command is similar to the following:

       ```text theme={null}
       git clone abcdefgh1234567@git.eu.upsun.com:abcdefgh1234567.git project-name
       ```
  </Tab>
</Tabs>

## 2. Download your files

Some files might not be stored in Git,
such as data your app writes [in mounts](/docs/configure-apps/image-properties/mounts).

You can download your files [using the CLI](/docs/development/file-transfer#transfer-files-using-the-cli) or [using SSH](/docs/development/file-transfer#transfer-files-using-an-ssh-client).

## 3. Download data from services

The mechanism for downloading from each service (such as your database) varies.

For services designed to hold non-persistent data, such as [Redis](/docs/add-services/redis) or [Solr](/docs/add-services/solr),
it's generally not necessary to download data as it can be rebuilt from the primary data store.

For services designed to hold persistent data, see each service's page for instructions:

* [MySQL](/docs/add-services/mysql#exporting-data)
* [PostgreSQL](/docs/add-services/postgresql#exporting-data)
* [MongoDB](/docs/add-services/mongodb#exporting-data)
* [InfluxDB](/docs/add-services/influxdb#export-data)

## 4. Get environment variables

Environment variables can contain critical information such as tokens or additional configuration options for your app.

Environment variables can have different prefixes:

* Variables beginning with `env:` are exposed [as Unix environment variables](/docs/development/variables#top-level-environment-variables).
* Variables beginning with `php:` are interpreted [as `php.ini` directives](/docs/development/variables#php-specific-variables).

All other variables are [part of `$PLATFORM_VARIABLES`](/docs/development/variables/use-variables#use-provided-variables).

To back up your environment variables:

<Tabs>
  <Tab title="Using the CLI">
    1. Get the variable's values by running the following command:

       ```bash theme={null}
       upsun ssh -- 'echo $PLATFORM_VARIABLES | base64 -d | jq'
       ```

       Note that you can also get all the environment variable values by running the following command:

       ```bash theme={null}
       upsun ssh -- env
       ```

    2. Store the data somewhere secure on your computer.
  </Tab>

  <Tab title="In the Console">
    1. In the [Console](https://console.upsun.com/), open your project and click **<SettingsIcon />**.
    2. Click **Project Settings <ChevronIcon />**.
    3. Click **Variables** and access your variable's values and settings.
    4. Store the data somewhere secure on your computer.

    Note that in the Console, you can't access the value of variables that have been [marked as sensitive](/docs/development/variables/set-variables#variable-options).
    Use the CLI to retrieve these values.
  </Tab>
</Tabs>

## What's next

* Migrate data from elsewhere [into Upsun Cloud](/tutorials/migration/from-other-provider).
* Migrate to [another region](/docs/projects/region-migration).
* To use data from an environment locally, export your data and set up your [local development environment](/docs/development/local).


# Common Tasks
Source: https://developer.upsun.com/docs/core-concepts/common-tasks/index

Here are a set of tutorials for migrating between regions, exporting data, and more.


<CardGroup>
  <Card title="Dependency updates" icon="refresh-cw" href="/docs/core-concepts/common-tasks/dependency-updates">
    Keep your project dependencies up to date.
  </Card>

  <Card title="Restrict service access" icon="lock" href="/docs/core-concepts/common-tasks/restrict-service-access">
    Control access to your services.
  </Card>

  <Card title="Export data" icon="download" href="/docs/core-concepts/common-tasks/exporting">
    Export data from your Upsun Cloud environments.
  </Card>

  <Card title="Upgrade runtimes and services" icon="shield-plus" href="/docs/core-concepts/upgrade-runtimes-services">
    Update a runtime or service to a supported version.
  </Card>
</CardGroup>


# Restrict access to a service
Source: https://developer.upsun.com/docs/core-concepts/common-tasks/restrict-service-access

Learn how to restrict access to a service using a worker and additional endpoints to the service.

Upsun Cloud allows you to restrict access to a service.

In this tutorial, learn how to grant your Data team `read-only` access to your production database.

## Before you start

You need:

* A project with a database service
* A `viewer` user on your project

## 1. Add a read-only endpoint to your database service

Edit your `.upsun/config.yaml` file and add the following [endpoints](/docs/add-services/mysql#define-permissions):

* `website` with `admin` access to the `main` database
* `reporting` with read-only `ro` access to the `main` database

## 2. Grant your app access to the new endpoints

Edit your app configuration and add new relationships to your new endpoints:

## 3. Create a worker with access to the read-only endpoint

Edit your app configuration to add a new worker which:

* Does nothing (`sleep infinity`)
* Can access the read-only `reporting` endpoint
* Allows SSH access to `viewer`

You're done!
From now on, your `viewer` users can SSH in to the worker application,
and connect to your database with read-only permissions.


# Get support
Source: https://developer.upsun.com/docs/core-concepts/get-support

Find out how to get help if you're experiencing issues with Upsun Cloud.


## Create a support ticket

Open a support ticket to report infrastructure, application container, or build issues, flag a possible bug, ask a general question, or submit a feature request:

1. [Open the Console](https://console.upsun.com/).
2. In the upper right corner, click **Help**, then select **Support**.
3. On the Upsun Help Center landing page, click **Create a new request**.
4. Complete and submit the form on the "Submit a request" page.

**Shortcuts**

* [Open a new ticket](https://support.upsun.com/hc/en-us/requests/new?ticket_form_id=35294051960082)
* [Submit a feature request](https://support.upsun.com/hc/en-us/requests/new?ticket_form_id=37982573191442)
* [View your tickets](https://support.upsun.com/hc/en-us/requests)

<Tip>
  You can't modify or delete a ticket after submitting it. To add more information, go to [your tickets](https://support.upsun.com/hc/en-us/requests) and add a message to the relevant one.
</Tip>

<Info>
  <h4>Upgrade to the Organization Support add-on</h4>
  The Upsun Cloud Organization Support add-on provides tiered support options tailored to organizational needs. All organizations are automatically enrolled in the Standard support tier.

  To upgrade to either the Premium or Advanced support tier, visit the [add-on subscriptions page](/docs/administration/billing/add-on-subscription#organization-support-add-on).
</Info>

## Community

To talk about app development or framework-related questions,
join other customers and engineers in the [Community Forum](https://community.upsun.com/).

<CommunityButtons />

## Contact Sales

If you have questions about pricing or need help figuring out if Upsun Cloud is the right solution for your team,
get in touch with [Sales](https://upsun.com/contact-us/).

## Delete your account

To permanently delete your Upsun account, follow these steps:

<Danger>
  Deleting your Upsun account automatically deletes all your linked Ibexa Cloud, Pimcore PaaS, and Shopware PaaS accounts.
</Danger>

1. [Open the Console](https://console.upsun.com/).
2. Open the user menu (your name or profile picture) and select **My Profile**.
3. Click **Delete account**.
4. Check that the pre-filled information is correct and click **Submit**.<br />
   Your request is now submitted and will be handled by Support shortly.


# What is Upsun Cloud?
Source: https://developer.upsun.com/docs/core-concepts/index

Find out which problem Upsun Cloud is trying to solve.

Upsun Cloud is a Cloud Application Platform built especially for continuous deployment.
It allows you to host web applications on the cloud while making your development and testing workflows more productive.

If you're new to Upsun Cloud, the [Philosophy](/docs/core-concepts/philosophy), [Structure](/docs/core-concepts/structure),
and [Build and Deploy](/docs/core-concepts/build-deploy) pages cover all the basics to start on the right track.

The main requirement of Upsun Cloud is that you use Git to manage your application code.
If you have a single-app project, you can configure it from a single `.upsun/config.yaml` file,
usually located at the root of your app folder in your Git repository.
[Multi-app projects](/docs/configure-apps/multi-app) can be set up in various ways.

Upsun Cloud is built on Debian, supports many different programming [languages](/docs/languages) and environments,
and features recommended optimizations for several [featured frameworks](/docs/get-started).

Finally, you can also get tips for setting up your own [development workflow](/docs/development)
and [administrating](/docs/administration) your Upsun account.

## Git Driven Infrastructure

As a Cloud Application Platform, Upsun Cloud automatically manages everything your application needs to run.
That means you can, and should, view your infrastructure needs as part of your application and address them under version control.

### Infrastructure as code

Upsun Cloud covers not only all of your hosting needs but also most of your DevOps needs. It is a single tool that covers the application life-cycle from development to production and scaling.

You only need to write your code, including a single or a few YAML files that specify your desired infrastructure, commit it to Git, and push.
You don't need to set up anything manually. The web server is already set up and configured, as is any database, search engine, or cache that you specify.

Every branch you push can be made a fully independent environment—complete with your application code, a copy of your database, a copy of your search index, a copy of your user files, everything.
Its automatically generated URL can be sent to stakeholders or automated CI systems.
It really is "what would my site look like if I merged this to production?" every time.

You can use these concepts to replicate a traditional development/staging/production workflow, or even to give every feature its own effective staging environment before merging to production (empowering you to use git-flow like methodologies even better). You could also have an intermediary integration branch for several other branches.

Upsun Cloud respects the structure of branches. It's entirely up to you.

### Full stack management

Managing your full stack on Upsun Cloud gives you the following unique features:

1. **Unified Environment:** All of your [services](/docs/add-services) (MySQL, Elasticsearch, MongoDB, etc.) are managed inside the cluster and included in the price, with no external single-points-of-failure. When you [back up an environment](/docs/environments/backup), you get a fully consistent snapshot of your whole application.
2. **Multi-Services & Multi-App:** You can deploy [multiple applications](/docs/configure-apps/multi-app) (for example, in a microservice-based architecture), using multiple data backends (MySQL, PostgreSQL, Redis, etc.) written in multiple frameworks (Drupal + NodeJS + Flask, for example) in multiple languages, all in the same cluster.
3. **Full Cluster Cloning Technology:** The full production cluster can be cloned in under a minute—including all of its data—to create on-the-fly, ephemeral [preview environments](/docs/glossary#preview-environment) that are a byte-level copy of production.
4. **Fail-Proof Deployments:** Every time you test a new feature, you also test the deployment process.
5. **Continuous Deployment from the Start:** Everything is build-oriented, with a consistent, repeatable build process, simplifying the process of keeping your application up-to-date and secure.


# Philosophy
Source: https://developer.upsun.com/docs/core-concepts/philosophy

Gain insight into the philosophy of Upsun Cloud.

Upsun aims to reduce configuration and make developers more productive.
It abstracts your project infrastructure and manages it for you,
so you never have to configure services like a web server, a MySQL database, or a Redis cache from scratch again.

Upsun Cloud is built on one main idea — your server infrastructure is part of your app,
so it should be version controlled along with your app.

Every branch you push to your Git repository can come with bug fixes,
new features, **and** infrastructure changes.
You can then test everything as an independent deployment,
including your application code and all of your services with a copy of their data
(database entries, search index, user files, etc.).

This allows you to preview exactly what your site would look like if you merged your changes to production.

## The basics

On Upsun Cloud, a **project** is linked to a Git repository and is composed of one or more **apps**.
An app is a directory in your Git repository with a specific Upsun Cloud configuration
and dedicated HTTP endpoints (via the `.upsun/config.yaml` file).

Projects are deployed in **environments**.
An environment is a standalone copy of your live app which can be used for testing,
Q\&A, implementing new features, fixing bugs, and so on.

Every project you deploy on Upsun Cloud is built as a *virtual cluster* containing a series of containers.
The main branch of your Git repository is always deployed as a production cluster.
Any other branch can be deployed as a staging or development cluster.

There are three types of containers within your cluster,
all usually configured from a single `.upsun/config.yaml` file stored alongside your code:

* The [*router*](/docs/routes) is a single Nginx process responsible for mapping incoming requests to an app container,
  and for optionally providing HTTP caching.

* One or more [*apps*](/docs/configure-apps) holding the code of your project.

* Some optional [*services*](/docs/add-services) like MySQL/MariaDB, Elasticsearch, Redis, or RabbitMQ.
  They come as optimized pre-built images.

## The workflow

Every time you deploy a branch to Upsun Cloud, the code is *built* and then *deployed* on a new cluster.

The [**build** process](/docs/core-concepts/build-deploy#build-steps) looks through the configuration files in your repository
and assembles the necessary containers.

The [**deploy** process](/docs/core-concepts/build-deploy#deploy-steps) makes those containers live, replacing the previous
versions, with no service downtime.

Depending on your needs, you can also [set up a **post-deploy** hook](#add-a-post-deploy-hook) to run after your app is deployed and your application container starts accepting traffic.
Adding a [`post-deploy` hook](/docs/configure-apps/hooks/hooks-comparison#post-deploy-hook) can be useful to run updates that don't require exclusive database access.

Note that if you're using Gatsby to pull from a backend container on the same environment,
you need a `post-deploy` hook to successfully build and deploy your app.

### How your app is built

During the [build step](/docs/core-concepts/build-deploy#build-steps),
dependencies specified in `.upsun/config.yaml` are installed on application containers.

You can also customize the build step by providing a [`build` hook](/docs/configure-apps/hooks/hooks-comparison#build-hook) composed of one or more shell commands
that help create your production codebase.
That could be compiling TypeScript files, running some scripts,
rearranging files on disk, or whatever else you want.

Note that at this point all you have access to is the filesystem;
there are **no services or other databases available**.
Your live website is unaffected.

Once the build step is completed, the filesystem is frozen and a read-only container image is created.
That filesystem is the final build artifact.

### How your app is deployed

Before starting the [deployment](/docs/core-concepts/build-deploy#deploy-steps) of your app,
Upsun Cloud pauses all incoming requests and holds them to avoid downtime.

Then, the current containers are stopped and the new ones are started.
Upsun Cloud then opens networking connections between the various containers,
as specified in `.upsun/config.yaml`.
The connection information for each service is available from the [service environment variables](/docs/development/variables#service-environment-variables), or the [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables).

Similar to the build step, you can define a [deploy hook](/docs/configure-apps/hooks/hooks-comparison#deploy-hook) to prepare your app.
Your app has complete access to all services, but the filesystem where your code lives is now read-only.

Finally, Upsun Cloud opens the floodgates and lets incoming requests through your newly deployed app.

### Add a post-deploy hook

You can add a [`post-deploy` hook](/docs/configure-apps/hooks/hooks-comparison#post-deploy-hook) to be run after the build and deploy steps.

Similar to the [`deploy` hook](/docs/configure-apps/hooks/hooks-comparison#deploy-hook),
the `post-deploy` hook only runs once your application container accepts requests.
So you can use it to run updates such as content imports or cache warmups that can be executed simultaneously with normal traffic.

During a redeploy, the `post-deploy` hook is the only hook that is run.

## Get support

If you're facing an issue with Upsun Cloud,
open a [support ticket](/docs/core-concepts/get-support).

## What's next?

To get a feeling of what working with Upsun Cloud entails,
see the [Get Started](/docs/get-started) framework guides.


# Structure
Source: https://developer.upsun.com/docs/core-concepts/structure

Learn about how your Upsun Cloud environments are structured and which files control that structure.

Each environment you deploy on Upsun Cloud is built as a set of containers.
Each container is an isolated instance with specific resources.

Each environment has 2 to 4 types of containers, all usually configured from your `.upsun/config.yaml` file.

* One [*router*](#router)
* One or more [*app* containers](#apps)
* Zero or more [*service* containers](#services)
* Zero or more [*worker* containers](#workers)

If you have two app containers, two services (a database and a search engine), and a worker,
requests to your environment might look something like this:

<img alt="A user request goes to the router, which sends it to either a Node.js app or a Python app. Each app communicates separately with the database and search services and sends responses to the user. The Node.js app triggers actions in a worker, which communicates separately with the database." />

If you have only one app container, your repository might look like this:

```text theme={null}
project
├── .git
├── .upsun/
│   └── config.yaml
└── <YOUR_APP_FILES>
```

## Router

Each environment always has exactly one router.

This router maps incoming requests to the appropriate app container
and provides basic caching of responses, unless configured otherwise.

The router is configured in a `.upsun/config.yaml` file.
If you don't include configuration, a single [default route is deployed](/docs/routes#default-route-definition).

Read more about how to [define routes](/docs/routes).

## Apps

You always need at least one app container, but you can have more.

App containers run the code you provide via your Git repository.
They handle requests from the outside world and can communicate with other containers within the environment.
Each app container is built from a specific language image with a given version for the language.

To configure your apps, you usually create a single `.upsun/config.yaml` file
and place it in the repository root.

Read more about how to [configure apps](/docs/configure-apps).

## Services

You don't need any service containers, but you can add them as you like.

Service containers run predefined code for specific purposes, such as a database or search service.
You don't need to add their code yourself, just set up how your apps communicate with them.

Service containers are configured by the `.upsun/config.yaml` file.

Read more about how to [add services](/docs/add-services).

## Workers

You don't need any worker containers, but you can add them as you like.

Worker containers are copies of an app containers
that have no access to the outside world and can have a different start command.
They're useful for continually running background processes.

Read more about how to [work with workers](/docs/configure-apps/workers).


# Upgrade to a maintained version of a runtime or service
Source: https://developer.upsun.com/docs/core-concepts/upgrade-runtimes-services

Upgrade a runtime or service to a maintained version to avoid build failures and stay protected against known CVEs.

Use a maintained runtime or service version — outdated images can fail to build or carry known CVEs. See [Image statuses](#image-statuses) to check your image's status and what to do next.

Once you know you need to upgrade, the steps are the same regardless of which runtime or service you use. For version-specific details, see the docs page for your runtime in [Languages](/docs/languages) or your service in [Add services](/docs/add-services).

## Image statuses

"Maintained" means **Active** or **Supported**, depending on the classification below.

<Note>
  Some runtimes and services (for example, [Redis](/docs/add-services/redis)) use the **Active/Sunset/Decommissioned** classification below.

  Others currently use the **Supported/Deprecated/Retired** classification, until they migrate to **Active/Sunset/Decommissioned**.
</Note>

<Tabs>
  <Tab title="Active/Sunset/Decommissioned">
    The Console shows an image's status as a banner on your project's Overview page, or as a decoration on the relevant activity in the **Activity** panel (active images show no decoration, since they're always supported).

    An image's status shows what's supported and what to do:

    | Image status | What it means | What to do |
    | - | - | - |
    | Active | Fully maintained, Upsun Cloud applies software and security updates received from upstream. | No action needed. |
    | Sunset | Existing projects (including code pushes) keep working; new projects can't use this image. Upsun Cloud applies only critical security updates from upstream, and the image is decommissioned 180 calendar days after entering Sunset. | Upgrade to an active version before the decommission date (180 calendar days after entering Sunset). |
    | Decommissioned | Upsun Cloud no longer supports this image. Existing projects with a decommissioned image continue to run as is. All code pushes are blocked. | Upgrade to an active version to continue deploying. |
  </Tab>

  <Tab title="Supported/Deprecated/Retired">
    "Image status" is the classification shown on each runtime's ([Languages](/docs/languages)) or service's ([Add services](/docs/add-services)) own docs page:

    | Image status | What it means | What to do |
    | - | - | - |
    | Supported | Fully maintained, Upsun Cloud applies software and security updates received from upstream. | No action needed. |
    | Deprecated | Still available and functional, but at end of life and no longer receiving security updates from upstream. | Switch to a supported version to keep receiving security updates. |
    | Retired | No longer available from upstream and not receiving further updates. This reflects the upstream project's own status only — Upsun Cloud doesn't enforce it, so the image keeps working with no scheduled decommission date. | Upgrade to a supported version, since no further security updates are available. |
    | Decommissioned\* | No longer supported by upstream. This reflects the upstream project's own status only — Upsun Cloud doesn't enforce it, so builds and deployments aren't blocked. | Upgrade to a supported version as soon as possible. |

    \* At this time, decommissioned images are not listed in the product docs.
  </Tab>
</Tabs>

## Before you upgrade

Test any version change on a non-production branch before merging.

## Upgrade a runtime

Runtimes are defined by the `type` key on your application in `.upsun/config.yaml`. Updating to a new version means changing that value and pushing it. This is a version change you choose and push yourself, so it applies on deploy as usual, whether or not your project has a [maintenance window](/docs/core-concepts/build-deploy#maintenance-window) — maintenance windows only govern the platform's own automatic patch updates.

1. Check your runtime's docs page in [Languages](/docs/languages) for supported versions — new versions may include breaking changes — then update the `type` key with the correct version number:

2) Push to a non-production branch. If you don't already have one, create it first:

```bash theme={null}
upsun branch upgrade-runtime
git add .upsun/config.yaml
git commit -m "Update runtime version"
upsun push
```

Pushing triggers Upsun Cloud to automatically build and deploy the environment.

3. Verify that your app builds and behaves correctly. Check the deploy log for errors:

```bash theme={null}
upsun activity:log
```

Then open the environment and test your app manually:

```bash theme={null}
upsun environment:url --primary
```

4. Merge to production:

```bash theme={null}
upsun merge
```

If your project uses a source integration (GitHub, GitLab, Bitbucket), `upsun merge` isn't available — merge through a pull/merge request in your Git provider instead.

## Upgrade a service

Services are defined under the `services:` key in `.upsun/config.yaml`. Updating the `type` value triggers a version change on the next deploy, the same as [upgrading a runtime](#upgrade-a-runtime): it's a change you choose and push yourself, independent of any [maintenance window](/docs/core-concepts/build-deploy#maintenance-window). Whether data migrates automatically depends on the service. Check [Add services](/docs/add-services) before you begin.

### In-place upgrade

Some services upgrade automatically when you change the version. PostgreSQL 10 and later, for example, include a built-in upgrade utility that runs at deploy time.

1. Update the `type` key for your service:

2) Push to a non-production branch. If you don't already have one, create it first:

```bash theme={null}
upsun branch upgrade-service
git add .upsun/config.yaml
git commit -m "Update service version"
upsun push
```

Pushing triggers Upsun Cloud to automatically build and deploy the environment.

3. Confirm the service starts and your app connects. Check the deploy log for errors:

```bash theme={null}
upsun activity:log
```

Then open the environment and test your app manually:

```bash theme={null}
upsun environment:url --primary
```

4. Create a production backup, then merge to production:

```bash theme={null}
upsun backup:create --environment main
upsun merge
```

If your project uses a source integration (GitHub, GitLab, Bitbucket), `upsun merge` isn't available — merge through a pull/merge request in your Git provider instead.

Downgrading is not supported after an in-place upgrade. If you need to roll back, restore from a backup.

### Manual data migration

When a service doesn't support in-place upgrades (for example, if you use composable image or Docker images), or when you're moving across several major versions, you need to export your data, provision a new service at the target version, and import.

1. [Export your data](/docs/core-concepts/common-tasks/exporting) from the current service.

2. Rename the service in `.upsun/config.yaml` and set the target version. Renaming forces the platform to create a fresh service container.

3) Update the `relationships` in any application that references the old service name:

4. Push to a non-production branch and import your data into the new service.

5. Verify your app works correctly, then merge to production.


# Workflow Overview
Source: https://developer.upsun.com/docs/core-concepts/workflow

Learn about the YAML configuration, project structure, build and deploy process, and how to get support.

<CardGroup>
  <Card title="YAML" icon="file-code" href="/docs/core-concepts/yaml">
    An overview of YAML and its use at Upsun Cloud.
  </Card>

  <Card title="Structure" icon="folder-tree" href="/docs/core-concepts/structure">
    Learn about how your Upsun Cloud environments are structured and which files control that structure.
  </Card>

  <Card title="Build and deploy" icon="rocket" href="/docs/core-concepts/build-deploy">
    See how applications get built and deployed with Upsun Cloud.
  </Card>

  <Card title="Get support" icon="headset" href="/docs/core-concepts/get-support">
    Find out how to get help if you're experiencing issues with Upsun Cloud.
  </Card>
</CardGroup>


# YAML
Source: https://developer.upsun.com/docs/core-concepts/yaml/index

An overview of YAML and its use at Upsun Cloud.

[YAML](https://en.wikipedia.org/wiki/YAML) is a human-readable format for data serialization across languages.
This means it's a good fit for human-edited configuration files, like those at Upsun Cloud.
You can control nearly all aspects of your project's build and deploy pipeline with YAML files.

Learn what YAML is or, if you're already familiar, what custom tags Upsun Cloud offers.

<CardGroup>
  <Card title="What YAML is" icon="file-code" href="/docs/core-concepts/yaml/what-is-yaml">
    An introduction to what YAML is and how to create and modify YAML files.
  </Card>

  <Card title="YAML structure" icon="list-tree" href="/docs/core-concepts/yaml/yaml-structure">
    A description of the YAML file for Upsun Cloud.
  </Card>

  <Card title="YAML tags" icon="tags" href="/docs/core-concepts/yaml/platform-yaml-tags">
    A description of custom YAML tags available for Upsun Cloud files.
  </Card>
</CardGroup>


# Upsun Cloud YAML tags
Source: https://developer.upsun.com/docs/core-concepts/yaml/platform-yaml-tags

A description of custom YAML tags available for Upsun Cloud files.

In addition to the [basic functions you should be familiar with](/docs/core-concepts/yaml/what-is-yaml), YAML allows for special tags.
Upsun Cloud accepts certain custom tags to facilitate working with configuration files.

These tags work with Upsun Cloud configuration files, but may not elsewhere.

## Include

Use the `!include` tag to embed external files within a given YAML file.

The tag requires two properties:

| Property | Type | Possible values | Description |
| - | - | - | - |
| `type` | `string` | `string`, `binary`, or `yaml` | See the descriptions of [strings](#string), [binaries](#binary), and [YAML](#yaml). Defaults to `yaml`. |
| `path` | `string` | | The path to the file to include, relative to the application directory or `source.root`. |

<Info>
  By default, `path` is relative to the current application's directory (what you would define with `source.root`).
  It is possible to include files from a directory parent to the folder however.

  For example, for the following project structure:

  ```text theme={null}
  .
  ├── .upsun/
  |   └── .upsun/config.yaml
  ├── backend
  │   ├── main.py
  │   ├── requirements.txt
  │   └── scripts
  │       ├── ...
  │       └── common_build.sh
  └── frontend
      ├── README.md
      ├── package-lock.json
      ├── package.json
      ├── public
      ├── scripts
      │   └── clean.sh
      └── src
  ```

  This configuration is valid:

  ```yaml .upsun/config.yaml theme={null}
  applications:
    frontend:
      source:
        root: frontend

      # ...

      hooks:
        build: !include
          type: string
          path: ../backend/scripts/common_build.sh
  ```
</Info>

### `string`

Use `string` to include an external file inline in the YAML file as if entered as a multi-line string.

For example, if you have a build hook like the following:

```yaml .upsun/config.yaml theme={null}
applications:
  myapp:
    hooks:
      build: |
        set -e
        cp a.txt b.txt
```

You could create a file for the script:

```text build.sh theme={null}
set -e
cp a.txt b.txt
```

And replace the hook with an include tag for an identical result:

```yaml .upsun/config.yaml theme={null}
applications:
  myapp:
    hooks:
      build: !include
        type: string
        path: build.sh
```

This helps you break longer configuration like build scripts out into a separate file for easier maintenance.

Even if `path` is relative to the current application's directory, it is also possible to include a shell script from a directory parent to the folder however.

For example, for the following project structure:

```bash theme={null}
.
├── .upsun/
|   └── config.yaml
├── backend
│   ├── main.py
│   ├── requirements.txt
│   └── scripts
│       ├── ...
│       └── common_build.sh
└── frontend
    ├── README.md
    ├── package-lock.json
    ├── package.json
    ├── public
    ├── scripts
    │   └── clean.sh
    └── src
```

This configuration is valid:

```yaml .upsun/config.yaml theme={null}
applications:
  frontend:
    source:
      root: frontend
    # ...
    hooks:
      build: !include
        type: string
        path: ../backend/scripts/common_build.sh
```

<Info>
  Please note that Upsun Cloud will execute this `../backend/scripts/common_build.sh` script using [Dash](https://wiki.archlinux.org/title/Dash).
</Info>

### `binary`

Use `binary` to include an external binary file inline in the YAML file.
The file is base64 encoded.

For example, you could include a `favicon.ico` file in the same folder as your app configuration.
Then you can include it as follows:

```yaml .upsun/config.yaml theme={null}
some-property:
  favicon: !include
    type: binary
    path: favicon.ico
```

### `yaml`

Use `yaml` to include an external YAML file inline as if entered directly.
Because `yaml` is the default, you can use it without specifying the type.

For example, you could have your configuration for works defined in a `worker.yaml` file:

```yaml worker.yaml theme={null}
commands:
  start: python queue-worker.py
variables:
  env:
    type: worker
```

Then the following three configurations are exactly equivalent:

```yaml .upsun/config.yaml theme={null}
workers:
  queue1: !include "worker.yaml"
```

```yaml .upsun/config.yaml theme={null}
workers:
  queue1: !include
    type: yaml
    path: 'worker.yaml'
```

```yaml .upsun/config.yaml theme={null}
workers:
  queue1:
    commands:
      start: python queue-worker.py
    variables:
      env:
        type: worker
```

This can help simplify more complex files.

For [multiple application](/docs/configure-apps/multi-app) project, you can also include another `.upsun/apps/my-app.yaml` file in the main `.upsun/config.yaml`.

```yaml .upsun/apps/my-app.yaml theme={null}
source:
  root: "/"
type: "nodejs:18"
web:
  commands:
    start: "node index.js"
  upstream:
    socket_family: tcp
  locations:
    "/":
      passthru: true
```

and including it:

```yaml .upsun/config.yaml theme={null}
applications:
  myapp:
    !include ./apps/my-app.yaml
```

## Archive

Use the `!archive` tag for a reference to an entire directory specified relative to where the YAML file is.

For example, you might want to define a configuration directory for your [Solr service](/docs/add-services/solr).
You might do so as follows:

```yaml .upsun/config.yaml theme={null}
mysearch:
  type: solr:8.0
  configuration:
      conf_dir: !archive "solr/conf"
```

The `!archive` tag means that the value for `conf_dir` isn't the string `solr/conf` but the entire `solr/conf` directory.
This directory is in the `.upsun/` directory, since that's where the `.upsun/config.yaml` file is.
The `solr/conf` directory is then copied into the Upsun Cloud management system to use with the service.


# What YAML is
Source: https://developer.upsun.com/docs/core-concepts/yaml/what-is-yaml

An introduction to what YAML is and how to create and modify YAML files.

[YAML](https://en.wikipedia.org/wiki/YAML) is a human-readable format for data serialization.
This means it can be used for structured data, like what you can find in configuration files.

Some basic rules about YAML files:

* YAML files end in `.yaml`.
  Some other systems use the alternative `.yml` extension.
* YAML is case-sensitive.
* YAML is whitespace-sensitive and indentation defines the structure,
  but it doesn't accept tabs for indentation.
* Empty lines are ignored.
* Comments are preceded by an octothorpe `#`.

## Data types

YAML represents data through three primitive data structures:

* Scalars (strings/numbers/booleans)
* Mappings (dictionaries/objects)
* Sequences (arrays/lists)

### Scalars (strings/numbers/booleans)

The most straightforward data structure involves defining key–value pairs where the values are strings or integers.

So you could have a basic configuration for an app:

```yaml .upsun/config.yaml theme={null}
applications:
  myapp:
    type: "golang:1.18"
    source:
      root: /app
    hooks:
      build: ./build.sh
```

You can spot three key–value pairs:

| Key | Value |
| - | - |
| `type` | "golang:1.18" |
| `root` | root: /app |
| `build ` | ./build.sh |

You can define strings either with or without quotes, which can be single `'` or double `"`.
Quotes let you escape characters (if double) and make sure the value is parsed as a string when you want it.

For example, you might be representing version numbers and want to parse them as strings.
If you use `version: 1.10`, it's parsed as an integer and so is treated the same as `1.1`.
If you use `version: "1.10"`, it's parsed as a string and isn't treated as the same as `1.1`.

### Mappings (dictionaries/objects)

In addition to basic scalar values, each key can also represent a set of other key–value pairs.
So you can define entire dictionaries of pairs.

The structure of the mapping is determined by the indentation.
So children are indented more than parents and siblings have the same amount of indentation.
The exact number of spaces in the indentation isn't important, just the level relative to the rest of the map.

In contrast, when you define mappings, the order doesn't matter.

So you could expand the configuration from before to add another mapping:

```yaml .upsun/config.yaml theme={null}
applications:
  myapp:
    type: "golang:1.18"

    web:
      commands:
        start: ./bin/app
      locations:
        '/':
          passthru: true
          allow: false
```

This creates a `web` dictionary that has two dictionaries within it: `commands` and `locations`,
each with their own mappings:

* `web` → `commands` → `start: ./bin/app`
* `web` → `locations` → `'/'` → `passthru: true` and `allow: false`

### Sequences (arrays/lists)

In addition to maps defining further key–value pairs, you can also use sequences to include lists of information.

```yaml .upsun/config.yaml theme={null}
applications:
  myapp:
    web:
      locations:
        '/':
          index:
            - index.html
            - index.htm
          passthru: true
          allow: false
```

You can also define sequences using a flow syntax:

```yaml .upsun/config.yaml theme={null}
applications:
  myapp:
    web:
      locations:
        '/':
          index: [index.html, index.htm]
          passthru: true
          allow: false
```

In either case, you get a list of values within `index`:

`web` → `locations` → `'/'` → `index` → `index.html` and `index.htm`

## Define multi-line strings

If you have a long string that spans multiple lines, use a pipe `|` to preserve line breaks.
The new lines need to have at least the same indentation as the first
(you can add more indentation that's then preserved).

So you could add a multi-line string to a `build` key in the `hooks` map:

```yaml .upsun/config.yaml theme={null}
applications:
  myapp:
    hooks:
      build: |
        set -x -e
        cp a.txt b.txt
```

And the resulting value preserves the line break.
This lets you do things like enter small shell scripts within a YAML file.

`hooks` → `build` → `set -x -e` and `cp a.txt b.txt`

## Reuse content

YAML supports internal named references, known as anchors, which can be referenced using an alias.
This allows you to reuse YAML blocks in multiple places within a single file.

Define an anchor by adding `&<NAME>` to the start of a value, where `<NAME>` is a unique identifier.
The anchor represents this entire value.
Then refer to the anchor using `*<NAME>`.

The following example shows 4 different workers:

```yaml .upsun/config.yaml theme={null}
applications:
  myapp:
    # ...
    workers:
      queue1: &runner
        commands:
          start: python queue-worker.py
      queue2: *runner
      queue3:
        <<: *runner
```

All of the workers above are identical to each other.

Note that you need to place an alias with `<<:` at the same level as the other keys within that value.

## What's next

* See what Upsun Cloud makes possible with [custom tags](/docs/core-concepts/yaml/platform-yaml-tags).
* Read everything that's possible with YAML in the [YAML specification](https://yaml.org/spec/1.2.2/).
* See a [YAML file that explains YAML syntax](https://learnxinyminutes.com/docs/yaml/).


# Upsun Cloud YAML structure
Source: https://developer.upsun.com/docs/core-concepts/yaml/yaml-structure

A description of the YAML file for Upsun Cloud.

In addition to the [basic functions you should be familiar with](/docs/core-concepts/yaml/what-is-yaml), YAML structure is important.
Upsun Cloud accepts a specific structure for YAML configuration files.

## YAML file location

When you run the [`upsun project:init` command](/docs/get-started/here/configure), a default `config.yaml` file is generated in the `.upsun` folder. It contains the minimum default configuration based on your detected local stack.
This YAML file is located in your `.upsun` directory, at the root of your project source code, and is a good starting point before customization.

```text theme={null}
.
├── .upsun/
│   └── config.yaml
└── <SOURCE_CODE>
```

## Top-level keys

In the `config.yaml` file, there are three top-level YAML keys:

* `applications`: this section of the file contains all of your [app definitions](/docs/configure-apps/app-reference/single-runtime-image)

<Note>
  Note that `applications` is a **mandatory** top-level key to include in your `config.yaml` file.
</Note>

* `routes`: this section of the file contains all of your [route definitions](/docs/routes) (for each of your apps)
* `services`: this section of the file contains all of your [service definitions](/docs/add-services) (for each of your apps)

This looks like:

```yaml apps theme={null}
applications:
  myapp:
    ...

services:
  mariadb:
    type: mariadb:10.6 # All available versions are: 10.6, 10.5, 10.4, 10.3

routes:
  "https://{default}/":
    type: upstream
    upstream: "myapp:http"
```

Below these three top-level key sections, you can use any of the [available YAML tags](/docs/core-concepts/yaml/platform-yaml-tags) you need.

<Note>
  Any YAML files located at the first level of your `.upsun/` folder, at the root of your project source code, are taken in account. See [Rules on YAML files](#rules-on-yaml-files).
</Note>

## Rules on YAML files

The following rules apply to YAML files contained in the `.upsun/` folder:

* All the existing YAML files located at the first level of the `.upsun/` folder are taken into account.
* All the existing YAML files located at the first level of the `.upsun/` folder must feature the [mandatory top-level keys](#top-level-keys), and must contain a [valid YAML configuration](/docs/configure-apps/app-reference/single-runtime-image).
* All the YAML files in subdirectories of the `.upsun/` folder need to be [manually imported](/docs/core-concepts/yaml/platform-yaml-tags#include) and contain a [valid YAML configuration](/docs/configure-apps/app-reference/single-runtime-image).

<Warning>
  <h4>Warning</h4>
  When Upsun Cloud combines all the YAML files located at the first level of the `.upsun/` folder, only the top-level keys (`applications`, `services`, and `routes`) are merged. So if you define an app named `myapp` in two different YAML files, Upsun Cloud only takes the second one into account.

  Example:

  ```yaml .upsun/app.yaml theme={null}
  applications:
    myapp:
      type: nodejs:16
      source:
        root: folder1
      ...
  ```

  ```yaml .upsun/app-bis.yaml theme={null}
  applications:
    myapp:
      type: nodejs:20
      build:
        flavor: none
      ...
  ```

  Once Upsun Cloud has combined the two configuration files,
  the blended configuration will be the following:

  ```yaml YAML config result theme={null}
  applications:
    myapp:
      type: nodejs:20
      build:
        flavor: none
      ...
  ```

  Note that `source.root` (and any other `.upsun/app.yaml` parameters) will *not* be included in the final configuration.
</Warning>


# Access your site
Source: https://developer.upsun.com/docs/development/access-site

Find the URLs you can use to access your site via a web browser.


Once you have an environment running, you can view it in a web browser.
To find which URLs you can use to access your site, follow these steps:

<Tabs>
  <Tab title="In the Console">
    1. Select the project whose URLs you want to find.
    2. From the **Environment** menu, select an environment.
    3. Click **URLs**.

    Copy and paste any of these URLs into a web browser and access your site.
  </Tab>

  <Tab title="Using the CLI">
    1. Run the following command:

       ```bash theme={null}
       upsun url
       ```

    2. Select the URL to open in a browser.
  </Tab>
</Tabs>

For more information about URLs in your project and how you can control access to your web applications,
see how to [define routes](/docs/routes).


# Use Drush with Upsun Cloud
Source: https://developer.upsun.com/docs/development/drush

Install Drush, make it available on your path, and run Drush commands against your Drupal site on Upsun Cloud through the CLI, SSH, or hooks.


[Drush](https://www.drush.org/) is a command-line shell and scripting interface for Drupal.
On Upsun Cloud, you have several ways to run it: through the Upsun Cloud CLI, over SSH, or from within your app's hooks.
This guide covers how to install Drush, make it available on your path, and choose the right way to run it for your use case.

## Before you begin

You need:

* A [Drupal site](/tutorials/drupal) deployed on Upsun Cloud.
* The [Upsun Cloud CLI](/cli) installed and authenticated.

## 1. Install Drush

Add Drush to your project as a Composer dependency:

```bash theme={null}
composer require drush/drush
```

Drush needs a writable scratch space for its own caches and backups.
Define [mounts](/docs/configure-apps/image-properties/mounts) for both in your app configuration:

```yaml .upsun/config.yaml theme={null}
applications:
  myapp:
    mounts:
      '/.drush':
        source: storage
        source_path: 'drush'
      '/drush-backups':
        source: storage
        source_path: 'drush-backups'
```

## 2. Make Drush available on your path

Composer installs Drush to your project's `vendor/bin` directory, which isn't on your path by default.
This is what makes running `drush` directly return `drush: command not found`.

Add the following to a [`.environment` file](/docs/development/variables/set-variables#set-variables-via-script) at the root of your app so Drush (and any other Composer binary) is available whenever you connect:

```bash .environment theme={null}
if [ -n "$PLATFORM_APP_DIR" -a -f "$PLATFORM_APP_DIR"/composer.json ] ; then
  bin=$(composer config bin-dir --working-dir="$PLATFORM_APP_DIR" --no-interaction 2>/dev/null)
  export PATH="${PLATFORM_APP_DIR}/${bin:-vendor/bin}:${PATH}"
fi
```

## 3. Set the site URI

Many Drush commands (such as `drush uli` for one-time login links) need to know your site's URL.
Set `DRUSH_OPTIONS_URI` from your [routes](/docs/routes) in the same `.environment` file:

```bash .environment theme={null}
export PRIMARY_URL="$(echo "$PLATFORM_ROUTES" | base64 --decode | jq -r 'to_entries[] | select(.value.primary) | .key | rtrimstr("/")')"
export DRUSH_OPTIONS_URI="$PRIMARY_URL"
```

## Run Drush commands

There are three ways to run Drush commands against a deployed environment, depending on your use case.

### Using the CLI

The Upsun Cloud CLI has a built-in [`drush` alias](/cli/reference#environmentdrush) that runs a command against a remote environment without opening a full SSH session:

```bash theme={null}
upsun drush -- <COMMAND>
```

For example, to rebuild the cache on your current environment:

```bash theme={null}
upsun drush -- cache-rebuild
```

This is the fastest option for one-off commands, and it works the same way whether or not Drush is on your local machine.

<Note>
  The `upsun` CLI doesn't support generating Drush aliases, so you'll need to [set them up manually](#set-up-drush-aliases-manually).
  This is unlike the `platform` CLI, which includes a `local:drush-aliases` command for this.
</Note>

### Over SSH

To run Drush as part of a longer interactive session, [connect over SSH](/docs/development/ssh) and run Drush directly, or pass the command inline:

```bash theme={null}
upsun ssh -e feature -- drush -y cache-rebuild
```

Replace `feature` with the name of the environment you want to target.

#### Set up Drush aliases manually

A Drush alias lets you run `drush @myproject.main <COMMAND>` from your local machine without connecting over SSH first.
Since the Upsun Cloud CLI doesn't generate these for you, create them by hand:

1. Get the [SSH host and username](/docs/development/ssh#get-ssh-connection-details) for each environment you want an alias for:

   ```bash theme={null}
   upsun ssh --pipe --project <PROJECT_ID> --environment <ENVIRONMENT_NAME>
   ```

2. Get the environment's primary URL with the [`url` command](/cli/reference#environmenturl):

   ```bash theme={null}
   upsun url --primary --project <PROJECT_ID> --environment <ENVIRONMENT_NAME>
   ```

3. Create a site alias file at `drush/sites/<PROJECT_NAME>.site.yml` in your local repository, with one entry per environment:

   ```yaml drush/sites/myproject.site.yml theme={null}
   main:
     host: ssh.us.upsun.com
     user: abc123-main-7cs6q4a--app
     root: /app/web
     uri: 'https://www.example.com'
   feature:
     host: ssh.us.upsun.com
     user: abc123-feature-7cs6q4a--app
     root: /app/web
     uri: 'https://feature-abc123.upsun.app'
   ```

   `root` is your app's docroot on the remote environment, the same directory Drush runs from in [deploy hooks](#in-hooks).

4. Run commands against an alias instead of connecting manually:

   ```bash theme={null}
   drush @myproject.main cache-rebuild
   ```

You need to update the file whenever an environment is created, renamed, or deleted, since Upsun Cloud doesn't keep it in sync automatically.

### In hooks

To run Drush automatically on every deployment, add it to a [`deploy` or `post_deploy` hook](/docs/configure-apps/hooks/hooks-comparison).
This assumes Drush is already [on your path](#2-make-drush-available-on-your-path). Without that, the hook fails with `drush: command not found`:

```yaml .upsun/config.yaml theme={null}
applications:
  myapp:
    hooks:
      deploy: |
        cd /app/web
        if [ -n "$(drush status --field=bootstrap)" ]; then
          drush -y cache-rebuild
          drush -y updatedb
          if [ -n "$(ls $(drush php:eval "echo realpath(Drupal\Core\Site\Settings::get('config_sync_directory'));")/*.yml 2>/dev/null)" ]; then
            drush -y config-import
          fi
        fi
```

The `drush status --field=bootstrap` check confirms Drupal is installed and bootstraps successfully before running further commands,
which avoids failed deployments on a fresh environment that hasn't been installed yet.

## Common commands

The following Drush commands are frequently useful in an Upsun Cloud workflow:

| Command | Purpose |
| - | - |
| `drush cache-rebuild` (`drush cr`) | Rebuild all Drupal caches. |
| `drush updatedb` (`drush updb`) | Run pending database updates. |
| `drush config-import` (`drush cim`) | Import configuration from the sync directory. |
| `drush sql:sanitize` | Remove personally identifiable information from a database. See [sanitizing MariaDB with Drush](/docs/development/sanitize-db/mariadb#with-drupal-and-drush). |
| `drush uli` | Generate a one-time login link for an administrator. |
| `drush state:set` | Set a Drupal state value, useful for gating one-time deploy hook logic. |

## Troubleshooting

### `composer require drush/drush` fails

If Composer reports that it can't find `drush/drush`, or blocks the install over a security advisory, this is usually a version mismatch rather than a network issue:

* **Package not found**: Drush's minimum PHP requirement increases with each major version. If your app's PHP version is older than any available Drush release supports, Composer reports it as unable to find a matching package. Check your app's PHP version against [Drush's current requirements](https://www.drush.org/latest/install/), and pin to an older Drush major version if you can't upgrade PHP yet, for example `composer require drush/drush:^11`.
* **Security-advisory conflict**: If your `composer.json` includes a package like `roave/security-advisories`, it blocks installing versions with known vulnerabilities. Composer's error output names the exact conflicting package and version — upgrade Drush past that range to resolve it.

### `drush: command not found`

Confirm Drush is installed as a Composer dependency and that
[your path includes `vendor/bin`](#2-make-drush-available-on-your-path).

### A command returns the wrong domain

If a command that depends on the site URI (such as `drush uli`) returns the wrong domain or an error,
confirm [`DRUSH_OPTIONS_URI` is set](#3-set-the-site-uri) for the environment you're running against.

### Drush can't query the database on a multisite install

On a multisite Drupal install, running a bare `drush` command can fail with an error like the following:

```bash theme={null}
Command config-get was not found. Drush was unable to query the database.
```

This happens because Drush can't determine which site to target when there are multiple sites under your site directory (for example, `web/sites`).
Specify the site with the `-l` (`--uri`) flag. Despite the flag's name, use the site's subdirectory name (for example, `site1`), not a full URL:

```bash theme={null}
drush -l <SITE> <COMMAND>
```

To run the same command across every site, loop over each site directory:

```bash theme={null}
cd web/sites
for site in site1 site2 site3; do
  drush -l $site <COMMAND>
done
```

## See also

* [Deploy Drupal on Upsun Cloud](/tutorials/drupal)
* [Sanitizing databases: MariaDB and Drupal](/docs/development/sanitize-db/mariadb)
* [Connect securely with SSH](/docs/development/ssh)
* [`environment:drush` CLI reference](/cli/reference#environmentdrush)


# Send email from your Upsun Cloud environment using an SMTP proxy
Source: https://developer.upsun.com/docs/development/email

Configure outgoing email for your Upsun Cloud environment, improve deliverability with SPF and DKIM, and send test messages using the built-in SMTP proxy.

You can configure your Upsun Cloud environments to send emails through an SMTP proxy.

Emails aren't guaranteed to be deliverable and you can't white-label them.
The SMTP proxy is intended as a zero-configuration, best-effort service.

<Note>
  Each preview environment (a development or staging environment) has its own SendGrid sub-user, so the 12,000 email credits per calendar month limit applies individually per environment, not as a shared pool across your project.
</Note>

## 1. Turn on outgoing email

You can turn on outgoing email for each environment.
By default, email is turned on for your Production environment and blocked for other environments.

To turn it on for a specific environment, follow these steps:

<Tabs>
  <Tab title="In the Console">
    1. Select the project.
    2. Select the environment from the **Environment** menu.
    3. Click <SettingsIcon /> **Settings**.
    4. On the **General** tab, select the **Enable outgoing emails** checkbox.

    To turn off outgoing email, clear the **Enable outgoing emails** checkbox.
  </Tab>

  <Tab title="Using the CLI">
    To turn on outgoing email, run the following command:

    ```bash theme={null}
    upsun environment:info --environment <ENVIRONMENT_NAME> enable_smtp true
    ```

    To turn off outgoing email, replace `true` with `false`.
  </Tab>
</Tabs>

Changing the setting rebuilds the environment.

## 2. (Recommended) Improve deliverability

Improve deliverability of your email with [Sender Policy Framework (SPF)](https://www.twilio.com/docs/sendgrid/glossary/spf).
If you don't have an SPF record, add the following `TXT` record to your domain's DNS records:

```txt theme={null}
v=spf1 include:sendgrid.net -all
```

Having several, conflicting `TXT` records isn't supported due to [rfc4408 section 3.1.2](https://datatracker.ietf.org/doc/html/rfc4408#section-3.1.2).

If you already have an SPF record, add SendGrid to your existing record.

## 3. (Optional) Validate your email

You can request DomainKeys Identified Mail (DKIM) validation for your domain.

DKIM improves your delivery rate as an email sender.
Learn more about [how DKIM works](https://www.twilio.com/docs/sendgrid/glossary/dkim).

To have DKIM enabled for your domain:

1. Open a [support ticket](/docs/core-concepts/get-support) and request the following, replacing `<SENDER_EMAIL_ADDRESS>` with the address you send from:

   ```
   subject: DKIM record

   Hello,

   I'd like to request DKIM records to be generated for project <PROJECT_ID>. Emails are sent from the address <SENDER_EMAIL_ADDRESS>.

   Kind regards
   ```

   <Note>
     The DKIM domain might not be the same as your site domain (but it can be). DKIM needs to be generated on the domain of the `<SENDER_EMAIL_ADDRESS>` you provide above (the *sender* address), not necessarily your site's domain. For example, if `<SENDER_EMAIL_ADDRESS>` is `noreply@media.yourdomain.com`, request DKIM for `media.yourdomain.com`, not `yourdomain.com`.

     Make sure you've sent at least one email before requesting DKIM.
   </Note>

2. Add the `CNAME` and `TXT` records from the support team's reply to your domain's DNS configuration.

   The reply looks similar to the following:

   ```txt theme={null}
   em1._domainkey.yourdomain.com        CNAME   em1.domainkey.u99999999.wl999.sendgrid.net
   em12._domainkey.yourdomain.com       CNAME   em12.domainkey.u99999999.wl999.sendgrid.net
   em9999.yourdomain.com        CNAME   u99999999.wl999.sendgrid.net

   yourdomain.com       TXT     v=spf1 include:em9999.yourdomain.com
   ```

   This `TXT` record replaces the generic one from [step 2](#2-recommended-improve-deliverability) — as part of DKIM setup, SendGrid provides a unique SPF record for your domain instead of the generic one.

   Checks for the expected DNS records run every 15 minutes. After SendGrid detects the records, it confirms them automatically — you don't need to take any further action.

   <Note>
     SendGrid rotates DKIM keys on an internal schedule that it doesn't publish, and offers no manual rotation option — the process is entirely transparent to you.
   </Note>

## 4. Test the email service

To test the email service, use the [CLI](/cli) to connect to your app by running `upsun ssh`.
Run the following command:

```bash theme={null}
printf "From: <SENDER_EMAIL_ADDRESS>\nSubject: Test \nThis is a test message" | /usr/sbin/sendmail <RECIPIENT_EMAIL_ADDRESS>
```

Replace the variables with actual email addresses as in the following example:

```bash theme={null}
printf "From: someone@example.com\nSubject: Test \nThis is a test message" | /usr/sbin/sendmail someone@example.net
```

Check the recipient's inbox, including the spam folder — the test message should arrive within a few minutes.

<Warning>
  When sending emails from your project, use an address on the same domain you requested DKIM for (see the [domain note](#3-optional-validate-your-email) above), otherwise the message will be flagged as a spoofing attempt and not be sent.

  Also, **make sure to test with real email addresses**. If you send emails to fake domains (such as `example.com`), they fail and hurt your sending reputation. Make sure your test emails are deliverable.
</Warning>

## 5. Send email from your app

You can use `/usr/sbin/sendmail` on your app container to send emails as with the example in the previous step.
Or use the `PLATFORM_SMTP_HOST` environment variable in your SMTP configuration.

When outgoing emails are on, `PLATFORM_SMTP_HOST` is the address of the SMTP host that should be used.
When outgoing emails are off, the variable is empty.

When using `PLATFORM_SMTP_HOST`, send email through port 25 (often the default).
Your emails are proxied through the Upsun Cloud SMTP host and encrypted over port 465
before being sent to the outside world.

The precise way to send email depends on the language and framework you use.
The following examples show PHP and Java.

<Tabs>
  <Tab title="PHP">
    To send email in PHP, you can use the built-in [`mail()` function](https://www.php.net/manual/en/function.mail.php).
    The PHP runtime is configured to send email automatically with the correct configuration.
    This works even for libraries such as PHPMailer, which uses the `mail()` function by default.

    **The `From` header is required**. Your email will not be sent if the header is missing.

    Beware of potential security problems when using the `mail()` function.
    If you use any input from users in the `$additional_headers` or `$additional_params` parameters,
    be sure to sanitize it first.
  </Tab>

  <Tab title="Java">
    JavaMail is a Java API used to send and receive email through SMTP, POP3, and IMAP.
    JavaMail is built into the [Jakarta EE](https://jakarta.ee/) platform, but also provides an optional package for use in Java SE.

    [Jakarta Mail](https://projects.eclipse.org/projects/ee4j.mail) defines a platform-independent and protocol-independent framework to build mail and messaging applications.

    The following example sends email using Jakarta Mail:

    ```java theme={null}
    import sh.platform.config.Config;

    import javax.mail.Message;
    import javax.mail.MessagingException;
    import javax.mail.Session;
    import javax.mail.Transport;
    import javax.mail.internet.InternetAddress;
    import javax.mail.internet.MimeMessage;
    import java.util.Properties;
    import java.util.logging.Level;
    import java.util.logging.Logger;

    public class JavaEmailSender {

        private static final Logger LOGGER = Logger.getLogger(JavaEmailSender.class.getName());

        public void send() {
            Config config = new Config();
            String to = "";//change accordingly
            String from = "";//change accordingly
            String host = config.getSmtpHost();
            //or IP address
            //Get the session object
            Properties properties = System.getProperties();
            properties.setProperty("mail.smtp.host", host);
            Session session = Session.getDefaultInstance(properties);

            //compose the message
            try {
                MimeMessage message = new MimeMessage(session);
                message.setFrom(new InternetAddress(from));
                message.addRecipient(Message.RecipientType.TO, new InternetAddress(to));
                message.setSubject("Ping");
                message.setText("Hello, this is example of sending email  ");

                // Send message
                Transport.send(message);
                System.out.println("message sent successfully....");

            } catch (MessagingException exp) {
                exp.printStackTrace();
                LOGGER.log(Level.SEVERE, "there is an error to send an message", exp);
            }
        }
    }

    ```

    Guides on using JavaMail:

    * [Send email with HTML formatting and attachments](https://mkyong.com/java/java-how-to-send-email/)
    * [JavaMail API](https://javaee.github.io/javamail/)
  </Tab>
</Tabs>

## Alternative: Use a different email server

If you need more options, use your own SMTP server or email delivery service provider.
Remember that TCP port 25 is blocked for security reasons.
Use port 465 or 587 instead to send email to your own external email server.


# Exporting data
Source: https://developer.upsun.com/docs/development/exporting

See how to export your code, files and service data.

As an Upsun user, your code and data belong to you.
At any time, you can download your site's data for local development, to back up your data, or to change provider.

## Before you begin

You need:

* [Git](https://git-scm.com/downloads)
* An Upsun account
* Code in your project
* Optional: the [Upsun CLI](/cli)

## 1. Download your app's code

Your app's code is maintained through the Git version control system.

To download your entire app's code history:

<Tabs>
  <Tab title="Using the CLI">
    1. List all your projects by running the following command:

       ```bash theme={null}
       upsun projects
       ```

    2. Retrieve the project you want to back up by running the following command:

       ```bash theme={null}
       upsun get <PROJECT_ID>
       ```
  </Tab>

  <Tab title="Using Git">
    1. In the [Console](https://console.platformsh.site/), open your project and click **Code <ChevronIcon />**.
    2. Click **Git**.
    3. To copy the command, click **<CopyIcon /> Copy**.
       The command is similar to the following:

       ```bash theme={null}
       git clone abcdefgh1234567@git.eu.platformsh.site:abcdefgh1234567.git project-name
       ```
  </Tab>
</Tabs>

## 2. Download your files

Some files might not be stored in Git,
such as data your app writes [in mounts](/docs/configure-apps/image-properties/mounts).

You can download your files [using the CLI](/docs/development/file-transfer#transfer-files-using-the-cli) or [using SSH](/docs/development/file-transfer#transfer-files-using-an-ssh-client).

### Network Storage mounts

If your project uses a [Network Storage service](/docs/add-services/network-storage)
(mounts with `source: service`), the data lives in a dedicated service container rather than in the app container itself.
The download process is the same as for local mounts — use the CLI or rsync over SSH — but you need to target the path
as it is mounted inside the app container.

For example, to download a `web/uploads` network mount using the CLI:

```bash Terminal theme={null}
upsun mount:download --mount web/uploads --target ./local-uploads
```

## 3. Download data from services

The mechanism for downloading from each service varies.

For services designed to hold non-persistent data in memory only — such as [ephemeral Redis](/docs/add-services/redis#ephemeral-redis),
[ephemeral Valkey](/docs/add-services/valkey), [Memcached](/docs/add-services/memcached),
or [Solr](/docs/add-services/solr) —
it's generally not necessary to download data as it can be rebuilt from the primary data store.

For services designed to hold persistent data, see the instructions for each service below.

### Relational databases

* [MySQL / MariaDB](/docs/add-services/mysql#exporting-data)
* [PostgreSQL](/docs/add-services/postgresql#exporting-data)

### Document and time-series databases

* [MongoDB](/docs/add-services/mongodb#exporting-data)
* [InfluxDB](/docs/add-services/influxdb#export-data)
* [ClickHouse](/docs/add-services/clickhouse#exporting-data)

### Search engines

* [Elasticsearch](/docs/add-services/elasticsearch#exporting-data)
* [OpenSearch](/docs/add-services/opensearch#exporting-data)

### Key-value stores (persistent)

* [Redis (persistent)](/docs/add-services/redis#exporting-data-persistent)
* [Valkey (persistent)](/docs/add-services/valkey#exporting-data-persistent)

### Message brokers

* [RabbitMQ](/docs/add-services/rabbitmq#exporting-data)
* [Kafka](/docs/add-services/kafka#exporting-data)

### Vector databases

* [Qdrant](/tutorials/self-hosted/qdrant#exporting-data)
* [Chroma](/tutorials/self-hosted/chroma#exporting-data)

## 4. Get environment variables

Environment variables can contain critical information such as tokens or additional configuration options for your app.

Environment variables can have different prefixes:

* Variables beginning with `env:` are exposed [as Unix environment variables](/docs/development/variables#top-level-environment-variables).
* Variables beginning with `php:` are interpreted [as `php.ini` directives](/docs/development/variables#php-specific-variables).

All other variables are [part of `$PLATFORM_VARIABLES`](/docs/development/variables/use-variables#use-provided-variables).

To back up your environment variables:

<Tabs>
  <Tab title="Using the CLI">
    1. Get the variable's values by running the following command:

       ```bash theme={null}
       upsun ssh -- 'echo $PLATFORM_VARIABLES | base64 -d | jq'
       ```

       Note that you can also get all the environment variable values by running the following command:

       ```bash theme={null}
       upsun ssh -- env
       ```

    2. Store the data somewhere secure on your computer.
  </Tab>

  <Tab title="In the Console">
    1. In the [Console](https://console.platformsh.site/), open your project and click **<SettingsIcon />**.
    2. Click **Project Settings <ChevronIcon />**.
    3. Click **Variables** and access your variable's values and settings.
    4. Store the data somewhere secure on your computer.

    Note that in the Console, you can't access the value of variables that have been [marked as sensitive](/docs/development/variables/set-variables#variable-options).
    Use the CLI to retrieve these values.
  </Tab>
</Tabs>

## What's next

* Migrate data from elsewhere [into Upsun](/tutorials/migration).
* Migrate to [another region](/docs/projects/region-migration).
* To use data from an environment locally, export your data and set up your [local development environment](/docs/development/local).


# Transfer files to and from your app
Source: https://developer.upsun.com/docs/development/file-transfer



After your app is built, its file system is read-only.
This means that the only way you can edit your app's code is through Git.

However, you can transfer files to and from your built app without using Git.
To do so, you need to configure mounts or use an SSH client.

[Mounts](/docs/configure-apps/image-properties/mounts) let you set up directories that remain writable after the build is complete.
You can then transfer files directly to and from mounts inside your app
with a single command via the [Upsun Cloud CLI](/cli).

Alternatively, you can transfer files to and from your built app using an SSH client
such as `scp` or `rsync`.

## Transfer files using the CLI

### View the mounts inside your app

Before you start transferring files,
you may want to view a list of all the mounts inside your app.
To do so, run the following command:

```bash theme={null}
upsun mounts
```

The output is similar to the following:

```bash theme={null}
Mounts on abcdefgh1234567-main-abcd123--app@ssh.eu.upsun.com:
+-------------------------+----------------------+
| Mount path              | Definition           |
+-------------------------+----------------------+
| web/sites/default/files | source: storage      |
|                         | source_path: files   |
| private                 | source: storage      |
|                         | source_path: private |
| tmp                     | source: tmp          |
|                         | source_path: temp    |
+-------------------------+----------------------+
```

### Transfer a file to a mount

To transfer a file to a mount using the CLI, you can use the `mount:upload` command.

For example, to upload the files contained in the local `private` directory to the `private` mount,
run the following command:

```bash theme={null}
upsun mount:upload --mount private --source ./private
```

You get the following output:

```bash theme={null}
Uploading files from ./private to the remote mount private

Are you sure you want to continue? [Y/n]

  sending incremental file list
  example.sh

  sent 2.35K bytes  received 20 bytes  1.58K bytes/sec
  total size is 1.77M  speedup is 745.09
```

### Transfer a file from a mount

To transfer a file from a mount using the CLI, you can use the `mount:download` command.

For example, to download a file from the `private` mount to your local `private` directory,
run the following command:

```bash theme={null}
upsun mount:download --mount private --target ./private
```

You get the following output:

```bash theme={null}
Downloading files from the remote mount private to ./private

Are you sure you want to continue? [Y/n]

  receiving incremental file list
  example.sh

  sent 2.35K bytes  received 20 bytes  1.58K bytes/sec
  total size is 1.77M  speedup is 745.09
```

## Transfer files using an SSH client

Another way to transfer files to and from your built app is to use an SSH client such as [`scp`](#scp),
[`rsync`](#rsync), or [`sftp`](#sftp).

### scp

You can use `scp` to copy files to and from a remote environment.

For example, to download a `diagram.png` file from the `web/uploads` directory
(relative to the [app root](/docs/configure-apps/app-reference/single-runtime-image#root-directory)),
run the following command:

```bash theme={null}
scp "$(upsun ssh --pipe)":web/uploads/diagram.png .
```

The `diagram.png` file is copied to the current local directory.

To copy files from your local directory to the Upsun Cloud environment,
reverse the order of the parameters:

```bash theme={null}
scp diagram.png "$(upsun ssh --pipe)":web/uploads
```

For other options, see the [`scp` documentation](https://www.man7.org/linux/man-pages/man1/scp.1.html).

### rsync

You can use `rsync` to copy files to and from a remote environment.

For example, to copy all the files in the `web/uploads` directory on the remote environment
to the local `uploads` directory,
run the following command:

```bash theme={null}
rsync -azP "$(upsun ssh --pipe)":web/uploads/ ./uploads/
```

To copy files from your local directory to the Upsun Cloud environment,
reverse the order of the parameters:

```bash theme={null}
rsync -azP uploads/ "$(upsun ssh --pipe)":web/uploads/
```

Note that `rsync` is very sensitive about trailing `/` characters.

If you're using UTF-8 encoded files on macOS,
add the `--iconv=utf-8-mac,utf-8` flag to your `rsync` call.

For more options, consult the [rsync documentation](https://man7.org/linux/man-pages/man1/rsync.1.html).

### sftp

You can use `sftp` to copy files to and from a remote environment.

<Note>
  Upsun Cloud supports `sftp`, but the following limitations apply:

  * You can only create `sftp` accounts with an existing Upsun Cloud user and an SSH key.
    Custom users and passwords aren't supported.
  * `sftp` access cannot be limited to a specific directory.
    Instead, access is given to **the whole application directory** and its mounts.
</Note>

#### Open an `sftp` connection

Run the following command:

```bash theme={null}
sftp "$(upsun ssh --pipe)"
```

When prompted, select the project and environment you want to connect to.
The `sftp` connection is open once the `sftp>` prompt is displayed in your terminal.

#### Download a file

Say you want to download a `diagram.png` file from the `web/uploads` directory
(relative to the [app root](/docs/configure-apps/app-reference/single-runtime-image#root-directory)).
To do so, run the following command:

```
sftp> get web/uploads/diagram.png
```

The `diagram.png` file is copied to the current local directory.

#### Upload a file

Say you want to upload a `diagram.png` file to the `web/uploads` directory
(relative to the [app root](/docs/configure-apps/app-reference/single-runtime-image#root-directory)).
To do so, run the following command:

```bash theme={null}
sftp> put diagram.png web/uploads
```

For other options, see the [`sftp` documentation](https://man7.org/linux/man-pages/man1/sftp.1.html).


# HTTP Headers
Source: https://developer.upsun.com/docs/development/headers

Upsun Cloud adds a number of HTTP headers to both inbound and outbound messages. Most of your own headers are passed through untouched, but a short list of headers is overwritten or removed so your app can trust them.


## Request headers

Upsun Cloud adds the following HTTP headers to give the application information about the connection. These are stable and may be examined by the application as necessary.

* `X-Forwarded-Proto`: The protocol forwarded to the application, for example: `http`, `https`.
* `X-Client-IP`: The remote IP address of the request.
* `X-Client-SSL`: Set "on" only if the client is using SSL connection, otherwise the header isn't added.
* `X-Original-Route`: The route in `.upsun/config.yaml` which is used currently, for example: `https://{default}/`.
* `X-Forwarded-For`: The client IP appended to any value sent by the client. When the request comes through a CDN that Upsun Cloud supports, the header is replaced with the end-client IP instead.

## Headers overwritten or removed from requests

Upsun Cloud passes your application's request headers through, with the exceptions below. These headers are set from values Upsun Cloud determines itself, so a client can't spoof them and your application can trust them.

| HTTP header | What happens |
| - | - |
| `Client-Cdn`, `Client-Country`, `Client-Abuse-Score`, `Client-Asn` | Overwritten with the [classification data](#classification-data-headers) computed for the request, or removed when no data is available. Values sent by the client are always discarded. |
| `X-Forwarded-Proto`, `X-Client-IP`, `X-Client-SSL`, `X-Original-Route` | Overwritten with the values described in [request headers](#request-headers). |
| `Host` | Overwritten with the host Upsun Cloud matched the request on, which mitigates a class of attacks based on the `Host` header. |
| `X-Client-Verify`, `X-Client-DN`, `X-Client-Cert` | Any value the client sends is discarded. On HTTPS requests, `X-Client-Verify` is set to `SUCCESS` or `NONE`, and `X-Client-DN` and `X-Client-Cert` are added only when a client certificate was validated on a route that uses [mTLS](/docs/routes/https#enable-mtls). On plain HTTP requests, none of the three are sent. |
| `Proxy` | Always removed, to protect applications affected by [httpoxy](https://httpoxy.org). |
| `Authorization` | Removed on routes protected by [HTTP access control](/docs/environments/http-access-control), because Upsun Cloud consumes the credentials itself. |
| `Connection`, `Keep-Alive`, `Proxy-Authenticate`, `Proxy-Authorization`, `TE`, `Trailers`, `Transfer-Encoding`, `Upgrade` | Not forwarded, as these hop-by-hop headers apply to a single connection. Protocol upgrades such as [WebSocket](/docs/routes#websocket-routes) requests keep them. |

Repeated headers are also normalized into a single value. Most are joined with a comma and a space, `Cookie` is joined with a semicolon and a space, and headers that aren't lists, such as `Content-Type` or `Authorization`, keep only their first value.

## Response headers

Upsun Cloud adds a number of response headers automatically to assist in debugging connections. These headers should be treated as a semi-private API. Do not code against them, but they may be inspected to help determine how Upsun Cloud handled the request to aid in debugging.

* `X-Platform-Cache`: Either `HIT` or `MISS` to indicate if the router in your cluster served the response from its own cache or if the request was passed through to the application.
* `X-Platform-Cluster`: The ID of the cluster that received the request. The cluster name is formed from the project ID and environment ID.
* `X-Platform-Processor`: The ID of the container that generated the response. The container ID is the cluster ID plus the container name.
* `X-Platform-Router`: The ID of the router that served the request. The router ID is the processor ID of the router container, specifically.
* `X-Debug-Info`: This is a header added by the edge layer. It doesn't contain any sensitive information or anything that could be misused. It has no relation to the PHP debugging tool [Xdebug](https://xdebug.org).

## Headers overwritten or removed from responses

Your application's response headers reach the client unchanged, apart from the following.

| HTTP header | What happens |
| - | - |
| `Server` | Always removed, so the response doesn't advertise the software serving it. |
| `X-Accel-Expires`, `X-Accel-Redirect`, `X-Accel-Limit-Rate`, `X-Accel-Buffering`, `X-Accel-Charset` | Removed and ignored. These control Upsun Cloud's own infrastructure, so your application can't use them. |
| `Surrogate-Control` | Removed on routes with [server-side includes](/docs/routes/ssi) enabled, since Upsun Cloud acts on it. |
| `Strict-Transport-Security` | Overwritten when [HSTS](/docs/routes/https#enable-http-strict-transport-security-hsts) is configured on the route. |
| `X-Robots-Tag` | Overwritten with `noindex, nofollow` when [search engine visibility](/docs/environments/search-engine-visibility) is restricted on the environment. |
| `Connection`, `Keep-Alive`, `Proxy-Authenticate`, `Proxy-Authorization`, `TE`, `Trailers`, `Transfer-Encoding`, `Upgrade` | Not forwarded, as these hop-by-hop headers apply to a single connection. Responses to protocol upgrades keep them. |

Repeated response headers are normalized the same way as request headers, so send a single `Content-Type` or `Location` rather than several. `Set-Cookie` is the exception and keeps every value you send.

Upsun Cloud also ignores `Expires` when deciding whether to cache a response. The header still reaches the client, but use `Cache-Control` to control [caching](/docs/routes/cache).

## Classification data headers

Upsun Cloud sends classification data to your backend system through the following HTTP headers. Each of them is set from Upsun Cloud's own data, or removed when there's no data for the request, so you can rely on their values even if a client sends its own.

| HTTP header | Type | Description |
| - | - | - |
| `Client-Cdn` | string | When a CDN that is supported by Upsun Cloud is used, this header displays its name (Fastly, Cloudflare, or Cloudfront). |
| `Client-Country` | string | The two-character ISO 3166-1 country code of the end-client IP (after CDN handling for the CDNs that Upsun Cloud supports).<br /> The geolocation data sent through this header is provided by [MaxMind GeoLite2](https://dev.maxmind.com/geoip/geolite2-free-geolocation-data). |
| `Client-Abuse-Score` | integer | The abuse score of the end-client IP. A score >= 100 indicates a near certainty that the request comes from an abusive IP. The score can also be negative, so parse it as a signed integer rather than assuming it starts at zero. <br /> The abuse data sent through this header is provided by [AbuseIPDB](https://www.abuseipdb.com/). |
| `Client-Asn` | integer | The Autonomous System number of the end-client IP. <br /> The geolocation data sent through this header is provided by [MaxMind GeoLite2](https://dev.maxmind.com/geoip/geolite2-free-geolocation-data). |

## Custom headers

Apart from those listed above, your application is responsible for setting its own response headers.

You can also [add headers to static files](/docs/configure-apps/web/custom-headers).


# Use DDEV for local development
Source: https://developer.upsun.com/docs/development/local/ddev

Use DDEV to set up local development environments.

[DDEV](https://ddev.readthedocs.io/en/stable/) is an open-source tool for local development environments.
It allows you to use Docker in your workflows while maintaining a GitOps workflow.
You get fully containerized environments to run everything locally
without having to install tools (including the Upsun Cloud CLI, PHP, and Composer) on your machine.

Please see the [Upsun Integration docs on DDEV Docs](https://ddev.readthedocs.io/en/stable/users/providers/upsun/).


# Set up your local development environment
Source: https://developer.upsun.com/docs/development/local/index

Set up a local development environment to test out changes to your app's code.

To make changes to your app's code and test them without affecting your production environment,
set up a local development environment on your computer.

For the most effective testing, you want your local environment to match your Upsun Cloud environments.
The best way to do this is to use a cross-platform tool based on Docker.
This ensures the changes you make locally appear as they would on your Upsun Cloud environments.
It also means you don't have to worry about configuring your machine with
the various dependencies, certificates, and connections your app needs to run.

The **recommended tool** for local development with Upsun Cloud is **[DDEV](/docs/development/local/ddev)**.
The integration with DDEV is maintained by Upsun Cloud to ensure it works smoothly.

If you choose to use DDEV, follow the steps [on its page](/docs/development/local/ddev). Otherwise, follow these steps to run your app on your computer.

## Before you begin

You need to have:

* An Upsun account:
  new users can [register here](https://upsun.com/register/)
* A working project
* [Git](https://git-scm.com/downloads)
* The [Upsun Cloud CLI](/cli)

## 1. Get your code

If you don't have your app code on your computer, download a copy.

1. Get your project ID by running `upsun projects`.

2. Get the code by running the following command:

   ```bash theme={null}
   upsun get <PROJECT_ID> <TARGET_DIRECTORY_NAME>
   ```

   Or pull from your [integrated Git repository](/docs/integrations/source).

You can now access your code from the project directory on your computer.
The CLI created a `.upsun/config.yaml/local` directory that's excluded from Git.
It contains builds and local metadata about your project.

You can now make changes to your project without pushing to Upsun Cloud each time to test them.
Instead, you can locally build your application using the Upsun Cloud CLI.

Note that if your app contains services, you need to open an SSH tunnel to connect to them.
For more information, see how to [connect services](/docs/add-services#2-define-the-relationship).

## 2. Connect to services

If your app requires services to run, you have two options for developing locally:

* [Tethered local development](/docs/development/local/tethered) involves running your app on a local web server
  but keeping all other services on Upsun Cloud and connecting to them over an SSH tunnel.
* [Untethered local development](/docs/development/local/untethered) involves running your entire site locally,
  including all services.

Choose the option that works for you and get your services running.


# Tethered local development
Source: https://developer.upsun.com/docs/development/local/tethered



To test changes locally, you can connect your locally running web server
to service containers on an active Upsun Cloud environment.
This method requires less configuration than tools such as [DDEV](/docs/development/local/ddev),
but may not perform well enough for everyday use.
Because it replies on a local web server, it's also less consistent across your team.

## Before you begin

You need:

* A local copy of the repository for a project running on Upsun Cloud.
  To get one, run `upsun get PROJECT_ID`.
  Alternatively, you can clone an integrated source repository and set the remote branch.
  To do so, run `upsun project:set-remote PROJECT_ID`.
* The [Upsun Cloud CLI](/cli)

## Create the tethered connection

1. Create a new environment based on production.

   ```bash theme={null}
   upsun branch new-feature <PRODUCTION_ENVIRONMENT_NAME>
   ```

   If you're using a [source integration](/docs/integrations/source),
   open a merge/pull request.

2. To open an SSH tunnel to the new environment's services, run the following command:

   ```bash theme={null}
   upsun tunnel:open
   ```

   This command returns the addresses for SSH tunnels to all of your services.

3. Export the `PLATFORMSH_RELATIONSHIPS` environment variable with information from the open tunnel:

   ```bash theme={null}
   export PLATFORM_RELATIONSHIPS="$(upsun tunnel:info --encode)"
   ```

4. Run your application locally.
   Make sure it's set up to read configuration from Upsun Cloud environment variables.

   If you app relies on other Upsun Cloud environment configuration, such as routes or secret variables,
   make sure to mock those variables as well.

   Your options for running the app depend on the language and configuration.
   You can use the server for your language, install a copy of Nginx,
   or use a virtual machine or Docker image.

5. When you've finished your work, close the tunnels to your services by running the following command:

   ```bash theme={null}
   upsun tunnel:close --all -y
   ```

## Connect to services directly

With open tunnels to all your services, you can also connect to the running services directly.
To get information on all running services, run the following command:

```bash theme={null}
upsun tunnels
```

You get a response similar to the following:

```bash theme={null}
+-------+---------------+-------------+-----+--------------+
| Port  | Project       | Environment | App | Relationship |
+-------+---------------+-------------+-----+--------------+
| 30000 | abcdefg123456 | new-feature | app | cache        |
| 30001 | abcdefg123456 | new-feature | app | database     |
+-------+---------------+-------------+-----+--------------+
```

You can use the port information to connect directly to a service.
If you need more detailed information, such as a path or password, run the following command:

```bash theme={null}
upsun tunnel:info
```

You can use the information returned to connect to the remote database as if it were local.
For example, the following command would connect to a MySQL database running through a tethered connection:

```bash theme={null}
mysql --host=127.0.0.1 --port=<PORT> --user=<USERNAME> --password=<PASSWORD> --database=<PATH>
```

## Next steps

You can now use your local environment to develop changes for review on Upsun Cloud environments.
The following examples show how you can take advantage of that.

### Onboard collaborators

It's essential for every developer on your team to have a local development environment to work on.
Place the local configuration into a script to ensure everyone has this.
You can merge this change into production.

1. Create a new environment called `local-config`.

2. To set up a local environment for a new Upsun Cloud environment, create an executable script.

   ```bash theme={null}
   touch init-local.sh && chmod +x init-local.sh
   ```

3. Fill it with something similar to the following example, depending on your app and configuration:

   ```bash init-local.sh theme={null}
   #!/usr/bin/env bash

   ENVIRONMENT=$1
   PARENT=$2

   # Create the new environment
   upsun branch $ENVIRONMENT $PARENT

   # Open a tunnel to the current environment
   upsun tunnel:open --no-interaction

   # Mock Upsun Cloud environment variables
   export PLATFORM_RELATIONSHIPS="$(upsun tunnel:info --encode)"

   # Add any other variables you need

   # If necessary, install dependencies here

   # Add the command to run the server
   ```

4. To commit and push the revisions, run the following command:

   ```bash theme={null}
   git add . && git commit -m "Add local configuration" && git push upsun local-config
   ```

5. Merge the change into production.

Once the script is merged into production,
any user can set up their local environment by running the following commands:

```bash theme={null}
upsun <PROJECT_ID>
cd <PROJECT_NAME>
./init-local.sh <PROJECT_ID> another-new-feature <PRODUCTION_ENVIRONMENT_NAME>
```


# Untethered local development
Source: https://developer.upsun.com/docs/development/local/untethered



It's possible to run your entire site locally on your computer.
That way you get better performance as there's no extra latency to connect to a remote database and doesn't require an active Internet connection to work.
But it does require running all necessary services (databases, search servers, and so on) locally.
These can be set up however you prefer, although Upsun recommends using a virtual machine to make it easier to share configuration between developers.

If you already have a development workflow in place that works for you, you can keep using it with virtually no changes.

To synchronize data from an environment on Upsun Cloud, consult the documentation for each [service](/docs/add-services).
Each service type has its own native data import/export process and Upsun Cloud doesn't get in the way of that.
It's also straightforward to [download user files](/docs/core-concepts/common-tasks/exporting) from your application using rsync.


# Pull code from a private Git repository
Source: https://developer.upsun.com/docs/development/private-repository

See how to pull code from a private Git repository into your Upsun Cloud build process.

To complete its build, your Upsun Cloud project may need to access pieces of code stored in private Git repositories.
Examples include themes, libraries, and modules.
Configure these repositories to grant access to your project.

To grant access to a private Git repository,
add the project's public SSH key to your Git repository's deploy keys.

## 1. Get your project's public key

1. In the Console, open the project you want.
2. Click **<SettingsIcon /> Settings**.
3. Under **Project settings**, click **Deploy key**.
4. Click **<CopyIcon /> Copy**.

<img alt="Deploy Key" />

## 2. Add the key to your repository in your Git provider

* [GitHub deploy key](https://docs.github.com/en/developers/overview/managing-deploy-keys#deploy-keys)
* [GitLab deploy key](https://docs.gitlab.com/ee/user/project/deploy_keys/#grant-project-access-to-a-public-deploy-key)
* [Bitbucket access key](https://support.atlassian.com/bitbucket-cloud/docs/configure-repository-settings/)

If you're only pulling code, the key doesn't need write permissions.

Now your Upsun Cloud project can access your private repository via SSH, including to add dependencies.

This means you can access the private repository through links like:
`git@<GIT_PROVIDER>:<PATH_OR_USERNAME>/<REPOSITORY>.git`.
For example, you can clone a repository in your [`build` hook](/docs/configure-apps/hooks):

You can also use [private repositories as submodules](/docs/development/submodules#use-private-git-repositories).

## Using multiple private GitHub repositories

GitHub requires a separate deploy key for each repository.
To grant your project access to multiple repositories, create an automated user account, known as a machine user, with its own SSH key.

You can then add the machine account as collaborator to specific repositories
or to a team with access to the repositories.

See more information about [machine users on GitHub](https://docs.github.com/en/developers/overview/managing-deploy-keys#machine-users).


# Regions
Source: https://developer.upsun.com/docs/development/regions

See information about Upsun Cloud regions, including their environmental impact and IP addresses.

Upsun Cloud offers several regions for hosting project data.
You can choose a region based on criteria such as its closeness to your users and its environmental impact.

## Environmental impact

Whenever you create a project with us, we provide information about the [carbon intensity level](https://upsun.com/greener-hosting/) of the region you are choosing.
This number indicates if the area is "greener", meaning if the local electric grid relies on high-carbon energy sources or not.
We consider a region as "greener" when the carbon intensity number is below 100 CO2e/kWh.
When choosing a region with a lower carbon intensity number, you are choosing greener sources of energy behind the data center electricity consumption, like renewables or nuclear power.
And we offer a 3% discount for this sustainable choice ([estimate your discount](#greener-region-discount)).

This carbon intensity data is sourced from the annual averages provided by the [IEA](https://www.iea.org/) and [ElectricityMaps](https://www.electricitymaps.com/).
If you want to see real-time emissions generated by each power grid, we recommend checking out [ElectricityMaps](https://app.electricitymap.org/map) live data.

Summary of data being used in Upsun Cloud's Region Picker when creating a new Project:

| Source | Last update of this page |
| - | - |
| We usually consider a region "greener" when it has a carbon density \<100 CO2e/kWh. Carbon intensity data sourced from IEA 2024, ElectricityMaps 2025. While ElectricityMaps give us more granularity for certain regions, we tend to favor IEA databases, as they are the most recognized on the market. | 8 April 2026 |

Information on carbon intensity is also available in the Upsun Cloud API.
For example, to get a list of the regions and their carbon intensities, run the following command:

```bash theme={null}
upsun api:curl regions | jq -r '.regions[] | select(.available != false) | "\(.label): \(.environmental_impact.carbon_intensity)"'
```

See all available information in the [API documentation](https://api.platform.sh/docs/#tag/Regions).

### Carbon Emissions dashboard

The [carbon emissions dashboard](https://upsun.com/blog/carbon-emissions-dashboard/) provides an overview of the yearly carbon footprint associated with your cloud resource usage.
Leveraging real usage data from the cloud bills provided by AWS, GCP and Azure, we partnered with the third-party climate experts Greenly to develop our own methodology to estimate your cloud emissions.
Users can view total emissions and project specific emissions (in kg CO2e) for the past year.

#### Access the dashboard

This dashboard is accessible via the Emissions tab within the Billing section in Console.

#### How is this calculated?

We collect detailed billing data from our cloud service providers (including associated costs and quantities) and this information is represented as line items.

Greenly, our climate expert partner for this project, calculates the energy use and embodied emissions for each line item. This is done through data gathering and modeling that estimates energy consumption, power usage effectiveness (PUE), and carbon intensity for the cloud providers. Using cost allocation models, your project’s share of emissions is then estimated.

We have been working closely with Greenly to build upon the model, tailoring it to better reflect our specific data and technical requirements to ensure your emissions data is credible, compliant and supports your progress toward real, measurable sustainability targets.

<Warning>
  Only AWS, GCP and Azure data are available in this dashboard.  Other providers are not covered by this analysis.
</Warning>

#### What affects emissions?

* **Where you run:** Data center regions vary greatly in grid-carbon intensity. Selecting a cleaner region is the most impactful way to reduce footprint.

* **What you provision:** Emissions rise in proportion to the resources you allocate.

<Tip>
  Optimizing code or app performance reduces emissions only if it leads to lower resource allocation.
</Tip>

### Greener Region Discount

You can get a 3% discount on your resource usage if you host your project in one of Upsun Cloud's eco-friendly regions:

* Gravelines, France (`fr-3.platform.sh`)
* Montreal, Canada (`ca-1.platform.sh`)
* Moses Lake, United States (`us-3.platform.sh`)
* Paris, France (`fr-4.platform.sh`)
* Stockholm, Sweden (`eu-5.platform.sh`)
* Zurich, Switzerland (`ch-1.platform.sh`)

The 3% discount covers application CPU, application memory, service CPU, service memory, and build resources.
It **doesn’t** apply to the project fee or other billing aspects.
It can be combined with other offers or discounts.

See [more information on the greener region discount](https://upsun.com/blog/announcing-greener-region-discount/).

## Region availability

The regions listed here may be different from those available to you when you create a new project.
Each organization can have its own rules for what regions to allow.
When adding a new project, you only see regions allowed by your organization.

## Region location

<RegionsLocationTable />

<Info>
  As an alternative, you can also browse the full region list at [https://meta.upsun.com/regions](https://meta.upsun.com/regions).

  You can also use the following command with the Upsun Cloud CLI to find out where a given region is hosted:

  ```bash theme={null}
  upsun api:curl regions | jq '.regions[] | select(.available)  | .id + ": " + .provider.name + " - " + .zone + " - " + .timezone' | sort
  ```

  The returned list contains, for each available region, its name, provider, geographic zone and its timezone - as shown above.
</Info>

## Public IP addresses

The public IP addresses for regions are stable, but not guaranteed to never change.
Before any change, you are notified well in advance regarding affected projects.

They're useful for cases such as when you have a corporate firewall that blocks outgoing SSH connections.
In such cases, add the inbound IP addresses for your region to your allow list.

## Regions

### <img alt="Australia flag" /> Australia

**au.platform.sh** — `Australia (au)`

Outbound IPs:

* `13.54.121.225`
* `13.55.135.0`
* `13.55.215.151`

Inbound IPs (via `gw.au.platformsh.site`):

* `13.54.222.56`
* `13.54.88.239`
* `13.55.140.143`

***

**au-2.platform.sh** — `Australia (au-2)`

Outbound IPs:

* `104.210.116.116`
* `104.210.117.92`
* `40.126.245.226`

Inbound IPs (via `gw.au-2.platformsh.site`):

* `20.191.224.199`
* `20.92.240.236`
* `20.92.240.74`

### <img alt="Canada flag" /> Canada

**ca-1.platform.sh** — `Canada (ca-1)`

Outbound IPs:

* `35.182.220.113`
* `35.182.24.224`
* `52.60.213.255`

Inbound IPs (via `gw.ca-1.platformsh.site`):

* `35.182.174.169`
* `35.182.59.77`
* `52.60.219.22`

### <img alt="Europe flag" /> Europe

**ch-1.platform.sh** — `Switzerland (ch-1)`

Outbound IPs:

* `34.65.144.16`
* `34.65.197.163`
* `34.65.72.28`

Inbound IPs (via `gw.ch-1.platformsh.site`):

* `34.65.152.61`
* `34.65.236.213`
* `34.65.244.185`

***

**de-2.platform.sh** — `Germany (de-2)`

Outbound IPs:

* `34.107.79.7`
* `34.159.181.149`
* `34.159.207.210`

Inbound IPs (via `gw.de-2.platformsh.site`):

* `35.242.229.239`
* `35.246.184.45`
* `35.246.248.138`

***

**eu.platform.sh** — `Europe - Ireland (eu)`

Outbound IPs:

* `54.72.94.105`
* `54.76.137.67`
* `54.76.137.94`

Inbound IPs (via `gw.eu.platformsh.site`):

* `54.76.136.188`
* `54.76.137.151`
* `54.76.137.79`

***

**eu-5.platform.sh** — `Europe - Sweden (eu-5)`

Outbound IPs:

* `13.48.116.14`
* `13.48.202.56`
* `13.51.46.87`

Inbound IPs (via `gw.eu-5.platformsh.site`):

* `13.51.62.86`

***

**fr-3.platform.sh** — `France (fr-3)`

Outbound IPs:

* `135.125.89.47`
* `135.125.90.255`
* `135.125.91.125`

Inbound IPs (via `gw.fr-3.platformsh.site`):

* `94.23.123.122`

***

**fr-4.platform.sh** — `France (fr-4)`

Outbound IPs:

* `20.188.46.156`
* `20.188.46.158`
* `20.188.46.165`

Inbound IPs (via `gw.fr-4.platformsh.site`):

* `20.74.41.190`
* `20.74.41.218`
* `20.74.42.30`

***

**uk-1.platform.sh** — `United Kingdom (uk-1)`

Outbound IPs:

* `34.147.217.161`
* `34.89.33.176`
* `35.246.36.142`

Inbound IPs (via `gw.uk-1.platformsh.site`):

* `34.147.168.147`
* `35.189.126.202`
* `35.242.142.110`
* `35.242.183.249`

### <img alt="United States flag" /> United States

**us.platform.sh** — `United States - East (us)`

Outbound IPs:

* `54.209.114.37`
* `54.210.53.51`
* `54.88.149.31`

Inbound IPs (via `gw.us.platformsh.site`):

* `54.210.49.244`
* `54.210.55.162`
* `54.88.225.116`

***

**us-2.platform.sh** — `United States - East (us-2)`

Outbound IPs:

* `34.238.64.193`
* `52.4.246.137`
* `54.157.66.30`

Inbound IPs (via `gw.us-2.platformsh.site`):

* `34.226.46.235`
* `34.238.11.122`
* `54.89.106.200`

***

**us-3.platform.sh** — `United States - West (us-3)`

Outbound IPs:

* `40.91.69.215`
* `52.148.128.255`
* `52.250.13.106`

Inbound IPs (via `gw.us-3.platformsh.site`):

* `51.143.107.76`
* `52.137.90.183`
* `52.156.93.30`

***

**us-4.platform.sh** — `United States - East (us-4)`

Outbound IPs:

* `104.196.203.234`
* `34.148.171.57`
* `35.243.131.172`

Inbound IPs (via `gw.us-4.platformsh.site`):

* `34.73.189.215`
* `34.74.8.155`
* `34.75.104.115`


# Sanitize databases
Source: https://developer.upsun.com/docs/development/sanitize-db/index

Remove sensitive information from databases on preview environments to control access.

When working on a new feature on your website, you want to use a new branch.
Using a new branch makes sure that you don't risk breaking your live, production website.

Creating a branch on Upsun Cloud copies both the code and the database to that new development branch.
These code and database changes need to be tested before being merged into production.
Depending on your processes, internal or external teams may interact with the preview environment branch.

Databases of live websites often contain personally identifiable information (PII)
such as full names, mailing addresses, and phone numbers.
To ensure people reviewing code changes can't access information they shouldn't,
sanitize your databases of any PII that they may contain.

## Examples

<CardGroup>
  <Card title="MariaDB and Drupal" icon="database" href="/docs/development/sanitize-db/mariadb">
    Sanitize MariaDB data in preview environments directly or by using Drush.
  </Card>

  <Card title="PostgreSQL and Django" icon="database" href="/docs/development/sanitize-db/postgresql">
    Sanitize PostgreSQL data in preview environments for Django apps.
  </Card>

  <Card title="PostgreSQL and Symfony" icon="database" href="/docs/development/sanitize-db/postgresql-symfony">
    Sanitize PostgreSQL data in preview environments for Symfony apps.
  </Card>
</CardGroup>


# Sanitizing databases: MariaDB and Drupal
Source: https://developer.upsun.com/docs/development/sanitize-db/mariadb

Sanitize MariaDB data in preview environments directly or by using Drush.

Databases of live websites often contain personally identifiable information (PII)
such as full names, mailing addresses, and phone numbers.
To ensure people reviewing code changes can't access information they shouldn't,
sanitize your databases of any PII that they may contain.

This example goes through the process for a MySQL database using Drupal.

## Before you begin

You need:

* A project with a [MySQL database](/docs/add-services/mysql).
* A command interface installed:
  * If doing it manually, the [Upsun Cloud CLI](/cli).
  * Otherwise, make sure [Drush](https://www.drush.org/latest/install/) is installed in your environment.

This guide is about sanitizing MySQL databases.

This guide doesn't address:

* Sanitizing NoSQL Databases (such as [MongoDB](/docs/add-services/mongodb))
* Input validation and input sanitization, which both help prevent security vulnerabilities

## Sanitize the database

Make sure that you only sanitize preview environments and **never** the production environment.
Otherwise you may lose most or even all of the relevant data stored in your database.

First, take a [database dump](/docs/add-services/mysql#exporting-data) of your preview environment.
This is just a safety precaution.
Production data isn't altered.
To get a database dump, run the following command:

`upsun db:dump -e DEVELOPMENT_ENVIRONMENT_NAME`.

<Tabs>
  <Tab title="Manually">
    Assumptions:

    * `users` is the table where all of your PII is stored in the `staging` development database.
    * `staging` is an exact copy of your production database.

    1. Connect to the `staging` database by running `upsun sql -e staging`.

    2. Display all fields from your `users` table, to select which ones need to be redacted. Run the following query:

       ```sql theme={null}
       MariaDB [main]> SELECT * FROM users;
       ```

       You see output like the following:

       ```sql theme={null}
       +----+------------+---------------+---------------------------+---------------+
       | ID | first_name | last_name     | user_email                | display_name  |
       +----+------------+---------------+---------------------------+---------------+
       |  1 | admin      | admin         | admin@yourcompany.com     | admin         |
       |  2 | john       | doe           | john.doe@gmail.com        | john          |
       |  3 | jane       | doe           | janedoe@ymail.com         | jane          |
       +----+------------+---------------+---------------------------+---------------+
       ```

    3. Change the fields where PII is contained with the [`UPDATE` statement](https://mariadb.com/kb/en/update/).
       For example, to change the display name of users with an email address not in your company's domain
       to a random value, run the following query:

       ```sql theme={null}
       UPDATE users
       SET display_name==substring(md5(display_name||'$PLATFORM_PROJECT_ENTROPY') for 8);
       WHERE email NOT LIKE '%@yourcompany%'
       ```

       Adapt and run that query for all fields that you need to sanitize.
       If you modify fields that you shouldn't alter, [you can restore them](/docs/environments/restore) from the dump you took in step 1.

       You can create a script to automate the sanitization process to be run automatically on each new deployment.
       Once you have a working script, add your script to sanitize the database to [a `deploy` hook](/docs/configure-apps/hooks/hooks-comparison#deploy-hook):

       ```yaml theme={null}
       applications:
           myapp:

               # ...

               hooks:
                   deploy: |

                       # ...

                       cd /app/public
                       if [ "$PLATFORM_ENVIRONMENT_TYPE" = production ]; then
                           # Do whatever you want on the production site.
                       else
                           # The sanitization of the database should happen here (since it's non-production)
                           sanitize_the_database.sh
                       fi
       ```
  </Tab>

  <Tab title="With Drupal and Drush">
    To sanitize your database and get rid of sensitive, live information, use the `drush sql:sanitize` command.
    Add your script to sanitize the database to [a `deploy` hook](/docs/configure-apps/hooks/hooks-comparison#deploy-hook)
    for preview environments:

    ```yaml .upsun/config.yaml theme={null}
    applications:
      myapp:
        hooks:
          deploy: |

            # ...

            cd /app/public
            if [ "$PLATFORM_ENVIRONMENT_TYPE" = production ]; then
              # Do whatever you want on the production site.
            else
              drush -y sql:sanitize
            fi
            drush -y updatedb
    ```

    More options are available.
    These are described in the [Drush documentation](https://www.drush.org/latest/commands/sql_sanitize/).

    To sanitize only on the initial deploy and not all future deploys,
    use [Drush state](https://www.drush.org/latest/commands/state_set/) as in the following example:

    ```yaml .upsun/config.yaml theme={null}
    applications:
      myapp:
        hooks:
          deploy: |

            # ...

            cd /app/public
            if [ "$PLATFORM_ENVIRONMENT_TYPE" = production ] || [ "$(drush state:get --format=string mymodule.sanitized)" != yes ]; then
              # Do whatever you want on the production site.
            else
              drush -y sql:sanitize
              drush state:set --input-format=string mymodule.sanitized yes
            fi
    ```
  </Tab>
</Tabs>

## What's next

You learned how to remove sensitive data from a database.

To replace sensitive data with other meaningful data, you can add a `faker` to the process.
A `faker` is a program that generates fake data that looks real.
Having meaningful PII-free data allows you to keep your current Q\&A, external reviews, and other processes.
To add a faker, adapt your sanitizing queries to replace each value that contains PII with a new value generated by the faker.

You might also want to make sure that you [implement input validation](https://cheatsheetseries.owasp.org/cheatsheets/Input_Validation_Cheat_Sheet.html#goals-of-input-validation).

If your database contains a lot of data, consider using the [`OPTIMIZE TABLE` statement](https://mariadb.com/kb/en/optimize-table/)
to reduce its size and help improve performance.


# Sanitizing databases: PostgreSQL and Django
Source: https://developer.upsun.com/docs/development/sanitize-db/postgresql

Sanitize PostgreSQL data in preview environments for Django apps.

Databases of live websites often contain personally identifiable information (PII)
such as full names, mailing addresses, and phone numbers.
To ensure people reviewing code changes can't access information they shouldn't,
sanitize your databases of any PII that they may contain.

This example goes through the process for a PostgreSQL database using Django.

## Before you begin

You need:

* A project with a [PostgreSQL database](/docs/add-services/postgresql).
* A command interface installed:
  * If doing it manually, the [Upsun Cloud CLI](/cli).
  * Otherwise, make sure `pqsl` is installed in your environment.

This guide is about sanitizing PostgreSQL databases.

This guide doesn't address:

* Sanitizing NoSQL Databases (such as [MongoDB](/docs/add-services/mongodb))
* Input validation and input sanitization, which both help prevent security vulnerabilities

## Sanitize the database

Make sure that you only sanitize preview environments and **never** the production environment.
Otherwise you may lose most or even all of the relevant data stored in your database.

First, take a [database dump](/docs/add-services/postgresql#exporting-data) of your preview environment.
This is just a safety precaution.
Production data isn't altered.
To get a database dump, run the following command:

`upsun db:dump -e DEVELOPMENT_ENVIRONMENT_NAME`.

<Tabs>
  <Tab title="Manually">
    Assumptions:

    * `users` is the table where all of your PII is stored in the `staging` development database.
    * `staging` is an exact copy of your production database.

    1. Connect to the `staging` database by running `upsun sql -e staging`.

    2. Display all fields from your `users` table, to select which ones need to be redacted. Run the following query:

       ```sql theme={null}
       main=> SELECT * FROM users;
       ```

       You see output like the following:

       ```sql theme={null}
       id   |                user_email               |     display_name
       -----+-----------------------------------------+-----------------------
       3501 | daniel02@yourcompany.com                | Jason Brown
       3502 | ismith@kim.com                          | Sandra Griffin
       3503 | olee@coleman-rodriguez.com              | Miss Christine Morgan
       ```

    3. Change the fields where PII is contained with the [`UPDATE` statement](https://mariadb.com/kb/en/update/).
       For example, to change the display name of users with an email address not in your company's domain
       to a random value, run the following query:

       ```sql theme={null}
       UPDATE users
       SET display_name==substring(md5(display_name||'$PLATFORM_PROJECT_ENTROPY') for 8);
       WHERE email NOT LIKE '%@yourcompany%'
       ```

       Adapt and run that query for all fields that you need to sanitize.
       If you modify fields that you shouldn't alter, [you can restore them](/docs/environments/restore) from the dump you took in step 1.

       You can create a script to automate the sanitization process to be run automatically on each new deployment.
       Once you have a working script, add your script to sanitize the database to [a `deploy` hook](/docs/configure-apps/hooks/hooks-comparison#deploy-hook):

       ```yaml theme={null}
       applications:
           myapp:

               # ...

               hooks:
                   deploy: |

                       # ...

                       cd /app/public
                       if [ "$PLATFORM_ENVIRONMENT_TYPE" = production ]; then
                           # Do whatever you want on the production site.
                       else
                           # The sanitization of the database should happen here (since it's non-production)
                           sanitize_the_database.sh
                       fi
       ```
  </Tab>

  <Tab title="Using a script with Django and `psql`">
    Assumptions:

    * `users` is the table where all of your PII is stored in the `staging` development database.
    * `database` is the relationship name for the PostgreSQL service.

    Set up a script by following these steps:

    1. Retrieve service credentials from the [service environment variables](/docs/development/variables#service-environment-variables) to use the `psql` command interface.
       Export these values to a [`.environment` file](/docs/development/variables/set-variables#set-variables-via-script)
       or include them directly in the sanitization script.

       ```bash .environment theme={null}
       # Pull credentials from the service environment variables.
       export DB_USER="${DATABASE_USERNAME}"
       export DB_HOST="${DATABASE_HOST}"
       export DB_PORT="${DATABASE_PORT}"
       export DB_PASS="${DATABASE_PASSWORD}"
       ```

    2. Create an executable sanitizing script by running the following command:

       ```bash theme={null}
       touch sanitize.sh && chmod +x sanitize.sh
       ```

    3. Make the script sanitize environments with an [environment type](/docs/administration/users#environment-type-roles)
       other than `production`.

       The following example runs only in preview environments
       and sanitizes the `display_name` and `email` columns of the `users` table.
       Adjust the details to fit your data.

       ```bash sanitize.sh theme={null}
       #!/usr/bin/env bash

       if [ "$PLATFORM_ENVIRONMENT_TYPE" != production ]; then
           # Sanitize data
           PGPASSWORD=$DB_PASS psql -c "UPDATE users SET display_name=substring(md5(display_name||'$PLATFORM_PROJECT_ENTROPY') for 8);" -U $DB_USER -h $DB_HOST -p $DB_PORT
           PGPASSWORD=$DB_PASS psql -c "UPDATE users SET email=substring(md5(email||'$PLATFORM_PROJECT_ENTROPY') for 8);" -U $DB_USER -h $DB_HOST -p $DB_PORT
       fi
       ```

       To sanitize only on the initial deploy and not all future deploys,
       on sanitization create a file on a [mount](/docs/configure-apps/image-properties/mounts).
       Then add a check for the file as in the following example:

       ```bash sanitize.sh theme={null}
       #!/usr/bin/env bash

       if [ "$PLATFORM_ENVIRONMENT_TYPE" != production ] && [ ! -f <MOUNT_PATH>/is_sanitized ]; then
           # Sanitize data
           touch <MOUNT_PATH>/is_sanitized
       fi
       ```

    4. Update the deploy hook to run your script on each deploy.

       ```yaml .upsun/config.yaml theme={null}
       applications:
         myapp:
           hooks:
             build: ...
             deploy: |
               python manage.py migrate
               bash sanitize.sh
       ```

    5. Commit your changes by running the following command:

       ```bash theme={null}
       git add .environment sanitize.sh .upsun/config.yaml&& git commit -m "Add sanitization."
       ```

       Push the changes to `staging` and verify that environment's database was sanitized.
       Once merged to production, all data from future preview environments are sanitized on environment creation.
  </Tab>
</Tabs>

## What's next

You learned how to remove sensitive data from a database.

To replace sensitive data with other meaningful data, you can add a `faker` to the process.
A `faker` is a program that generates fake data that looks real.
Having meaningful PII-free data allows you to keep your current Q\&A, external reviews, and other processes.
To add a faker, adapt your sanitizing queries to replace each value that contains PII with a new value generated by the faker.

You might also want to make sure that you [implement input validation](https://cheatsheetseries.owasp.org/cheatsheets/Input_Validation_Cheat_Sheet.html#goals-of-input-validation).

If your database contains a lot of data, consider using the [`REINDEX` statement](https://www.postgresql.org/docs/current/sql-reindex.html) to help improve performance.


# Sanitizing databases: PostgreSQL and Symfony
Source: https://developer.upsun.com/docs/development/sanitize-db/postgresql-symfony

Sanitize PostgreSQL data in preview environments for Symfony apps.

Databases of live websites often contain personally identifiable information (PII)
such as full names, mailing addresses, and phone numbers.
To ensure people reviewing code changes can't access information they shouldn't,
sanitize your databases of any PII that they may contain.

This example goes through the process for a PostgreSQL database using Symfony.

## Before you begin

You need:

* A project with a [PostgreSQL database](/docs/add-services/postgresql).
* A command interface installed:
  * If doing it manually, the [Symfony CLI](https://symfony.com/download).
  * Otherwise, make sure `pqsl` is installed in your environment.

This guide is about sanitizing PostgreSQL databases.

This guide doesn't address:

* Sanitizing NoSQL Databases (such as [MongoDB](/docs/add-services/mongodb))
* Input validation and input sanitization, which both help prevent security vulnerabilities

## Sanitize the database

Make sure that you only sanitize preview environments and **never** the production environment.
Otherwise you may lose most or even all of the relevant data stored in your database.

First, take a [database dump](/docs/add-services/postgresql#exporting-data) of your preview environment.
This is just a safety precaution.
Production data isn't altered.
To get a database dump, run the following command:

`symfony db:dump -e DEVELOPMENT_ENVIRONMENT_NAME`.

<Tabs>
  <Tab title="Manually">
    Assumptions:

    * `users` is the table where all of your PII is stored in the `staging` development database.
    * `staging` is an exact copy of your production database.

    1. Connect to the `staging` database by running `symfony sql -e staging`.

    2. Display all fields from your `users` table, to select which ones need to be redacted. Run the following query:

       ```sql theme={null}
       main=> SELECT * FROM users;
       ```

       You see output like the following:

       ```sql theme={null}
       id   |                user_email               |     display_name
       -----+-----------------------------------------+-----------------------
       3501 | daniel02@yourcompany.com                | Jason Brown
       3502 | ismith@kim.com                          | Sandra Griffin
       3503 | olee@coleman-rodriguez.com              | Miss Christine Morgan
       ```

    3. Change the fields where PII is contained with the [`UPDATE` statement](https://mariadb.com/kb/en/update/).
       For example, to change the display name of users with an email address not in your company's domain
       to a random value, run the following query:

       ```sql theme={null}
       UPDATE users
       SET display_name==substring(md5(display_name||'$PLATFORM_PROJECT_ENTROPY') for 8);
       WHERE email NOT LIKE '%@yourcompany%'
       ```

       Adapt and run that query for all fields that you need to sanitize.
       If you modify fields that you shouldn't alter, [you can restore them](/docs/environments/restore) from the dump you took in step 1.

       You can create a script to automate the sanitization process to be run automatically on each new deployment.
       Once you have a working script, add your script to sanitize the database to [a `deploy` hook](/docs/configure-apps/hooks/hooks-comparison#deploy-hook):

       ```yaml theme={null}
       applications:
           myapp:

               # ...

               hooks:
                   deploy: |

                       # ...

                       cd /app/public
                       if [ "$PLATFORM_ENVIRONMENT_TYPE" = production ]; then
                           # Do whatever you want on the production site.
                       else
                           # The sanitization of the database should happen here (since it's non-production)
                           sanitize_the_database.sh
                       fi
       ```
  </Tab>

  <Tab title="Using a Symfony Command">
    Assumptions:

    * An Entity User exist and contains all of your PII (Personally Identifiable Information)
    * [fakerphp/faker](https://fakerphp.github.io/) has been installed as a dependency on your Symfony application

    Set up a script by following these steps:

    1. Create a Symfony command to sanitize data

       ```php src/Command/SanitizeDataCommand.php theme={null}
       <?php
       namespace App\Command;

       use App\Entity\User;
       use App\Repository\UserRepository;
       use Doctrine\ORM\EntityManagerInterface;
       use Faker;
       use Symfony\Component\Console\Command\Command;
       use Symfony\Component\Console\Input\InputInterface;
       use Symfony\Component\Console\Output\OutputInterface;
       use Symfony\Component\Console\Style\SymfonyStyle;

       class SanitizeDataCommand extends Command
       {
           protected static $defaultName = 'app:sanitize-data';

           protected static $defaultDescription = 'Sanitize user data (username and email).';

           public function __construct(
             private UserRepository $userRepository,
             private EntityManagerInterface $entityManager
           )
           {
               parent::__construct();
           }

           protected function configure()
           {
               $this->setDescription('This command allows you to sanitize user data (username and email).');
           }

           protected function execute(InputInterface $input, OutputInterface $output)
           {
               $io = new SymfonyStyle($input, $output);

               $users = $this->userRepository->findAll();
               $io->progressStart(count($users));

               /** @var User $user */
               foreach ($users as $user) {
                   $io->progressAdvance();

                   // initialize faker
                   $faker = Faker\Factory::create();

                   // sanitize user info
                   $user->setUsername(uniqid($faker->userName()));
                   $user->setEmail($faker->email());
                   // adapt to your needs

                   $this->entityManager->flush();
               }
               $io->progressFinish();

               return static::SUCCESS;
           }
       }
       ```

    2. Update the deploy hook to run your Symfony Command on each deploy.

       ```yaml .upsun/config.yaml theme={null}
       applications:
         myapp:
           hooks:
             build: ...
             deploy: |
               if [ "$PLATFORM_ENVIRONMENT_TYPE" != production ]; then
                 # The sanitization of the database should happen here (since it's non-production)
                 php bin/console app:sanitize-data
               fi
       ```

       To sanitize only on the initial deploy and not all future deploys, on sanitization create a file on a mount. Then add a check for the file as in the following example:

       ```yaml .upsun/config.yaml theme={null}
       applications:
         myapp:
           hooks:
             build: ...
             deploy: |
               if [ "$PLATFORM_ENVIRONMENT_TYPE" != production ] && [ ! -f MOUNT_PATH/is_sanitized ]; then
                 # The sanitization of the database should happen here (since it's non-production)
                 php bin/console app:sanitize-data
                 touch MOUNT_PATH/is_sanitized
               fi
       ```

    3. Commit your changes by running the following command:

       ```bash theme={null}
       git add src/Command/SanitizeDataCommand.php .upsun/config.yaml && git commit -m "Add sanitization."
       ```

       Push the changes to `staging` and verify that environment's database was sanitized.
       Once merged to production, all data from future preview environments are sanitized on environment creation.
  </Tab>

  <Tab title="Using a shell script">
    This example show you how to sanitize data on multiple projects inside an organization, except for production environments.

    Assumptions:

    * Symfony Command from previous tab `Using a Symfony Command` has already been pushed to all of your environments.

    Set up a script by following these steps:

    1. Create an executable sanitizing script by running the following command:

       ```bash theme={null}
       touch sanitize_fleet.sh && chmod +x sanitize_fleet.sh
       ```

    2. Make the script sanitize environments with an [environment type](/docs/administration/users#environment-type-roles)
       other than `production`.

       The following example runs only in preview environments
       and sanitizes data using the Symfony Command from previous tab, already pushed to all of your environments.

       ```bash sanitize_fleet.sh theme={null}
       if [ -n "$ZSH_VERSION" ]; then emulate -L ksh; fi
       ######################################################
       # fleet sanitization demo script, using the Symfony CLI.
       #
       # Enables the following workflow on a project:
       # .
       # └── main
       #     ├── staging
       #     |   └── new-feature
       #     └── auto-updates
       #
       # Usage
       # 1. source this script: `. sanitize_fleet.sh` or `source sanitize_fleet.sh` depending of your local machine
       # 2. define ORGANIZATION var: ORGANIZATION=<organizationIdentifier>
       # 3. run `sanitize_organization_data $ORGANIZATION`
       ######################################################

       # Utility functions.

       # list_org_projects: Print list of projects operation will be applied to before starting.
       #   $1: Organization, as it appears in console.upsun.com.
       list_org_projects () {
          symfony project:list -o $1 --columns="ID, Title"
       }

       # get_org_projects: Retrieve an array of project IDs for a given organization.
       #   Note: Makes array variable PROJECTS available to subsequent scripts.
       #   $1: Organization, as it appears in console.upsun.com.
       get_org_projects () {
         PROJECTS_LIST=$(symfony project:list -o $1 --pipe)
         PROJECTS=($PROJECTS_LIST)
       }

       # get_project_envs: Retrieve an array of envs IDs for a project.
       #   Note: Makes array variable ENVS available to subsequent scripts.
       #   $1: ProjectId, as it appears in console.upsun.com.
       get_project_envs () {
         ENV_LIST=$(symfony environment:list -p $1 --pipe)
         ENVS=($ENV_LIST)
       }

       # list_project_envs: Print list of envs operation will be applied to before starting.
       #   $1: ProjectId, as it appears in console.upsun.com.
       list_project_envs () {
         symfony environment:list -p $1
       }

       # add_env_var: Add environment level environment variable.
       #   $1: Variable name.
       #   $2: Variable value.
       #   $3: Target project ID.
       #   $4: Target environment ID.
       add_env_var () {
         VAR_STATUS=$(symfony project:curl -p $3 /environments/$4/variables/env:$1 | jq '.status')
         if [ "$VAR_STATUS" != "null" ]; then
           symfony variable:create \
           --name $1 \
           --value "$2" \
           --prefix env: \
           --project $3 \
           --environment $4 \
           --level environment \
           --json false \
           --sensitive false \
           --visible-build true \
           --visible-runtime true \
           --enabled true \
           --inheritable true \
           -q
         else
           printf "\nVariable $1 already exists. Skipping."
         fi
       }

       # Main functions.
       sanitize_organization_data () {
         list_org_projects $1
         get_org_projects $1
         for PROJECT in "${PROJECTS[@]}"
         do
           printf "\n### Project $PROJECT."
           # get environments list
           list_project_envs $PROJECT
           get_project_envs $PROJECT
           for ENVIRONMENT in "${ENVS[@]}"
           do
             unset -f ENV_CHECK
             ENV_CHECK=$(symfony project:curl -p $PROJECT /environments/$ENVIRONMENT | jq -r '.status')
             unset -f ENV_TYPE
             ENV_TYPE=$(symfony project:curl -p $PROJECT /environments/$ENVIRONMENT | jq -r '.type')

             if [ "$ENV_CHECK" = active -a "$ENV_TYPE" != production ]; then
               unset -f DATA_SANITIZED
               DATA_SANITIZED=$(symfony variable:get -p $PROJECT -e $ENVIRONMENT env:DATA_SANITIZED --property=value)
               if [ "$DATA_SANITIZED" != true ]; then
                 printf "\nEnvironment $ENVIRONMENT exists and isn't sanitized yet. Sanitizing data."
                 printf "\n"
                 # do sanitization here
                 symfony ssh -p $PROJECT -e $ENVIRONMENT -- php bin/console app:sanitize-data
                 printf "\nSanitizing data is finished, redeploying"
                 add_env_var DATA_SANITIZED true $PROJECT $ENVIRONMENT
               else
                 printf "\nEnvironment $ENVIRONMENT exists and doesn't need to be sanitized. skipping."
               fi
             elif [ "$ENV_TYPE" == production ]; then
               printf "\nEnvironment $ENVIRONMENT is production one, skipping."
             else
               printf "\nEnvironment $ENVIRONMENT isn't active $ENV_CHECK, skipping."
             fi
           done
         done
       }
       ```

    3. use this shell script

       Depending on the machine you want to run this script on, adapt this to your needs.

       ```bash theme={null}
       . sanitize_fleet.sh  # or source sanitize_fleet.sh
       ORGANIZATION=<organizationIdentifier>
       sanitize_organization_data $ORGANIZATION
       ```

    <Note>
      You can find the organization identifier for a specific project, within the Upsun Cloud Console, by clicking on your name, and then on "Settings", in the top right corner.
    </Note>

    4. \[Option] Commit your changes by running the following command:

       ```bash theme={null}
       git add sanitize_fleet.sh && git commit -m "Add sanitization."
       ```

       Push the changes to `staging` and verify that environment's database was sanitized.
       Once merged to production, all data from future preview environments are sanitized on environment creation.
  </Tab>
</Tabs>

## What's next

You learned how to remove sensitive data from a database.

To replace sensitive data with other meaningful data, you can add a `faker` to the process.
A `faker` is a program that generates fake data that looks real.
Having meaningful PII-free data allows you to keep your current Q\&A, external reviews, and other processes.
To add a faker, adapt your sanitizing queries to replace each value that contains PII with a new value generated by the faker.

You might also want to make sure that you [implement input validation](https://cheatsheetseries.owasp.org/cheatsheets/Input_Validation_Cheat_Sheet.html#goals-of-input-validation).

If your database contains a lot of data, consider using the [`REINDEX` statement](https://www.postgresql.org/docs/current/sql-reindex.html) to help improve performance.


# Connect securely with SSH
Source: https://developer.upsun.com/docs/development/ssh/index

Keep your project and apps safe by connecting with SSH when you're interacting with your deployed environments or using the Upsun Cloud CLI.

When you interact with a deployed environment, you need to guard your connection against unauthorized access.
Use Secure Shell (SSH) to provide a secure channel.

You can securely log in to your deployed app to troubleshoot and read logs.
And create a tunnel to export data through.
And interact with your project through the CLI.
All secured through SSH.

## Connect to apps

To connect to an app securely with SSH, follow two steps.

### 1. Authenticate with the CLI

To authenticate with the CLI:

1. Install the [Upsun Cloud CLI](/cli).
2. Run `upsun login`.
3. In the open browser window, log in with your Upsun account credentials.
   (This webpage is encrypted with [HTTPS](/docs/routes/https), making it secure.)
4. Authorize the CLI to use your account.

A certificate gets stored in your local SSH configuration.
The certificate is automatically cycled every hour for a new certificate as long as your session is active.

If you are inactive for an extended period,
your certificate expires and you are asked to login again the next time you use a command that requires authentication.

You are now ready to run CLI commands and connect to an environment.

### 2. Connect to an app with SSH

To access an app in a given environment via the CLI, run the following command:

```bash theme={null}
upsun ssh --project <PROJECT_ID> --environment <ENVIRONMENT_NAME> --app <APPLICATION_NAME>
```

Replace each of `<PROJECT_ID>`, `<ENVIRONMENT_NAME>`, and `<APPLICATION_NAME>` with the values you want to access.
To find these values in the Console,
navigate to the environment you want to access and click **SSH** in the top right-hand corner.

Alternatively, just run `upsun ssh` and select the values from each list presented to you.

Once you've connected, you get a welcome message detailing which environment you're connected to.

Now you can interact with the environment as you want.
Note that your app's file system is read-only,
except for any [mounts you've defined](/docs/configure-apps/image-properties/mounts).

## Connect to services

To connect to a service, you need the [service credentials](/docs/add-services#connect-to-a-service).
Then you can connect either with a [direct tunnel](#use-a-direct-tunnel) or a [tunnel in your app](#use-an-app-tunnel).

### Use a direct tunnel

To open SSH tunnels for all of your services, run the following command:

```bash theme={null}
upsun tunnel:open
```

You get output similar to the following:

```bash theme={null}
SSH tunnel opened to database at: http://127.0.0.1:30000

Logs are written to: ~/.upsun/tunnels.log

List tunnels with: upsun tunnels
View tunnel details with: upsun tunnel:info
Close tunnels with: upsun tunnel:close

Save encoded tunnel details to the PLATFORM_RELATIONSHIPS variable using:
  export PLATFORM_RELATIONSHIPS="$(platform tunnel:info --encode)"
```

Use the returned host (in this case `http://127.0.0.1:30000`) for your connection
and fill in the details with the rest of your [service credentials](/docs/add-services#connect-to-a-service).

The `tunnel:open` command connects all relationships defined in your [app configuration](/docs/configure-apps).

To open only one connection when you have multiple relationships defined, run `tunnel:single`.
By default, this opens a tunnel at `http://127.0.0.1:30000`.
You can specify the port for the connection using the `--port` flag.

### Use an app tunnel

Many database applications (such as MySQL Workbench) support establishing their own SSH tunnel.
You need to use [SSH keys](/docs/development/ssh/ssh-keys) for authentication.
Consult the documentation for your application for how to enter SSH credentials.

#### Get SSH connection details

To get the host and username for connections, follow these steps:

<Tabs>
  <Tab title="Using the CLI">
    Run the following command:

    ```bash theme={null}
    upsun ssh --pipe --project <PROJECT_ID>
    ```

    You get output similar to the following:

    ```bash theme={null}
    jyu7waly36ncj-main-7rqtwti--app@ssh.us.upsun.com
    ```
  </Tab>

  <Tab title="In the Console">
    1. Navigate to the environment you want to connect to.
    2. Click **SSH** in the top right-hand corner.
    3. You get output similar to the following:<br />
       `jyu7waly36ncj-main-7rqtwti--app@ssh.us.upsun.com`
  </Tab>
</Tabs>

The host is everything after the `@` and the username is what's before it.
In this case, the host is `ssh.us.upsun.com` and the username is `jyu7waly36ncj-main-7rqtwti--app`.
The host is the same for the entire project, while the username varies by environment.

To connect to a service, fill in the details with the rest of your [service credentials](/docs/add-services#connect-to-a-service).

## Alternative authentication methods

There are three basic ways to authenticate with Upsun Cloud:

* [Through the CLI](#1-authenticate-with-the-cli)
  * The fastest and easiest method.
  * Supports multifactor authentication.
  * Automatically generates new certificates to keep your connection safe.
  * Necessary when using the CLI and when your organization has multifactor authentication set up.
* [Using SSH keys](/docs/development/ssh/ssh-keys)
  * Requires more setup on your part.
  * Represents only a single authentication method.
  * Requires you to regularly change the keys to maintain security.
  * Useful for checking out code as part of an automated process.
* [Using API tokens](/cli/api-tokens)
  * Good for letting automation tools use the CLI.
  * Requires you to regularly change the tokens to maintain security.

## SSH into an MFA-protected environment

For enhanced security, as an organization owner or admin user,
you can [enforce multifactor authentication (MFA) within your organization](/docs/administration/security/mfa#enforce-mfa-within-your-organization).

As a project contributor, if you haven't enabled MFA on your user account and SSH into an environment that is protected by MFA,
you get an error message. See how you can [troubleshoot that error message](/docs/development/ssh/troubleshoot-ssh#mfa-related-error-message).


# Authenticate with SSH keys
Source: https://developer.upsun.com/docs/development/ssh/ssh-keys

See how to authenticate your app connections using SSH keys.

To connect to your app using SSH keys, you need two keys:

* A **private key** you must keep *secret*
* A **public key** stored in your Upsun account

A given SSH key pair can only be linked to a single user account.

A key pair is valid for as long as you have access to the private key on the system from which you are connecting.
If you have a key pair available, you aren't prompted to login.

To keep connection secure, you need to regularly update the keys you use.
A well-encrypted key is no substitute for regular key rotation.

If you used GitHub to sign up for your Upsun account
your public keys from GitHub are automatically synced to your Upsun account.
So you can use them already with the CLI or to [connect to your app](/docs/development/ssh#2-connect-to-an-app-with-ssh).

## Add SSH keys

If you don't have keys already added,
you might be able to [find existing keys](#1a-find-your-keys) or else you need to [generate new keys](#1b-generate-new-keys).

### 1A. Find your keys

If you haven't used SSH keys before or it's been a while since you created the key,
skip right to [generating new keys](#1b-generate-new-keys).

If you have generated SSH keys before and want to find them on your system,
follow these instructions.

A public key file has a name ending in `.pub`.
It contains seemingly random lines of characters,
like this example of a public [RSA key](https://en.wikipedia.org/wiki/RSA_%28cryptosystem%29)
(note the email address at the end, which wouldn't be present in a private key):

```text {no-copy="true"} theme={null}
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC2nDRLgPANWParTiaGIgySG+thTtnqFGI1tMWyqDdfvH+5hL91w2tK9PzaP+NJ5hA/cOyh30YRFb52Y64toU16Ko5K1mLqNFJajjWEI5Y4VukG6betrWfqdQ7XBr/s7nBuDOFQ5+eKbvug4rRSCSo8CsEI1eI0VNQkC9HJWYK28k7KurMdTN7X/Z/4vknM4/Rm2bnMk2idoORQgomeZS1p3GkG8dQs/c0j/b4H7azxnqdcCaR4ahbytX3d49BN0WwE84C+ItsnkCt1g5tVADPrab+Ywsm/FTnGY3cJKKdOAHt7Ls5lfpyyug2hNAFeiZF0MoCekjDZ2GH2xdFc7AX/ your_email_address@example.com
```

To find your public key file:

1. Open a terminal.
2. Run the following commands:

   ```bash theme={null}
   cd ~/.ssh
   ls -a
   ```

If you find a file ending in `.pub`,
copy the location and [add it to your Upsun account](#2-add-an-ssh-key-to-your-account).

If you don't find an existing key, [generate new keys](#1b-generate-new-keys).

### 1B. Generate new keys

If you're logged in using the [Upsun Cloud CLI](/docs/development/ssh#1-authenticate-with-the-cli),
generate a key and have it added to your Upsun account automatically.

1. In a terminal, run `upsun ssh-key:add`.
2. If necessary, log in to a browser.
3. Press `Y` and `enter` to create a new SSH key.
4. Copy the location of the generated key.
5. Run the following commands (replacing `<PATH_TO_YOUR_KEY>` with the location you copied):

   ```bash theme={null}
   eval $(ssh-agent)
   ssh-add '<PATH_TO_YOUR_KEY>'
   ```

To generate a key otherwise, GitHub has a good [walk-through for creating SSH key pairs](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent) on various operating systems.

Then you need to [add it to your Upsun account](#2-add-an-ssh-key-to-your-account).

### 2. Add an SSH key to your account

Once you have the location of your public key, add it to your Upsun account.

If you're logged in using the [Upsun Cloud CLI](/docs/development/ssh#1-authenticate-with-the-cli),
in a terminal run the following command (replacing `<PATH_TO_YOUR_KEY>` with the location of your public key):

```bash theme={null}
upsun ssh-key:add '<PATH_TO_YOUR_KEY>'
```

You can also add it in the Console,
similar to this [video](https://docs.platform.sh/videos/management-console/add-ssh-mc.mp4).

You can also add it in the Console.

Now you are ready to use the key to [connect to an environment](/docs/development/ssh#2-connect-to-an-app-with-ssh).

### 3. Connect to your server with SSH keys

To connect to a server using SSH keys, find the details in the Console:

1. Open the [Upsun Cloud Console](https://console.upsun.com/).
2. Select a project.
3. In the **Environment** dropdown, select the environment you want to access.
4. Click the **SSH** dropdown.
5. Copy the ssh command for where you want access.
   (Example: `ssh abcdefghi5k-main-7rqtwti--app@ssh.us-2.upsun.com`)
6. Enter the command into a terminal.

Note that if you have just added your SSH key,
you need to [redeploy your environment](/docs/development/ssh/troubleshoot-ssh#redeploy-your-environment) before you can access it using SSH keys.

## Forwarding keys by default

It may be helpful to set your SSH client to always forward keys to Upsun Cloud servers, which can simplify other SSH or rsync commands.
To do so, include a block in your local `~/.ssh/config` file like so:

```text theme={null}
Host *.us.upsun.com
       ForwardAgent yes
Host *.eu.upsun.com
       ForwardAgent yes
```

Include one `Host` entry for each Upsun Cloud region you want to connect to, such as `us-2` or `eu-4`.
(You can include other configuration as desired.)


# Troubleshoot SSH
Source: https://developer.upsun.com/docs/development/ssh/troubleshoot-ssh



While trying to use SSH, you may get a response indicating permission is denied. Or if you get an error with a code of 255, it means there's a problem with your SSH connection.

```txt {no-copy="true"} theme={null}
The command failed with the exit code: 255
```

There are several places to check to try to solve such issues.

## Check your environment

If your environment is [inactive](/docs/glossary#inactive-environment) or the deployment has failed,
you can't log in to it.
To make sure the environment is active and the deployment has succeeded,
check it using `upsun environment:list` or in the [Console](https://console.upsun.com/) .

## Redeploy your environment

If you have just added your SSH key or made changes to [access rules](/docs/administration/users), you need to redeploy your environment before you can access it using SSH keys. You can do this in the [Console](https://console.upsun.com/), by running `upsun redeploy`, or by pushing an empty git commit:

```bash theme={null}
git commit --allow-empty -m 'chore: force redeploy'
git push origin main
```

## Check your public key

Make sure your public key has been uploaded to your user account. Check it in the [Upsun Cloud Console](https://console.upsun.com/).

## SSH key can not be duplicated

A given SSH key pair can only be linked to a single user account.
If you add an already used SSH key to another account, you see the error: `SSH key can not be duplicated`.
[Generate a new pair of SSH keys](/docs/development/ssh/ssh-keys#add-ssh-keys) for the second user account you want to add.

## Check your SSH agent

Check that your key is properly added to your SSH agent. This is an authentication agent that manages your private key.

1. Run `ssh-add -l` in your terminal:

   ```bash theme={null}
   ssh-add -l
   ```

   You get output similar to the following:

   ```bash theme={null}
   2048 12:b0:13:83:7f:56:18:9b:78:ca:54:90:a7:ff:12:69 /Users/your_username/.ssh/id_rsa (RSA)
   ```

2. Check that the file exists and that the file name or comment matches your private key file.

3. If you don't see your private key file, add your private key:

   ```bash theme={null}
   ssh-add path-to-your-key
   ```

## Specify your identity file

If your identity (SSH key) associated with Upsun Cloud isn't in a default file name
(as may be explained in your SSH software manual, for example),
you may have to append a specification like the one below so that the SSH software finds the correct key.

```bash theme={null}
Host platform.sh
IdentityFile ~/.ssh/id_upsun
```

Be aware that, above, `upsun` stands for a hostname.
Each different hostname you connect to Upsun Cloud at may have to be specified in the host line, separated by spaces.

## Check your Git integrations

If your project is integrated with another Git provider (such as GitHub), that provider controls Git operations.
Make sure you have added your public SSH key to your provider and that your user there has access.

## Generate SSH debug information

If your private key and public key both look OK but you don't have any luck logging in, print debugging information.
These lines often give clues about what's going wrong.

Run the SSH command with the `-v` option, like so:

```bash theme={null}
ssh -v [SSH-URL]
```

You get output similar to the following:

```bash theme={null}
OpenSSH_6.7.8, OpenSSL 1.2.3 1 Sep 2014
debug1: Connecting to ssh.eu.upsun.com [54.32.10.98] port 22.
debug1: Connection established.
debug1: identity file /Users/your_username/.ssh/id_rsa type 1
...(many more lines of this light reading)...
debug1: Offering RSA public key: /Users/your_username/.ssh/id_rsa
debug1: Authentications that can continue: publickey
debug1: No more authentication methods to try.
Permission denied (publickey).
```

Alternatively, you can run the following command:

```bash theme={null}
GIT_SSH_COMMAND="ssh -v" git clone <REPO_URL>
```

You can use this information to make one last check of the private key file.

## MFA-related error message

If you haven't enabled MFA on your user account and try to SSH into an environment that is protected by MFA,
you get the following error message:

```bash theme={null}
Error: Access denied
Service: abcdefg123456-main-bvxea6i--app
User: <USER NAME> (<USER ID>)
Parameters: {"amr":["mfa"]}
Detail: Additional authentication is required:
	 - Multifactor authentication (MFA)
```

To solve this, [enable MFA on your user account](/docs/administration/security/mfa#enable-mfa-on-your-user-account).

Alternatively, open the Console and select the desired organization.
Follow the instructions so you can effectively access its contents.

Similarly for bot users and CLI tokens, you may see the message:

```bash theme={null}
  [RequestException]
  Multifactor authentication (MFA) is required.
  The API token may need to be re-created after enabling MFA.
```

In this case, as described, it will be necessary to:

1. Enable MFA on the (bot) user account associated with the token.
2. Generate a new access token, and then replace its value in your workflow that requires the token (such as updating a GitHub workflow secret variable).

## Something still wrong?

For more general information, see how to [troubleshoot development](/docs/troubleshooting/general).

If you're still stuck, open a [support ticket](/docs/core-concepts/get-support) and provide the full SSH debug information.


# Use Git submodules
Source: https://developer.upsun.com/docs/development/submodules



## Clone submodules during deployment

Upsun Cloud allows you to use submodules in your Git repository.
They're usually listed in a `.gitmodules` file at the root of your Git repository.
When you push via Git, Upsun Cloud tries to clone them automatically.

The following example is based on [a Bigfoot multi-app project](https://github.com/platformsh-templates/bigfoot-multiapp/tree/multiapp-subfolders-applications) which uses the following submodules:

* A [BigFoot app](https://github.com/platformsh-templates/bigfoot-multiapp-api/tree/without-platform-app-yaml)
* An [API Platform v3, Admin component](https://github.com/platformsh-templates/bigfoot-multiapp-admin/tree/without-platform-app-yaml)
* A [Gatsby frontend](https://github.com/platformsh-templates/bigfoot-multiapp-gatsby/tree/without-platform-app-yaml)
* A [Mercure Rocks server](https://github.com/platformsh-templates/bigfoot-multiapp-mercure/tree/without-platform-app-yaml)

<img alt="Diagram of a project containing multiple apps" />

Say you have a multi-app project that includes the following submodules:

* A BigFoot app
* An API Platform v3, Admin component
* A Gatsby frontend
* A Mercure Rocks server

To import all the submodules, run the following commands from your multiple application project's root folder:

```bash theme={null}
touch .gitmodules
git submodule add --name admin https://github.com/platformsh-templates/bigfoot-multiapp-admin.git admin
git submodule add --name api https://github.com/platformsh-templates/bigfoot-multiapp-api.git api
git submodule add --name gatsby https://github.com/platformsh-templates/bigfoot-multiapp-gatsby.git gatsby
git submodule add --name mercure https://github.com/platformsh-templates/bigfoot-multiapp-mercure.git mercure
git add .
git commit -m "Adding submodules for Bigfoot App, API Platform Admin, Gatsby frontend and Mercure Rocks server"
git push
```

Here is an example of a `.gitmodules` file:

```ini theme={null}
[submodule "admin"]
  path = admin
  url = https://github.com/platformsh-templates/bigfoot-multiapp-admin.git
[submodule "api"]
  path = api
  url = https://github.com/platformsh-templates/bigfoot-multiapp-api.git
[submodule "gatsby"]
  path = gatsby
  url = https://github.com/platformsh-templates/bigfoot-multiapp-gatsby.git
[submodule "mercure"]
  path = mercure
  url = https://github.com/platformsh-templates/bigfoot-multiapp-mercure.git
```

When you run `git push`, you can see the output of the logs:

```bash theme={null}
  Validating submodules
    Updating submodule ttps://github.com/platformsh-templates/bigfoot-multiapp-admin.git
    Updated submodule https://github.com/platformsh-templates/bigfoot-multiapp-admin.git: 549 references updated.
    Updating submodule ttps://github.com/platformsh-templates/bigfoot-multiapp-api.git
    Updated submodule https://github.com/platformsh-templates/bigfoot-multiapp-api.git: 898 references updated.
    Updating submodule https://github.com/platformsh-templates/bigfoot-multiapp-gatsby.git
    Updated submodule https://github.com/platformsh-templates/bigfoot-multiapp-gatsby.git: 257 references updated.
    Updating submodule https://github.com/platformsh-templates/bigfoot-multiapp-mercure.git
    Updated submodule https://github.com/platformsh-templates/bigfoot-multiapp-mercure.git: 124 references updated.
  ...
```

<Note>
  If your submodule contains an independent app,
  see [how to configure it properly](/docs/configure-apps/multi-app/project-structure#split-your-code-source-into-multiple-git-submodule-repositories).
</Note>

## Update submodules

<Tabs>
  <Tab title="Manual update">
    When you amend your submodules' code, make sure your changes are applied by running the following commands
    before redeploying:

    ```bash theme={null}
    git submodule update --remote [submodule]
    Submodule path 'admin': checked out 'a020894cf94de6e79748890c942206bc7af752af'
    Submodule path 'api': checked out 'dce6617cc2db159c1a871112909e9ea4121135ec'
    Submodule path 'gatsby': checked out '012ab16b05f474278ad0f9916e1cb94fc9df5ba4'
    Submodule path 'mercure': checked out '94ccae5055983004aa8ab2c17b1daabd0c0a4927'
    ```

    <Note>
      To specify which submodule needs to be updated, replace `[submodule]` with your submodule path.
    </Note>
  </Tab>

  <Tab title="Automated update">
    <Warning>
      <h4>Tier availability</h4>
      This feature is available for **Elite** and **Enterprise** customers.
      [Compare the Upsun tiers](https://upsun.com/fixed-pricing/) on our pricing page,
      or [contact our Sales team](https://upsun.com/contact-us/) for more information.
    </Warning>

    Automate your submodule updates using a [source operation](/docs/configure-apps/source-operations).
    To do so, follow these steps:

    1. Define a source operation.<br />
       Add the following configuration to your `.upsun/config.yaml` file:

    ```yaml .upsun/config.yaml theme={null}
    applications:
      # The name of the app container. Must be unique within a project.
      myapp:
        # The location of the application's code.
        source:
          operations:
            rebuild:
              command: |
                set -e
                git submodule update --init --recursive
                git submodule update --remote --checkout
                git add admin api gatsby mercure
                if ! git diff-index --quiet HEAD; then
                  git commit -m "Updating submodules admin, api, gatsby and mercure"
                fi
    ```

    For multiple app projects, make sure you define your source operation
    in the configuration of an app whose source code **is not** in a submodule.

    If you use [Git submodules for each of your apps](/docs/configure-apps/multi-app/project-structure#split-your-code-source-into-multiple-git-submodule-repositories), define a new app at the top level of your project repository.
    Don't define routes so your app isn't exposed to the web.
    To define a source operation, add the following configuration to your [app configuration](/docs/configure-apps/app-reference):

    2. Run your source operation.<br />

       To do so, in the [Console](/docs/administration/web),
       navigate to the environment where you want to run the source operation.<br />
       Click <MoreIcon /> **More**.<br />
       Click **Run Source Operation**.<br />
       Select the operation you want to run.<br />
       Click **Run**.

       Alternatively, to run your source operation from the [Upsun Cloud CLI](/cli),
       run the following command:

       ```bash theme={null}
       upsun source-operation:run <SOURCE_OPERATION_NAME>
       ```
  </Tab>
</Tabs>

## Error when validating submodules

Using an SSH URL (`git@github.com:...`) to fetch submodules triggers the following error:

```bash theme={null}
Validating submodules.
  Found unresolvable links, updating submodules.

E: Error validating submodules in tree:
    - admin: Exception: commit 03567c6 not found.

   This might be due to the following errors fetching submodules:
    - git@github.com:platformsh-templates/bigfoot-multiapp-admin.git: HangupException: The remote server unexpectedly closed the connection.
```

This is due to the fact that the Upsun Cloud Git server can't connect to GitHub via SSH without being granted an SSH key to do so.
To solve this issue, use an HTTPS URL (`https://github.com/...`) instead.

## Use private Git repositories

When using Git submodules that are private repositories, URLs with the HTTPS protocol fail with errors such as the following:

```bash theme={null}
GitProtocolError: unexpected http resp 401 for https://bitbucket.org/myusername/mymodule.git/info/refs?service=git-upload-pack
```

To fix this, follow these steps:

1. Change your module declarations to use SSH for URLs.

   Your existing declaration might look like this:

   ```bash .gitmodules theme={null}
   [submodule "support/module"]
       path = support/module
       url = https://bitbucket.org/username/module.git
       branch = submodule/branch
   ```

   Change this to the following:

   ```bash .gitmodules theme={null}
   [submodule "support/module"]
       path = support/module
       url = git@bitbucket.org:username/module.git
       branch = submodule/branch
   ```

2. Add the [project's public key to your remote Git repository](/docs/development/private-repository). If there are nested
   submodules in your submodule, then add the public key to those repositories as well. This allows your
   Upsun Cloud project to pull the repository from the remote Git service.

<Note>
  Deploy keys only grant access to a single repository,
  which can cause issues when attempting to pull several repositories to the same server.
  If your server needs access to multiple repositories, follow these steps:

  1. [Create a machine user](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/managing-deploy-keys#machine-users)
     with access rights to each of the private repositories.
  2. Attach the deploy key to your machine user.
</Note>

## Removing submodules

These steps aren't specific to Upsun Cloud, but kept as a reference for Git so that submodules are effectively removed before entering the build process.

1. In your `.gitmodules` and `.git/config` files, delete the information related to the submodule you want to remove.

   ```bash theme={null}
   git submodule deinit -f path_to_submodule
   ```

2. Stage changes to `.gitmodules`:

   ```bash theme={null}
   git add .gitmodules
   ```

3. Remove the submodule from the repository (without trailing slash):

   ```bash theme={null}
   git rm --cached path_to_submodule
   ```

4. Remove the submodule files in `.git` from the repository  (without trailing slash):

   ```bash theme={null}
   rm -rf .git/modules/path_to_submodule
   ```

5. Commit the changes:

   ```bash theme={null}
   git commit -m "Removed submodule."
   ```

6. Remove the submodule code locally, now no longer tracked:

   ```bash theme={null}
   rm -rf path_to_submodule
   ```


# Development tools
Source: https://developer.upsun.com/docs/development/tools

Tools and utilities to help you develop and manage your applications.

<CardGroup>
  <Card title="Access your site" icon="globe" href="/docs/development/access-site">
    Find the URLs you can use to access your site via a web browser.
  </Card>

  <Card title="Transfer files" icon="file-up" href="/docs/development/file-transfer">
    Transfer files to and from your app without using Git.
  </Card>

  <Card title="HTTP Headers" icon="heading" href="/docs/development/headers">
    HTTP headers added to both inbound and outbound messages.
  </Card>

  <Card title="Send email" icon="mail" href="/docs/development/email">
    Send email from your Upsun Cloud environments.
  </Card>

  <Card title="Private Git repository" icon="lock" href="/docs/development/private-repository">
    Pull code from a private Git repository into your build process.
  </Card>

  <Card title="Git submodules" icon="git-branch" href="/docs/development/submodules">
    Use Git submodules in your repository.
  </Card>

  <Card title="Regions" icon="map" href="/docs/development/regions">
    See information about Upsun Cloud regions, including environmental impact and IP addresses.
  </Card>

  <Card title="Drush" icon="terminal" href="/docs/development/drush">
    Install Drush and run commands against your Drupal site through the CLI, SSH, or hooks.
  </Card>
</CardGroup>


# Variables overview
Source: https://developer.upsun.com/docs/development/variables/index

Variables give you control over your project's build process and runtime environment. You can set them in your code to make changes across your project or independent of the code for environment-specific settings.


In this way, your app has additional information, such as database credentials, the host or port it can use, and which server to connect to.

## Variable types

You can set variables at different levels.
All variables can be strings or base64-encoded JSON-serialized values.

The following table defines what types of variables are available to you:

| Type | Definer | Scope | Precedence | Build | Runtime | Uses |
| - | - | - | - | - | - | - |
| [Application](/docs/development/variables/set-variables#set-variables-in-your-app) | Application | Application | 4 | Yes | Yes | Non-secret values that are the same across all environments |
| [Project](/docs/development/variables/set-variables#create-project-variables) | User | Project | 3 | Yes | Yes | Secret values that are the same across all environments, such as database credentials |
| [Environment](/docs/development/variables/set-variables#create-environment-specific-variables) | User | Environment | 2 | Some | Yes | Values that vary by environment, such as which database to connect to or which payment API keys to use |
| [Upsun Cloud](/docs/development/variables/use-variables#use-provided-variables) | Pre-defined | Environment | 1 | Some | Yes | For information about your Upsun Cloud project |

If there are conflicts between variables with the same name, variables [take precedence](#overrides) from 1 down.
So Upsun Cloud-provided values (1) override environment variables (2), which override project variables (3),
which override application-provided variables (4).

All of the variables can also be [overridden via a script](/docs/development/variables/set-variables#set-variables-via-script).

### Choosing a variable type

Choose how to set the variable based on what you are trying to do.

Some environment variables should be the same for all environments.
For example:

* Build tool versions.
  If you have scripts that use specific versions of build tools (such as a [specific Node.js version](/docs/languages/nodejs/node-version)),
  You want the tools to be versioned along with your code so you can track the impact of changes.
  Set those variables [in the application](/docs/development/variables/set-variables#set-variables-in-your-app).
* Credentials for common services.
  If you have credentials for services shared across your environments,
  you don't want to commit these secrets to code.
  Set them as sensitive [project variables](/docs/development/variables/set-variables#create-project-variables).

Other configurations should vary between environment types.
For example:

* Service configuration for databases and such.
  This information be read from the [service environment variables](/docs/development/variables#service-environment-variables),
  or the Upsun Cloud-provided [`PLATFORM_RELATIONSHIPS` variable](/docs/development/variables/use-variables#use-provided-variables).
  It varies by environment automatically.
* Mode toggles such as enabling `debug` mode, disabling certain caches, and displaying more verbose errors.
  This information might vary by environment type and should be set on the [environment level](/docs/development/variables/set-variables#create-environment-specific-variables).
* API keys for remote services, especially payment gateways.
  If you have a different payment gateway for production and for testing,
  set its keys on the [environment level](/docs/development/variables/set-variables#create-environment-specific-variables).

## Overrides

If the names of variables at different levels match,
an environment variable overrides a variable with the same name in a parent environment
and both override a project variable.
All variables can also be [overridden via script](/docs/development/variables/set-variables#set-variables-via-script).

For an example of how the different levels work,
suppose you have the following inheritable variables defined for the `main` environment:

```sh theme={null}
upsun var -e main
Variables on the project Example (abcdef123456), environment main:
+----------------+-------------+--------+---------+
| Name           | Level       | Value  | Enabled |
+----------------+-------------+--------+---------+
| system_name    | project     | Spiffy |         |
| system_version | project     | 1.5    |         |
| api_key        | environment | abc123 | true    |
| debug_mode     | environment | 1      | true    |
+----------------+-------------+--------+---------+
```

And the following variables defined for the `feature-x` environment, a child environment of `main`:

```sh theme={null}
upsun var -e feature-x
Variables on the project Example (abcdef123456), environment feature-x:
+----------------+-------------+--------+---------+
| Name           | Level       | Value  | Enabled |
+----------------+-------------+--------+---------+
| system_name    | project     | Spiffy |         |
| system_version | project     | 1.5    |         |
| api_key        | environment | def456 | true    |
| system_version | environment | 1.7    | true    |
+----------------+-------------+--------+---------+
```

In the `main` environment, you can access `$PLATFORM_VARIABLES`:

```bash theme={null}
echo $PLATFORM_VARIABLES | base64 --decode | jq
```

The output looks like this:

```json theme={null}
{
    "system_name": "Spiffy",
    "system_version": "1.5",
    "api_key": "abc123",
    "debug_mode": "1"
}
```

While in the `feature-x` environment, it looks like this:

```json theme={null}
{
    "system_name": "Spiffy",
    "system_version": "1.7",
    "api_key": "def456",
    "debug_mode": "1"
}
```

To get a visual overview of which variables are overridden in an environment,
navigate in the Console to that environment's variables settings.
This example shows how it looks within the `feature-x` environment:

<img alt="The Console showing the variables split into environment and project ones, with the environment variables api_key and system_version labeled as overridden and debug_mode as inherited the project variable system_version labeled as inactive." />

Project variables that conflict with environment variables are labeled as **Inactive**.
Environment variables are labeled as **Inherited** when they get their value from a parent environment
and as **Overridden** when there is a conflict and the parent environment's value doesn't apply.

## Variable prefixes

Certain variable name prefixes have special meanings.
Some are defined by Upsun Cloud and apply automatically.
Others are just available as a convention for your application code to follow.

### Top-level environment variables

By default, project and environment variables are only added to the `PLATFORM_VARIABLES` environment variable.
You can also expose a variable as its own environment variable by giving it the prefix `env:`.

For example, the variable `env:foo` creates an environment variable called `FOO`.
(Note the automatic upper-casing.)

```bash theme={null}
upsun variable:create --name env:foo --value bar
```

You can then access that variable directly in your app container:

```bash theme={null}
echo $FOO
bar
```

Note that environment variables with the `env:` prefix aren't added to the `PLATFORM_VARIABLES` environment variable.

### PHP-specific variables

Any variable with the prefix `php` is added to the PHP configuration for all PHP-based application containers in the project.

Using variables, you can use the same files for all your environments and override values on any given environment if needed.

You can set the PHP memory limit to 256 MB on a specific environment by running the following [CLI command](/cli):

```bash theme={null}
upsun variable:create --level environment --prefix php --name memory_limit --value 256M --environment <ENVIRONMENT_NAME>
```

To use variables across environments, set them in your [app configuration](/docs/configure-apps).
For example, to change the PHP memory limit for all environments, use the following configuration:

## Framework-specific variables

For specific frameworks, you can implement logic to override global configurations with [environment-specific variables](/docs/development/variables/set-variables#create-environment-specific-variables).
So you can use the same codebase and settings for all your environments,
but still adapt the behavior to each environment.

## Service environment variables

For each service defined via a relationship to your application,
Upsun Cloud automatically generates corresponding environment variables within your application container,
in the `$<RELATIONSHIP-NAME>_<SERVICE-PROPERTY>` format.
All the non-alphanumerical or `_` characters (`[^0-9A-Z_]`) are transformed into an `_` , such as `MY_DATABASE_PASSWORD` for a `my-database` relationship name.

**Example:**

For a relationship named `database` to a service named `postgresql`,
the following environment variables are automatically generated in your `myapp` container:


# Set variables
Source: https://developer.upsun.com/docs/development/variables/set-variables

See how to set variables that you can later use to take control over your app's environment.

To set variables, determine which [type of variable](/docs/development/variables#variable-types) to use.
Remember to take into account the order of precedence.
All of the variables can also be [overridden via script](#set-variables-via-script).

## Set variables in your app

Set variables [in code](/docs/configure-apps/image-properties/variables) using the `.upsun/config.yaml` file.
These values are the same across all environments and present in the Git repository,
which makes them a poor fit for API keys and other such secrets.

They're better fits for uses such as configuration for consistent builds across every environment,
including setting [PHP configuration values](/docs/development/variables#php-specific-variables).

Application variables are available at both build time and runtime.

## Create project variables

Add secrets for all environments in project variables
using [the Console](/docs/administration/web/configure-project#variables) or the [CLI](/cli).

For example, you may need to vary API credentials between production and other environments.
To do so, set the non-production credentials as a project variable
and then override these credentials for the production environment by setting a [variable specific to that environment](#create-environment-specific-variables).

Third-party API keys are common candidates for this — for example, a payment gateway credential, or the LLM provider API key (`ANTHROPIC_API_KEY` or `OPENAI_API_KEY`) required by the [Upsun Cloud performance agent](/docs/get-started/ai/upsun-cloud-performance-agent).

<Tabs>
  <Tab title="Using the CLI">
    To add a project variable, run the following command:

    ```bash theme={null}
    upsun variable:create --level project --name <VARIABLE_NAME> --value <VARIABLE_VALUE>
    ```

    To specify other options, use the [flags for variable options](#variable-options).
  </Tab>

  <Tab title="In the Console">
    To add a project variable, follow these steps:

    1. Select the project where you want to create a variable.
    2. Click <SettingsIcon /> **Settings**.
    3. Under **Project settings**, click **Variables**.
    4. Click **+ Create variable**.
    5. Enter a name for the variable.
    6. Enter the variable value.
    7. Ensure you have selected the right [other options](#variable-options).
    8. Click **Create variable**.
  </Tab>
</Tabs>

When naming variables, be sure to take [variable prefixes](/docs/development/variables#variable-prefixes) into account.
In particular, to expose a variable as its own environment variable,
[use the prefix `env:`](/docs/development/variables#top-level-environment-variables).

### Variable options

Variables have several Boolean options you can set in the Console or the CLI:

| Option | CLI flag | Default | Description |
| - | - | - | - |
| JSON | `--json` | `false` | Whether the variable is a JSON-serialized value (`true`) or a string (`false`). |
| Sensitive | `--sensitive` | `false` | If set to `true`, the variable's value is hidden in the Console and in CLI responses for added security. It's still readable within the app container. |
| Runtime | `--visible-runtime` | `true` | Whether the variable is available at runtime. |
| Build | `--visible-build` | `true` | Whether the variable is available at build time. |
| Application Scope | `--app-scope` | - | Limits the variable visibility to specific app(s) and/or their workers. By default the variable is available across all the applications. |

So if you want the `foo` variable to be visible at build time but hidden during runtime,
you can set it by running the following command:

```bash theme={null}
upsun variable:create --level project --name foo --value bar --visible-build true --visible-runtime false 
```

You can also change the variable options after you create them (except for sensitive values, which can't be set to non-sensitive).
For example, to make the `foo` variable visible at runtime and hidden during the build, run the following command:

```bash theme={null}
upsun variable:update foo --visible-build false --visible-runtime true
```

#### Limiting variables to specific applications

If you want the `foo` variable to be available only to certain applications, you can limit its scope using the `--app-scope` option:

```bash theme={null}
upsun variable:create --level project --name foo --value bar --app-scope frontend1,frontend2
```

Where `frontend1` and `frontend2` are the names of your applications.

Note that for changes to project variables to have effect,
you need to [redeploy](/docs/troubleshooting/general#force-a-redeploy) your environments.

## Create environment-specific variables

Set variables for specific environments using [the Console](/docs/administration/web/configure-environment#variables) or the CLI.
Variables can be inherited or overridden from parent environments and project variables.
See [more on overriding values](/docs/development/variables#overrides).

<Tabs>
  <Tab title="Using the CLI">
    To create a variable for the current environment, run the following command:

    ```bash theme={null}
    upsun variable:create --level environment --name <VARIABLE_NAME> --value <VARIABLE_VALUE>
    ```

    To specify the environment for the variable, use the `-e` flag to specify its name.
    To specify other options, use the [flags for variable options](#environment-variable-options).
  </Tab>

  <Tab title="In the Console">
    To add a project variable, follow these steps:

    1. Select the project where you want to create a variable.
    2. Click <SettingsIcon /> **Settings**.
    3. Under **Environments**, click the environment where you want to create a variable.
    4. Click **Variables**.
    5. Click **+ Create variable**.
    6. Enter a name for the variable.
    7. Enter the variable value.
    8. Ensure you have selected the right [other options](#environment-variable-options).
    9. Click **Create variable**.
  </Tab>
</Tabs>

When naming variables, be sure to take [variable prefixes](/docs/development/variables#variable-prefixes) into account.
In particular, to expose a variable as its own environment variable,
[use the prefix `env:`](/docs/development/variables#top-level-environment-variables).

### Environment variable options

Environment variables share all of the [options available for project variables](#variable-options).
Environment variables have one additional option:

| Option | CLI flag | Default | Description |
| - | - | - | - |
| Inheritable | `--inheritable` | `true` | Whether the variable is inherited by child environments. |

This option is useful for setting production-only values such as credentials.
For example, to set a PayPal secret value for only the `main` branch and have it not be readable elsewhere,
run the following command:

```bash theme={null}
upsun variable:create -e main --name paypal_id --inheritable false --sensitive true
```

Other environments don't inherit it and get either a project variable of the same name if it exists or no value at all.

Note that changing an environment variable causes that environment to be redeployed so the new value is available.
But child environments are *not* redeployed.
To make the new value accessible to those environments, [trigger a redeploy](/docs/troubleshooting/general#force-a-redeploy).

### Example environment variable

Environment variables are a good place to store values that apply only on Upsun Cloud and not on your local development environment.
This includes API credentials for third-party services, mode settings, and which server (development vs. production) to use.

One example would be to define a Node.js application's build on a production branch (`NODE_ENV=production`),
but use development mode (`NODE_ENV=development`) for each of your preview environments.
Assuming you have a `main` environment for production and a `staging` environment with more child environments for development,
run the following commands:

```bash theme={null}
upsun variable:create -l environment -e main --prefix env: --name NODE_ENV --value production --visible-build true --inheritable false
upsun variable:create -l environment -e staging --prefix env: --name NODE_ENV --value development --visible-build true --inheritable true
```

Now `NODE_ENV` is `production` on the default branch but `development` on `staging` and each of its child environments.
Note that build visible environment variables change the application's build configuration ID:
value updates trigger a rebuild of the application in the same way that a commit would.

## Set variables via script

You can also provide a `.environment` file as in [your app root](/docs/configure-apps/app-reference/single-runtime-image#root-directory).
This file runs as a script in dash when the container starts and on all SSH logins.
It can be used to set any environment variables directly, such as the PATH variable.

For example, the following `.environment` file allows any executable installed in the `vendor/bin` directory
(such as executables installed using Composer)
to be run regardless of the current directory:

```bash .environment theme={null}
export PATH="/app/vendor/bin:${PATH}"
```

You can also dynamically define environment variables based on the current environment.
For example, you might want to get the [defined route](/docs/routes) with the id `api` for the current environment.
To define it as the `URL` environment variable, you might add something like:

```bash .environment theme={null}
URL=$(echo $PLATFORM_ROUTES | base64 --decode | jq -r 'to_entries[] | select (.value.id == "api") | .key')
```

Note that the file is sourced after all other environment variables above are defined and so they're available to the script.
This also means the `.environment` script has the last word on environment variable values and can override anything it wants to.

### Testing `.environment` scripts

You may find that a command that works during an SSH session provides a `bad substitution` error when placed in a `.environment` file.
Remember, `.environment` is sourced using dash, not bash.
When testing your `.environment` logic, be sure to first enter a `dash` session in your terminal or within the SSH session.

When testing, you might print to stdout (using an `echo` or `printf` command) to check what's happening.
The following example looks for a `deploy/environment.tracker.txt` file.
It displays a different message if it's found or not, which helps you track what variables are being set.

```bash .environment theme={null}
if [ -f "deploy/environment.tracker.txt" ]; then
    echo "File found."
    export DEPLOY='Friday'
else
    echo "File not found."
    export DEPLOY='Never on a Friday'
fi
```

While sanity checks like this are useful during troubleshooting, you shouldn't include such commands in your final code.
Because the `.environment` file is run at the start of an SSH session, the message is printed at the start of the session.

Even when your SSH command executes successfully, you might later attempt to download data from one of your mounts,
such as by using the CLI command `upsun mount:download`.
When you do, you see this error:

```bash theme={null}
protocol version mismatch -- is your shell clean?
(see the rsync man page for an explanation)
rsync error: protocol incompatibility (code 2) at .../rsync/compat.c(61) [receiver=2.6.9]

[ProcessFailedException]
The command failed with the exit code: 2
```

This failure comes because `mount:download` and `rsync` don't expect output when the SSH connection is made.
To solve the issue, remove the printed output from your `.environment` file.

## Map variables

If your app needs different names for environment variable than those set by Upsun Cloud, which is common for database connections,
map the Upsun Cloud's variable names to those required by the application via a shell script.

You can obtain relationship information through the [service environment variables](/docs/development/variables#service-environment-variables) themselves,
or through the [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables).
For example, if your application has a relationship named `database` to a database service named `mariadb`:

<Tabs>
  <Tab title="Service environment variables">
    ```bash .environment theme={null}
    export APP_DATABASE_HOST="${DATABASE_HOST}"
    export APP_DATABASE_USER="${DATABASE_USERNAME}"
    ```

    This sets environment variables with the names your app needs,
    and the values from [service environment variables](/docs/development/variables#service-environment-variables).
  </Tab>

  <Tab title="`PLATFORM_RELATIONSHIPS` environment variable">
    It uses the `jq` library, which is included in all app containers for this purpose.

    ```bash .environment theme={null}
    export APP_DATABASE_HOST="$(echo "$PLATFORM_RELATIONSHIPS" | base64 --decode | jq -r '.database[0].host')"
    export APP_DATABASE_USER="$(echo "$PLATFORM_RELATIONSHIPS" | base64 --decode | jq -r '.database[0].username')"
    ```

    This sets environment variables with names your app needs,
    and the values from [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables).
  </Tab>
</Tabs>

## When to use `.env` files

Upsun Cloud does not read `.env files`, as conventionally they are not committed to Git. You can use these for local
development, but they will not be sourced on any Upsun Cloud environment. Typically, you can add `.env` to your .gitignore
file so that its contents can vary for different developers.

Read more about [the use cases for `.env` files](https://upsun.com/blog/what-is-env-file/).


# Use variables
Source: https://developer.upsun.com/docs/development/variables/use-variables

See how to use variables that have already been set so you can take control over your app's environment.

Get a list of all variables defined on a given environment in [the Console](/docs/administration/web/configure-environment#variables)
or use the CLI:

```bash theme={null}
upsun var
```

You get output similar to the following:

```bash theme={null}
Variables on the project Example (abcdef123456), environment main:
+------+---------+-------+---------+
| Name | Level   | Value | Enabled |
+------+---------+-------+---------+
| foo  | project | bar   | true    |
+------+---------+-------+---------+
```

## Access variables in a shell

Project and environment variables with the [prefix](/docs/development/variables#top-level-environment-variables) `env:`
are available as Unix environment variables in all caps.
Access these variables and Upsun Cloud-provided variables directly like this:

```bash theme={null}
echo $FOO
bar
echo $PLATFORM_APPLICATION_NAME
Sample Project
```

Other project and environment variables are listed together in the `PLATFORM_VARIABLES` variable as a base64-encoded JSON object.
Access them like this:

```bash theme={null}
echo $PLATFORM_VARIABLES | base64 --decode
{"theanswer": "42"}
```

You can also get the value for a single variable within the array, such as with this command,
which uses the [`jq` processor](https://stedolan.github.io/jq/):

```bash theme={null}
echo $PLATFORM_VARIABLES | base64 --decode | jq '.theanswer'
"42"
```

Variable availability depends on the type and configuration.
Variables available during builds can be accessed in `build` hooks and those available at runtime can be accessed in `deploy` hooks.

## Access variables in your app

To access environment variables in your app, use a built-in method for the given language.

* PHP: The [`getenv()` function](https://www.php.net/manual/en/function.getenv.php)
* Python: The [`os.environ` object](https://docs.python.org/3/library/os.html#os.environ)
* Node.js: The [`process.env` object](https://nodejs.org/api/process.html#process_process_env)
* Ruby: The [`ENV` accessor](https://docs.ruby-lang.org/en/master/ENV.html)
* Java: The [`System.getenv()` method](https://docs.oracle.com/javase/8/docs/api/java/lang/System.html#getenv-java.lang.String-)

<Tabs>
  <Tab title="PHP">
    ```php theme={null}
    <?php

    // A simple variable.
    $projectId = getenv('PLATFORM_PROJECT');

    // An encoded JSON object.
    $variables = json_decode(base64_decode(getenv('PLATFORM_VARIABLES')), TRUE);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import os
    import json
    import base64

    # A simple variable.
    project_id = os.getenv('PLATFORM_PROJECT')

    # An encoded JSON object.
    variables = json.loads(base64.b64decode(os.getenv('PLATFORM_VARIABLES')).decode('utf-8'))
    ```
  </Tab>

  <Tab title="Node.js">
    ```js theme={null}
    const { env } = process;

    // Utility to assist in decoding a packed JSON variable.
    function read_base64_json(varName) {
      try {
        return JSON.parse(Buffer.from(env[varName], "base64").toString());
      } catch (err) {
        throw new Error(`no ${varName} environment variable`);
      }
    };

    // A simple variable.
    const projectId = env.PLATFORM_PROJECT;

    // An encoded JSON object.
    const variables = read_base64_json('PLATFORM_VARIABLES');
    ```
  </Tab>

  <Tab title="Ruby">
    ```ruby theme={null}
    # A simple variable.
    project_id = ENV["PLATFORM_PROJECT"] || nil

    # An encoded JSON object.
    variables = JSON.parse(Base64.decode64(ENV["PLATFORM_VARIABLES"]))
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    import com.fasterxml.jackson.databind.ObjectMapper;

    import java.io.IOException;
    import java.util.Base64;
    import java.util.Map;

    import static java.lang.System.getenv;
    import static java.util.Base64.getDecoder;

    public class App {

        public static void main(String[] args) throws IOException {
            // A simple variable.
            final String project = getenv("PLATFORM_PROJECT");
            // An encoded JSON object.
            ObjectMapper mapper = new ObjectMapper();
            final Map<String, Object> variables = mapper.readValue(
                    String.valueOf(getDecoder().decode(getenv("PLATFORM_VARIABLES"))), Map.class);
        }
    }
    ```
  </Tab>
</Tabs>

### Access complex values

Variables can have nested structures.
The following example shows nested structures in an [app configuration](/docs/configure-apps/image-properties/variables):

You can access these nested variables as follows:

<Tabs>
  <Tab title="Shell">
    ```bash theme={null}
    echo $BASIC
    a string
    echo $INGREDIENTS
    ["peanut butter", "jelly"]
    echo $QUANTITIES
    {"cookies": "1 kg", "milk": "1 liter"}
    echo "$PLATFORM_VARIABLES" | base64 --decode | jq '."stuff:STEPS"'
    [
      "one",
      "two",
      "three"
    ]
    echo "$PLATFORM_VARIABLES" | base64 --decode | jq '."stuff:COLORS"'
    {
      "blue": "#0000FF",
      "green": "#00FF00",
      "red": "#FF0000"
    }
    ```
  </Tab>

  <Tab title="PHP">
    ```php theme={null}
    <?php
    var_dump($_ENV['BASIC']);
    // string(8) "a string"

    var_dump($_ENV['INGREDIENTS']);
    // string(26) "["peanut butter", "jelly"]"

    var_dump($_ENV['QUANTITIES']);
    // string(38) "{"milk": "1 liter", "cookies": "1 kg"}"

    $variables = json_decode(base64_decode($_ENV['PLATFORM_VARIABLES']), TRUE);

    print_r($variables['stuff:STEPS']);
    /*
    array(3) {
      [0]=>
      string(2) "one"
      [1]=>
      string(4) "two"
      [2]=>
      string(5) "three"
    }
    */

    print_r($variables['stuff:COLORS']);
    /*
    array(3) {
      ["red"]=>
      string(7) "#FF0000"
      ["green"]=>
      string(7) "#00FF00"
      ["blue"]=>
      string(7) "#0000FF"
    }
    */
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import os
    import json
    import base64

    print os.getenv('BASIC')
    # a string

    print os.getenv('INGREDIENTS')
    # ["peanut butter", "jelly"]

    print os.getenv('QUANTITIES')
    # {"milk": "1 liter", "cookies": "1 kg"}

    variables = json.loads(base64.b64decode(os.getenv('PLATFORM_VARIABLES')).decode('utf-8'))

    print variables['stuff:STEPS']
    # [u'one', u'two', u'three']
    print variables['stuff:COLORS']
    # {u'blue': u'#0000FF', u'green': u'#00FF00', u'red': u'#FF0000'}
    ```
  </Tab>

  <Tab title="Node.js">
    ```java theme={null}
    scriptconst { BASIC, INGREDIENTS, QUANTITIES, PLATFORM_VARIABLES } = process.env;

    const { "stuff:STEPS": stuffSteps, "stuff:COLORS": stuffColors } = JSON.parse(
      Buffer.from(PLATFORM_VARIABLES, "base64").toString()
    );

    console.log(BASIC);
    // "a string"
    console.log(INGREDIENTS);
    // ["peanut butter", "jelly"]
    console.log(QUANTITIES);
    // {"cookies": "1 kg", "milk": "1 liter"}
    console.log(stuffSteps);
    // [ 'one', 'two', 'three' ]
    console.log(stuffColors);
    // { blue: '#0000FF', green: '#00FF00', red: '#FF0000' }
    ```
  </Tab>
</Tabs>

## Use provided variables

Upsun Cloud also provides a series of variables to inform your app about its runtime configuration.
Many of them have a `PLATFORM_` prefix to differentiate them from user-provided values.
You can't set or update them directly.

The following table presents all available variables
and whether they're available at build time (during [build hooks](/docs/configure-apps/hooks/hooks-comparison#build-hook))
and at runtime.

| Variable name | Build | Runtime | Description |
| - | - | - | - |
| `CI` | Yes | No | Available for use in build scripts and tooling to modify build behavior (for example, to disable attempts to connect to other containers during the build phase, or to disable interactivity), which can help to reduce build failures. |
| `PLATFORM_APP_COMMAND` | No | Yes | The contents of the [web start command](/docs/configure-apps/image-properties/web#web-commands). |
| `PLATFORM_APP_DIR` | Yes | Yes | The absolute path to the app directory. |
| `PLATFORM_APPLICATION` | Yes | Yes | A base64-encoded JSON object that describes the app. It maps certain attributes from your [app configuration](/docs/configure-apps), some with more structure. See [notes](#platform_application). |
| `PLATFORM_APPLICATION_NAME` | Yes | Yes | The app name as set in your [app configuration](/docs/configure-apps). |
| `PLATFORM_BRANCH` | No | Yes | The name of the Git branch. |
| `PLATFORM_CACHE_DIR` | Yes | No | The directory where files are cached from one build to the next. The directory is shared among all branches, so the same cache is used for all environments. |
| `PLATFORM_DOCUMENT_ROOT` | No | Yes | The absolute path to the web document root, if applicable. |
| `PLATFORM_ENVIRONMENT` | No | Yes | The name of the Upsun Cloud environment. |
| `PLATFORM_ENVIRONMENT_TYPE` | No | Yes | The environment type of the Upsun Cloud environment (`development`, `staging`, or `production`). |
| `PLATFORM_OUTPUT_DIR` | Yes | No | The output directory for compiled languages at build time. Equivalent to `PLATFORM_APP_DIR` in most cases. |
| `PLATFORM_POST_APP_COMMAND` | No | Yes | The contents of the [web post\_start command](/docs/configure-apps/image-properties/web#web-commands). |
| `PLATFORM_PRE_APP_COMMAND` | No | Yes | The contents of the [web pre\_start command](/docs/configure-apps/image-properties/web#web-commands). |
| `PLATFORM_PROJECT` | Yes | Yes | The project ID. |
| `PLATFORM_PROJECT_ENTROPY` | Yes | Yes | A random, 56-character value created at project creation and then stable throughout the project's life. Can be used for Drupal hash salts, Symfony secrets, and other similar values. |
| `PLATFORM_RELATIONSHIPS` | No | Yes | The `PLATFORM_RELATIONSHIPS` variable is automatically broken down into [service environment variables](/docs/development/variables#service-environment-variables), so your app can seamlessly connect to databases and other services defined in `.upsun/config.yaml`.<br /><br />For some advanced use cases, you may need to use the `PLATFORM_RELATIONSHIPS` variable itself. It is a base64-encoded JSON object of relationships, with keys that indicate the relationship names, and values that are arrays of relationship endpoint definitions. The exact format is defined differently for each [service](/docs/add-services).<br />You may need to gather `PLATFORM_RELATIONSHIPS` information in a `.environment` file. See how to [use `.env` files](/docs/development/variables/set-variables#when-to-use-env-files), and refer to [dedicated service pages](/docs/add-services) for examples. |
| `PLATFORM_ROUTES` | No | Yes | A base64-encoded JSON object that describes the routes for the environment. It maps the content of your [routes configuration](/docs/routes). Note that this information is also available in your `/run/config.json` file. |
| `PLATFORM_SMTP_HOST` | No | Yes | The SMTP host to send email messages through. Is empty when mail is disabled for the current environment. |
| `PLATFORM_SOURCE_DIR` | Yes | No | The path to the root directory of your code repository in the context of a running [source operation](/docs/configure-apps/source-operations). The directory contains a writable copy of your repository that you can commit to during the operation. |
| `PLATFORM_TREE_ID` | Yes | Yes | The ID of the tree the application was built from, essentially the SHA hash of the tree in Git. Use when you need a unique ID for each build. |
| `PLATFORM_VARIABLES` | Some | Some | A base64-encoded JSON object with all user-defined project and environment variables that don't use a [prefix](/docs/development/variables#variable-prefixes). The keys are the variable names and the values are the variable values. Availability during builds and at runtime depends on the settings for each variable. See how to [access individual variables](#access-variables-in-a-shell). |
| `PLATFORM_VENDOR` | Yes | No | Allows you to change the behavior of the build according to the vendor (Upsun Cloud or Platform.sh). |
| `PORT` | No | Yes | A `string` representing the port to which requests are sent if the [`web.upstream.socket_family` property](/docs/configure-apps/image-properties/web#upstream) is unset or set to `tcp`. |
| `SOCKET` | No | Yes | A `string` representing the path to the Unix socket file to use if the [`web.upstream.socket_family` property](/docs/configure-apps/image-properties/web#upstream) is set to `unix`. |

### `PLATFORM_APPLICATION`

The `PLATFORM_APPLICATION` variable is available both at build time and in the runtime environment.
But the specific attributes it contains differ in each case.

Each environment's build is associated with a configuration ID that identifies it uniquely so builds can be reused.
The ID is a product of your app code and some of its [configuration for Upsun Cloud](/docs/configure-apps).
Not every attribute your app configuration is relevant to the build.
Only those attributes that are relevant to builds are accessible at build time from `PLATFORM_APPLICATION`.

Attributes that are **not** available in `PLATFORM_APPLICATION` during builds:

* Everything under `access`
* Everything under `relationship`
* `hooks.deploy` and `hooks.post_deploy`
* Everything under `crons`
* Everything under  `web`, except `web.mounts`
* Everything under `workers`, except `workers.mounts`

These attributes aren't visible during build because they aren't included as a part of the configuration component of the build slug.
So modifying these values in your [app configuration](/docs/configure-apps) doesn't trigger an app rebuild, only a redeploy.
For more information, read about [how builds work](/docs/core-concepts/build-deploy#the-build).

## Use variables in static files

Some apps require configuration values to be specified in a static, non-executable file (such as a `.ini`, `.xml`, or `.yaml` file)
and don't support reading from environment variables.

To populate these files with variables you set yourself,
make sure the variables are set to be [visible at build time](/docs/development/variables/set-variables#variable-options).

The files can't be populated with Upsun Cloud-provided variables not available at build time (such as `PLATFORM_RELATIONSHIPS` or [service environment variables](/docs/development/variables#service-environment-variables)).
You also can't write to them in a `deploy` hook as the file system is read only.

One workaround is to create a symbolic link to a writable location and then write to it in a [`deploy` hook](/docs/configure-apps/hooks/hooks-comparison#deploy-hook).
The following example shows the process, though you have to modify it to fit your needs.

1. Create a mount that isn't accessible to the web in your [app configuration](/docs/configure-apps):

2) Create a symbolic link from the config file the application wants to a location in that mount:

   ```bash theme={null}
   # From the application root...

   ln -s config/db.yaml db.yaml
   ```

   This example assumes the app wants a `db.yaml` file in its root for configuration.
3) Commit the symbolic link and an empty `config` directory to Git.
4) Configure a script to read from environment variables and write to `config/db.yaml` through the [service environment variables](/docs/development/variables#service-environment-variables) themselves, or through the [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables).
   <br />Create a file with a shell script similar to this:

<Tabs>
  <Tab title="Service environment variables">
    ```bash export-config.sh theme={null}
       #!/bin/bash

       # Ensure the file is empty.
       cat '' > config/db.yaml

       # Map the database information from the service environment variable into the YAML file.
       # Use this process to use whatever variable names your app needs.
       # For more information, please visit /docs/development/variables#service-environment-variables.

       printf "host: %s\n" $(echo $DATABASE_HOST) >> config/db.yaml
       printf "user: %s\n" $(echo $DATABASE_USERNAME) >> config/db.yaml
    ```
  </Tab>

  <Tab title="`PLATFORM_RELATIONSHIPS` environment variable">
    ```bash export-config.sh theme={null}
       #!/bin/bash

       # Ensure the file is empty.
       cat '' > config/db.yaml

       # Map the database information from the PLATFORM_RELATIONSHIPS variable into the YAML file.
       # Use this process to use whatever variable names your app needs.
       # For more information, please visit /docs/development/variables/use-variables#use-provided-variables.

       printf "host: %s\n" $(echo $PLATFORM_RELATIONSHIPS | base64 --decode | jq -r ".database[0].host") >> config/db.yaml
       printf "user: %s\n" $(echo $PLATFORM_RELATIONSHIPS | base64 --decode | jq -r ".database[0].username") >> config/db.yaml
    ```
  </Tab>
</Tabs>

5. Call the script from the `deploy` hook your [app configuration](/docs/configure-apps):

Now, when your app starts and attempts to parse `db.yaml`, the symbolic link redirects it to `config/db.yaml`.
Your script writes to that file on each deploy with updated information.
Your app reads the exported values and proceeds as expected.


# Set up your Cloudflare CDN
Source: https://developer.upsun.com/docs/domains/cdn/cloudflare

Learn how to configure your Cloudflare CDN.

You can [use a CDN](/docs/domains/cdn) to deliver your site's content to users more quickly.

## Before you begin

You need:

* An up-and-running Upsun Cloud project
* A [Cloudflare](https://www.cloudflare.com/) CDN subscription

## 1. Avoid double-caching

To avoid stale content that can't be cleared,
avoid using Cloudflare with [HTTP caching](/docs/routes/cache).

For routes where Cloudflare is used,
disable HTTP caching using the following configuration:

```yaml .upsun/config.yaml theme={null}
https://{default}/:
    type: upstream
    ...
    cache:
        enabled: false
```

## 2. Set up your Cloudflare CDN

To properly configure your Cloudflare CDN,
see the Cloudflare official documentation on [how to get started](https://developers.cloudflare.com/cache/get-started/).
Then set up a [custom domain](/docs/domains/steps).
To get the [DNS challenge to succeed](/docs/domains/troubleshoot#ownership-verification),
have your CDN point to your [project's target URL](/docs/domains/steps#1-get-the-target-for-your-project).

## 3. Handle apex domains

To start routing client traffic through Cloudflare,
you need to [create `CNAME` records for your domain names](/docs/domains/steps/dns)
through your DNS provider.

But `CNAME` records can't point to apex domains.
As a workaround, Cloudflare offers [`HTTPS` records](https://developers.cloudflare.com/dns/manage-dns-records/reference/dns-record-types/#svcb-and-https) and [`CNAME` flattening](https://developers.cloudflare.com/dns/additional-options/cname-flattening/).

## 4. Mitigate security risks

Like all networks exposed to the internet, your origin server may become the target of security attacks.
The best way to protect your site from threats like on-path attacks, spoofing attacks, or credential stuffing,
is to configure mutual TLS (mTLS).

[mTLS](https://www.cloudflare.com/en-gb/learning/access-management/what-is-mutual-tls/) not only has both parties in a connection authenticate each other
through the TLS protocol.
It also ensures that requests can't be sent directly to the origin server (Upsun Cloud).
Instead, requests must transit through Cloudflare first.

<Note>
  mTLS is only compatible with environments where you have attached domains you own, meaning:

  * Your production environment
  * Each preview environment where you have [attached a custom domain](/docs/domains/steps/custom-domains-preview-environments)

  Therefore, mTLS is **not** compatible with preview environments created by a [source code integration](/docs/integrations/source).
</Note>

If you can't use mTLS, you can still take the following measures to protect your site from on-path attacks:

1. [Enable full strict SSL/TLS encryption](https://developers.cloudflare.com/ssl/origin-configuration/ssl-modes/full-strict/).<br />
   Any communication between a client and Cloudflare or between Cloudflare and your Upsun Cloud server is then encrypted through HTTPS.
   In addition, Cloudflare checks that your Upsun Cloud server's [TLS certificate](/docs/glossary#transport-layer-security-tls)
   was issued by a trusted certificate authority.
   This confirms the client is truly communicating with your Upsun Cloud server.

2. [Enable HTTP strict transport security (HSTS)](https://developers.cloudflare.com/ssl/edge-certificates/additional-options/http-strict-transport-security/).<br />
   This ensures that your HTTPS connections can't be downgraded to HTTP.


# Set up your Fastly CDN
Source: https://developer.upsun.com/docs/domains/cdn/fastly

Learn how to configure your Fastly CDN.

You can [use a CDN](/docs/domains/cdn) to deliver your site's content to users more quickly.

To set up a Fastly CDN with your own Fastly subscription,
follow the instructions on this page.

## Before you begin

You need:

* An up-and-running Upsun Cloud project
* A [Fastly](https://www.fastly.com/) CDN subscription

## 1. Avoid double-caching

To avoid stale content that can't be cleared,
avoid using Fastly with [HTTP caching](/docs/routes/cache).

For routes where Fastly is used,
disable HTTP caching using the following configuration:

```yaml .upsun/config.yaml theme={null}
https://{default}/:
    type: upstream
    ...
    cache:
        enabled: false
```

## 2. Set up your Fastly CDN

To properly configure your Fastly CDN,
see the Fastly official documentation on [how to get started](https://docs.fastly.com/en/guides/getting-started#_basics).
Then set up a [custom domain](/docs/domains/steps).
To get the [DNS challenge to succeed](/docs/domains/troubleshoot#ownership-verification),
have your CDN point to your [project's target URL](/docs/domains/steps#1-get-the-target-for-your-project).

## 3. Handle apex domains

To start routing client traffic through Fastly,
[create `CNAME` records for your domain names](/docs/domains/steps/dns)
through your DNS provider.
`CNAME` records can't point to apex domains.
As a workaround, Fastly offers [Anycast options](https://docs.fastly.com/en/guides/using-fastly-with-apex-domains).

## 4. Optional: Protect your site from on-path attacks

An on-path attack occurs when a hacker intercepts
or modifies the communication between a client and a server.
This can lead to sensitive data leaks.
To prevent such attacks, make sure all communication with your site is encrypted through HTTPS
and can't be downgraded to HTTP.

To do so, enable HTTP strict transport security (HSTS).
HSTS forces clients to always communicate with your site over HTTPS.

You can [enable HSTS](https://docs.fastly.com/en/guides/enabling-hsts-through-fastly#forcing-tls-and-enabling-hsts)
in your Fastly account.
All HTTP requests are then automatically redirected to HTTPS.


# Content delivery networks (CDNs)
Source: https://developer.upsun.com/docs/domains/cdn/index

Improve performance for distributed end-users of your website with a content delivery network (CDN).

Using a CDN speeds up the delivery of your site's content to its users.
The CDN deploys edge servers at many locations around the world.
These edge servers behave like local caches to nearby users.
Bringing content closer to users helps enhance your site's perceived performance
and so can improve user engagement and retention.

Fastly is the recommended CDN for Upsun Cloud projects.
Self-service projects don't include a CDN by default, but you can set up one at any time,
such as [Fastly](/docs/domains/cdn/fastly) or [Cloudflare](/docs/domains/cdn/cloudflare).

## DNS records

To start routing client traffic through your CDN, [set up a custom domain](/docs/domains/steps).

If you use `CNAME` records for your custom domain, these records [can't point to apex domains](/docs/domains/steps/dns).
But most CDN providers offer workarounds.
For example, Fastly offers [Anycast options](/docs/domains/cdn/fastly#3-handle-apex-domains)
and Cloudflare offers [`CNAME` flattening](/docs/domains/cdn/cloudflare#3-handle-apex-domains).

## Host header forwarding

When an HTTP request is made to a website, the client adds a `Host` header to the request.
The value of this header is the domain name the request is made to.
When a server hosts multiple websites, like what a CDN does,
it can use the `Host` header to identify which domain to access to handle the request.

When a request is made from a client to fetch a resource on a CDN edge server,
the `Host` header value is rewritten to point to the CDN.
If the requested resource isn't cached on the edge server,
the edge server makes a request to the Upsun Cloud server to pull and cache the resource.

For this process to be successful,
set an `X-Forwarded-Host` header to forward the original `Host` header value to the Upsun Cloud server.
Use your root domain as the value of your `X-Forwarded-Host` header,
for example: `example.com`.

To ensure your app handles the `X-Forwarded-Host` header,
you might need to adjust your app configuration.
For more information on how to set up an `X-Forwarded-Host` HTTP header,
see your CDN provider's official documentation.

## Disable the router cache

When you use a CDN, the Upsun Cloud router [HTTP caching](/docs/routes/cache) becomes redundant.
To disable it, change your cache configuration for the routes behind a CDN to the following:

```yaml .upsun/config.yaml theme={null}
routes:
  "https://{default}/":
    type: upstream
    upstream: "myapp:http"
    cache:
      # Disable the HTTP cache on this route. It's handled by the CDN instead.
      enabled: false
```

## Prevent direct access to your server

When you use a CDN, you might want to prevent direct access to your Upsun Cloud server for security purposes.

### IP filtering and HTTP auth

While using password or IP based authentication might be possible, it is insecure, and unreliable. There are many scenarios in which the implementation can fail, and the security features circumvented.

Furthermore, IP based filtering will usually be impossible due to the fact that most CDNs use the `x-forwarded` HTTP header, which your project origin will use as the visitor IP address.

Both methods are highly insecure, and we highly recommend against them.

### Enable mTLS

If your CDN provider supports it,
you can secure your site through [mTLS](/docs/routes/https#enable-mtls).

To enable mTLS, follow these steps:

1. Obtain an Origin Certificate Authority (CA) certificate from your CDN provider.

2. Check that the CA certificate is a `.crt` file.
   If the file is a `.pem` file, rename it to `cdn.crt`.

3. Add the `cdn.crt` file to your Git repository.

4. Change your routing configuration for the routes behind a CDN to the following:

   ```yaml .upsun/config.yaml theme={null}
   routes:
     "https://{default}":
       tls:
         client_authentication: "require"
         client_certificate_authorities:
           - !include
             type: string
             path: cdn.crt
   ```

The procedure can vary depending on your CDN.
Contact your CDN provider for specific assistance.

Note that mTLS is a mutual authentication process.
It allows your CDN to check that it's communicating with your Upsun Cloud server
and vice versa.
So in addition to the CA certificate supplied by your CDN provider,
you need to [create your own TLS certificate](/docs/routes/https).


# Managed Fastly CDN
Source: https://developer.upsun.com/docs/domains/cdn/managed-fastly

Bring your content closer to users with a Fastly CDN fully managed by Upsun Cloud.

Instead of starting your own Fastly subscription and [managing your CDN yourself](/docs/domains/cdn/fastly),
you can take advantage of a Fastly CDN provided by Upsun Cloud.
These CDNs are exclusively set up and managed by Upsun Cloud.

To modify any settings for a managed Fastly CDN, or to request one for your project, open a [support ticket](/docs/core-concepts/get-support).
Add-ons that require a commitment, such as the Upsun Cloud Web Application Firewall (WAF) and edge-level rate limiting, involve [Sales](https://upsun.com/contact-us/).

<Note>
  Upsun Cloud does not write nor debug any custom VCL on Managed Fastly CDN services.
</Note>

<Note>
  <h4>Monitor CDN metrics</h4>
  You can access a summary of your monthly traffic usage under the "Traffic this month" section at the Project level inside [Console](https://console.upsun.com/). This will help you monitor your monthly bandwidth and requests consumption.

  In this summary, you will find specific details about:

  * **Origin Bandwidth:** Data transferred from origin servers (in TB).

  * **Origin Requests:** Requests served by origin servers (in millions of requests).

  * **CDN Bandwidth & CDN Requests:** Shown if you have Fastly CDN enabled.

  This data is updated daily and will reflect your traffic usage throughout the billing period.
</Note>

<Info>
  <h4>Set up traffic alerts</h4>
  You can also set up consumption alerts for your resource usage. Click the Alert button in the "Traffic this month" block within [Console](https://console.upsun.com/) to configure usage thresholds. For more information, head to the [Pricing docs page](/docs/administration/pricing).
</Info>

## How Managed Fastly works

Upsun Cloud’s Managed Fastly CDN routes incoming traffic through the Fastly edge network before requests reach your application. This enables global caching, edge logic (VCL), performance optimisation, and optional security features.

The Fastly CDN must be provisioned and managed by Upsun Cloud. Features such as the Upsun Cloud Web Application Firewall (WAF), edge rate limiting, and image optimization depend on this managed integration and cannot be used with a customer-managed Fastly account.

Once enabled, Fastly operates as the first point of contact for all HTTP requests, allowing requests to be cached, filtered, transformed, or blocked entirely at the edge.

<Info>
  <h4>Feature dependencies</h4>

  * The Upsun Cloud WAF requires the Upsun Cloud Managed Fastly CDN and a commitment arranged through [Sales](https://upsun.com/contact-us/).
  * Customers cannot attach the WAF to an existing third-party Fastly service.
  * Advanced Fastly features such as virtual patching and per-project logging require a configurable Fastly workspace.
</Info>

### Domain control validation

When you request for a new domain to be added to your Fastly service,
Upsun Cloud [Support](/docs/core-concepts/get-support) provides you with a [`CNAME` record](/docs/domains/steps/dns) for [domain control validation](/docs/domains/troubleshoot#ownership-verification).
To add this `CNAME` record to your domain settings,
see how to [configure your DNS provider](/docs/domains/steps#2-configure-your-dns-provider).

### Transport Layer Security (TLS) certificates

By default, two [TLS certificates](/docs/glossary#transport-layer-security-tls) are included: an apex and a wildcard one.
This allows for encryption of all traffic between your users and your app.

If you use a Fastly CDN provided by Upsun Cloud,
you can provide your own third-party TLS certificates for an additional fee.

To do so, if you don't have one,
set up a [mount](/docs/configure-apps/image-properties/mounts) that isn't accessible to the web.
Use an environment with access limited to Upsun Cloud Support and trusted users.
[Transfer](/docs/development/file-transfer) each certificate, its unencrypted private key,
and the intermediate certificate to the mount.
To notify Upsun Cloud that a certificate is to be added to your CDN configuration,
open a [support ticket](/docs/core-concepts/get-support).

If you need an Extended Validation TLS certificate,
you can get it from any TLS provider.
To add it to your CDN configuration, open a [support ticket](/docs/core-concepts/get-support).

Note that when you add your own third-party TLS certificates,
you are responsible for renewing them in due time.
Failure to do so may result in outages and compromised security for your site.

### Retrieve your Fastly API token

The API token for your managed Fastly CDN is stored in the `FASTLY_API_TOKEN` or the `FASTLY_KEY` environment variables.

This variable is usually set in the `/master/settings/variables` folder of your project,
and you can access it [from a shell](/docs/development/variables/use-variables#access-variables-in-a-shell)
or directly [in your app](/docs/development/variables/use-variables#access-variables-in-your-app).

## Dynamic ACL and rate limiting

For details about updating an access control list (ACL) and applying rate limiting, check out the [Working with Upsun Cloud rate-limiting implementation](https://support.platform.sh/hc/en-us/articles/29528777071890-Upsun-Fastly-Rate-Limiting-How-it-works-how-to-tune-it) article in the Upsun Community.

## Edge-level rate limiting

Upsun Cloud provides edge-level rate limiting through Fastly, allowing you to control how many requests a single IP address or network can make within a given time window.

Rate limiting is applied at the edge, before requests reach your application, helping to reduce load and mitigate abusive traffic patterns.

### What Edge-level rate limiting can do

* Protect sensitive endpoints such as `/login`, `/admin`, or checkout paths
* Limit request floods from a single IP or IP range
* Reduce application load during traffic spikes
* Enable Upsun Cloud Support to better handle attacks or high-traffic events by throttling traffic at the edge

Edge-level rate limiting is available as a standalone add-on (without the WAF), and requires a commitment arranged through [Sales](https://upsun.com/contact-us/).

### Configuration and defaults

There are no default rate-limiting rules applied automatically. Rate limiting is configured during onboarding, or by request via Upsun Cloud [Support](/docs/core-concepts/get-support).

Rules can be scoped by:

* Request path
* Request type
* IP address or network
* Custom thresholds and actions (block, allow, log)

### Limitations

Edge-level rate limiting is a rule-based control mechanism, not an automated bot-detection system. It does not:

* Identify bots automatically
* Present CAPTCHA or JavaScript challenges
* Provide AI-driven mitigation

For advanced bot and scraper protection, Upsun Cloud offers separate third-party integrations.


# Custom domains
Source: https://developer.upsun.com/docs/domains/index

Add a custom domain to your Upsun Cloud project, configure DNS, set up a CDN, and go live.

<CardGroup>
  <Card title="Set up a custom domain" icon="globe" href="/docs/domains/steps">
    Add your own domain to a production or preview environment. Covers DNS setup, TLS, and subdomain sharing.
  </Card>

  <Card title="Content delivery network (CDN)" icon="server" href="/docs/domains/cdn">
    Set up a CDN with Fastly or Cloudflare for your custom domain.
  </Card>
</CardGroup>


# Set up a custom domain on a preview environment
Source: https://developer.upsun.com/docs/domains/steps/custom-domains-preview-environments

Learn how to set up custom domains on your preview environments

By default, Upsun Cloud makes each [preview environment](/docs/glossary#preview-environment)
available at an automatically generated URL — for example, something like
`staging-abc123-yourproject.eu.platformsh.site`. This is true even if you've already added a custom
domain to your production environment; preview environments don't automatically inherit it.

If you want preview environments accessible at meaningful, predictable URLs, you can add a custom
domain to each one — but you must have at least one custom domain set up on your production
environment first. You then follow the same basic steps as [setting up a production
custom domain](/docs/domains/steps) — configure DNS, then add the domain to the environment
— with two differences:

* You don't need to update your [routes configuration](/docs/routes)
* You must attach the preview domain to its corresponding production domain — that is, tell Upsun Cloud which production domain's routing rules the preview domain should follow.

If you have multiple custom domains on your production environment, select which one to attach the preview domain to. Upsun Cloud derives the routing automatically.

<Note>
  <h4>Example</h4>
  You have two environments, a production environment and a staging environment.
  You've added the `example.com` custom domain to your production environment.

  You want to add the `staging.example.com` custom domain to your staging environment.
  To do so, you need to attach the new `staging.example.com` custom domain
  to its corresponding custom production domain `example.com`.

  You can then access your staging environment through `staging.example.com`,
  and still access your production environment through `example.com`.
</Note>

## Before you start

You need:

* A production environment with at least one custom domain configured
* At least one preview (staging or development) environment
* Optional: The [Upsun Cloud CLI](/cli) (v4.8.0+)

By default, you can add custom domains to up to 5 preview environments per project.
You can increase this limit without charge by [contacting Support](/docs/core-concepts/get-support).

<Warning>
  <h4>Deleting a production domain removes attached preview domains</h4>
  If you [remove a production domain](/docs/domains/steps#remove-a-domain), all preview domains attached to it are also deleted.
</Warning>

## Add a custom domain to a preview environment

To add a custom domain to a preview environment, follow these steps:

<Tabs>
  <Tab title="Using the CLI">
    1. Get the CNAME value for your preview environment — this is the Upsun Cloud-provided hostname your DNS record needs to point to:

       ```bash theme={null}
       upsun environment:info edge_hostname --environment <ENVIRONMENT_NAME>
       ```

    2. [Configure your DNS provider](/docs/domains/steps#2-configure-your-dns-provider).
       In particular, make sure your DNS record points to the target of your preview environment.

       <Note>
         Use your preview environment's CNAME value rather than your production environment's. Upsun recommends this to ensure correct routing for your preview environment.
       </Note>

    3. Run a command similar to the following:

       ```bash theme={null}
       upsun domain:add <YOUR_PREVIEW_DOMAIN> --environment <STAGING_ENVIRONMENT_ID> --attach <PRODUCTION_CUSTOM_DOMAIN_TO_ATTACH>
       ```
  </Tab>

  <Tab title="In the Console">
    1. Get the CNAME value for your preview environment — this is the Upsun Cloud-provided hostname your DNS record needs to point to.<br />
       Navigate to your preview environment and click **<SettingsIcon /> Settings**.<br />
       Select the **Domains** tab.<br />
       In the **Configure your domain** section, copy the content of the **CNAME record** field.<br />
       Save it for later use at step 7.

    2. Click **Add domain**.

    3. Name the custom domain for your preview environment.

    4. Attach the custom domain for your preview environment to the desired production custom domain.

    5. Click **Add**.

    6. Click **Okay**.

    7. [Configure your DNS provider](/docs/domains/steps#2-configure-your-dns-provider).<br />
       In particular, make sure your DNS record points to the target of your preview environment.

    <Note>
      Use your preview environment's CNAME value rather than your production environment's. Upsun recommends this to ensure correct routing for your preview environment.
    </Note>
  </Tab>
</Tabs>

<Note>
  <h4>Preview domains cannot be edited</h4>
  To change a preview environment’s custom domain, delete it and add a new one.
</Note>

### Example

You've added the `example.com` custom domain to your production environment.
You now want to add the `staging.example.com` custom domain to a preview environment called `staging`.

To do so, follow these steps:

<Tabs>
  <Tab title="Using the CLI">
    Run the following command:

    ```bash theme={null}
    upsun domain:add staging.example.com --environment staging --attach example.com
    ```
  </Tab>

  <Tab title="In the Console">
    1. Get the CNAME value for `staging`.<br />
       To do so, navigate to `staging` and click **<SettingsIcon /> Settings**.<br />
       Select the **Domains** tab.<br />
       In the **Configure your domain** section, copy the content of the **CNAME record** field.<br />
       Save it for later use at step 7.

    2. Click **Add domain**.

    3. Enter `staging.example.com` as the custom domain you want to add to `staging`.

    4. Select `example.com` as the production custom domain you want to attach `staging.example.com` to.

    5. Click **Add**.<br />

    6. Click **Okay**.

    7. [Configure your DNS provider](/docs/domains/steps#2-configure-your-dns-provider).<br />
       In particular, make sure your DNS record points to `staging`'s CNAME value.
  </Tab>
</Tabs>

In the above example, the `staging` environment needs to exist
for you to add the `staging.example.com` custom domain successfully.
If the `staging` environment is later removed,
the `staging.example.com` custom domain is removed too.

## Manage custom domains on a preview environment

<Tabs>
  <Tab title="Using the CLI">
    | Action | Command |
    | - | - |
    | List all domains | `upsun domain:list --environment <ENVIRONMENT_NAME>` |
    | View a specific domain | `upsun domain:get <YOUR_PREVIEW_DOMAIN> --environment <ENVIRONMENT_NAME>` |
    | Remove a domain | `upsun domain:delete <YOUR_PREVIEW_DOMAIN> --environment <ENVIRONMENT_NAME>` |
  </Tab>

  <Tab title="In the Console">
    1. Navigate to your preview environment and click **<SettingsIcon /> Settings**.
    2. Select the **Domains** tab.<br />
       All the custom domains for your preview environment are displayed.
    3. To act on a domain, click **<MoreIcon /> More** next to it:
       * To view details, select the domain from the list.
       * To delete a domain, click **Delete**, then confirm.
  </Tab>
</Tabs>


# DNS management and apex domains
Source: https://developer.upsun.com/docs/domains/steps/dns

See why `CNAME` records are used and how to handle apex domains.

Using `CNAME` records helps [prevent downtime](#cname-records) during maintenance operations.
But `CNAME` records can't point to apex domains,
so you need to [set up a workaround](#workarounds-for-apex-domains).
Available workarounds depend on your DNS provider.

## `CNAME` records

Each site on Upsun Cloud is made up of a set of containers.
To map incoming requests to the appropriate container,
Upsun Cloud runs routers in [each region](/docs/development/regions).
A router's IP address can change in two cases:

* During an upgrade or maintenance operation, routers can be taken offline while changes are applied.
* During a region upscale or downscale, routers can be added or removed.

In such situations, using `A` records can cause downtime.
`A` records map a domain to an IP address.
When a router's IP address changes,
you need to manually update your `A` records.
Your site remains offline until you do,
or until the router is back from maintenance.

To prevent downtime, create `CNAME` records through your DNS provider.
`CNAME` records map a domain to another.
Set up your `CNAME` records to point at your project's [target URL](/docs/domains/steps#1-get-the-target-for-your-project).
The DNS record for this target URL automatically resolves to the IP addresses of the routers in your project's region.
When a router's IP address changes,
the DNS record is automatically and immediately updated.
This prevents downtime without intervention from you.

Note that `CNAME` records can't point to [apex domains](/docs/glossary#apex-domain).
Check with your DNS provider if they offer [workarounds](#workarounds-for-apex-domains).

## Workarounds for apex domains

Although `CNAME` records can't point to apex domains,
most DNS providers offer workarounds.
Contact your DNS provider and choose the option that works for you.

If you use a CDN, you likely already have a workaround in place,
such as with [Fastly](/docs/domains/cdn/fastly#3-handle-apex-domains)
and [Cloudflare](/docs/domains/cdn/cloudflare#3-handle-apex-domains).

### Custom records

Some DNS providers offer custom records such as `ANAME`, `ALIAS` or `HTTPS` records,
which you can manage like `CNAME` records.
But unlike `CNAME` records, these custom records can point to apex domains.

To use custom records, follow the instructions on [how to set up a custom domain](/docs/domains/steps).
When you come to configuring your DNS provider, instead of a `CNAME` record,
add a custom record pointing from your domain to [your project's target URL](/docs/domains/steps#1-get-the-target-for-your-project).

### Domain forwarding

If your DNS provider doesn't support custom records,
consider using domain forwarding.

If your domain is `example.com`, domain forwarding redirects all requests from `example.com` to `www.example.com`.

To use domain forwarding, follow these steps:

1. Make the `www.` version of your site the default (canonical) version
   and configure your app and routes to [use the `www` subdomain as `upstream`](/docs/routes).

2. Follow the instructions on [how to set up a custom domain](/docs/domains/steps).
   When you come to configuring your DNS provider,
   instead of a `CNAME` record, add a record forwarding requests
   from `<YOUR_DOMAIN>` to `www.<YOUR_DOMAIN>`.

### Redirection service

If your DNS provider doesn't support custom records or domain forwarding,
consider using a redirection service.
If your domain is `example.com`,
a redirection service uses an `A` record to redirect all requests from `example.com` to `www.example.com`.

To use a redirection service, follow these steps:

1. Make the `www.` version of your site the default (canonical) version
   and configure your app and routes to [use the `www` subdomain as `upstream`](/docs/routes).

2. Follow the instructions on [how to set up a custom domain](/docs/domains/steps).
   When you come to configuring your DNS provider, instead of a `CNAME` record,
   add an `A` record pointing from your domain to the redirection service.

### `A` records

If your DNS provider doesn't support any other workaround,
consider using `A` records, but only as a last resort.
When you use `A` records, [if a router's IP address changes](#cname-records),
you need to update your `A` records manually.
Until you do, your site can appear offline because requests are lost.

To use `A` records, follow these steps:

1. [Get the IP addresses](/docs/development/regions#public-ip-addresses) of your project's production environment.

2. Follow the instructions on [how to set up a custom domain](/docs/domains/steps).
   When you come to configuring your DNS provider, instead of a `CNAME` record,
   add `A` records pointing from your domain to each of the IP addresses from step 1.
   When a request comes in, one of those IP addresses is used at random.


# DNS challenge for domain ownership
Source: https://developer.upsun.com/docs/domains/steps/dns-challenge

Verify domain ownership using a DNS TXT record to prevent unauthorized domain assignment across organizations.

When DNS challenge verification is enabled and you add a domain to an Upsun Cloud project, the platform performs a DNS challenge to verify that your organization owns the domain. This prevents another organization from claiming your domain and intercepting its traffic.

<Warning>
  <h4>Contact support to enable</h4>
  DNS challenge verification is not enabled by default and is controlled by the `requires_domain_ownership` setting. Contact <a href="https://docs.upsun.com/docs/overview/get-support">support</a> to have it enabled for your project.
</Warning>

## When to use DNS challenges

Consider using DNS challenges when you share a domain across multiple projects. If different projects within your organization use subdomains of the same apex domain (for example, `app.example.com` and `api.example.com`), setting up a DNS challenge ensures that no other organization can claim any of those subdomains.

<Info>
  <h4>DNS challenges complement existing protections</h4>
  The DNS challenge is an additional layer of security on top of the existing [Public Suffix List (PSL) approach](/docs/domains/steps/subdomains#how-domain-reservation-works). It does not replace it. If you are also sharing subdomains across multiple projects, you still need to follow the steps in [Enable subdomains across multiple projects](/docs/domains/steps/subdomains#enable-subdomains-across-multiple-projects). The DNS challenge adds organizational ownership verification independently of that process.
</Info>

## Why DNS challenges exist

Without ownership verification, a domain whose DNS still points to Upsun Cloud's infrastructure could be claimed by a different organization's project, letting that organization receive traffic meant for the legitimate owner. This can happen, for example, if you remove a domain from one project but leave its DNS records pointing to Upsun Cloud. The DNS challenge ensures only the organization that controls a domain's DNS records can add it to a project.

## How it works

<Info>
  <h4>Legacy `_upsun-organization` records still work</h4>

  This challenge record was renamed from `_upsun-organization.<YOUR_DOMAIN>` to `_domain-ownership.<YOUR_DOMAIN>`. If you're still using the legacy `_upsun-organization` name, update to `_domain-ownership` when convenient. The platform continues to honor the legacy name, so this isn't urgent.

  If both records exist for the same domain, `_domain-ownership.<YOUR_DOMAIN>` takes precedence.
</Info>

When you add a domain to a project, Upsun Cloud checks for a `TXT` record on a special subdomain: `_domain-ownership.<YOUR_DOMAIN>`. The `TXT` record must contain your organization ID in the following format:

```text theme={null}
organization=<YOUR_ORG_ID>
```

You can retrieve your organization ID by running the following CLI command:

```bash Terminal theme={null}
upsun organization:info --format plain
```

The `id` field in the response is the value to use in the `TXT` record.

If the organization ID in the `TXT` record doesn't match the organization that owns the project, the domain is rejected.

<Warning>
  <h4>Keep the TXT record in place</h4>
  The `TXT` record must remain in your DNS for as long as the domain points to Upsun Cloud's servers. The platform re-checks it periodically, so removing it while the domain is active can cause issues.
</Warning>

### Example

For a project with the following details:

| Detail | Value |
| - | - |
| Domain to add | `app.example.com` |
| Project ID | `abcdefg` |
| Organization ID | `123456` |

You would create the following `TXT` record:

```text theme={null}
_domain-ownership.app.example.com  TXT  "organization=123456" # Do not remove
```

You can verify the record is in place by running:

```bash Terminal theme={null}
dig +short _domain-ownership.app.example.com TXT
```

The `CNAME` configuration for the domain itself remains unchanged:

```bash Terminal theme={null}
dig +short app.example.com CNAME
main-bvxea6i-abcdefg.eu-3.platformsh.site.
```

## Subdomain trimming

You don't need to create a separate challenge record for every subdomain. Upsun Cloud walks up the domain hierarchy, from the full domain toward the apex, until it finds a valid challenge record.

For example, to allow both `app.example.com` and `api.example.com` to be added to the same organization, you can create a single record at the parent domain level:

```text theme={null}
_domain-ownership.example.com  TXT  "organization=123456" # Do not remove
```

This record covers all subdomains under `example.com`. The platform stops checking as soon as it finds a valid challenge record.

<Info>
  <h4>Public Suffix List</h4>
  The trimming process respects the Public Suffix List (PSL). The platform won't look for challenge records on public suffixes like `.org` or `.co.uk`.
</Info>

## Multiple organizations

If you need to allow multiple organizations to add subdomains under the same parent domain, you can include multiple organization IDs in a single `TXT` record. Separate each entry with a **space**:

```text theme={null}
_domain-ownership.example.com  TXT  "organization=01234 organization=56789" # Do not remove
```

<Warning>
  <h4>Use spaces only</h4>
  The separator between organization entries must be a space. Commas, semicolons, and newlines are not supported.
</Warning>

## Validation behavior

The DNS challenge check runs every time a domain is added to a project, regardless of whether the feature is explicitly enabled. However, how the result is enforced depends on the project's configuration:

| Project setting | TXT record present | Behavior |
| - | - | - |
| `requires_domain_ownership`: **true** | Yes, valid | Domain is added successfully |
| `requires_domain_ownership`: **true** | No or invalid | Domain is **rejected** |
| `requires_domain_ownership`: **false** | Yes | TXT record is validated — domain is rejected if the org ID doesn't match |
| `requires_domain_ownership`: **false** | No | Domain is added without challenge validation |

## Set up a DNS challenge

To set up domain ownership verification, follow these steps:

1. Find your organization ID in the Upsun Cloud Console under your organization settings.

2. Create a `TXT` record with your DNS provider:

   | Record type | Name | Value |
   | - | - | - |
   | `TXT` | `_domain-ownership.<YOUR_DOMAIN>` | `organization=<YOUR_ORG_ID>` |

   To cover all subdomains under a parent domain, set the record at the parent level (e.g. `_domain-ownership.example.com`).

3. Wait for DNS propagation, then verify the record:

   ```bash Terminal theme={null}
   dig +short _domain-ownership.<YOUR_DOMAIN> TXT
   ```

4. Add your domain to your Upsun Cloud project as usual. The platform automatically validates the challenge record during this step.

   Leave the `TXT` record in place afterwards. It is checked again every time you add another domain or subdomain.


# Set up a custom domain
Source: https://developer.upsun.com/docs/domains/steps/index

Add a custom domain to your project once it's ready to go live.

Once your project is ready for production, replace the automatically generated domain with your own custom domain.
Note that adding a domain disables the automatically generated URL for your Production environment only.

You can also [customize the URLs for your preview environments](/docs/domains/steps/custom-domains-preview-environments).

## Before you begin

You need:

* A project that's ready to go live
* A domain with access to its settings with the registrar
* A registrar that allows `CNAME` records or [one of the alternatives](/docs/domains/steps/dns) on [apex domains](/docs/glossary#apex-domain)
* Optional: The [CLI](/cli) installed locally

If you are planning to use several subdomains of the same domain on different projects,
see how to [manage multiple subdomains](/docs/domains/steps/subdomains) *before* you add your domain to Upsun Cloud.

## 1. Get the target for your project

You want to point your DNS record to the automatically generated URL.
Your domain needs to point to that target for your site to go live.

<Tabs>
  <Tab title="Using the CLI">
    Get the target by running the following [CLI command](/cli):

    ```bash theme={null}
    upsun environment:info edge_hostname
    ```
  </Tab>

  <Tab title="In the Console">
    1. Navigate to your production environment and click **<SettingsIcon /> Settings**.
    2. Select the **Domains** tab.
    3. In the **Configure your domain** section, copy the content of the **CNAME record** field.
  </Tab>
</Tabs>

## 2. Configure your DNS provider

Your DNS provider (usually your registrar) is where you manage your domain.
Most registrars offer similar functionalities regarding DNS configuration but use different terminology or configuration.
For example, some registrars require you to use an `@` to create custom records on the apex domain, while others don't.
Check your registrar's documentation.

Note that depending on your registrar and the time to live (TTL) you set,
it can take anywhere from 15 minutes to 72 hours for DNS changes to be taken into account.

<Tabs>
  <Tab title="Not using a CDN">
    To configure your domain name to point to your project:

    1. Consult your provider’s documentation to find out how to add or edit DNS records.
    2. Open your registrar’s domain management system.
    3. Set the TTL on your domain to the lowest possible value to minimize transition time.
    4. Add a `CNAME` record pointing from your domain to the [target](#1-get-the-target-for-your-project).
       Not all registrars allow these kinds of records.
       If yours doesn’t, see the [alternatives](/docs/domains/steps/dns#workarounds-for-apex-domains).
    5. Optional: If you have multiple domains you want to be served by the same app, add a `CNAME` record for each of them.
       That includes the `www` subdomain if you are using it in your [routes configuration](/docs/routes).
    6. Set the TTL value back to its previous value.

    If your domain is `example.com` and you are using the `www` subdomain, you have records like the following:

    * `example.com` is a `CNAME`/`ANAME`/`ALIAS` record pointing to `main-abcd123.abcdefgh1234567.eu.platformsh.site`.
    * `www.example.com` is a `CNAME` record pointing to `main-abcd123.abcdefgh1234567.eu.platformsh.site`.

    Both `example.com` and `www.example.com` point to the same target.
    Redirects are handled by the [router you configure](/docs/routes).
  </Tab>

  <Tab title="Using a CDN">
    To configure your CDN and your domain name to point to your project:

    1. Open your CDN’s management system.
    2. Point the CDN at your [target](#1-get-the-target-for-your-project).
    3. Open your registrar’s domain management system.
    4. Open your registrar’s domain management system and configure your DNS zone settings to point at your CDN.
       The address or `CNAME` record to use varies by CDN provider.
       Refer to the official documentation of your DNS provider and CDN provider.
    5. Check that redirects and subdomains are set correctly for the [TLS certificate ownership verification](/docs/domains/troubleshoot#ownership-verification).
    6. [Disable the router cache](/docs/domains/cdn#disable-the-router-cache).
    7. Optional: For increased security and to prevent the CDN from being bypassed,
       you can force all traffic to [go through the CDN](/docs/domains/cdn#prevent-direct-access-to-your-server).
    8. Optional: If you have multiple domains you want to be served by the same app, add a `CNAME` record for each of them.
       That includes the `www` subdomain if you are using it in your [routes configuration](/docs/routes).

    Adding a custom domain sets your site as [visible to search engines](/docs/environments/search-engine-visibility#how-its-done).

    See how you can further [configure your CDN](/docs/domains/cdn).
  </Tab>
</Tabs>

## 3. Set your domain

Add a single domain to your project:

<Tabs>
  <Tab title="Using the CLI">
    Run the following command:

    ```bash theme={null}
    upsun domain:add <YOUR_DOMAIN>
    ```
  </Tab>

  <Tab title="In the Console">
    1. Select the project where you want to add a domain.
    2. Click <SettingsIcon /> **Settings**.
    3. Click **Domains**.
    4. In the **Domain** field, enter your domain.
    5. Click **Add domain**.
  </Tab>
</Tabs>

## Remove a domain

<Warning>
  <h4>Removing a production domain deletes attached preview domains</h4>
  Removing a custom production domain also deletes all preview domains attached to it.
  Trigger a rebuild on the affected preview environments to complete the deletion.
</Warning>

<Tabs>
  <Tab title="Using the CLI">
    Run the following command:

    ```bash theme={null}
    upsun domain:delete <YOUR_DOMAIN>
    ```
  </Tab>

  <Tab title="In the Console">
    1. Select the project where you want to remove a domain.
    2. Click <SettingsIcon /> **Settings**.
    3. Click **Domains**.
    4. Click **<MoreIcon /> More** next to the domain you want to remove.
    5. Click **Delete**.
    6. Confirm the deletion.
  </Tab>
</Tabs>

## What's next

* [Use a content delivery network](/docs/domains/cdn)
* [Use subdomains across multiple projects](/docs/domains/steps/subdomains)
* [Use a custom TLS certificate](/docs/domains/steps/tls)
* [Set search engine visibility for your production environment](/docs/environments/search-engine-visibility)


# Share subdomains across different projects
Source: https://developer.upsun.com/docs/domains/steps/subdomains

Learn how to host subdomains from the same apex domain across multiple Upsun Cloud projects using a DNS TXT record and DNS challenge.

By default, Upsun Cloud lets only one project at a time use a given domain. This prevents other users
from claiming your subdomains. If you need multiple Upsun Cloud projects to share subdomains of the same root domain
(the *apex domain*, for example `example.com`), you must explicitly allow this by adding a DNS TXT record and optionally, a DNS challenge.

Sharing subdomains across projects is common in the following scenarios:

* **Decoupled architectures**: A frontend project (for example, Next.js or React) uses `example.com` and a separate
  backend API project uses `api.example.com`, with independent resource allocations per project.
* **Microservices**: A product is split into independently deployable services, each mapped to its own subdomain
  (`checkout.example.com`, `account.example.com`, `catalog.example.com`). Sharing an apex domain can simplify cookie
  and session handling and reduce cross-origin complexity, but requests between subdomains are still cross-origin and may require cross-origin
  reference sharing (CORS).
* **Multi-tenant applications**: Each customer gets a dedicated subdomain (`client-a.example.com`,
  `client-b.example.com`) with private data and configuration, while all subdomains share the same apex domain.
* **Multi-region deployment**: Identical codebases run in different Upsun Cloud projects in different
  geographic regions. Users reach the project in their region through the same parent domain.

To host multiple subdomains within a *single* project instead, use [routes](/docs/routes).

<Info>
  <h4>Domain ownership verification</h4>
  The steps below protect against subdomain takeover within Upsun Cloud. To also prevent other organizations
  from claiming your domain, complete the recommended [DNS challenge](/docs/domains/steps/dns-challenge) in step 4.
</Info>

If you attempt to add a subdomain that is already in use by another project,
you get an error similar to the following:

```text {no-copy="true"} theme={null}
This domain is already claimed by another service
```

## Enable subdomains across multiple projects

<Info>
  <h4>Two different TXT records, two different purposes</h4>

  This guide refers to two separate DNS `TXT` records that serve distinct roles:

  | Record | Purpose | Lifetime |
  | - | - | - |
  | `_public-suffix-root.<YOUR_APEX_DOMAIN>` (step 1) | Tells Upsun Cloud to allow multiple projects to share your domain | **Temporary** — remove it after linking all subdomains |
  | `_domain-ownership.<YOUR_DOMAIN>` (step 4) | Proves your organization owns the domain | **Permanent** — keep it in place |

  `<YOUR_DOMAIN>` in the DNS challenge record can be your apex domain (`example.com`) or any subdomain level (`app.example.com`). A record set at a parent level covers all subdomains beneath it — you don't need a separate record for each subdomain.

  The first record enables subdomain sharing within Upsun Cloud. The second prevents a different organization from claiming your domain entirely. They solve different problems.
</Info>

1. Add a `TXT` DNS record for your apex domain. This tells Upsun Cloud to allow multiple projects to use
   different subdomains under the same root.

   ```text {no-copy="true"} theme={null}
   _public-suffix-root.<YOUR_APEX_DOMAIN> TXT "public-suffix-root=<YOUR_APEX_DOMAIN>"
   ```

   Replace `<YOUR_APEX_DOMAIN>` with your domain (for example, `example.com`). This temporarily tells Upsun Cloud
   to treat your domain like a top-level domain — which allows each subdomain to be assigned to a different project.
   See [how domain reservation works](#how-domain-reservation-works) for a full explanation.

2. Add each subdomain to its respective Upsun Cloud project. Follow the standard [domain setup steps](/docs/domains/steps)
   for each project.

   <Info>
     <h4>Domain already claimed?</h4>
     If your domain is locked to a specific project (for example, if Upsun Cloud support added it manually), neither
     the apex domain (`example.com`)
     nor any subdomain (`app.example.com`) can be added to a second project. [Contact Support](/docs/core-concepts/get-support)
     and include the project ID of the project that already has the domain.
   </Info>

3. Remove the `TXT` record. This reinstates [subdomain takeover protection](#how-domain-reservation-works) and prevents other
   users from adding your subdomains to their own projects.

   If you don't remove the `TXT` record:

   * Other users can claim subdomains of your domain unless you have wildcard DNS records pointing at Upsun Cloud.
     Wildcard DNS records are the one thing that blocks other users from claiming subdomains.
   * You can't add your apex domain to a different project until you remove the record.

4. (Recommended, but not required) Set up a [DNS challenge](/docs/domains/steps/dns-challenge) to verify organizational ownership
   of your domain. This uses a **separate** `TXT` record (`_domain-ownership.<YOUR_DOMAIN>`) that is different from the one in
   step 1, and unlike the step 1 record, you keep it permanently. It prevents a different organization on Upsun Cloud
   from claiming your domain, even if your DNS still points to Upsun Cloud's infrastructure.

## How domain reservation works

Upsun Cloud's domain sharing behaviour is built on two security concepts from the browser world. Expand either for a full explanation.

<AccordionGroup>
  <Accordion title="The Public Suffix List">
    Upsun Cloud's subdomain sharing feature is modeled on the browser Public Suffix List (PSL) — a standard that
    determines which domains get treated like top-level domains for security purposes.

    Domain names are divided into hierarchical levels separated by `.`. The rightmost part, such as `.com`, `.edu`, or `.fr`,
    is the top-level domain (TLD). Browsers apply special rules to TLDs. For example, a page at `app.region.checkout.example.com` can
    set a cookie scoped to `example.com`, making it available to all its subdomains. That same page can't set a cookie scoped
    to `.com` itself, since that would affect every `.com` site.

    Browser vendors extend these rules through the [Public Suffix List (PSL)](https://publicsuffix.org/), a curated list of
    domain suffixes that receive TLD-like treatment. If `example.com` were on the PSL, browsers would reject a cookie scoped
    to `example.com` when set by a page at `app.example.com`. They would still accept a cookie set directly by `example.com`.
  </Accordion>

  <Accordion title="Subdomain takeover protection">
    By default, when you add a domain to an Upsun Cloud project, Upsun Cloud reserves the first level of
    that domain not covered by the PSL. Adding `app.region.checkout.example.com` reserves `example.com` for that project, so no other
    project can claim any domain under `*.example.com`. You can still add multiple subdomains within that same project.

    This prevents subdomain takeover. Without this protection, a malicious user could register `evil.example.com` in a
    separate project and use it to set cookies on your `example.com` site.

    This is secure by default, but it creates a conflict when you legitimately want multiple separate projects to share
    subdomains of the same apex domain.

    Upsun Cloud solves this with a small extension to the PSL. When you add a `TXT` record for a domain,
    Upsun Cloud treats that domain as a PSL entry. This shifts what gets reserved when you add a subdomain:

    * Without the `TXT` record: adding `app.region.checkout.example.com` reserves `example.com` for that project.
    * With the `TXT` record for `example.com`: adding `app.region.checkout.example.com` reserves only `checkout.example.com`.
      Another project can then claim `api.example.com` without conflict.

    You can apply this at any subdomain level. If you set a `TXT` record for `checkout.example.com` and add
    `app.region.checkout.example.com` to a project, only `region.checkout.example.com` is reserved for that project.
  </Accordion>
</AccordionGroup>


# Configure a third-party TLS certificate
Source: https://developer.upsun.com/docs/domains/steps/tls



Upsun Cloud automatically provides standard Transport Layer Security (TLS) certificates for all sites and environments.
These certificates are issued at no charge by [Let's Encrypt](https://letsencrypt.org/) and cover most needs.
To use them, you need to [specify HTTPS routes](/docs/routes/https#enable-https).
Note that some [limitations](/docs/routes/https#lets-encrypt-limitations) apply.

Upsun Cloud allows you to use third-party TLS certificates free of charge.

You can use many kinds of custom certificates, including domain-validated, extended validation, high-assurance, or wildcard certificates.
Consult your TLS issuer for pricing and instructions on how to generate a TLS certificate.

Seven days before a third-party custom certificate is due to expire,
Upsun Cloud replaces it with a new default Let’s Encrypt certificate.
This helps prevent downtime.
To avoid switching to a default certificate,
make sure you replace your custom certificate with an updated one
more than seven days before its expiration date.

Note that custom certificates aren't necessary for preview environments as we provision Let's Encrypt certificates by default for them.

### Add a custom certificate

You can add a custom certificate using the [CLI](/cli) or in the [Console](/docs/administration/web).

Your certificate has to be in PKCS #1 format and start with `-----BEGIN RSA PRIVATE KEY-----`.
If it doesn't start that way, [change the format](#change-the-private-key-format).

To add your custom certificate, follow these steps:

<Tabs>
  <Tab title="Using the CLI">
    1. Run the following command:

       ```bash theme={null}
       upsun domain:add <YOUR_DOMAIN> --cert <PATH_TO_CERTIFICATE_FILE> --key <PATH_TO_PRIVATE_KEY_FILE>
       ```

       For example:

       ```bash theme={null}
       upsun domain:add secure.example.com --cert /etc/TLS/private/secure-example-com.crt --key /etc/TLS/private/secure-example-com.key
       ```

       You can optionally include intermediate SSL certificates by adding `--chain <PATH_TO_FILE>` for each one.

    2. Redeploy your production environment with the following command:

       ```bash theme={null}
       upsun environment:redeploy
       ```
  </Tab>

  <Tab title="In the Console">
    1. Open the project where you want to add a certificate.
    2. Click <SettingsIcon /> **Settings**.
    3. Click **Certificates**.
    4. Click **+ Add**.
    5. Fill in your private key, public key certificate, and (optionally) intermediate SSL certificates.
    6. Click **Add Certificate**.
    7. Access your production environment.
    8. Click <MoreIcon /> **More**.
    9. Click **Redeploy**.
  </Tab>
</Tabs>

### Change the private key format

The expected format for your certificate’s private key is PKCS #1.
Private keys in PKCS #1 format start with `-----BEGIN RSA PRIVATE KEY-----`.
If your private key starts with `-----BEGIN PRIVATE KEY-----`, it’s in PKCS #8 format, which isn’t appropriate.

To convert your private key (`private.key`) from PKCS #8 to PKCS #1 format (`private.rsa.key`), run the following command:

```bash theme={null}
openTLS rsa -in private.key -out private.rsa.key
```


# Troubleshoot domain issues
Source: https://developer.upsun.com/docs/domains/troubleshoot

If your site doesn't resolve after you've made DNS changes, check potential solutions to common issues.


## Verify DNS

On the command line using macOS, Linux, or the Windows Subsystem for Linux, run the following command:

```bash theme={null}
host www.<YOUR_DOMAIN>
```

If your domain is `example.com`, the response should be something like the following:

```text {no-copy="true"} theme={null}
www.example.com is an alias for main-abcd123.abcdefgh1234567.eu.platformsh.site
main-abcd123.abcdefgh1234567.eu.platformsh.site has address 192.0.2.1
```

If it isn't, try the following steps:

* Your DNS server might not be correctly configured or the old DNS records are still cached.
  Try removing your local DNS cache.
* Set your computer's DNS server to any Public DNS resolver (like [CloudFlare](https://developers.cloudflare.com/1.1.1.1/) or [Google](https://developers.google.com/speed/public-dns/docs/using))
  to see if the issue is with the DNS server you are using.
* Run `ping www.<YOUR_DOMAIN>`.
  If the result is different from what you got from running `host www.<YOUR_DOMAIN>`,
  you might need to remove your test settings.

## Verify SSL/TLS encryption

To find out where your domain is pointing to,
you can use [the certificate checker tool](https://certcheck.upsun.com/).
This tool provides guidance on certificates,
including when you use a [CDN](/docs/domains/cdn).
Check both the apex and the `www` domains to ensure they both point to your project.

For further investigations, run the following command in a shell:

```bash theme={null}
curl -I -v  https://www.<YOUR_DOMAIN>
```

Look for error messages.
Often the problem is caused by a mismatch between the certificate and the domain name or an expired [custom certificate](/docs/domains/steps/tls).

### Error provisioning certificates

When a Let's Encrypt certificate fails to provision after the build hook has completed,
you get output similar to the following:

```bash theme={null}
Provisioning certificates
  Validating 2 new domains

  E: Error validating domains: urn:ietf:params:acme:error:rejectedIdentifier :: The server will not issue certificates for the identifier :: NewOrder request did not include a SAN short enough to fit in CN
  Unable to validate domains domain a-new-and-really-awesome-feature-abc1234-defghijk56789.eu3.platformsh.site, www.domain a-new-and-really-awesome-feature-abc1234-defghijk56789.eu3.platformsh.site, will retry in the background.
  (Next refresh will be at 2026-04-28 02:22:50.639301+00:00.)

  E: Error: TLS Certificate provisioning failed
```

The renewal may fail because of the 64-character limit Let's Encrypt places on URLs.
If you have a branch with a long name, the environment URL is over this limit and the certificate is rejected.
To solve this, shorten your branch name so it doesn't exceed 20 characters.

Generated URLs for environments have the following pattern:

```bash theme={null}
<ENVIRONMENT>-<PROJECT_ID>.<REGION>.platformsh.site
```

If you have a [default domain](/docs/routes#default) set up, the generated URL has the following pattern:

```bash theme={null}
<YOUR_DOMAIN>.<ENVIRONMENT>-<PROJECT_ID>.<REGION>.platformsh.site
```

The generated URLs consist of:

* `<YOUR_DOMAIN>` = the amount of characters your domain has
* `<ENVIRONMENT>` = `<BRANCH_NAME>` + 7 character hash
* `<PROJECT_ID>` = 13 characters
* `<REGION>` = 2 to 4 characters, depending on the region
* `platformsh.site` = 15 characters
* extra characters like `.` and `-` = 4 to 5 characters, depending on if you have a default domain

This leaves you with 21 to 23 characters for your branch name (`<BRANCH_NAME>`) without exceeding the 64-character limit,
depending on the region.
To ensure your renewals succeed,
keep your branch names under 20 characters.

### Ownership verification

To provide a valid TLS-certificate,
the certificate issuer checks that the requester is entitled to receive the requested certificate.
This check is known as the *Challenge* step.

The certificate request is generated based on your [routes definition](/docs/routes).
If you want your site to be available with `example.com` and its `www.example.com` subdomain, make sure both are defined in your routes.

To pass this verification, there are requirements you need to meet.

<Tabs>
  <Tab title="Without a CDN">
    Upsun Cloud checks that all the routes you defined are pointing to your project.
    For the challenge to complete,
    domains and subdomains must point directly to your Upsun Cloud project.

    Otherwise, you get an error similar to:

    ```text {no-copy="true"} theme={null}
      E: Error validating domain www.example.com: Couldn't complete challenge [HTTP01: pending | DNS01: pending | TLSALPN01: pending]
      Unable to validate domains www.example.com, will retry in the background.
    ```
  </Tab>

  <Tab title="Using a CDN">
    When you use a CDN, to ensure the challenge succeeds, check that:

    * Your domains and subdomains point to your CDN
    * The [`_acme-challenge.` subdomain](https://www.rfc-editor.org/rfc/rfc8555#section-8.4),
      as in `_acme-challenge.example.com`, points to your CDN
    * The [`/.well-known/` route](https://www.rfc-editor.org/rfc/rfc8555#section-8.3),
      as in `https://www.example.com/.well-known/`, is accessible with no redirects

    If you don't follow those requirements, you get an error message similar to:

    ```text {no-copy="true"} theme={null}
      W: Failed to verify the challenge at the gateway for the domain 'www.example.com'
      E: Error validating domain www.example.com: Couldn't complete challenge [HTTP01: The client lacks sufficient authorization]
    ```

    For more information, see how to [setup your CDN](/docs/domains/cdn).
    For more details regarding the challenge step, consult your certificate issuer's documentation.
    A common issuer is [Let's Encrypt](https://letsencrypt.org/docs/challenge-types/).
  </Tab>
</Tabs>

Make sure that the [apex domain](/docs/glossary#apex-domain) and its `www` subdomain are both pointing where needed.
Note that it can take up to 72 hours for DNS changes to be effective.
For more information, see how to [set up a custom domain](/docs/domains/steps).

If the changes take longer than expected,
[redeploy](/docs/troubleshooting/general#force-a-redeploy) the impacted environment.

Also make sure that no conflicting DNS records exist for your domain.
For example, a conflicting AAAA (IPv6) DNS record can result in a `[HTTP01: The client lacks sufficient authorization]` error.

If the certificate generation issue persists,
check if an outage is ongoing with your certificate issuer (the most common one is [Let's Encrypt](https://letsencrypt.status.io/))
and with your CDN provider if you have one.
If not, [contact Support](/docs/core-concepts/get-support).

### Check your routes configuration

Certificates are generated based on your [routes configuration](/docs/routes).
When a certificate is renewed, the renewal bot checks that all of the defined routes can be accessed.
If at least one of the routes defined in your `.upsun/config.yaml` file can't be accessed,
the renewal fails and the following error is displayed:

```
Provisioning certificates
  Validating 2 new domains
  W: Failed to verify the challenge at the gateway for the domain 'www.example.com'
  E: Error validating domain www.example.com: Couldn't complete challenge [HTTP01: There was a problem with a DNS query during identifier validation]
  Unable to validate domains www.example.com, will retry in the background.
  (Next refresh will be at 2026-07-04 17:43:10.259891+00:00.)
  Certificates
  - certificate 61bc4c8: expiring on 2026-09-02 01:11:12+00:00, covering sdgs.un.org

E: Error: TLS Certificate provisioning failed
```

For example, if you add `example.com` and `www.example.com` to your routes configuration
but the `www` subdomain doesn't point to your project through [a `CNAME` record](/docs/domains/steps/dns#cname-records),
the certificate renewal fails.
For the renewal to succeed, add the missing `CNAME` record to your DNS
or remove `www.example.com` (and any other `www` route) from your `.upsun/config.yaml` file.

## Verify your application

Check your app's logs and look for anomalies.
On the command line type `upsun logs app` and `upsun logs error`.

## Use ASCII for the domain

Upsun Cloud expects an ASCII representation of your domain.
To use an internationalized domain name (IDN), convert it to ASCII.
Use a tool such as the [conversion tool provided by Verisign](https://www.verisign.com/en_US/channel-resources/domain-registry-products/idn/idn-conversion-tool/index.xhtml).

## Something still wrong?

For more general information, see how to [troubleshoot development](/docs/troubleshooting/general).

If your website is still not working as expected, [contact support](/docs/core-concepts/get-support).


# Environment actions
Source: https://developer.upsun.com/docs/environments/actions

Manage the lifecycle of your environments by canceling activities or deactivating environments.

<CardGroup>
  <Card title="Cancel an activity" icon="x" href="/docs/environments/cancel-activity">
    Cancel running or pending activities in an environment.
  </Card>

  <Card title="Deactivate an environment" icon="power-off" href="/docs/environments/deactivate-environment">
    Deactivate environments you aren't using.
  </Card>
</CardGroup>


# Back up an environment
Source: https://developer.upsun.com/docs/environments/backup

See how to protect yourself from potential data loss by backing up your environments so they can be restored later.

When you're making changes to your apps,
you want to be sure those changes only improve things and don't make you lose any data.
You also want to have a disaster recovery plan in place.
Backups help you protect yourself against potential data loss.

You might want to create backups of your live environment before merging a different environment into it
or each time you increase the storage space of your services.

You also have regularly scheduled automated backups of your production environments to cover most cases.

Note that you can only create backups and restore active environments.
To work with an [inactive environment](/docs/glossary#inactive-environment),
first activate it.

## How backup and restore works

1. As an [admin user](/docs/administration/users), you can do a backup of your environment.
   This backup includes the complete data and code of the environment.
   All persistent data from all running [services](/docs/add-services)
   and any files stored on [mounts](/docs/configure-apps/image-properties/mounts) are included.
   The backup is stored internally on Upsun Cloud.
   That is, the backup can be applied to environments on Upsun Cloud, but it can't be downloaded.
   If you need to download backups, instead [export your mount and service data](/docs/core-concepts/common-tasks/exporting)).

2. You restore your environment using the backup.
   At this point, the data and code from the backup are restored to ensure a consistent state.
   The latest code in your repository may have been modified such that it no longer works correctly with the old, restored data.

   <Warning>
     Upsun Cloud does not modify your Git repository. Any further changes you make use the latest code in your repository.
   </Warning>

3. Depending on your needs, you can do the following:

   a) To use the code from the time of the backup as a baseline for future changes,
   make sure you restore it yourself in your Git repository.
   To do so, use Git commands such as `revert`.

   b) To use your latest code instead, just redeploy your environment or push a new change.

<Note>
  You may not want the code from the backup to be restored at step 2.
  For instance, if you have deleted containers since the backup, you may not want them to be restored with the backup.

  In this case, you can opt out of restoring the code.
  To do so, when you restore your backup, use the `--no-code` flag.

  Also, see [how resource allocation works](/docs/manage-resources/resource-init#backup-restoration) when you restore a backup.
</Note>

## Backups and downtime

By default, creating a manual backup causes a momentary pause in site availability so that all requests can complete.
This means the environment is backed up in a known consistent state.
The total interruption is usually only 15 to 30 seconds.
Any requests during that time are held temporarily, not dropped.

To avoid this downtime, use [live backups](#live-backups).

For consistent backups, create the backups during non-peak hours for your site.

## Data retention

### Manual backups

[Manual backups](/docs/environments/backup#create-a-manual-backup) are retained until you delete them or replace them with another backup.

You can configure the maximum number of manual backups. Once that number is reached, any new manual backup automatically replaces the oldest backup.

### Automated backups

Automated backups are retained for 2 days when you use the [default backup policy](#default-backup-policy)
(meaning, 2 days worth of backups are retained at any given point).

When you [configure your own automated backup policy](#configure-a-backup-policy),
the retention time varies based on that configuration.

Automated backups are always [live](#live-backups).

## Backup policy

### Default backup policy

By default, Upsun Cloud provides 1 automated backup a day for your production environment,
with a [2-day retention](/docs/security/data-retention) (2 days worth of backups are retained at any given point).

You can [configure your own backup policy](#configure-a-backup-policy).
The default backup policy is equivalent to a custom backup policy using a `1d` interval and a count of `2` (see below).

### Configure a backup policy

Upsun Cloud allows you to fully configure your own backup policy.
You can setup a different automated backup schedule per environment type (production, staging, and development environments).

On a given environment type, you can configure:

* The total number of backups (manual and automated)
* The total number of manual backups specifically
* Multiple schedules for automated backups

An automated backup schedule is composed of an interval and a count.<br />
The interval defines the frequency of the backups.
An interval can be a couple of hours, days, weeks, months, or years.
To configure an interval, use the following values:

* `h` for hour
* `d` for day
* `w` for week
* `M` for month
* `y` for year

The count defines the number of backups to retain.

### Configuration examples

To take a backup every day and keep up to 7 backups,
run the following command:

```bash Terminal theme={null}
upsun project:curl settings -X PATCH \
   -d '{
       "data_retention": {
          "production": {
             "default_config": {
                "schedule": [
                  {"interval": "1d", "count": 7},
                 ]
              }
           }
        }
      }'
```

#### Configure multiple automated backup schedules

You can use multiple schedules to implement you own backup policy.
For instance, you may want to keep multiple recent backups and fewer older backups,
using a command similar to the following:

```bash Terminal theme={null}
upsun project:curl settings -X PATCH \
   -d '{
       "data_retention": {
          "production": {
             "default_config": {
                "schedule": [
                  {"interval": "1d", "count": 7},
                  {"interval": "1w", "count": 4},
                  {"interval": "1M", "count": 12}
                 ]
              }
           }
        }
      }'
```

The command results in:

* A backup every day for 7 days
* A backup every week for 4 weeks
* A backup every month for 12 months

#### Set a limit for backups

To configure the maximum number of backups (automated and manual backups alike) on your production environment,
run a command similar to the following:

```bash Terminal theme={null}
upsun project:curl /settings -X PATCH -d '{"data_retention": {"production": {"max_backups": 10}}}'
```

To configure the maximum number of manual backups on the production environment,
run a command similar to the following:

```bash Terminal theme={null}
upsun project:curl /settings -X PATCH -d '{"data_retention": {"production": {"default_config":  {"manual_count": 1}}}}'
```

## Live backups

You can create backups without any downtime.
This means your environment is running and open to connections during the backup.

Because the connections may come in during backup creation, live backups may have data inconsistencies among containers.
They may make restorations less reliable.
To avoid such issues, schedule [manual backups](#create-a-manual-backup) during non-peak hours,
when the short amount of downtime is least noticed.

You can create a manual live backup on a Grid project:

<Tabs>
  <Tab title="Using the CLI">
    Use the `--live` flag:

    ```bash theme={null}
    upsun backup:create --live
    ```
  </Tab>

  <Tab title="In the Console">
    When [creating the backup](#create-a-manual-backup), select **Run live backup** in the last step.
  </Tab>
</Tabs>

## Create a manual backup

You can create a manual backup using the [CLI](/cli) or in the [Console](/docs/administration/web).

<Tabs>
  <Tab title="Using the CLI">
    ```bash theme={null}
    upsun backup:create
    ```
  </Tab>

  <Tab title="In the Console">
    1. Navigate to the environment you want to back up.
    2. Click **Backups**.
    3. Click <BackupIcon /> **Backup**.
    4. Click **Backup**.
  </Tab>
</Tabs>

See more information on [backup policies](#backup-policy) and [data retention](#data-retention).

### Automate manual backups

You can also automate the process of creating manual backups through [cron jobs](/docs/configure-apps/image-properties/crons).
The cron job uses the CLI command to back up the environment.
It requires you to [set up the CLI on the environment with an API token](/cli/api-tokens#authenticate-in-an-environment).

Although this process is automated,
backups created in this way count as [manual backups](#manual-backups).
They don't affect the automated backups taken as part of [a schedule](#configure-a-backup-policy).

## Physical storage location

Backups are stored as binary large objects separate from your environments.
This storage is replicated over multiple data centers in different locations
[within the region your project is hosted in](https://upsun.com/trust-center/security/data-security/).
This means that in the rare event a data center becomes unavailable, your backups are still available.


# Backup & restore
Source: https://developer.upsun.com/docs/environments/backup-restore

Protect yourself from potential data loss by backing up and restoring your environments.

<CardGroup>
  <Card title="Back up an environment" icon="cloud-upload" href="/docs/environments/backup">
    Protect yourself from potential data loss by backing up your environments.
  </Card>

  <Card title="Restore an environment" icon="history" href="/docs/environments/restore">
    Restore an environment from a previous backup.
  </Card>
</CardGroup>


# Cancel an activity
Source: https://developer.upsun.com/docs/environments/cancel-activity

See how to cancel running or pending activities in an environment.

If you have a stuck activity or you pushed a change you know doesn't work,
you can cancel a running or pending activity on an environment.
This works for activities such as builds, cron jobs, and source operations.

You can cancel activities using the [CLI](/cli)
or in the [Console](/docs/administration/web).

<Tabs>
  <Tab title="Using the CLI">
    Run the following command:

    ```bash theme={null}
    upsun activity:cancel
    ```

    If you have more than one running or pending activity, choose which activity to cancel.

    You can also cancel a specific activity by specifying its ID:

    ```bash theme={null}
    upsun activity:cancel <ACTIVITY_ID>
    ```

    Get the ID from the [activity log](/docs/observability/logs/access-logs#activity-logs).
  </Tab>

  <Tab title="In the Console">
    1. Open the environment where you want to cancel an activity.
    2. In the [activity log](/docs/observability/logs/access-logs#activity-logs),
       click <MoreIcon /> **More** next to the activity you want to cancel.
    3. Click **Cancel**.
  </Tab>
</Tabs>

## Non-cancellable activities

An activity can finish in between when you load the Console and when you click **Cancel**.
For example, when the activity is a [source operation](/docs/configure-apps/source-operations)
and the related build hook has already completed.
In such cases, you get a message that the activity can't be cancelled.


# Change an environment's parent
Source: https://developer.upsun.com/docs/environments/change-parent

Learn how to change a given environment's parent environment.

All environments default to having another environment as their parent.
If you [branched](/docs/glossary#branch) the environment from another,
its parent starts as the environment it was created from.
If you pushed a branch through Git or a [source integration](/docs/integrations/source),
the parent defaults to the default environment.

To change the environment's parent, follow these steps:

<Tabs>
  <Tab title="In the Console">
    1. Select the project where you want to change the parent.
    2. From the **Environment** menu, select the environment you want to change.
    3. Click <SettingsIcon /> **Settings**.
    4. In the row with the environment's name, click **Edit <ChevronIcon />**.
    5. Select a **Parent environment**.
    6. Click **Save**.
  </Tab>

  <Tab title="Using the CLI">
    Run the following command:

    ```bash theme={null}
    upsun environment:info -e <CHILD_ENVIRONMENT_NAME> parent <PARENT_ENVIRONMENT_NAME>
    ```

    So if you have the environment `new-feature` and want to change its parent to `main`, run the following:

    ```bash theme={null}
    upsun environment:info -e new-feature parent main
    ```
  </Tab>
</Tabs>

If you're not using a [source integration](/docs/integrations/source),
you can also set a parent for your environment when pushing changes to it.
To do so, run the following command:

```bash theme={null}
git push -o "environment.parent=<PARENT_ENVIRONMENT_NAME>"
```

Learn more about how to [trigger actions on `push`](/docs/environments#push-options).


# Deactivate an environment
Source: https://developer.upsun.com/docs/environments/deactivate-environment

See how to deactivate environments you aren't using.

If you have environments you aren't using, you may want to deactivate them to save resources for what you need.
To deactivate an environment, you need to be an admin for the project or the given environment.

<Note>
  Your default environment is protected.
  It can't be deactivated through the Console or the CLI.
  To change which environment is the default, see how to [rename the default branch](/docs/environments/default-environment).
</Note>

Deactivating the project results in the following:

* The environment becomes [inactive](/docs/glossary#inactive-environment).
  Unless it's reactivated, it's no longer deployed and isn't accessible from the web or via SSH.
* All services running on this environment are deleted.
* All data specific to the environment is deleted.
  If the environment is reactivated, it syncs data from its parent environment.

## Deactivate an environment

To deactivate an environment, follow these steps:

<Tabs>
  <Tab title="In the Console">
    1. Select the project with an environment you want to deactivate.
    2. From the **Environment** menu, select the environment.
    3. Click <SettingsIcon /> **Settings**.
    4. In the row with **Status**, click **Edit <ChevronIcon />**.
    5. Select the checkbox to show you understand the consequences.
    6. Click **Deactivate & Delete Data**.
    7. Confirm your choice.
  </Tab>

  <Tab title="Using the CLI">
    Run the following command:

    ```bash theme={null}
    upsun environment:deactivate <ENVIRONMENT_NAME>
    ```
  </Tab>
</Tabs>

## Delete the branch

Inactive environments still have branches in Git.
To delete the branch entirely, run the following command:

```bash theme={null}
git push origin --delete <BRANCH_NAME>
```

## Reactivate an environment

Reactivating an environment [syncs](/docs/glossary#sync) data from its parent environment.

To reactivate an inactive environment, follow these steps:

<Tabs>
  <Tab title="In the Console">
    1. Select the project with an environment you want to reactivate.
    2. From the **Environment** menu, select the environment.
    3. Click <SettingsIcon /> **Settings**.
    4. In the row with **Status**, click **Edit <ChevronIcon />**.
    5. Click **Activate**.
  </Tab>

  <Tab title="Using the CLI">
    Run the following command:

    ```bash theme={null}
    upsun environment:activate <ENVIRONMENT_NAME>
    ```
  </Tab>
</Tabs>

If you're not using a [source integration](/docs/integrations/source),
you can also activate an environment when pushing changes to it.
To do so, run the following command:

```bash theme={null}
git push -o "environment.status=active"
```

Learn more about how to [trigger actions on `push`](/docs/environments#push-options).


# Rename the default environment
Source: https://developer.upsun.com/docs/environments/default-environment

See how to change the name of your default/production environment after creating a project.

You can set the name of your default/production environment when creating a project.
To change it after project creation, follow the steps below.
For consistency, the steps are all given using the [CLI](/cli).

The examples below are based off of changing the default environment from `old` to `main`.
Replace these names with what suits your situation.

If your site is already live,
remember that deactivating an environment is a destructive operation that can result in data loss.
To minimize potential issues, take the following steps:

* Switch the default environment during non-peak hours.
* Keep your data by taking a [backup of the `old` environment](/docs/environments/backup)
* Reduce your DNS time-to-live (TTL) to a minimum.

## Requirements

If you have a domain set for your default environment, remove it before changing the default branch.
Otherwise you get an error that `default domain must be a valid project domain`.

To change the default branch, you need to be an [admin for the project](/docs/administration/users)

## Note on source integrations

The following steps depend of whether your project has a [source integration](/docs/integrations/source).

If it doesn't, Upsun Cloud is your primary remote repository for the project.
If it does, GitHub, GitLab, or BitBucket hosts your primary remote repository for the project.

## 1. Create a `main` environment

<Tabs>
  <Tab title="Without a source integration">
    In your local copy of your repository, create a new environment from `old` called `main`:

    ```bash theme={null}
    upsun environment:branch main old
    ```
  </Tab>

  <Tab title="With a source integration">
    In your local copy of the external repository, make sure your default branch is up to date:

    ```bash theme={null}
    git checkout old && git pull origin old
    ```

    Then create the `main` branch off of your default branch and push it to the remote repository:

    ```bash theme={null}
    git checkout -b main
    git push origin main
    ```

    Source integrations include all branches, but don't activate the corresponding environments in Upsun Cloud.
    Activate the `main` environment by running the following command:

    ```bash theme={null}
    upsun environment:activate main
    ```
  </Tab>
</Tabs>

## 2. Copy settings

If you have variables or other settings specific to your default environment, add those to the `main` environment.

For example, you may have variables for your production environment set to not be inheritable
(such as if you set them with `--inheritable=false` through the CLI).
These variables aren't added automatically to child environments and so you need to add them to the `main` environment manually.

If you want the `main` environment to send emails, [turn on outgoing email](/docs/development/email).

## 3. Make `main` a top-level branch

To have `main` be your default, it needs to not be a child of `old`.
Use the following command to remove its parent and make it a top-level branch:

```bash theme={null}
upsun environment:info -e main parent -
```

## 4. Make `main` the parent for other environments

<Tabs>
  <Tab title="Without a source integration">
    You probably have other environments that are children of `old`.
    For each environment, update its parent to `main`:

    ```bash theme={null}
    upsun environment:info -e <ENVIRONMENT_NAME> parent main
    ```
  </Tab>

  <Tab title="With a source integration">
    To preserve your data on Upsun Cloud,
    it's best to switch your work in progress to be based off of `main`.

    Close any open pull/merge requests and resubmit them against `main`.
    If you want to continue working on branches after switching the default branch,
    rebase them by running `git rebase --onto main <BRANCH_NAME>`.
    Once you resubmit a request, it appears under the `main` environment on Upsun Cloud.
  </Tab>
</Tabs>

## 5. Deactivate the `old` branch

To change your default branch, you first need to deactivate the existing default branch to remove protections.
Deactivate the `old` environment without deleting it by running the following CLI command:

```bash theme={null}
upsun environment:delete --no-delete-branch old
```

## 6. Set `main` as the default branch

<Tabs>
  <Tab title="Without a source integration">
    Once `old` has been deactivated, set the project's default branch to `main`:

    ```bash theme={null}
    upsun project:info default_branch main
    ```
  </Tab>

  <Tab title="With a source integration">
    Set the project's default branch in Upsun Cloud to `main`:

    ```bash theme={null}
    upsun project:info default_branch main
    ```

    Follow the instructions to change the default branch to `main` for your provider:

    * [GitHub](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/changing-the-default-branch)
    * [GitLab](https://docs.gitlab.com/ee/user/project/repository/branches/default.html#change-the-default-branch-name-for-a-project)
    * [BitBucket](https://community.atlassian.com/t5/Bitbucket-questions/How-to-change-MAIN-branch-in-BitBucket/qaq-p/977418)
  </Tab>
</Tabs>

## 7. Update DNS records

Whether or not you're using a CDN,
if your site is live you have probably added an Upsun Cloud address somewhere when configuring a [custom domain](/docs/domains/steps).
If you have a CDN, it's with the CDN provider.
If you don't have a CDN, it's probably a `CNAME` record.

In either case, the setting probably has the old environment name as part of it.
Update the setting to use the new environment name.

Verify that the new URL is correct by comparing it to the result from this command:

```bash theme={null}
upsun environment:info edge_hostname
```

## 8. Optional: Delete the `old` environment

If you no longer want the `old` environment, such as to stop accidental use, delete it completely:

```bash theme={null}
upsun environment:delete --delete-branch old
```


# Configure HTTP access control
Source: https://developer.upsun.com/docs/environments/http-access-control

Learn how to control access to a given environment using HTTP methods.

When developing your site, you might want to hide your preview environments from outside viewers.
Or you may find you have performance issues from [excessive bot access](https://support.platform.sh/hc/en-us/community/posts/16439634723858).
You can control access with a username and password **or** by allowing/denying specific IP addresses or networks.
This setting applies to the entire environment.

The settings for a specific environment are inherited by all of its children.
So if you have a `staging` environment and you [branch environments from it](/docs/glossary#branch),
all of the environments branched from it inherit the same authentication information.

Changing access control triggers a new deploy of the current environment.
The changes don't propagate to child environments until they're [redeployed manually](/docs/troubleshooting/general#force-a-redeploy).

## Use a username and password

You can set up one or more combinations of a username and password.
To add a username and password, follow these steps:

<Tabs>
  <Tab title="In the Console">
    1. Select the project where you want to add login details.
    2. From the **Environment** menu, select an environment.
    3. Click <SettingsIcon /> **Settings**.
    4. In the row with **HTTP access control**, click **Edit <ChevronIcon />**.
    5. Click **+ Add Login**.
    6. Enter the username (login) and password into the given fields.
    7. Click **Save**.
  </Tab>

  <Tab title="Using the CLI">
    Run the following command:

    ```bash theme={null}
    upsun environment:http-access -e <ENVIRONMENT_NAME> --auth <USERNAME>:<PASSWORD>
    ```

    For example, to add the username `name` with the password `12321` to the `test` environment, run:

    ```bash theme={null}
    upsun environment:http-access -e test --auth name:12321
    ```
  </Tab>
</Tabs>

## Filter IP addresses

Alternatively, you can control access to environments by allowing or denying specific IP addresses or ranges of IP addresses.
The addresses should be in the [CIDR format](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing).
Both`4.5.6.7` and `4.5.6.0/8` are accepted formats.

Note that `allow` entries should come before `deny` entries in case they both match.

For example, the following configuration allows only the IP `198.51.100.0` to access your website.

```txt theme={null}
198.51.100.0 allow
0.0.0.0/0 deny
```

<Note>
  <h4>Pick your authentication method</h4>
  When you set up IP filtering authentication,
  make sure no [username and password are defined](#use-a-username-and-password) for your environment.

  Otherwise, your environment will remain accessible through the defined username and password combination,
  regardless of your IP filtering settings.
</Note>

To control access based on IP address, follow these steps:

<Tabs>
  <Tab title="In the Console">
    1. Select the project where you want to control access.
    2. From the **Environment** menu, select the environment to control.
    3. Click <SettingsIcon /> **Settings**.
    4. In the row with **HTTP access control**, click **Edit <ChevronIcon />**.
    5. Enter the IP addresses or ranges into the **IP addresses** field. Put one address or range per line, followed by a space and then `allow` or `deny`.
    6. Click **Save**.
  </Tab>

  <Tab title="Using the CLI">
    Run the following command:

    ```bash theme={null}
    upsun environment:http-access -e <ENVIRONMENT_NAME> --access allow:<IPS_TO_ALLOW> --access deny:<IPS_TO_DENY>
    ```
  </Tab>
</Tabs>


# Manage Upsun Cloud environments
Source: https://developer.upsun.com/docs/environments/index

Learn what environments on Upsun Cloud are and how to take advantage of them.

An Upsun Cloud environment contains one instance of an app (or [group of apps](/docs/configure-apps/multi-app))
with all the services needed for it to run.

Each project can include multiple environments,
often divided into [environment types](/docs/administration/users#environment-type-roles).
If you have a live site, you have at least a production environment.
You may also have additional environments of the Staging or Development [environment type](/docs/administration/users#environment-type-roles), but there will only ever be one production environment.

You can think of other environments as copies of your live site
where you can run tests without worrying about damaging anything in production.
Once you have completed your tests,
you can merge your changes so that they're instantly and seamlessly deployed to production.

You can create environments for development, testing, staging, review, and so on.
To organize your environments, you can create [hierarchical relationships](#hierarchy).

## Create environments

You can create new environments in one of two ways:

* Push a local branch through Git or a [source integration](/docs/integrations/source).

* [Branch](/docs/glossary#branch) existing environments using the [CLI](/cli)
  or the [Console](/docs/administration/web).

When you branch an environment, you might want to create exact replicas of it.
In this case, each new environment inherits all of the data and services from its parent environment.
This includes databases, network storage, queues, and routing configurations.

You can create Upsun Cloud environments on demand.
Each environment is tied to a Git branch.
If you use a source integration,
you can even have environments created automatically for your pull requests and branches.

You can also have branches that aren't tied to a running instance of your application.
These are called [inactive environments](#environment-status).

## Default environment

Your default environment comes from your default branch and is a
[production environment](/docs/administration/users#environment-type-roles). Your project must have a default
environment, but you can [name it as you want](/docs/environments/default-environment). This environment is your
**live site**. You might want to give it a [custom domain name](/docs/domains/steps).

## Environment status

Your environments can have one of three statuses:

* [Active](/docs/glossary#active-environment):
  A deployed environment with services and data.

* [Inactive](/docs/glossary#inactive-environment):
  An environment that isn't deployed and has no services or data, only code.

* [Paused](#paused-environments):
  An environment that hasn't been redeployed in 14 days or longer.

You can see the status of your environments in the [Console](/docs/administration/web) or the [CLI](/cli).

<Tabs>
  <Tab title="In the Console">
    When you open your project, inactive environments appear lighter in the environment list.
    You also can't select them from the **Environment** dropdown menu.

    To check the status of an environment,
    you can also open it and view its information panel.
  </Tab>

  <Tab title="Using the CLI">
    To check the status of all your environments, from your project directory run the `upsun environments` command.
  </Tab>
</Tabs>

You can [change an environment's status](/docs/environments/deactivate-environment) at any time.

## Organize your environments

### Hierarchy

<img alt="Environment hierarchy" />

In Upsun Cloud, your environments are organized in a hierarchy featuring parent and child environments.

When you [branch](/docs/glossary#branch) an environment,
the parent of the new environment is the environment it was created from.
You can [change the environment's parent](/docs/environments/change-parent) after it's been created.

When you push a branch through Git or a [source integration](/docs/integrations/source),
the parent environment of the new environment is your [default environment](#default-environment).
Alternatively, you can [change the environment's parent](/docs/environments/change-parent) after it's been created.

Each child environment can [sync](/docs/glossary#sync) code and/or data down from its parent
and [merge](/docs/glossary#merge) code up to its parent.
You can use child environments for development, staging, and testing.

### Workflows

Since you can customize your [environment hierarchy](#hierarchy), you can create your own workflows.
You can decide which structure best fits your needs.

#### Possible approaches

You may want to take one of the following approaches when creating your workflows:

* **Agile**: A child environment per sprint.
  Each story in the sprint can have its own environment as a child of the sprint environment.

* **Developer-centric**: One QA environment and a few preview environments
  (*per developer*, *per task*, or similar).

* **Testing**: An operational test environment, a user test environment, and a few unit test environments.

* **Hotfix**: One environment for each bug, security issue, or hotfix that needs deployment.

#### Example workflow

Example Agile workflow:

1. An admin [branches](/docs/glossary#branch) the Live (default) environment to create a Sprint environment.

2. The admin gives each developer permission to branch the Sprint environment to create new feature environments.

   <img alt="Agile branches with Live as the top parent, Sprint 1 as a child, and Feature 1 and Feature 2 as children of Sprint" />

3. Feature 1 is developed and work is reviewed by accessing the deployed Feature 1 environment.

4. When the review is done, Feature 1 is [merged](/docs/glossary#merge) into the Sprint environment.

   <img alt="Feature 1 is merged into the Sprint 1 environment" />

5. The remaining features [sync](/docs/glossary#sync) with the Sprint environment.
   This ensures their working environment is up-to-date with the latest code.

   <img alt="Features from the Sprint 1 environment are synced with the Feature 2 environment" />

6. When the sprint is complete and all features merged into the Sprint environment,
   the admin makes a backup of the live site.

7. The admin merges the Sprint environment into the Live environment.

   <img alt="Features from the Sprint 1 environment are merged into the Live environment" />

8. The admin syncs the next sprint's environment with the Live environment
   to repeat and continue the development process.

   <img alt="Features from the Live environment are synced with the Sprint 2 environment" />

### Naming conventions

You can organize and work with your preview environments in many different ways.
It can help to introduce a convention for how you name and structure your environments.

For each environment, choose a name that represents what the environment is for.
If you use Agile, for example, you can adopt a naming convention similar to the following:

```text {no-copy="true"} theme={null}
Live
  Sprint1
    Feature1
    Feature2
    Feature3
  Sprint2
    Feature1
    Feature2
```

If you prefer splitting your environments per developer and having a specific environment for each task or ticket,
you can adopt a naming convention similar to the following:

```text {no-copy="true"} theme={null}
Staging
  Developer1
    Ticket-526
    Ticket-593
  Developer2
    Ticket-395
```

## Paused environments

[Preview environments](/docs/glossary#preview-environment) are often used for a limited time and then abandoned.
To prevent unnecessary consumption of resources,
Upsun Cloud automatically pauses preview environments ([of both development and staging types](/docs/glossary#environment-type)) that haven't been redeployed in 14 days.

You can pause (and resume) an environment manually at any time.

### Pause an environment

To pause an environment, follow these steps:

<Tabs>
  <Tab title="Using the CLI">
    Run the following command:

    ```bash theme={null}
    upsun environment:pause --project <PROJECT_ID> --environment <ENVIRONMENT_NAME>
    ```
  </Tab>

  <Tab title="In the Console">
    1. Navigate to your project and click <SettingsIcon /> **Settings**.
    2. Under **Environments**, select the environment you want to pause.
    3. In the **General** tab, click **Pause environment**.
  </Tab>
</Tabs>

### Resume a paused environment

Pushing new code or redeploying a paused environment automatically resumes it.
You can also resume it manually at any time.

<Tabs>
  <Tab title="Using the CLI">
    Run the following command:

    ```bash theme={null}
    upsun environment:resume --project <PROJECT_ID> --environment <ENVIRONMENT_NAME>
    ```
  </Tab>

  <Tab title="In the Console">
    1. Navigate to the paused environment.
    2. In the Activity tab, click **Resume environment**.
    3. In the **Resume environment** window, click **Resume**.
  </Tab>
</Tabs>

The environment is redeployed and becomes available for use again.

## Push options

Git provides push options to pass a string to the server (see [the official Git documentation](https://git-scm.com/docs/git-push#Documentation/git-push.txt--oltoptiongt)).

Upsun Cloud supports some of these push options,
which allows you to push changes to your environment and trigger the following actions at the same time:

| Action | Command |
| - | - |
| Activate the environment | `git push upsun -o "environment.status=active"` |
| Set a title for the environment | `git push upsun -o "environment.title=<ENVIRONMENT_TITLE>"` |
| Set the parent environment | `git push upsun -o "environment.parent=<PARENT_ENVIRONMENT_NAME>"` |
| Clone the data from the parent environment | `git push upsun -o "environment.clone_parent_on_create=True"` |
| Disable the cloning of the data from the parent environment | `git push upsun -o "environment.clone_parent_on_create=False"` |
| Set the environment type (`development`, `staging`, or `production`) | `git push upsun -o "environment.type=<ENVIRONMENT_TYPE>"` |
| Define a [resource initialization strategy](/docs/manage-resources/resource-init#specify-a-resource-initialization-strategy) (`default`, `manual`, `minimum`, or `parent`) | `git push upsun -o "resources.init=<RESOURCE_INITIALIZATION_STRATEGY>"` |

If your remote location isn't named `upsun`,
make sure you adjust the commands accordingly.

<Note>
  You can't use push options if you have a [source integration](/docs/integrations/source) set up.
</Note>

The following example shows how, through a single `push`,
you can activate your environment, set a title for it,
set a parent environment for it, and clone the data from its parent into it.

```bash Terminal theme={null}
git push upsun -o "environment.status=active" -o "environment.title=my-environment-title" -o "environment.parent=my-parent-environment" -o "environment.clone_parent_on_create=True"
```


# Restore an environment from a backup
Source: https://developer.upsun.com/docs/environments/restore

See how to restore an environment from a previous state.

Once you have [backups of your environment](/docs/environments/backup), you can restore data from a previous point.

To restore an environment, you need an [Admin role for that environment type](/docs/administration/users).

## 1. List available backups

To restore an environment, first select one of the available backups:

<Tabs>
  <Tab title="Using the CLI">
    Run the following command:

    ```bash theme={null}
    upsun backups
    ```

    You get a response similar to the following:

    ```bash theme={null}
    Backups on the project My Project (1234567abcdef), environment main (type: production):
    +---------------------------+----------------------------+------------+
    | Created                   | Backup ID                  | Restorable |
    +---------------------------+----------------------------+------------+
    | 2026-08-15T09:48:58+01:00 | 5ouvtgo4v75axijww7sqnftste | true       |
    | 2026-07-09T14:17:17+01:00 | 7jks7dru5xpx5p5id5wtypur2y | true       |
    | 2026-06-22T18:33:29+01:00 | f3jbyxlhtmalco67fmfoxs7n4m | true       |
    +---------------------------+----------------------------+------------+
    ```

    Select one of the backups marked as **Restorable** and copy its **Backup ID**.
  </Tab>

  <Tab title="In the Console">
    1. Navigate to the environment where you want to see backups.
    2. Click **Backups**.

    Select one of the backups marked as having completed successfully <SuccessIcon />.
  </Tab>
</Tabs>

## 2. Restore from a backup

To restore the backup you've selected, follow these steps:

<Tabs>
  <Tab title="Using the CLI">
    1. Run the following command:

       ```bash theme={null}
       upsun backup:restore <BACKUP_ID>
       ```

    2. Press `enter` to agree with the consequences and continue.
  </Tab>

  <Tab title="In the Console">
    1. Next to the backup you've selected, click **More** <MoreIcon />.
    2. Click **Restore**.
    3. Read through the consequences and click **Yes, Restore**.
  </Tab>
</Tabs>

The data is restored and your backed-up environment is deployed.
This deployment uses the built app, including variables, from when the backup was taken.

<Warning>
  <h4>Warning</h4>
  The code is also initially restored, but Upsun Cloud doesn't modify your Git repository.
  So any future (re)deployments use the current Git repository to build the environment.

  To restore your code to its previous state when the backup was taken,
  use Git commands such as [revert](https://git-scm.com/docs/git-revert).

  Note that you can also opt out of restoring the code entirely by using the `--no-code` flag.
  For more information, see [how backup and restore works on Upsun Cloud](/docs/environments/backup#how-backup-and-restore-works).

  Also, see [how resource allocation works](/docs/manage-resources/resource-init#backup-restoration) when you restore a backup.
</Warning>

## Restore to a different environment

You can restore backups to a different environment than they were created on using the CLI:

1. Switch to the branch where the backup was created.
2. To restore your backup to an existing environment, run the following command:

   ```bash theme={null}
   upsun backup:restore --target=<TARGET_ENVIRONMENT_NAME> <BACKUP_ID>
   ```

   If your target environment doesn't exist yet, you can create it by [branching an existing environment](/docs/glossary#branch).
   The new target environment will be an exact copy of the existing (parent) environment.

   To do so, use the `--branch-from` option to specify the parent of your new target environment:

   ```bash theme={null}
   upsun backup:restore --target=<TARGET_ENVIRONMENT_NAME> --branch-from=<PARENT_ENVIRONMENT_NAME> <BACKUP_ID>
   ```


# Manage search indexing for an environment
Source: https://developer.upsun.com/docs/environments/search-engine-visibility

Protect SEO health by managing an environment's visibility to search engines.

Exposing multiple environments in the same project to search engines can harm your
production site's SEO rankings, for example, through duplicate content, broken links, or unpolished pages.

Whether search engines can index an environment depends on its domain:

* **No custom domain**: Always hidden from search engines. This default behavior cannot be changed.
* **Preview environment with a custom domain**: Hidden by default. You can make it visible.
* **Production environment with a custom domain (new project)**: When you add a custom domain, the site becomes visible to search engines by default. You can change this at any time.
* **Production environment with a custom domain (existing project)**: Retains its current setting when a custom domain is added. You can change this at any time.

<Note>
  If multiple environments have [custom domains](/docs/domains/steps), ensure that **at most** one is visible to avoid duplicate content and SEO dilution.
</Note>

To change whether search engines can index an environment:

<Tabs>
  <Tab title="In the Console">
    Prerequisite: The environment must have a [custom domain](/docs/domains/steps).

    1. Select the project you want to update.
    2. From the **Environment** menu, select the environment.
    3. Click <SettingsIcon /> **Settings**.
    4. Select or clear the **Hide from search engines** checkbox.
  </Tab>

  <Tab title="Using the CLI">
    Prerequisite: The environment must have a [custom domain](/docs/domains/steps).

    Run the following command:

    ```bash theme={null}
    upsun environment:info --environment <ENVIRONMENT_NAME> restrict_robots false
    ```
  </Tab>
</Tabs>

<Note>
  Upsun Cloud can't guarantee that indexers follow the instructions.
  To restrict access entirely, set up [HTTP access control](/docs/environments/http-access-control).
</Note>

## How it works

When **Hide from search engines** is enabled, Upsun Cloud adds the following header
to responses, which instructs search engines to not index and to not traverse your site:

```txt theme={null}
X-Robots-Tag: noindex, nofollow
```

This setting can only be changed on environments with a custom domain.

## Alternative method: Use a robots.txt file

You can also send instructions to search engine indexers using a `robots.txt` file.
Your app can serve this as a static file from its disk or as a dynamic response from its `passthru`.
Control either with the [`location` section of your app configuration](/docs/configure-apps/image-properties/web#locations).

If your `robots.txt` file instructs search engines to ignore a page, that instruction takes effect regardless of whether Upsun Cloud is configured to send the `X-Robots-Tag` header.

## What's next

* [Add a custom domain to your production environment](/docs/domains/steps)


# Environment settings
Source: https://developer.upsun.com/docs/environments/settings

Configure your environment's parent, default branch, access control, and search engine visibility.

<CardGroup>
  <Card title="Change an environment's parent" icon="arrow-up" href="/docs/environments/change-parent">
    Learn how to change a given environment's parent environment.
  </Card>

  <Card title="Rename the default environment" icon="pen" href="/docs/environments/default-environment">
    Change the name of your default/production environment after creating a project.
  </Card>

  <Card title="HTTP access control" icon="shield" href="/docs/environments/http-access-control">
    Control access to a given environment using HTTP methods.
  </Card>

  <Card title="Search engine visibility" icon="search" href="/docs/environments/search-engine-visibility">
    Change a given environment's visibility to search engines.
  </Card>
</CardGroup>


# Deploy AI apps on Upsun Cloud
Source: https://developer.upsun.com/docs/get-started/ai

Deploy AI applications, agents, and MCP servers on Upsun Cloud.


Deploy AI workloads on Upsun Cloud using any supported runtime.

<CardGroup>
  <Card title="AI Agents" icon="brain" href="/docs/get-started/ai/aiagent">
    Host conversational AI agents and chatbots.
  </Card>

  <Card title="MCP Servers" icon="server" href="/docs/get-started/ai/deploy-mcp">
    Deploy Model Context Protocol servers.
  </Card>

  <Card title="Upsun MCP Server" icon="terminal" href="/docs/get-started/ai/using-the-mcp">
    Use the Upsun MCP Server.
  </Card>
</CardGroup>


# Host AI Agents
Source: https://developer.upsun.com/docs/get-started/ai/aiagent



You can host AI agents on Upsun Cloud using any runtime that supports your preferred
programming language and integrate with various LLM APIs. Upsun Cloud provides
container-based deployments that give you control over your application
architecture and dependencies.

If you're planning to build an agent that analyzes application performance, Upsun Cloud already provides one: the [Upsun Cloud performance agent](/docs/get-started/ai/upsun-cloud-performance-agent).

## Runtime and language support

Upsun Cloud supports multiple runtimes through container-based deployments including
Python, Node.js, PHP, Ruby, Go, Java, and more. For the complete list of
supported runtimes and their versions, see the [runtime types reference](/docs/configure-apps/app-reference/single-runtime-image#type).

Configure your runtime in the [`.upsun/config.yaml`](/docs/core-concepts/yaml/yaml-structure)
file.
The platform builds your application in a container with the specified runtime
and dependencies.

## LLM API integration

You can integrate your AI agent with any LLM API that your chosen runtime supports:

* **OpenAI API**: Use the [official OpenAI client libraries](https://platform.openai.com/docs/libraries)
  for Python, Node.js, and other languages
* **Anthropic Claude API**: Use the [Anthropic client libraries](https://docs.anthropic.com/en/docs/getting-started-with-the-api) for Python,
  Node.js, and other languages
* **Google Gemini**: Use the [Google AI client libraries](https://ai.google.dev/docs)
  for Python, Node.js, and other languages
* **Azure OpenAI**: Use the [Azure OpenAI client libraries](https://learn.microsoft.com/en-us/azure/ai-services/openai/) for Python,
  Node.js, and other languages
* **AWS Bedrock**: Use the [AWS Bedrock client libraries](https://docs.aws.amazon.com/bedrock/) for Python, Node.js, and other languages
* **Other providers**: Integrate with any API that provides HTTP endpoints

Your application code handles the API calls and response processing. Upsun Cloud doesn't
restrict which services you can use.

## Environment management

Upsun Cloud provides isolated environments for development, testing, and production:

* **Branch-based environments**: Each Git branch creates a separate environment
* **Data isolation**: Each environment has its own services and data
* **Easy cloning**: Clone production data to development environments for testing
* **Environment variables**: Store API keys and configuration securely using
  [variables](/docs/development/variables)

## Tutorials

* **Deploy a RAG-based conversational agent with Chainlit**: Build a Retrieval-Augmented
  Generation agent using Chainlit, llama\_index, and OpenAI, then deploy it on Upsun Cloud.
  See the [Chainlit deployment tutorial](https://devcenter.upsun.com/posts/deploying-chainlit-with-rag/).

* **Access Documentation contextually via Context7 + MCP**: Use the Model Context
  Protocol to let AI assistants fetch your Upsun documentation in real-time. See the
  [Context7 MCP article](https://devcenter.upsun.com/posts/context7-mcp/).

* **Use the Upsun Cloud API to automate Agent deployment**: Automate deployments, environment
  management, and configuration through the Upsun Cloud API. See the
  [API usage guide](https://devcenter.upsun.com/posts/using-the-upsun-api/).

## Configuration example

Here's a basic configuration for a Python AI agent. For more configuration
options, see the [complete application reference](/docs/configure-apps/app-reference/single-runtime-image):

```yaml theme={null}
# .upsun/config.yaml
applications:
  ai-agent:
    source:
      root: "/"
    type: "python:3.11"
    mounts:
      ".data": source: "storage", source_path: "data"
    web:
      commands:
        start: "python agent.py"
      upstream:
        socket_family: tcp
        locations:
          "/": root: "", passthru: true
```

## Application Code

For examples of how to implement AI agents with different frameworks and APIs,
see the [AI and Machine Learning tutorials on DevCenter](https://developer.upsun.com/tutorials/ai?utm_source=docs\&utm_medium=ai-agent\&utm_campaign=tutorials).

## Deploy your Agent

1. Add your code to Git:

   ```bash theme={null}
   git add .
   git commit -m "Add AI agent service"
   ```

2. Set your OpenAI API key as an environment variable using the \[CLI]
   (/cli):

   ```bash theme={null}
   upsun variable:create env:OPENAI_API_KEY --value=<your_key>
   ```

   For more information about setting variables, see \[how to set variables]
   (/docs/development/variables/set-variables).

3. Deploy to Upsun Cloud:

   ```bash theme={null}
   upsun push
   ```

Your agent will be available at your Upsun Cloud environment URL. The platform handles
the containerization, networking, and scaling automatically. For more deployment
options, see [deploy your project](/docs/core-concepts/build-deploy).

***

## Key benefits

* **Runtime flexibility**: Choose the programming language and version that fits
  your needs
* **Service independence**: Use any LLM API or external service
* **Environment isolation**: Test changes safely in separate environments
* **Automated deployment**: Deploy through Git pushes or API calls
* **Scalability**: The platform handles load balancing and resource allocation

For more information about building and deploying applications, see the
[configure apps](/docs/configure-apps) section.


# Hosting Model Context Protocol (MCP) Servers
Source: https://developer.upsun.com/docs/get-started/ai/deploy-mcp



<Note title="Connect to the Upsun MCP Server">
  The Upsun Cloud Model Context Protocol (MCP) Server allows users to perform infrastructure operations, monitor environments, and manage resources using natural language commands.

  **You can set up the Upsun Cloud MCP Server with this [step-by-step guide](/docs/get-started/ai/using-the-mcp).**
</Note>

**Model Context Protocol (MCP)** is a standard interface that allows large
language models (LLMs) to communicate with external tools and data sources.
With MCP, developers and tool providers integrate once and ensure
interoperability across any MCP-compatible system.

For comprehensive information about the Model Context Protocol, including
specifications, examples, and implementation details, we recommend you visit the
[official MCP documentation](https://modelcontextprotocol.io/) maintained by Anthropic.

## Get started with MCP on Upsun Cloud

* **[Build and deploy AI-native applications with MCP servers on Upsun Cloud](https://devcenter.upsun.com/posts/deploy-mcp-servers-on-upsun/)**\
  Learn how to build and deploy AI-native applications by leveraging MCP servers
  hosted on Upsun Cloud.

## Why connect LLMs to external systems?

LLMs typically lack direct access to real-time or system-specific data. To
provide current, relevant responses—such as live configuration settings or API
data—LLMs need to connect with external systems.

Every service offers a different API, schema, and authentication. Without a
standard, managing multiple integrations becomes complex, brittle, and
error-prone.

## Standardizing LLM interactions with MCP

MCP standardizes how LLMs interact with external services. Developers create a
single MCP integration point that can interface with any MCP-compatible provider.

Similarly, tool and data providers only need to expose their service via an MCP
interface once—making it accessible to any MCP-enabled application.

Think of MCP as the **USB-C of LLM integration**—one interface that works
uniformly across devices.

## MCP Hosts, Clients, and Servers

MCP operates on a client–server model:

* **MCP Host**: The AI application environment (e.g., your IDE, ChatGPT-like
  interface, or AI agent).

* **MCP Client**: The connection created by the host to talk to a service.

* **MCP Server**: The external service that exposes an MCP interface.

To connect to multiple external services, a single host needs to manage multiple
MCP clients, each connecting to a different MCP server.

## Additional resources

* **[Deep Dive into MCP's Interaction Model](https://devcenter.upsun.com/posts/mcp-interaction-types-article/?utm_source=chatgpt.com)**\
  Explore MCP's three core interaction types—*prompts* (user-driven),
  *resources* (application-driven), and *tools* (model-driven)—to design more
  powerful and flexible AI workflows.

## Summary table

| Concept | Upsun Article (Link) |
| - | - |
| Accessing Docs | [Access Upsun documentation via Context7 using MCP](https://devcenter.upsun.com/posts/context7-mcp/?utm_source=chatgpt.com) |
| Deploying MCP | [Build and deploy AI-native applications with MCP servers on Upsun](https://developer.upsun.com/posts/hands-on/deploy-mcp-servers-on-upsun) |
| MCP Interaction | [Beyond Tool Calling: Understanding MCP's Three Core Interaction Types](https://devcenter.upsun.com/posts/mcp-interaction-types-article/?utm_source=chatgpt.com) |

***


# How to deploy AI
Source: https://developer.upsun.com/docs/get-started/ai/index



Upsun Cloud provides powerful capabilities for hosting AI applications,
agents, and services. You can deploy AI workloads using any supported runtime
and integrate with various LLM APIs and services.

<Info>
  Before you start, check out the [Upsun Cloud demo app](https://console.upsun.com/projects/create-project)
  and the main [Getting started guide](/docs/get-started/here).
  They provide all the core concepts and common commands you need to know before
  using the following materials.
</Info>

## AI applications and services

* [**AI Agents**](/docs/get-started/ai/aiagent) - Host conversational AI agents
  and chatbots using any
  supported runtime
* [**MCP Servers**](/docs/get-started/ai/deploy-mcp) - Deploy Model Context Protocol servers for
  AI tool integration
* [**Upsun Cloud MCP Server**](/docs/get-started/ai/using-the-mcp) - Use the Upsun Cloud Model Context Protocol Server
* [**Upsun Cloud performance agent**](/docs/get-started/ai/upsun-cloud-performance-agent) - Analyze Upsun Blackfire profiles, continuous profiling data, and traffic to generate a performance report
* **Vector Databases** - [Chroma](/tutorials/self-hosted/chroma), [Qdrant](/tutorials/self-hosted/qdrant)

## Supported technologies

* **Runtimes**: Python, Node.js, PHP, Ruby, Go, Java, and
  [supported runtime types](/docs/configure-apps/app-reference/single-runtime-image#type)
* **LLM APIs**: [OpenAI](https://platform.openai.com/docs),
  [Anthropic Claude](https://docs.anthropic.com/en/docs/getting-started-with-the-api),
  [Google Gemini](https://ai.google.dev/docs),
  [Azure OpenAI](https://learn.microsoft.com/en-us/azure/ai-services/openai/),
  [AWS Bedrock](https://docs.aws.amazon.com/bedrock/),
  and any other HTTP-based API service
* **AI Frameworks**: [LangChain](https://docs.langchain.com/oss/python/langchain/install),
  [LlamaIndex](https://docs.llamaindex.ai/), [Chainlit](https://docs.chainlit.io/),
  and custom implementations
* **Integration**: REST APIs, WebSockets, and event-driven architectures

<Info>
  <h4>API flexibility</h4>
  Upsun Cloud supports integration with **any** LLM service that provides an HTTP API.
  The services listed above are just popular examples. You can integrate with
  self-hosted models, specialized AI services, or any custom API endpoint that
  follows standard HTTP protocols.
</Info>

## Get started

1. **Choose your runtime**: Select the programming language that
   best fits your AI application needs.
2. **Configure your app**: Set up your application in the `.upsun/config.yaml` configuration file. You can use AI to [generate an initial configuration](/cli/init).
3. **Integrate LLM APIs**: Connect to your preferred AI service providers.
4. **Deploy and scale**: Push your code and let Upsun Cloud handle the infrastructure.

For detailed examples and tutorials, see the
[AI and Machine Learning tutorials on DevCenter](https://developer.upsun.com/tutorials/ai?utm_source=docs\&utm_medium=ai-section\&utm_campaign=tutorials).

Find out more about the many [languages Upsun Cloud supports](/docs/languages).


# Upsun Cloud performance agent
Source: https://developer.upsun.com/docs/get-started/ai/upsun-cloud-performance-agent

Automatically find performance bottlenecks in your Upsun Cloud application. The performance agent analyzes up to 7 days of profiling and traffic data and generates an AI-powered report with actionable recommendations.

# Upsun Cloud performance agent

The `performance-agent` correlates a range of observability signals from an application or worker deployed on Upsun Cloud, including Upsun Blackfire profiles, continuous profiling data, traffic, and your source code, then generates a performance analysis report. It analyzes a configurable window of up to 7 days (24 hours by default), subject to your [profiling retention](#analysis-window).

## Run as an Upsun Cloud task

The agent runs as an Upsun Cloud [`task`](/docs/configure-apps/tasks), so it requires no local installation.

The only credential you supply is an LLM provider API key: `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`. The provider is deduced from the `MODEL` you set (`claude*` uses `ANTHROPIC_API_KEY`, `gpt*` uses `OPENAI_API_KEY`). You bring your own key, and your provider bills the tokens the agent consumes directly to you. See [What a run costs](#what-a-run-costs).

Store the API key as a sensitive variable rather than passing it inline. Passing it inline exposes the secret in shell history.

```bash theme={null}
upsun variable:create -p <project-id> --level project --name env:ANTHROPIC_API_KEY \
    --value "<key>" --sensitive true --visible-runtime true
```

### 1. Add the task to your Upsun Cloud configuration

Add the following to `.upsun/config.yaml`:

```yaml theme={null}
tasks:
  performance-agent:
    base: "performance-agent"
```

Commit the change and deploy it so the task is available on your environment:

```bash theme={null}
git add .upsun/config.yaml
git commit -m "Add performance agent task"
upsun push
```

### 2. Run the agent

You can run the agent from the Console, or through the CLI and API.

#### From the Console

1. Open your environment overview page.
2. Either find the **Tasks** card in the left-hand column, or open the **Containers** tab and select **performance-agent** under **Tasks**.
3. In the **Run performance-agent task on `<environment>`** dialog, set the following:
   * **Analysis scope**: use the **Select the application or worker** dropdown to choose the container to analyze.
   * **Analysis period**: choose 15 minutes, 1 hour, 24 hours, or 7 days. The dialog shows the profiling coverage included with your plan inline, for example *Your plan covers 15 minutes. For more, upgrade continuous profiling.* See [Analysis window](#analysis-window).
   * **AI engine and guard rails**: the model, thinking level, maximum number of findings, and budget cap. These map to the [`MODEL`, `THINKING`, `MAX_FINDINGS`, and `MAX_BUDGET_USD`](#task-environment-variables) variables.
4. Click **Run**.

When the analysis completes, the results appear in the **Report** tab, marked with a sparkle icon. The report lists each finding and the suggested diff that addresses it.

#### From the CLI or API

Replace the project ID, environment, and application name with yours:

```bash theme={null}
upsun e:curl -p <project-id> -e <env> -X POST /tasks/performance-agent/run \
  --json '{"variables":{"env":{"AGENT_APPLICATION":"<app-name>"}}}'
```

To analyze a worker instead, pass the worker name in `AGENT_APPLICATION`. There is no qualifier or special syntax:

```bash theme={null}
upsun e:curl -p <project-id> -e <env> -X POST /tasks/performance-agent/run \
  --json '{"variables":{"env":{"AGENT_APPLICATION":"<worker-name>"}}}'
```

`AGENT_APPLICATION` is the only required variable. The report is written to the task activity log.

### Analysis window

The agent analyzes a window of up to 7 days. Set it with `FROM_TIMESTAMP` and `TO_TIMESTAMP` from the CLI and API, or with the **Analysis period** presets in the Console.

How much of that window the agent can draw on depends on your continuous profiling retention. Every project includes 15 minutes of continuous profiling. Longer history comes from the [continuous profiling add-on](/docs/administration/billing/add-on-subscription#continuous-profiling-add-on), which retains 30 days per project.

The default 15 minutes is enough for the agent to run without failing, but it only covers the last few minutes of activity. Feeding the agent more profiling data surfaces bottlenecks that build up over time, like a slow path under peak traffic or a weekly batch job.

### Task environment variables

Pass additional variables under `variables.env` in the run command.

| Env var | Default | Description |
| - | - | - |
| `AGENT_APPLICATION` | (required) | Name of the Upsun Cloud application or worker to analyze. |
| `CLONE_TIMEOUT` | `900` | Timeout in seconds for cloning the environment's source; also the requested proxy token TTL. Raise for very large repos. |
| `FROM_TIMESTAMP` | (binary default: `to - 86400`) | Window start in Unix seconds. Window capped at 7 days. See [Analysis window](#analysis-window). |
| `TO_TIMESTAMP` | (binary default: now) | Window end in Unix seconds. |
| `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` | (required) | Provider API key, read by the binary directly from env. The provider is deduced from `MODEL` (`claude*` uses `ANTHROPIC_API_KEY`, `gpt*` uses `OPENAI_API_KEY`). Set it as a sensitive variable, not inline. |
| `MODEL` | `claude-opus-4-8` | Model ID. See [Available models](#available-models). |
| `LOG_LEVEL` | `info` | `trace`, `debug`, `info`, `warn`, `error`, `fatal`, or `silent`. |
| `THINKING` | `xhigh` | `minimal`, `low`, `medium`, `high`, or `xhigh`. |
| `MAX_FINDINGS` | `5` | Integer 1–15. |
| `MAX_BUDGET_USD` | `5` | Cost ceiling in USD. |
| `QUIET` | `false` | Read by the binary directly from env; `0`/`false`/`no`/`off` to disable. |
| `VERBOSE` | `false` | Read by the binary directly from env; `0`/`false`/`no`/`off` to disable. |

Variables with a binary default are the agent's own defaults. The task only passes a flag when the variable is set. `--project` and `--environment` are locked to the runtime's `PLATFORM_PROJECT` and `PLATFORM_BRANCH` and cannot be overridden through environment variables.

### Available models

Set `MODEL` to any of the following IDs. Aliases resolve to the latest matching model. The provider is deduced from the model ID.

| Model | Alias | Provider |
| - | - | - |
| `claude-opus-4-8` | `claude-opus` | `anthropic` |
| `claude-opus-4-7` | | `anthropic` |
| `claude-sonnet-5` | `claude-sonnet` | `anthropic` |
| `claude-sonnet-4-6` | | `anthropic` |
| `gpt-5.5` | | `openai` |
| `gpt-5.6-sol` | | `openai` |
| `gpt-5.6-luna` | | `openai` |
| `gpt-5.6-terra` | `gpt` | `openai` |

## What a run costs

Upsun Cloud doesn't charge for the performance agent itself. There is no license, subscription, or per-run fee.

Each run costs you the compute of the [task container](/docs/configure-apps/tasks#resources-variables-and-access) it runs in, billed per second at the resources you allocate to the task. Task compute cost is the same regardless of which model you use. Your LLM provider then bills the tokens the agent consumes to your own API key, and this billing varies by task model (see the table below). Upsun doesn't resell those tokens, and task compute doesn't cover them.

The [continuous profiling add-on](/docs/administration/billing/add-on-subscription#continuous-profiling-add-on) is optional and billed separately, as a per-project fee. See the [pricing page](https://upsun.com/pricing/).

### Cost by model

Cost per run depends on the model, the length of the analysis window, and how much observability data your app produces. The `MAX_BUDGET_USD` variable (default `5`) caps spend per run.

<Note>
  The figures below come from internal tests and are only a rough sense of scale, not a guarantee. Your actual cost will vary.
</Note>

| Model | Approximate cost per run |
| - | - |
| `gpt-5.6-terra` | \~\$0.25 to \$0.85 |
| `claude-sonnet-5` | \~\$0.65 to \$2.20 |
| `claude-opus-4-8` | \~\$1.00 to \$2.90 |


# The Upsun MCP Server
Source: https://developer.upsun.com/docs/get-started/ai/using-the-mcp

The Upsun Model Context Protocol (MCP) Server allows users to perform infrastructure operations, monitor environments, and manage resources using natural language commands and AI assistants.

The Upsun Cloud Model Context Protocol [(MCP) Server](https://devcenter.upsun.com/posts/upsun-mcp-announcement/) enables management of Upsun Cloud projects and environments through AI assistants such as Claude. It supports conversational commands to create, modify, and monitor infrastructure without using the terminal or Console.

<img alt="MCP projects" />

## Key capabilities

| Capability | Description | Use case |
| - | - | - |
| **Natural Language Infrastructure Management** | Converts user instructions written in natural language to corresponding API operations. | - “Show me all active environments in my project.” <br /> - “Add Redis caching to my staging environment.” |
| **CI/CD Integration** | Integrates with existing development workflows and interacts with CI/CD pipelines to trigger or respond to automated workflows. | - Trigger deployments from the IDE. <br /> - Monitor build progress from documentation tools or chat interfaces. |
| **AI-Based Automation** | Supports AI-driven automation that adapts to real-world conditions by analyzing metrics, historical data, and usage patterns. | - Resource allocation based on usage trends. <br /> - Automated troubleshooting with suggested root causes. <br /> - Adaptive backup scheduling. |

## Security Model

All MCP operations follow the existing Upsun Cloud [security model](https://upsun.com/trust-center/security/). The MCP Server defaults to read-only operations for safety, with write operations available through explicit configuration.

To enable write operations, include the following header in your MCP configuration:

```json theme={null}
{
  "enable-write": "true"
}
```

<Warning>
  <h4>Security Implications</h4>
  Enable write operations **only** if you understand the associated security implications and trust your AI assistant to modify infrastructure resources.
</Warning>

## Architecture

The Upsun Cloud MCP Server uses [Streamable HTTP transport](https://modelcontextprotocol.io/docs/learn/architecture) for communication and event streaming.

It uses HTTP POST for client-to-server messages with optional Server-Sent Events for streaming capabilities. This transport enables remote server communication and supports standard HTTP authentication methods including bearer tokens, API keys, and custom headers.

<img alt="MCP Architecture" />

## Installation

### 1. Generate an API Token

* In the Upsun Cloud [Console](https://console.upsun.com/), open your account settings.
* Generate a new API token with permissions appropriate for your projects.

### 2. Configure the MCP Client

* Configure your MCP client to connect to `mcp.upsun.com/mcp`.

### 3. Connect and Use

* Connect your AI assistant or any MCP-compatible client.
* Begin managing Upsun Cloud resources using natural language commands.

<Info>
  <h4>Select your preferred client</h4>
  The Upsun Cloud MCP server works with all major AI development environments.

  **Choose your preferred client from the list below:**
</Info>

<AccordionGroup>
  <Accordion title="Install in Cursor">
    Go to: `Settings` -> `Cursor Settings` -> `MCP` -> `Add new global MCP server`

    Copying the following configuration into your Cursor `~/.cursor/mcp.json` file is the recommended approach. You may also install in a specific project by creating `.cursor/mcp.json` in your project folder.

    See the [Cursor MCP docs](https://docs.cursor.com/context/model-context-protocol) for more info.

    #### Cursor Remote Server Connection

    ```json theme={null}
    {
      "mcpServers": {
        "upsun": {
          "url": "https://mcp.upsun.com/mcp",
          "headers": {
            "upsun-api-token": "YOUR_API_TOKEN",
            "enable-write": "false"
          }
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Install in Claude Code">
    Run this command. See [Claude Code MCP docs](https://docs.anthropic.com/en/docs/claude-code/mcp) for more info.

    #### Claude Code Remote Server Connection

    ```sh theme={null}
    claude mcp add --transport http upsun https://mcp.upsun.com/mcp --header "upsun-api-token: YOUR_API_TOKEN" --header "enable-write: false"
    ```
  </Accordion>

  <Accordion title="Install in Windsurf">
    Add this to your Windsurf MCP config file. See [Windsurf MCP docs](https://docs.windsurf.com/windsurf/cascade/mcp) for more info.

    #### Windsurf Remote Server Connection

    ```json theme={null}
    {
      "mcpServers": {
        "upsun": {
          "serverUrl": "https://mcp.upsun.com/mcp",
          "headers": {
            "upsun-api-token": "YOUR_API_TOKEN",
            "enable-write": "false"
          }
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Install in VS Code">
    Add this to your VS Code MCP config file. See [VS Code MCP docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more info.

    #### VS Code Remote Server Connection

    ```json theme={null}
    "mcp": {
      "servers": {
        "upsun": {
          "type": "http",
          "url": "https://mcp.upsun.com/mcp",
          "headers": {
            "upsun-api-token": "YOUR_API_TOKEN",
            "enable-write": "false"
          }
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Install in Cline">
    You can easily configure the Upsun MCP server through Cline:

    1. Open **Cline**.
    2. Click the hamburger menu icon (☰) to enter the **MCP Servers** section.
    3. On the **Remote Servers** tab, click **Edit Configuration**.
    4. Add upsun to `mcpServers`:

    ```json theme={null}
    {
      "mcpServers": {
        "upsun": {
          "url": "https://mcp.upsun.com/mcp",
          "type": "streamableHttp",
          "headers": {
            "upsun-api-token": "YOUR_API_TOKEN",
            "enable-write": "false"
          }
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Install in Zed">
    Add this to your Zed `settings.json`. See [Zed Context Server docs](https://zed.dev/docs/assistant/context-servers) for more info.

    ```json theme={null}
    {
      "context_servers": {
        "Upsun": {
          "settings": {
            "url": "https://mcp.upsun.com/mcp",
            "headers": {
              "upsun-api-token": "YOUR_API_TOKEN",
              "enable-write": "false"
            }
          }
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Install in Augment Code">
    To configure the Upsun MCP server in Augment Code:

    **Manual Configuration**

    1. Press Cmd/Ctrl+Shift+P or go to the hamburger menu in the Augment panel.
    2. Select Edit Settings
    3. Under Advanced, click Edit in settings.json
    4. Add the server configuration to the `mcpServers` array in the `augment.advanced` object

    ```json theme={null}
    "augment.advanced": {
      "mcpServers": [
        {
          "name": "upsun",
          "url": "https://mcp.upsun.com/mcp",
          "headers": {
            "upsun-api-token": "YOUR_API_TOKEN",
            "enable-write": "false"
          }
        }
      ]
    }
    ```

    Once the MCP server is added, restart your editor. If you receive any errors, check the syntax to make sure closing brackets or commas are not missing.
  </Accordion>

  <Accordion title="Install in Roo Code">
    Add this to your Roo Code MCP configuration file. See [Roo Code MCP docs](https://docs.roocode.com/features/mcp/using-mcp-in-roo) for more info.

    #### Roo Code Remote Server Connection

    ```json theme={null}
    {
      "mcpServers": {
        "upsun": {
          "type": "streamable-http",
          "url": "https://mcp.upsun.com/mcp",
          "headers": {
            "upsun-api-token": "YOUR_API_TOKEN",
            "enable-write": "false"
          }
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Install in Gemini CLI">
    See [Gemini CLI Configuration](https://google-gemini.github.io/gemini-cli/docs/tools/mcp-server.html) for details.

    1. Open the Gemini CLI settings file. The location is `~/.gemini/settings.json` (where `~` is your home directory).
    2. Add the following to the `mcpServers` object in your `settings.json` file:

    ```json theme={null}
    {
      "mcpServers": {
        "upsun": {
          "httpUrl": "https://mcp.upsun.com/mcp",
          "headers": {
            "upsun-api-token": "YOUR_API_TOKEN",
            "enable-write": "false",
            "Accept": "application/json, text/event-stream"
          }
        }
      }
    }
    ```

    If the `mcpServers` object does not exist, create it.
  </Accordion>

  <Accordion title="Install in Claude Desktop">
    #### Remote Server Connection

    Open Claude Desktop and navigate to Settings > Connectors > Add Custom Connector. Enter the name as `Upsun` and the remote MCP server URL as `https://mcp.upsun.com/mcp`.

    Add your API token in the headers configuration:

    ```json theme={null}
    {
      "upsun-api-token": "YOUR_API_TOKEN",
      "enable-write": "false"
    }
    ```
  </Accordion>

  <Accordion title="Install in Opencode">
    Add this to your Opencode configuration file. See [Opencode MCP docs](https://opencode.ai/docs/mcp-servers) for more info.

    #### Opencode Remote Server Connection

    ```json theme={null}
    "mcp": {
      "upsun": {
        "type": "remote",
        "url": "https://mcp.upsun.com/mcp",
        "headers": {
          "upsun-api-token": "YOUR_API_TOKEN",
          "enable-write": "false"
        },
        "enabled": true
      }
    }
    ```
  </Accordion>

  <Accordion title="Install in JetBrains AI Assistant">
    See [JetBrains AI Assistant Documentation](https://www.jetbrains.com/help/ai-assistant/configure-an-mcp-server.html) for more details.

    1. In JetBrains IDEs, go to `Settings` -> `Tools` -> `AI Assistant` -> `Model Context Protocol (MCP)`
    2. Click `+ Add`.
    3. Click `Command` in the top-left corner of the dialog and select **As JSON** from the list.
    4. Add this configuration and click `OK`

    ```json theme={null}
    {
      "mcpServers": {
        "upsun": {
          "url": "https://mcp.upsun.com/mcp",
          "headers": {
            "upsun-api-token": "YOUR_API_TOKEN",
            "enable-write": "false"
          }
        }
      }
    }
    ```

    5. Click `Apply` to save changes.
    6. Repeat these steps to add `upsun` for JetBrains Junie: Go to `Settings` -> `Tools` -> `Junie` -> `MCP Settings`.
  </Accordion>

  <Accordion title="Install in Kiro">
    See [Kiro Model Context Protocol Documentation](https://kiro.dev/docs/mcp/configuration/) for details.

    1. Navigate `Kiro` > `MCP Servers`
    2. Add a new MCP server by clicking the `+ Add` button.
    3. Paste the configuration given below:

    ```json theme={null}
    {
      "mcpServers": {
        "Upsun": {
          "url": "https://mcp.upsun.com/mcp",
          "headers": {
            "upsun-api-token": "YOUR_API_TOKEN",
            "enable-write": "false"
          },
          "disabled": false,
          "autoApprove": []
        }
      }
    }
    ```

    4. Click `Save` to apply the changes.
  </Accordion>

  <Accordion title="Install in Trae">
    Use the **Add manually** feature and populate the JSON configuration information for that MCP server.
    For more details, visit the [Trae documentation](https://docs.trae.ai/ide/model-context-protocol?_lang=en).

    #### Trae Remote Server Connection

    ```json theme={null}
    {
      "mcpServers": {
        "upsun": {
          "url": "https://mcp.upsun.com/mcp",
          "headers": {
            "upsun-api-token": "YOUR_API_TOKEN",
            "enable-write": "false"
          }
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Install in Amazon Q Developer CLI">
    Add this to your Amazon Q Developer CLI configuration file. See [Amazon Q Developer CLI docs](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line-mcp-configuration.html) for more details.

    ```json theme={null}
    {
      "mcpServers": {
        "upsun": {
          "url": "https://mcp.upsun.com/mcp",
          "headers": {
            "upsun-api-token": "YOUR_API_TOKEN",
            "enable-write": "false"
          }
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Install in Warp">
    See [Warp Model Context Protocol Documentation](https://docs.warp.dev/knowledge-and-collaboration/mcp#adding-an-mcp-server) for details.

    1. Navigate `Settings` > `AI` > `Manage MCP servers`.
    2. Add a new MCP server by clicking the `+ Add` button.
    3. Paste the configuration given below:

    ```json theme={null}
    {
      "Upsun": {
        "url": "https://mcp.upsun.com/mcp",
        "headers": {
          "upsun-api-token": "YOUR_API_TOKEN",
          "enable-write": "false"
        },
        "start_on_launch": true
      }
    }
    ```

    4. Click `Save` to apply the changes.
  </Accordion>

  <Accordion title="Install in Copilot Coding Agent">
    **Using Upsun MCP with Copilot Coding Agent**

    Add the following configuration to the `mcp` section of your Copilot Coding Agent configuration file Repository->Settings->Copilot->Coding agent->MCP configuration:

    ```json theme={null}
    {
      "mcpServers": {
        "upsun": {
          "type": "http",
          "url": "https://mcp.upsun.com/mcp",
          "headers": {
            "upsun-api-token": "YOUR_API_TOKEN",
            "enable-write": "false"
          }
        }
      }
    }
    ```

    For more information, see the [official GitHub documentation](https://docs.github.com/en/enterprise-cloud@latest/copilot/how-tos/agents/copilot-coding-agent/extending-copilot-coding-agent-with-mcp).
  </Accordion>

  <Accordion title="Install in LM Studio">
    See [LM Studio MCP Support](https://lmstudio.ai/blog/lmstudio-v0.3.17) for more information.

    #### Manual set-up:

    1. Navigate to `Program` (right side) > `Install` > `Edit mcp.json`.
    2. Paste the configuration given below:

    ```json theme={null}
    {
      "mcpServers": {
        "Upsun": {
          "url": "https://mcp.upsun.com/mcp",
          "headers": {
            "upsun-api-token": "YOUR_API_TOKEN",
            "enable-write": "false"
          }
        }
      }
    }
    ```

    3. Click `Save` to apply the changes.
    4. Toggle the MCP server on/off from the right hand side, under `Program`, or by clicking the plug icon at the bottom of the chat box.
  </Accordion>

  <Accordion title="Install in Visual Studio 2022">
    You can configure the Upsun MCP server in Visual Studio 2022 by following the [Visual Studio MCP Servers documentation](https://learn.microsoft.com/visualstudio/ide/mcp-servers?view=vs-2022).

    Add this to your Visual Studio MCP config file (see the [Visual Studio docs](https://learn.microsoft.com/visualstudio/ide/mcp-servers?view=vs-2022) for details):

    ```json theme={null}
    {
      "inputs": [],
      "servers": {
        "upsun": {
          "type": "http",
          "url": "https://mcp.upsun.com/mcp",
          "headers": {
            "upsun-api-token": "YOUR_API_TOKEN",
            "enable-write": "false"
          }
        }
      }
    }
    ```

    For more information and troubleshooting, refer to the [Visual Studio MCP Servers documentation](https://learn.microsoft.com/visualstudio/ide/mcp-servers?view=vs-2022).
  </Accordion>

  <Accordion title="Install in Crush">
    Add this to your Crush configuration file. See [Crush MCP docs](https://github.com/charmbracelet/crush#mcps) for more info.

    #### Crush Remote Server Connection (HTTP)

    ```json theme={null}
    {
      "$schema": "https://charm.land/crush.json",
      "mcp": {
        "upsun": {
          "type": "http",
          "url": "https://mcp.upsun.com/mcp",
          "headers": {
            "upsun-api-token": "YOUR_API_TOKEN",
            "enable-write": "false"
          }
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Install in BoltAI">
    Open the "Settings" page of the app, navigate to "Plugins," and configure the Upsun MCP server:

    ```json theme={null}
    {
      "mcpServers": {
        "upsun": {
          "url": "https://mcp.upsun.com/mcp",
          "headers": {
            "upsun-api-token": "YOUR_API_TOKEN",
            "enable-write": "false"
          }
        }
      }
    }
    ```

    More information is available on [BoltAI's Documentation site](https://docs.boltai.com/docs/plugins/mcp-servers). For BoltAI on iOS, [see this guide](https://docs.boltai.com/docs/boltai-mobile/mcp-servers).
  </Accordion>

  <Accordion title="Install in Rovo Dev CLI">
    Edit your Rovo Dev CLI MCP config by running the following command:

    ```bash theme={null}
    acli rovodev mcp
    ```

    Example config -

    #### Remote Server Connection

    ```json theme={null}
    {
      "mcpServers": {
        "upsun": {
          "url": "https://mcp.upsun.com/mcp",
          "headers": {
            "upsun-api-token": "YOUR_API_TOKEN",
            "enable-write": "false"
          }
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Install in Zencoder">
    To configure the Upsun MCP server in Zencoder, follow these steps:

    1. Go to the Zencoder menu (...)
    2. From the dropdown menu, select Agent tools
    3. Click on the Add custom MCP
    4. Add the name and server configuration from below, and make sure to hit the Install button

    ```json theme={null}
    {
      "url": "https://mcp.upsun.com/mcp",
      "headers": {
        "upsun-api-token": "YOUR_API_TOKEN",
        "enable-write": "false"
      }
    }
    ```

    Once the MCP server is added, you can easily continue using it.
  </Accordion>

  <Accordion title="Install in Qodo Gen">
    See [Qodo Gen docs](https://docs.qodo.ai/qodo-documentation/qodo-gen/qodo-gen-chat/agentic-mode/agentic-tools-mcps) for more details.

    1. Open Qodo Gen chat panel in VSCode or IntelliJ.
    2. Click Connect more tools.
    3. Click + Add new MCP.
    4. Add the following configuration:

    #### Qodo Gen Remote Server Connection

    ```json theme={null}
    {
      "mcpServers": {
        "upsun": {
          "url": "https://mcp.upsun.com/mcp",
          "headers": {
            "upsun-api-token": "YOUR_API_TOKEN",
            "enable-write": "false"
          }
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Install in Perplexity Desktop">
    See [Local and Remote MCPs for Perplexity](https://www.perplexity.ai/help-center/en/articles/11502712-local-and-remote-mcps-for-perplexity) for more information.

    1. Navigate to `Perplexity` > `Settings`.
    2. Select `Connectors`.
    3. Click `Add Connector`.
    4. Select `Advanced`.
    5. Enter Server Name: `Upsun`
    6. Paste the following JSON in the text area:

    ```json theme={null}
    {
      "url": "https://mcp.upsun.com/mcp",
      "headers": {
        "upsun-api-token": "YOUR_API_TOKEN",
        "enable-write": "false"
      }
    }
    ```

    7. Click `Save`.
  </Accordion>
</AccordionGroup>

## Related content

### Upsun Cloud AI tutorials

* Upsun Cloud [AI and Machine Learning tutorials](https://developer.upsun.com/tutorials/ai?utm_source=docs\&utm_medium=ai-agent\&utm_campaign=tutorials)
* [Experiment with Chainlit AI interface with RAG](https://devcenter.upsun.com/posts/deploying-chainlit-with-rag/) on Upsun Cloud
* [Access Upsun Documentation contextually via Context7 + MCP](https://devcenter.upsun.com/posts/context7-mcp/)
* Use the Upsun Cloud API to [automate Agent deployment](https://devcenter.upsun.com/posts/using-the-upsun-api/)
* Upsun Cloud [MCP Server Announcement](https://devcenter.upsun.com/posts/upsun-mcp-announcement/)

### Upsun AI documentation

* [Host AI Agents](/docs/get-started/ai/aiagent) on Upsun Cloud
* [Deploy AI](/docs/get-started/ai) on Upsun Cloud
* [Upsun Cloud performance agent](/docs/get-started/ai/upsun-cloud-performance-agent), which reads your observability data and returns a report of bottlenecks with recommended code changes


# Configure your project
Source: https://developer.upsun.com/docs/get-started/here/configure/index

Add the required YAML configuration files to deploy your project on Upsun Cloud.

## Required files

Upsun Cloud uses a YAML configuration file to control your application's behavior.
Place this file inside a `.upsun/` folder at the root of your source code:

```text Example file structure theme={null}
my-app
├── .upsun
│   └── config.yaml
├── [.environment]
└── <project sources>
```

To generate these YAML files, run the following command from the root of your project:

```bash Terminal theme={null}
upsun project:init
```

Follow the prompts. The `upsun project:init` command does the following:

* Detects your framework automatically. If it can't, it asks which [runtime language](/docs/languages) your codebase uses.
* Asks if you want to [add any services](/docs/add-services).
* Generates the `.upsun/config.yaml` and `.environment` files.

The [generated configuration](/docs/configure-apps/app-reference/single-runtime-image) varies slightly based on your answers and whether a framework is detected. The file structure looks similar to the following:

```yaml {configFile="app"} theme={null}
applications:
  # Configuration for all applications within an environment.
  myapp:
    # configuration for the application 'myapp'

services:
  # Configuration for all services within an environment.
  db:
    # configuration for service 'db'

routes:
  # Configuration for routing to applications
  'https://{default}/':
```

The top-level keys map to:

* [`applications`](/docs/configure-apps/app-reference/single-runtime-image): configuration for all applications within an environment
* [`services`](/docs/add-services): configuration for all services within an environment
* [`routes`](/docs/routes): configuration for how requests are handled by the router

<Note>
  For more information on the structure of this configuration file, see the [YAML structure page](/docs/core-concepts/yaml/yaml-structure).
</Note>

<Info>
  <h4>Committing variables</h4>
  An additional [`.environment` file](/docs/development/variables/set-variables#set-variables-via-script) may be located at the root of your source code. This file contains Upsun Cloud-specific environment variables.
</Info>

Commit your new files:

```bash Terminal theme={null}
git add . && git commit -m "Add configuration for Upsun Cloud."
```

Push to your Upsun Cloud project:

```bash theme={null}
upsun push
```

Upsun Cloud reads your configuration files, builds your application image, and allocates resources to your containers.

<Note>
  By default, Upsun Cloud uses default resources for each of your services and apps. You can [adjust these resources](/docs/get-started/here/set-resources).
</Note>

## Errors on first push

If you push code without an Upsun Cloud configuration, the following error appears:

<Tabs>
  <Tab title="Using Upsun Cloud CLI">
    ```bash theme={null}
    Found 749 commits

    E: Error parsing configuration files:
    - : Configuration directory '.upsun' not found.

    E: Error: Invalid configuration files, aborting build
    ```
  </Tab>

  <Tab title="Using Console">
    <img alt="Create project options" />
  </Tab>
</Tabs>

Add the configuration files described above and push again.

## Configuration errors

The `project:init` command uses your responses and framework-detection logic to generate a starting configuration. Because every project is different, the generated configuration may not cover all your requirements.

Upsun Cloud provides a customizable configuration schema you can adjust for your package manager, environment variables, builds, deploys, workers, crons, and other requirements.

To explore what might still be needed, see the language-specific configuration pages:

* [JavaScript/Node.js](/docs/get-started/here/configure/nodejs)
* [PHP](/docs/get-started/here/configure/php)
* [Python](/docs/get-started/here/configure/python)

## Next steps

After deployment, Upsun Cloud sets resources for your application and service containers automatically:

<Info>
  Each time you create a new branch, your new environment inherits its parent environment's resource allocation.
</Info>

If you need more disk for [uploaded files](/docs/development/file-transfer), or less memory for rarely used [services](/docs/add-services), you can [adjust resources](/docs/manage-resources/adjust-resources) at any time.


# JavaScript/Node.js
Source: https://developer.upsun.com/docs/get-started/here/configure/nodejs

All you need to know about configuring a new Javascript/Node.js project with Upsun Cloud

When dealing with Javascript/Node.js stacks, the information below may help customize your configuration.
These sections provide Javascript/Node.js-specific configuration details, but you can also refer to the common Upsun documentation:

* [Configuring applications](/docs/configure-apps)
* [Setting up managed services](/docs/add-services)
* [Handling requests](/docs/routes)

## Build flavors

By default, Upsun Cloud makes assumptions about how you want to build your application.
Namely, that you are managing your dependencies with npm, and that the very first thing you'd like to run is a particular and common production flavor of `npm install`.

This is called a build `flavor`, but its assumption may prove inappropriate for your application and cause your builds to fail (such as if you'd like to use yarn or bun instead of npm).
Therefore, you can [disable this feature](/docs/languages/nodejs#dependencies).

## Available package managers

Certain package managers come pre-installed on all Upsun Cloud `nodejs` container types:

* *npm*; example: `npm install platformsh-config`
* *npx*; example: `npx create-strapi-app <APP_NAME>`
* *bun*; example: `bun install platformsh-config`

You can also use Yarn if you [install it explicitly](/docs/languages/nodejs#use-yarn-as-a-package-manager), or [nvm](/docs/languages/nodejs/node-version#use-nvm).

## Sample configuration

Below are some examples from common Node.js framework configuration:

## Frameworks

The Upsun documentation includes a wide array of community resources to help with framework-specific configuration:

* [Express](/docs/get-started/stacks/express)
* [Next.js](/docs/get-started/stacks/nextjs)
* [Strapi](/docs/get-started/stacks/strapi)

## Get support

While there are virtually no restrictions to you deploying any kind of application on Upsun Cloud, configuration may still be unclear at this point.

Not to worry! The Upsun community is here to help.
Come and say hello, share your work, ask for help, and peek in on what others are working on.

Welcome to the Upsun community!

<CommunityButtons />


# PHP
Source: https://developer.upsun.com/docs/get-started/here/configure/php

All you need to know about configuring a new PHP project with Upsun Cloud

When dealing with PHP stacks, the information below may help customize your configuration.
These sections provide PHP-specific configuration details, but you can also refer to the common Upsun documentation:

* [Configuring applications](/docs/configure-apps)
* [Setting up managed services](/docs/add-services)
* [Handling requests](/docs/routes)

## Build flavors

By default, Upsun Cloud makes assumptions about how you want to build your application.
Namely, that you are managing your dependencies with Composer, and that the very first thing you'd like to run is a particular and common production flavor of `composer install`.

This is called a build `flavor`, but its assumption may prove inappropriate for your application and cause your builds to fail.
Therefore, you can [disable this feature](/docs/languages/php#dependencies).

## Authenticated Composer

Packagist is the primary Composer repository for public PHP packages. But you can also have Composer download PHP packages from a private, third-party Composer repository. To make sure Composer has the necessary credentials to do so, follow the instructions on the [Authenticated Composer documentation](/docs/languages/php/composer-auth).

## PHP settings

Upsun Cloud provides additional configuration possibilities to control:

* [PHP-FPM runtime configuration](/docs/configure-apps/app-reference/single-runtime-image#runtime)
* [PHP settings](/docs/languages/php#php-settings)

## Enabling/disabling extensions

PHP has a number of extensions developed by members of the community.
Some of these extensions need to be enabled, while others are enabled by default and must be disabled if desirable.

See which [PHP extensions](/docs/languages/php/extensions) are available for your version of PHP.

## Web servers

While PHP-FPM is the default behavior, Upsun Cloud provides some support for different web servers by modifying the `web.commands.start` property:

* [Alternate start commands](/docs/languages/php#alternate-start-commands)
* [Swoole](/docs/languages/php/swoole)

## Frameworks

The Upsun documentation includes a wide array of community resources to help with framework-specific configuration:

* [Laravel](/docs/get-started/stacks/laravel)
* [Symfony](/docs/get-started/stacks/symfony)

## Get support

While there are virtually no restrictions to you deploying any kind of application on Upsun Cloud, configuration may still be unclear at this point.

Not to worry! The Upsun community is here to help.
Come and say hello, share your work, ask for help, and peek in on what others are working on.

Welcome to the Upsun community!

<CommunityButtons />


# Python
Source: https://developer.upsun.com/docs/get-started/here/configure/python

All you need to know about configuring a new Python project with Upsun Cloud

When dealing with Python stacks, the information below may help customize your configuration.
These sections provide Python-specific configuration details, but you can also refer to the common Upsun documentation:

* [Configuring applications](/docs/configure-apps)
* [Setting up managed services](/docs/add-services)
* [Handling requests](/docs/routes)

## Managing dependencies

Pip comes pre-installed in all `python` runtime containers.
With it, you can add `pip install` to your build hook and be well on your way to building your apps.

Alternatively, you can [use a different package manager](/docs/languages/python/dependencies), such as Poetry or Pipvenv.

## Configuring web servers

Upsun Cloud doesn't enforce an assumption of what Python web server package you are using to serve your applications.
You can use any server on Upsun Cloud by modifying the `web.commands.start` property of your application configuration.
For more information, see how to [configure web servers](/docs/languages/python/server).

## Frameworks

The Upsun documentation includes a wide array of community resources to help with framework-specific configuration:

* [Django](/docs/get-started/stacks/django)
* [Flask](/docs/get-started/stacks/flask)

## Get support

While there are virtually no restrictions to you deploying any kind of application on Upsun Cloud, configuration may still be unclear at this point.

Not to worry! The Upsun community is here to help.
Come and say hello, share your work, ask for help, and peek in on what others are working on.

Welcome to the Upsun community!

<CommunityButtons />


# Create a project
Source: https://developer.upsun.com/docs/get-started/here/create-project

All you need to know about creating a new project with Upsun Cloud

To create a new project on Upsun Cloud, you can take one of two paths:

<AccordionGroup>
  <Accordion title="Using the Console (recommended)">
    Open the [Upsun Cloud management Console](https://console.upsun.com/-/create-project) to create your project.

    <Note>
      If you haven't done so already, you are prompted to create your first organization where your project will reside.
    </Note>

    <img alt="Create project options" />

    From the Console, what you do next entirely depends on where the "source of truth" of your codebase is located.
    In this guide, you will push your local repository to Upsun Cloud.
    That is, the only copy of your codebase you'd like to deploy is on your local computer.

    Click **Start from scratch** from the **Deploy with Git** option.

    <Info>
      <h4>Git integrations</h4>
      This guide does not specifically address integrating an Upsun Cloud project with a third party repository such as one on GitHub, even though the **Connect repository** option is available at this stage.

      For now, continue to work locally.
      Third party integrations will be addressed at the end of this guide.
    </Info>

    Add details about your project, such as:

    * The name of your project.
    * The default branch of your local repository.
    * Select the region where you want your project to be hosted.

    As suggested in the Console, connect the local copy of your repository to your project:

    ```bash theme={null}
    upsun project:set-remote <PROJECT_ID>
    ```

    Your local source code is automatically linked to your newly created Upsun Cloud project through the creation of a `.upsun/local/project.yaml` file.  This file contains the corresponding `<projectId>` and sets a Git remote to `upsun`.
  </Accordion>

  <Accordion title="Using the CLI">
    To create a new project with the Upsun Cloud CLI, use the following command and follow the prompts:

    ```bash Terminal theme={null}
    upsun project:create
    ```

    <Info>
      <h4>Default branches</h4>
      When creating a new project using the Upsun Cloud CLI command `project:create`, the default production branch is set to `main`. Change it if your default branch is different (*e.g.*: `master`).
    </Info>

    Then, you are asked if you want to set the local remote to your new project. Enter **Yes (y)**.

    Your local source code is automatically linked to your newly created Upsun Cloud project through the creation of a `.upsun/local/project.yaml` file.  This file contains the corresponding `<projectId>` and sets a Git remote to `upsun`.

    In this guide, you will push your local repository to Upsun Cloud.
    That is, the only copy of your codebase you'd like to deploy is on your local computer.

    <Info>
      <h4>Git integrations</h4>
      This guide does not specifically address integrating an Upsun Cloud project with a third party repository such as one on GitHub, even though you will notice the **Connect repository** option available at this stage.

      For now, continue to work locally.
      Third party integrations will be addressed at the end of this guide.
    </Info>

    So long as you chose `y` (yes) to the question `Set the new project <projectName> as the remote for this repository?` during the `project:create` command, your local project is already integrated to the Upsun Cloud project.
  </Accordion>
</AccordionGroup>


# Getting started with Upsun Cloud
Source: https://developer.upsun.com/docs/get-started/here/index



Welcome to Upsun Cloud!

Follow this guide to set up your very first custom application on Upsun Cloud.
In the process, you will learn more about Upsun Cloud, what it does, and how you can work with it to your best advantage.

<Info>
  <h4>Have you seen the demo?</h4>
  Find out how Upsun Cloud works and gain a better understanding of what it provides. To check the demo out, [create a new project](https://console.upsun.com/projects/create-project) and select **Deploy demo project**.
</Info>

Once you have finished the demo, you'll go through the following steps to accomplish your custom deployment:

<Info>
  Follow the steps listed in the sidebar to complete the guide.
</Info>


# Local development
Source: https://developer.upsun.com/docs/get-started/here/local/index

All you need to know about working locally with an Upsun Cloud project.


A significant amount of work developing your app takes place locally rather than on an active Upsun Cloud environment.
You want to ensure that the process of local development is as close as possible to a deployed environment.

You can achieve this through the following approaches:

* [Tethered local development](/docs/get-started/here/local/tethered)

Each of these approaches:

* Creates a local development environment for your site.
* Syncs data from the active Upsun Cloud environment where team review takes place.
* Commits aspects of that local development method to the project so collaborators can replicate configuration to contribute.


# Tethered
Source: https://developer.upsun.com/docs/get-started/here/local/tethered

Sync your local Upsun Cloud with your remote environment to start contributing.


When you develop a project, a significant amount of work takes place
locally rather than on an active Upsun Cloud environment. You want to ensure
that the process of local development is as close as possible to a deployed
environment.

You can achieve this through various approaches. For example, you can use
Symfony Server with tethered data.

To do so, when testing changes locally, you can connect your locally running
Symfony Server to service containers on an active Upsun Cloud environment.

This methodology has several advantages:

* It avoids installing anything on your local machine but your stack runtime.
* It ensures that you are using the same versions of all services on your local
  machine and in production.

<Warning>
  <h4>Warning</h4>
  Never use this method on the **main** environment as changes made on your local
  machine will impact production data.
</Warning>

## 1. Start your local Server

Use the official path to start your local server locally.

## 2. Create the tethered connection

1. Create a new environment off of production:

   ```bash theme={null}
   upsun branch new-feature main
   ```

2. Open an SSH tunnel to the new environment's services:

   ```bash theme={null}
   upsun tunnel:open
   ```

   This command returns the addresses for SSH tunnels to all of your services that you can then use within your local source code:

   ```bash theme={null}
   upsun tunnel:open
       SSH tunnel opened to rediscache at: redis://127.0.0.1:30000
       SSH tunnel opened to database at: pgsql://main:main@127.0.0.1:30001/main

       Logs are written to: /Users/acmeUser/.upsun/tunnels.log

       List tunnels with: upsun tunnels
       View tunnel details with: upsun tunnel:info
       Close tunnels with: upsun tunnel:close

       Save encoded tunnel details to the PLATFORM_RELATIONSHIPS variable using:
       export PLATFORM_RELATIONSHIPS="$(upsun tunnel:info --encode)"
   ```

3. When you've finished your work,
   close the tunnels to your services by running the following command:

   ```bash theme={null}
   upsun tunnel:close --all -y
   ```


# Make changes to your project
Source: https://developer.upsun.com/docs/get-started/here/make-changes

How to work on a daily basis with an Upsun Cloud project

Upsun Cloud allows you to make changes to your project and test them on a preview environment before introducing them to Production.

In your project, the default branch (e.g. `main`, `master`, whichever chosen during project creation) always represents the production environment.
Other branches are for developing new features, fixing bugs, or updating the infrastructure.

To make changes to your project, follow these steps:

## 1. Create a new environment

Create a new environment (a Git branch) to make changes without impacting production:

Run the following command:

```bash Terminal theme={null}
upsun branch feat-a
```

This creates a new local `feat-a` Git branch based on the `main` Git branch
and activates a related environment on Upsun Cloud.
The new environment inherits the data (service data and assets) of its parent environment (the production environment here).

## 2. Make changes to your project

Depending on the stack you're using, change something within your source code.

## 3. Commit your changes

```bash Terminal theme={null}
git add index.js
git commit -m "Update source code"
```

## 4. Deploy your changes

Deploy your changes to the `feat-a` environment:

```bash Terminal theme={null}
upsun push
```

Note that each environment has its own domain name.
To open the URL of your new environment, run the following command:

```bash Terminal theme={null}
upsun environment:url --primary
```

<Warning>
  <h4>Warnings</h4>
  If your environment is inactive, you need to [activate it](/docs/environments/deactivate-environment#reactivate-an-environment) first, using the following command:

  ```bash Terminal theme={null}
  upsun environment:activate
  ```
</Warning>

## 5. Iterate

Iterate by changing the code, committing, and deploying.
When satisfied with your changes, merge them to the main branch,
and remove the feature branch:

```bash Terminal theme={null}
upsun merge
 Are you sure you want to merge feat-a into its parent, main? [Y/n] y
upsun checkout main
git pull upsun main
upsun environment:delete feat-a
git fetch --prune
```

<Note>
  Deploying after a merge is fast because the image built for the feature environment is reused for the targeted environment.
</Note>

## 6. Keep your branch up to date

For a long running development branch, to keep the code up-to-date with the `main` branch, use `git merge main` or `git rebase main`.
You can also keep the data in sync with the parent environment by using [`upsun env:sync data`](/cli/reference#environmentsynchronize).


# Set resources
Source: https://developer.upsun.com/docs/get-started/here/set-resources

Flexible resources on Upsun Cloud are easy to use. Find all you need to know about resources allocation there.

You can define how much CPU, memory, and disk you want to assign to each of your service and app containers.

If you don't explicitly set resources, Upsun Cloud uses [default resources](/docs/manage-resources/resource-init) instead.
Upsun Cloud also offers several [resource initialization strategies](/docs/manage-resources/resource-init) to help you allocate resources depending on your needs and use cases.

<Note>
  If you are using a [source integration](/docs/integrations/source), resource initialization for new environments is controlled by the `resources-init` option on the integration.
  See [resource initialization with source integrations](/docs/manage-resources/resource-init#environment-branch).
</Note>

However, for the sake of this guide, let's set resources manually.
To do so, follow these steps:

1. Run the following command:

   ```bash Terminal theme={null}
   upsun resources:set
   ```

   This launches an interactive prompt to walk you through setting up your application's resources:

   ```bash Terminal theme={null}
   upsun resources:set
   Resource configuration for the project app (123456azerty), environment main (type: production):
   +-----------------------+---------+---------+-------------+-----------+-----------+
   | App or service        | Size    | CPU     | Memory (MB) | Disk (MB) | Instances |
   +-----------------------+---------+---------+-------------+-----------+-----------+
   | myapp                   | 1       | 1       | 384         | N/A       | 1         |
   | [<additional-service>]| 0.1     | 0.1     | 128         | N/A       | 1         |
   +-----------------------+---------+---------+-------------+-----------+-----------+
   ```

2. Select the profile size you want applied to your application image. For instance, `0.1`:

   ```bash Terminal theme={null}
   App: myapp
   Choose a profile size:
      [0.1 ] CPU 0.1, memory 64 MB
      [0.25] CPU 0.25, memory 128 MB
      [0.5 ] CPU 0.5, memory 224 MB
      [1   ] CPU 1, memory 384 MB
      [2   ] CPU 2, memory 704 MB
      [4   ] CPU 4, memory 1216 MB
      [6   ] CPU 6, memory 1728 MB
      [8   ] CPU 8, memory 2240 MB
      [10  ] CPU 10, memory 2688 MB
     > 0.1
   ```

3. Define how many [instances](/docs/manage-resources/adjust-resources#horizontal-scaling) of your application container you want to deploy. For instance, `1`:

   ```bash Terminal theme={null}
   Enter the number of instances (default: 1): 1
   ```

4. To confirm your choices, select `Y`.

   Upsun Cloud grabs the previous built images from earlier, applies your resource selections to them, and deploys your full application!

   <Note>
     If the deployment fails, you may need to set the resources again.
   </Note>


# Setup
Source: https://developer.upsun.com/docs/get-started/here/setup



<Info>
  <h4>Got code?</h4>
  In order to follow along with this guide, you need a local project.
  While the guide has been written to accommodate the following stacks, it is not limited to just those listed and are here only as examples.

  <AccordionGroup>
    <Accordion title="JavaScript/Node.js">
      * [Express installation guide](https://expressjs.com/en/starter/installing.html)
      * [Next.js installation guide](https://nextjs.org/docs/getting-started/installation)
      * [Strapi installation guide](https://docs.strapi.io/dev-docs/installation)
    </Accordion>

    <Accordion title="PHP">
      * [Laravel installation guide](https://laravel.com/docs/10.x#creating-a-laravel-project)
      * [Symfony installation guide](/docs/get-started/stacks/symfony)
    </Accordion>

    <Accordion title="Python">
      * [Flask installation guide](https://flask.palletsprojects.com/en/2.3.x/installation)
      * [Django installation guide](https://docs.djangoproject.com/en/5.0/intro/tutorial01/)
    </Accordion>
  </AccordionGroup>
</Info>

<GuidesRequirements />

<Info>
  <h4>Trials</h4>
  When you create your first organization on Upsun Cloud, you are also activating your trial for that organization.
  Get [more information on trials](/docs/glossary#trial).
</Info>

## Initialize your Git repository

A Git repository is required for Upsun Cloud projects.
If you haven't already done so, initialize a Git repository for your codebase, and commit your files:

```bash Terminal theme={null}
git init
git add .
git commit -m "Initial commit."
```

This guide assumes that your repository's default branch is `main`.
Your Git configuration may result in different default branches (like `master`), so please run `git branch -M main` before proceeding.

<Info>
  <h4>Don't commit dependencies</h4>
  Whether you're migrating your own project, or testing Upsun Cloud with a starter project, **never commit your app's dependencies**.
  Make sure you ignore directories containing dependencies by updating your `.gitignore` file.

  ```bash theme={null}
  # JavaScript/Node.js
  echo "node_modules" >> .gitignore

  # PHP
  echo "vendor" >> .gitignore

  # Python
  echo "env" >> .gitignore

  git add .gitignore && git commit -m "Update .gitignore to ignore deps."
  ```
</Info>


# Get support
Source: https://developer.upsun.com/docs/get-started/here/support

Find out how to get help if you're experiencing issues with Upsun Cloud.


## Create a support ticket

Open a support ticket to report infrastructure, application container, or build issues, flag a possible bug, ask a general question, or submit a feature request:

1. [Open the Console](https://console.upsun.com/).
2. In the upper right corner, click **Help**, then select **Support**.
3. On the Upsun Help Center landing page, click **Create a new request**.
4. Complete and submit the form on the "Submit a request" page.

**Shortcuts**

* [Open a new ticket](https://support.upsun.com/hc/en-us/requests/new?ticket_form_id=35294051960082)
* [Submit a feature request](https://support.upsun.com/hc/en-us/requests/new?ticket_form_id=37982573191442)
* [View your tickets](https://support.upsun.com/hc/en-us/requests)

<Tip>
  You can't modify or delete a ticket after submitting it. To add more information, go to [your tickets](https://support.upsun.com/hc/en-us/requests) and add a message to the relevant one.
</Tip>

<Info>
  <h4>Upgrade to the Organization Support add-on</h4>
  The Upsun Cloud Organization Support add-on provides tiered support options tailored to organizational needs. All organizations are automatically enrolled in the Standard support tier.

  To upgrade to either the Premium or Advanced support tier, visit the [add-on subscriptions page](/docs/administration/billing/add-on-subscription#organization-support-add-on).
</Info>

## Community

To talk about app development or framework-related questions,
join other customers and engineers in the [Community Forum](https://community.upsun.com/).

<CommunityButtons />

## Contact Sales

If you have questions about pricing or need help figuring out if Upsun Cloud is the right solution for your team,
get in touch with [Sales](https://upsun.com/contact-us/).

## Delete your account

To permanently delete your Upsun account, follow these steps:

<Danger>
  Deleting your Upsun account automatically deletes all your linked Ibexa Cloud, Pimcore PaaS, and Shopware PaaS accounts.
</Danger>

1. [Open the Console](https://console.upsun.com/).
2. Open the user menu (your name or profile picture) and select **My Profile**.
3. Click **Delete account**.
4. Check that the pre-filled information is correct and click **Submit**.<br />
   Your request is now submitted and will be handled by Support shortly.


# Third party integrations
Source: https://developer.upsun.com/docs/get-started/here/third-party



In this guide, you've configured and deployed a local copy of your codebase to Upsun Cloud.
You can continue to work, but the primary remote your team would share would be Upsun Cloud itself.

It's more likely that your codebase is on a third party Git service like GitHub, GitLab, or Bitbucket.

Now that you've learned the basics of Upsun Cloud configuration and deployment, you can create new projects within the management Console, by choosing the **Connect repository** option to set up a GitHub application.

At this stage, if you want to make another remote (i.e. `origin`) the primary remote, and Upsun Cloud a deployment mirror, you can override your current configuration by setting up an integration:

* [BitBucket](/docs/integrations/source/bitbucket)
* [GitHub](/docs/integrations/source/github)
* [GitLab](/docs/integrations/source/gitlab)

Once the integration is added, all commits on the service are mirrored, built, and deployed on Upsun Cloud.


# Get Started with Upsun Cloud
Source: https://developer.upsun.com/docs/get-started/index

Deploy your first project in minutes.

Upsun Cloud is a cloud hosting platform that builds, deploys, and scales your applications automatically. This guide walks you through deploying your first project—from installing the CLI to seeing your app live in production. The entire process takes about 10-15 minutes.

## Before you begin

You need:

* An Upsun account ([sign up for free](https://console.upsun.com/))
* A supported runtime (Node.js, PHP, Python, Go, Java, Ruby, or .NET)
* Git installed locally
* Basic command-line familiarity

## Choose your path

Pick the situation that matches yours and we'll take you straight to the right guide.

<CardGroup>
  <Card title="Start from zero" icon="layers" href="/docs/get-started/here/setup">
    No project yet? Install the CLI, spin up a new project, and deploy your first app.
  </Card>

  <Card title="Bring your project" icon="folder-open" href="/docs/get-started/here/create-project">
    Got an app? Add one YAML file to your repo, push to Upsun Cloud, and you're live.
  </Card>

  <Card title="Connect your repo" icon="git-branch" href="/docs/get-started/here/third-party">
    Already on GitHub? Link GitHub, GitLab, or Bitbucket. Every PR auto-deploys to a live preview.
  </Card>

  <Card title="Deploy AI & agents" icon="bot" href="/docs/get-started/ai/aiagent">
    Building with AI? Deploy AI agents, LLM-powered apps, or MCP servers.
  </Card>
</CardGroup>

## Get started quickly

The steps below follow the **"Start from zero"** path—creating a new project from scratch and deploying it to Upsun Cloud. If you already have an existing application or want to connect a Git repository, choose the appropriate card above instead.

Follow these steps to go from zero to a live Upsun Cloud deployment as fast as possible.

<Steps>
  <Step title="Install the Upsun Cloud CLI">
    Install the CLI for your operating system.

    <Tabs>
      <Tab title="macOS">
        ```bash theme={null}
        brew install upsun/tap/upsun-cli
        ```
      </Tab>

      <Tab title="Linux / WSL">
        ```bash theme={null}
        curl -fsSL https://raw.githubusercontent.com/upsun/cli/main/installer.sh | bash
        ```
      </Tab>

      <Tab title="Windows">
        ```bash theme={null}
        scoop bucket add upsun https://github.com/upsun/homebrew-tap.git
        scoop install upsun
        ```
      </Tab>
    </Tabs>

    <div>
      Then log in to your Upsun account:

      ```bash theme={null}
      upsun login
      ```
    </div>

    [Full setup guide](/docs/get-started/here/setup) · [CLI reference](/cli)

    <div />
  </Step>

  <Step title="Create your first project">
    Create a new Upsun Cloud project using the Console **(Create project → Start from scratch)** or the CLI:

    ```bash theme={null}
    upsun project:create
    ```

    [Full guide](/docs/get-started/here/create-project) · [Open Console ↗](https://console.upsun.com/projects/create-project)

    <div />
  </Step>

  <Step title="Add your config file">
    Run `upsun init` to generate `.upsun/config.yaml`, which defines your app's runtime, services, and routes.

    If your project uses services (such as a database or caching service), `upsun init` also generates an executable `.environment` script. See the full guide below for details.

    <Tabs>
      <Tab title="Node.js">
        ```yaml .upsun/config.yaml theme={null}
        applications:
          myapp:
            type: 'nodejs:22'
            hooks:
              build: 'npm install && npm run build'

        services:
          db:
            type: 'postgresql:16'

        routes:
          'https://{default}/':
            type: upstream
            upstream: 'myapp:http'
        ```
      </Tab>

      <Tab title="PHP">
        ```yaml .upsun/config.yaml theme={null}
        applications:
          myapp:
            type: 'php:8.3'
            hooks:
              build: 'composer install'

        services:
          db:
            type: 'mariadb:11.4'

        routes:
          'https://{default}/':
            type: upstream
            upstream: 'myapp:http'
        ```
      </Tab>

      <Tab title="Python">
        ```yaml .upsun/config.yaml theme={null}
        applications:
          myapp:
            type: 'python:3.12'
            hooks:
              build: 'pip install -r requirements.txt'

        services:
          db:
            type: 'postgresql:16'

        routes:
          'https://{default}/':
            type: upstream
            upstream: 'myapp:http'
        ```
      </Tab>
    </Tabs>

    [Full guide](/docs/get-started/here/configure) · [Node.js](/docs/get-started/here/configure/nodejs) · [PHP](/docs/get-started/here/configure/php) · [Python](/docs/get-started/here/configure/python)

    <div />
  </Step>

  <Step title="Set CPU, RAM & disk">
    Configure resources for your app with `upsun resources:set`:

    ```bash theme={null}
    upsun resources:set --size myapp:1
    ```

    [Full guide](/docs/get-started/here/set-resources) · [Resource docs](/docs/manage-resources/adjust-resources)

    <div />
  </Step>

  <Step title="Push and go live">
    Commit your configuration and push to deploy:

    ```bash theme={null}
    git add .upsun/config.yaml
    git commit -m "Add Upsun Cloud configuration"
    upsun push
    ```

    [Full guide](/docs/get-started/here/make-changes)

    <div />
  </Step>

  <Step title="Develop locally">
    Open a tunnel to connect your local environment to live Upsun Cloud services:

    ```bash theme={null}
    upsun tunnel:open
    npm run dev
    ```

    [Full guide](/docs/get-started/here/local) · [Tethered setup](/docs/development/local/tethered)

    <div />
  </Step>

  <Step title="Connect your Git provider (optional)">
    **Optional:** Link [GitHub](/docs/integrations/source/github), [GitLab](/docs/integrations/source/gitlab), or [Bitbucket](/docs/integrations/source/bitbucket) to mirror, build, and auto-deploy on every push:

    ```bash theme={null}
    upsun integration:add --type github --repository myorg/myapp
    ```

    This step is optional—you can continue using `upsun push` directly. Source integrations are recommended for team workflows and CI/CD automation.

    [Full guide](/docs/get-started/here/third-party)

    <div />
  </Step>
</Steps>

## What's next

Now that you have a live deployment, explore these key topics to make the most of Upsun Cloud:

<CardGroup>
  <Card title="Manage environments" icon="git-branch" href="/docs/environments">
    Create branches, preview environments, and manage your development workflow.
  </Card>

  <Card title="Scale resources" icon="gauge" href="/docs/manage-resources">
    Adjust CPU, RAM, and disk allocation to match your application's needs.
  </Card>

  <Card title="Add a custom domain" icon="globe" href="/docs/domains">
    Configure your production domain and SSL certificates.
  </Card>

  <Card title="Monitor & debug" icon="chart-line" href="/docs/observability">
    View logs, metrics, and application performance data.
  </Card>
</CardGroup>


# Deploy Django on Upsun Cloud
Source: https://developer.upsun.com/docs/get-started/stacks/django

A step-by-step guide to deploy a Django application on Upsun Cloud, from a blank project to a live URL.


This guide walks you through deploying a Django application on Upsun Cloud step by step — from a blank project to a live URL.

If you have read the [Getting started guide](/docs/get-started/here), this page adds Django-specific detail that the generic guide skips.
If you haven't, no problem — this guide is self-contained.

<GuidesRequirements name="Django" />

You also need **Python 3.9+** and `pip` installed locally.

## 1. Create a Django project

Create a directory, activate a virtual environment, and install Django:

```bash theme={null}
mkdir djangotutorial && cd djangotutorial
python -m venv venv
source venv/bin/activate
pip install Django
```

<Info>
  <h4>Windows</h4>
  Replace `source venv/bin/activate` with `venv\Scripts\activate`.
</Info>

Scaffold the project. The trailing `.` places all files directly in the current directory and avoids a nested folder:

```bash theme={null}
django-admin startproject mysite .
```

Your directory now looks like this:

```
djangotutorial/
├── manage.py
└── mysite/
    ├── __init__.py
    ├── asgi.py
    ├── settings.py
    ├── urls.py
    └── wsgi.py
```

Initialize a Git repository and make your first commit:

```bash theme={null}
git init && git branch -M main
git add .
git commit -m "Initial Django project"
```

## 2. Add production dependencies

Upsun Cloud runs your Django app using [Gunicorn](https://gunicorn.org), a production-grade WSGI server.
You also need a database adapter that matches your chosen database.

<Tabs>
  <Tab title="MariaDB">
    ```bash theme={null}
    pip install gunicorn mysqlclient
    ```
  </Tab>

  <Tab title="PostgreSQL">
    ```bash theme={null}
    pip install gunicorn psycopg2-binary
    ```
  </Tab>
</Tabs>

Save the dependency list so Upsun Cloud can install it at build time:

```bash theme={null}
pip freeze > requirements.txt
git add requirements.txt
git commit -m "Add production dependencies"
```

## 3. Set environment variables

Create a `.environment` file at the root of your project.
Upsun Cloud sources this file automatically before starting your app, on every environment (production, preview branches, etc.).

```bash .environment theme={null}
export DJANGO_SETTINGS_MODULE="mysite.settings"
export DJANGO_SECRET_KEY="$PLATFORM_PROJECT_ENTROPY"
export DJANGO_ALLOWED_HOSTS="$(echo "$PLATFORM_ROUTES" | base64 --decode | jq -r 'to_entries[] | select(.value.primary == true) | .key' | sed 's:/*$::' | sed 's|https\?://||')"
```

What each variable does:

* **`DJANGO_SETTINGS_MODULE`** — tells Django which settings file to load.
* **`DJANGO_SECRET_KEY`** — uses `PLATFORM_PROJECT_ENTROPY`, a unique value Upsun Cloud generates per project. The key is never stored in your repository.
* **`DJANGO_ALLOWED_HOSTS`** — dynamically extracts the hostname of the current environment from your project routes, so every preview branch and production environment works automatically.

<Warning>
  <h4>Commit .environment to Git</h4>
  This file contains no secrets — the values are resolved at runtime from Upsun Cloud variables.
  It must be committed so Upsun Cloud can source it on every deploy.
</Warning>

```bash theme={null}
git add .environment
git commit -m "Add Upsun Cloud environment variables"
```

## 4. Update `settings.py`

Open `mysite/settings.py` and make three changes.

**Add `import os`** at the top of the file, after `from pathlib import Path`:

```python mysite/settings.py theme={null}
import os
```

**Replace the `ALLOWED_HOSTS` line.** The default `[]` rejects all requests when `DEBUG = False`.
Use the environment variable set in the previous step:

```python mysite/settings.py theme={null}
ALLOWED_HOSTS = os.getenv('DJANGO_ALLOWED_HOSTS', 'localhost').split(',')
```

**Add the Upsun Cloud production block** at the very bottom of the file.
It only activates when `PLATFORM_APPLICATION_NAME` is present — a variable Upsun Cloud injects automatically at runtime.
Your local development settings are untouched.

<Tabs>
  <Tab title="MariaDB">
    ```python mysite/settings.py theme={null}
    # Upsun Cloud production settings
    if os.getenv('PLATFORM_APPLICATION_NAME') is not None:
        DEBUG = False

        if os.getenv('PLATFORM_APP_DIR') is not None:
            STATIC_ROOT = os.path.join(os.getenv('PLATFORM_APP_DIR'), 'static')

        if os.getenv('PLATFORM_PROJECT_ENTROPY') is not None:
            SECRET_KEY = os.getenv('PLATFORM_PROJECT_ENTROPY')

        if os.getenv('PLATFORM_ENVIRONMENT') is not None:
            DATABASES = {
                'default': {
                    'ENGINE': 'django.db.backends.mysql',
                    'NAME': os.getenv('DATABASE_PATH'),
                    'USER': os.getenv('DATABASE_USERNAME'),
                    'PASSWORD': os.getenv('DATABASE_PASSWORD'),
                    'HOST': os.getenv('DATABASE_HOST'),
                    'PORT': os.getenv('DATABASE_PORT'),
                }
            }
    ```
  </Tab>

  <Tab title="PostgreSQL">
    ```python mysite/settings.py theme={null}
    # Upsun Cloud production settings
    if os.getenv('PLATFORM_APPLICATION_NAME') is not None:
        DEBUG = False

        if os.getenv('PLATFORM_APP_DIR') is not None:
            STATIC_ROOT = os.path.join(os.getenv('PLATFORM_APP_DIR'), 'static')

        if os.getenv('PLATFORM_PROJECT_ENTROPY') is not None:
            SECRET_KEY = os.getenv('PLATFORM_PROJECT_ENTROPY')

        if os.getenv('PLATFORM_ENVIRONMENT') is not None:
            DATABASES = {
                'default': {
                    'ENGINE': 'django.db.backends.postgresql',
                    'NAME': os.getenv('DATABASE_PATH'),
                    'USER': os.getenv('DATABASE_USERNAME'),
                    'PASSWORD': os.getenv('DATABASE_PASSWORD'),
                    'HOST': os.getenv('DATABASE_HOST'),
                    'PORT': os.getenv('DATABASE_PORT'),
                }
            }
    ```
  </Tab>
</Tabs>

The `DATABASE_*` environment variables are exposed automatically by the relationship you define in the next step.

```bash theme={null}
git add mysite/settings.py
git commit -m "Add Upsun Cloud production settings"
```

## 5. Create your Upsun Cloud project

If you don't have an Upsun Cloud project yet, create one with the CLI:

```bash theme={null}
upsun project:create
```

The CLI asks for a project name and region, then automatically links your local repository to the new project.

<Info>
  <h4>Already have a project?</h4>
  If you created a project from the [Upsun Cloud Console](https://console.upsun.com), link your local repository to it:

  ```bash theme={null}
  upsun project:set-remote <PROJECT_ID>
  ```

  Find your project ID in the Console or by running `upsun project:list`.
</Info>

## 6. Configure Upsun Cloud

Create a `.upsun/` directory at the root of your project, then add a `config.yaml` file inside it.
This single file defines your application container, database service, and routing.

Key points:

* **`build: flavor: none`** — disables default build behaviors so only your `hooks.build` commands run.
* **`relationships`** — exposes `DATABASE_*` environment variables to your app (used by `settings.py`).
* **`hooks.build`** — installs Python dependencies during the build phase (no database access yet).
* **`hooks.deploy`** — runs `collectstatic` and migrations at deploy time (database is available).
* **`mounts`** — declares `static/` as a persistent writable directory for collected static files.
* **`web.commands.start`** — starts Gunicorn over a Unix socket (`$SOCKET`), which Upsun Cloud manages automatically.

```bash theme={null}
git add .upsun/
git commit -m "Add Upsun Cloud configuration"
```

## 7. Deploy

Push everything to Upsun Cloud:

```bash theme={null}
upsun push
```

The first deploy installs dependencies, collects static files, and runs database migrations.
It takes a minute or two. Subsequent deploys are faster.

Open your app once the deploy completes:

```bash theme={null}
upsun url --primary
```

## Troubleshooting

**400 Bad Request on every page**

`ALLOWED_HOSTS` is rejecting the request. Check two things:

1. `mysite/settings.py` has `ALLOWED_HOSTS = os.getenv('DJANGO_ALLOWED_HOSTS', 'localhost').split(',')` at the **top level** — not inside the `if` block.
2. `.environment` is committed to Git.

**Build fails — `mysqlclient` or `psycopg2` not found**

`requirements.txt` is missing the database adapter. Run:

```bash theme={null}
pip install gunicorn mysqlclient   # or psycopg2-binary
pip freeze > requirements.txt
git add requirements.txt && git commit -m "Fix missing DB adapter"
upsun push
```

**`gunicorn: command not found` in deploy logs**

Same cause — `gunicorn` is missing from `requirements.txt`. Apply the same fix above.

**Static files return 404**

Check that `STATIC_ROOT` in `settings.py` uses `os.path.join(os.getenv('PLATFORM_APP_DIR'), 'static')` and that the mount key in `.upsun/config.yaml` is also `static`. They must match exactly.

## Further resources

### Documentation

* [Python documentation](/docs/languages/python)
* [Managing Python dependencies](/docs/languages/python/dependencies)
* [Configuring web servers](/docs/languages/python/server)
* [Getting started guide](/docs/get-started/here)

### Blogs

* [*Up(sun) and running with Django*](https://upsun.com/blog/setting-up-django-on-upsun/)


# Add a database to Express
Source: https://developer.upsun.com/docs/get-started/stacks/express/add-database

Once your Express app has been deployed on Upsun Cloud, you might want to add a service to it.


Upsun Cloud projects already include a [variety of managed services](/docs/add-services#available-services), so you don’t have to subscribe to an external cache or search-engine services.

As these services are included in your project, you can manage them through Git.
They’re backed up along with the rest of your project.
You can add new services and manage existing service configurations from your `.upsun/config.yaml` file.

For example, to add a [MariaDB database engine](/docs/add-services/mysql) to your Express project, complete the following steps:

## 1. Create a new branch for testing

To create a new branch, run the following command:

```bash Terminal theme={null}
upsun environment:branch add-mysql-database
```

## 2. Add a MariaDB service

Configure the MariaDB service by adding a `database` service to your `.upsun/config.yaml` file:

To connect the service to your application (`APP_NAME`), add the following relationship:

Commit your change:

```bash Terminal theme={null}
git commit -am "adding MariaDb database service"
upsun push
```

Upsun Cloud now reads your configuration files and deploys your project using [default container resources](/docs/manage-resources/resource-init).
If you don't want to use those default resources,
define your own [resource initialization strategy](/docs/manage-resources/resource-init#specify-a-resource-initialization-strategy),
or [amend those default container resources](/docs/manage-resources/adjust-resources) after your project is deployed.

## 3. Connect to the service

To configure your Express app so it uses your new database,
you need a Node.s module named `mysql2`.
To install it, run the following command:

```bash Terminal theme={null}
npm install mysql2
```

Wherever your application code attemps to connect to the database service,
Upsun Cloud will automatically generate environment variables containing connection credentials as a function of the relationship name.

In this example, the MariaDB service access is granted to the application container via the relationship `database`.
Upsun Cloud will therefore generate the variable `DATABASE_HOST` (among many others), using this name.

Here's an example of how this credential variable naming convention is used to connect to a MariaDB service:

```javascript index.js theme={null}
const express = require('express')
const app = express()
const mysql = require("mysql2/promise");
const port = (process.env.PORT || '3000');

function openConnection() {
  return mysql.createConnection({
    host: process.env.DATABASE_HOST,
    port: process.env.DATABASE_PORT,
    user: process.env.DATABASE_USERNAME,
    password: process.env.DATABASE_PASSWORD,
    database: process.env.DATABASE_DATABASE
  });
}

function createTable(connection) {
  return connection.execute(
    `CREATE TABLE IF NOT EXISTS upsuninfo (
      uid INT(10) NOT NULL AUTO_INCREMENT,
      username VARCHAR(64) NULL DEFAULT NULL,
      departname VARCHAR(128) NULL DEFAULT NULL,
      created DATE NULL DEFAULT NULL,
      PRIMARY KEY (uid)
    ) DEFAULT CHARSET=utf8 COLLATE=utf8_unicode_ci;`
  );
}

function insertData(connection) {
  return connection.execute(
    "INSERT INTO upsuninfo (username, departname, created) VALUES ('upsun', 'Deploy Friday', '2026-09-29')"
  );
}

function readData(connection) {
  return connection.query("SELECT * FROM upsuninfo");
}

function dropTable(connection) {
  return connection.execute("DROP TABLE upsuninfo");
}

// Define the main route.
app.get('/', async function(req, res){

  // Connect to MariaDB.
  const connection = await openConnection();

  await createTable(connection);
  await insertData(connection);

  const [rows] = await readData(connection);

  const droppedResult = await dropTable(connection);

  // Make the output.
  const outputString = `Hello, World! - A simple Express web framework template for Upsun Cloud

MariaDB Tests:

* Connect and add row:
  - Row ID (1): ${rows[0].uid}
  - Username (upsun): ${rows[0].username}
  - Department (Deploy Friday): ${rows[0].departname}
  - Created (2026-09-29): ${rows[0].created}
* Delete row:
  - Status (0): ${droppedResult[0].warningStatus}`;

  res.set('Content-Type', 'text/plain');
  res.send(outputString);
});

// Get PORT and start the server
app.listen(port, function() {
  console.log(`Listening on port ${port}`)
});
```

Commit and deploy your changes:

```bash Terminal theme={null}
git add package.json package-lock.json index.js && git commit -m "adding MariaDb database service"
upsun push
upsun environment:url --primary
```

## 4. Merge to production

When satisfied with your changes, merge them to the main branch:

```bash Terminal theme={null}
upsun merge
```

<Note>
  You can [adjust your project resources](/docs/manage-resources/adjust-resources) at any time.
</Note>

## 5. Remove the feature branch

Then, remove the feature branch:

```bash Terminal theme={null}
upsun checkout main
git pull upsun main
upsun environment:delete add-mysql-database
git fetch --prune
```

<Note>
  When the `environment:delete` CLI command is run, the CLI suggests you deactivate and delete your `add-mysql-database` environment.
  Make sure you opt in.
</Note>

## Tips and Tricks

You can get your project's relationship information using the following command:


# Deploy Express on Upsun Cloud
Source: https://developer.upsun.com/docs/get-started/stacks/express/index

Complete the last required steps to successfully deploy Express on Upsun Cloud.


<Info>
  <h4>Note</h4>
  Before you start, check out the [Upsun Cloud demo app](https://console.upsun.com/projects/create-project) and the main [Getting started guide](/docs/get-started/here).
  They provide all of the core concepts and common commands you need to know before using the materials below.
</Info>

<GuidesRequirements name="Express" />

## 1. Create an Express app

To create your Express app, follow these steps.

1. Follow the Express [installation guide](https://expressjs.com/en/starter/installing.html).
   To fast track the process, run the following commands:

   ```bash Terminal theme={null}
   mkdir my-express-app && cd my-express-app
   npx express-generator
   ```

2. To initialize the local Git repository and commit local files, run the following commands:

   ```bash Terminal theme={null}
   git init
   echo "node_modules" >> .gitignore
   git add .
   git commit -m "Init Express application."
   ```

<Info>
  You can view your running app locally by installing dependencies (`npm install`) and running `npm run dev`.
  The local server is visible at `localhost:3000`.
</Info>

## 2. Create a new project

To create a project on Upsun Cloud,
follow these steps.

<Note>
  <h4>Remember</h4>
  After creating your Upsun Cloud project, copy your new **project ID** for later use.
</Note>

<Tabs>
  <Tab title="Using the CLI">
    To create a new project with the Upsun Cloud CLI, use the following command and follow the prompts:

    ```bash Terminal theme={null}
    upsun project:create
    ```

    <Note>
      When creating a new project using the Upsun Cloud CLI command `project:create`,
      you are asked if you want to set the local remote to your new project. Enter **Yes (y)**.

      Your local source code is automatically linked to your newly created Upsun Cloud project
      through the creation of a `.upsun/local/project.yaml`.
      This file contains the corresponding `<projectId>` for the Upsun Cloud CLI to use,
      and sets a Git remote to `upsun`.
    </Note>
  </Tab>

  <Tab title="Using the Console">
    1. Create an organization or select an existing one.

    2. Click **Create from scratch**.

    3. Fill in details like the project name and [region](/docs/development/regions).

       <Note>
         You can define resources for your project later on, after your first push.
       </Note>

    4. To link your local source code to your new Upsun Cloud project,
       run the following command:

       ```bash Terminal theme={null}
       upsun project:set-remote <projectId>
       ```

       This command adds a new remote called `upsun` to your local Git repository,
       which is equivalent to the following commands:

       ```bash Terminal theme={null}
       git remote
       origin
       upsun
       ```

       It also creates a new `.upsun/local/project.yaml` file that contains the `<projectId>`
       for the `upsun` CLI to use.

       <Tip>
         If you forget your `<projectId>`, run the following command and find your project in the list:

         ```bash Terminal theme={null}
         upsun project:list
         ```
       </Tip>
  </Tab>
</Tabs>

## 3. Choose your Git workflow

You can use Upsun Cloud projects as a classic Git repository,
where you are able to push your source code in different ways,
using either the Git CLI or the Upsun Cloud CLI.
You can choose which way —or Git workflow— you want to use for your project from the following options:

* Your project source code is **hosted on an Upsun Cloud Git repository**
* Your project source code is **hosted on your own GitHub repository**

<Tabs>
  <Tab title="Upsun Cloud Git repository">
    For the rest of this guide, you will use the normal Git workflow (`git add . && git commit -m "message" && git push upsun`) to commit your source code changes to Git history.
    You will also use the Upsun Cloud CLI to deploy your [Upsun Cloud environment](/docs/environments) with the latest code updates.
  </Tab>

  <Tab title="GitHub repository">
    Upsun Cloud provides a [Github integration](/docs/integrations/source/github) that allows your Upsun Cloud project to be fully integrated with your Github repository.
    This enables you, as a developer, to use a normal Git workflow (`git add . && git commit -m "message" && git push`) to deploy your environment—with no need to connect to the Upsun Cloud Console.

    <Note>
      Make sure you complete the following steps before adding a [Github integration](/docs/integrations/source/github):

      1. Create a Git repository in your own organization following the relevant [Github repository creation guide](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-new-repository).
      2. Create a [Github integration](/docs/integrations/source/github).
      3. Add a Git remote to your local project, from the root of your Express directory.<br />
         To do so, run the following commands:

         ```bash Terminal theme={null}
         git remote add origin <urlOfYourOwnGitHubRepo>
         git add . && git commit -m "init express"
         git push origin
         ```
    </Note>
  </Tab>
</Tabs>

## 4. Configure your project

To host your Express application on Upsun Cloud,
you need to have a few YAML configuration files at the root of your project.
These files manage your app's behavior.
They are located in a `.upsun/` folder at the root of your source code
and structured in a similar way to this:

```text Example file structure theme={null}
my-express-app
├── .upsun
│   └── config.yaml
├── [.environment]
└── <project sources>
```

To generate these files, run the following command at the root of your project:

```{location="Terminal"} theme={null}
upsun project:init
```

Follow the prompts.

To commit your new files, run the following commands:

```bash Terminal theme={null}
git add .
git commit -m "Add Upsun Cloud config files"
```

## 5. Deploy

And just like that, it’s time to deploy!

Depending on the Git workflow you chose at the beginning of this tutorial,
there are two ways to deploy your source code changes.

<Tabs>
  <Tab title="Using Upsun Cloud Git repository">
    You can push your code using the normal Git workflow (`git add . && git commit -m "message" && git push`). This pushes your source code changes to your `upsun` remote repository. Alternatively, you can use the following Upsun Cloud CLI command:

    ```bash Terminal theme={null}
    upsun push
    ```
  </Tab>

  <Tab title="Using a third-party Git repository">
    When you choose to use a third-party Git hosting service, the Upsun Cloud Git
    repository becomes a read-only mirror of the third-party repository. All your
    changes take place in the third-party repository.

    Add an integration to your existing third-party repository:

    * [BitBucket](/docs/integrations/source/bitbucket)
    * [GitHub](/docs/integrations/source/github)
    * [GitLab](/docs/integrations/source/gitlab)

    If you are using an integration, on each code updates,
    use the normal Git workflow (`git add . && git commit -m "message" && git push`) to push your code to your external repository.
    To do so, run the following command:

    ```bash Terminal theme={null}
    git push origin
    ```

    Your GitHub, GitLab, or Bibucket integration process then automatically deploys changes to your environment.
    If you're pushing a new Git branch, a new environment is created.
  </Tab>
</Tabs>

Upsun Cloud then reads your configuration files,
and deploys your project using [default container resources](/docs/manage-resources/resource-init).
If you don't want to use those default resources,
define your own [resource initialization strategy](/docs/manage-resources/resource-init#specify-a-resource-initialization-strategy),
or [amend those default container resources](/docs/manage-resources/adjust-resources) after your project is deployed.

Et voilà, your Express application is live!

<Info>
  <h4>Tip</h4>
  Each environment has its own domain name.
  To open the URL of your new environment, run the following command:

  ```bash Terminal theme={null}
  upsun environment:url --primary
  ```
</Info>

## 6. Make changes to your project

Now that your project is deployed, you can start making changes to it.
For example, you might want to fix a bug or add a new feature.

In your project, the `main` branch always represents the production environment.
Other branches are for developing new features, fixing bugs, or updating the infrastructure.

To make changes to your project, follow these steps:

1. Create a new environment (a Git branch) to make changes without impacting production:

   ```bash Terminal theme={null}
   upsun branch feat-a
   ```

   This command creates a new local `feat-a` Git branch based on the main Git branch,
   and activates a related environment on Upsun Cloud.
   The new environment inherits the data (service data and assets) of its parent environment (the production environment here).

2. Make changes to your project.
   For example, edit the `views/index.jade` file and make the following changes:

   ```diff {no-copy="true"} theme={null}
   diff --git a/views/index.jade b/views/index.jade
   index 3d63b9a..77aee43 100644
   --- a/views/index.jade
   +++ b/views/index.jade
   @@ -2,4 +2,4 @@ extends layout

    block content
      h1= title
   -  p Welcome to #{title}
   +  p Welcome to #{title} on Upsun Cloud
   ``

   ```

3. Commit your changes:

   ```bash Terminal theme={null}
   git add views/index.jade
   git commit -m "Update index page view."
   ```

4. Deploy your changes to the `feat-a` environment:

   ```bash Terminal theme={null}
   upsun push
   ```

5. Iterate by changing the code, committing, and deploying.
   When satisfied with your changes, merge them to the main branch,
   and remove the feature branch:

   ```bash {location="Terminal", no-copy="true"} theme={null}
   upsun merge
       Are you sure you want to merge feat-a into its parent, main? [Y/n] y
   upsun checkout main
   git pull upsun main
   upsun environment:delete feat-a
   git fetch --prune
   ```

   Note that deploying to production is fast because the image built for the `feat-a` environment is reused.

   For a long running branch, to keep the code up-to-date with the main branch, use `git merge main` or `git rebase main`.
   You can also keep the data in sync with the production environment by using `upsun env:sync`.

## Further resources

### Documentation

* [JavaScript/Node.js documentation](/docs/languages/nodejs)
* [Managing dependencies](/docs/languages/nodejs#dependencies)
* [Add a database to Express](/docs/get-started/stacks/express/add-database)

### Community content

* [ExpressJS topics](https://support.platform.sh/hc/en-us/search?utf8=%E2%9C%93\&query=express)
* [Node.js topics](https://support.platform.sh/hc/en-us/search?utf8=%E2%9C%93\&query=node)
* [JavaScript topics](https://support.platform.sh/hc/en-us/search?utf8=%E2%9C%93\&query=js)

### Blogs

* [A quick-start guide on hosting Express on Upsun Cloud](https://upsun.com/blog/setting-up-express-on-upsun/)


# Deploy Flask on Upsun Cloud
Source: https://developer.upsun.com/docs/get-started/stacks/flask

Complete the last required steps to successfully deploy Flask on Upsun Cloud.


<Info>
  <h4>Note</h4>
  Before you start, check out the [Upsun Cloud demo app](https://console.upsun.com/projects/create-project) and the main [Getting started guide](/docs/get-started/here).
  They provide all the core concepts and common commands you need to know before using the materials below.
</Info>

For Flask to successfully deploy and operate, **after completing the [Getting started guide](/docs/get-started/here)**,
you still need to make a few changes to your Upsun Cloud configuration.

<GuidesRequirements name="Django" />

## 1. Leverage environment variables

The CLI generated a `.environment` file during the Getting started guide.
Notice it has already created some environmental variables for you to connect to your database service.

```bash .environment theme={null}
export RELATIONSHIPS_JSON="$(echo "$PLATFORM_RELATIONSHIPS" | base64 --decode)"

# Set database environment variables
export DB_HOST="$(echo $RELATIONSHIPS_JSON | jq -r '.postgresql[0].host')"
export DB_PORT="$(echo $RELATIONSHIPS_JSON | jq -r '.postgresql[0].port')"
export DB_DATABASE="$(echo $RELATIONSHIPS_JSON | jq -r '.postgresql[0].path')"
export DB_USERNAME="$(echo $RELATIONSHIPS_JSON | jq -r '.postgresql[0].username')"
export DB_PASSWORD="$(echo $RELATIONSHIPS_JSON | jq -r '.postgresql[0].password')"
export DB_CONNECTION="$(echo $RELATIONSHIPS_JSON | jq -r '.postgresql[0].scheme')"
export DATABASE_URL="postgresql://${DB_USERNAME}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT}/${DB_DATABASE}"
```

To configure all the environment variables Flask needs to run smoothly, follow these steps.

1. Set the `FLASK_APP` environment variable to specify how to load the app.

   ```bash .environment theme={null}
   export FLASK_APP="autoapp.py"
   ```

   The above example uses the file `autoapp.py` as the main entry.
   Adjust according to your situation.

2. Set the `FLASK_ENV` environment variable to enable behaviors based on the environment type.

   Upsun Cloud provides information about what type of environment the app is running in via the `PLATFORM_ENVIRONMENT_TYPE` environment variable.
   Its values can be `production`, `development`, or `staging`.
   Use this information to set the value for `FLASK_ENV`.

   ```bash .environment theme={null}
   export FLASK_ENV="${PLATFORM_ENVIRONMENT_TYPE}"
   ```

   Several other environmental variables need to change based on the environment type.
   Leverage the information in `PLATFORM_ENVIRONMENT_TYPE` for these other variables too.

3. Set the `FLASK_DEBUG` environment variable to `1` (enabled) if you're not running in production.

   ```bash .environment theme={null}
   if [ "$PLATFORM_ENVIRONMENT_TYPE" = "production" ]; then
     FLASK_DEBUG=0
   else
     FLASK_DEBUG=1
   fi
   export FLASK_DEBUG
   ```

4. Do the same for `LOG_LEVEL`.

   ```bash .environment theme={null}
   if [ "$PLATFORM_ENVIRONMENT_TYPE" = "production" ]; then
     LOG_LEVEL="info"
   else
     LOG_LEVEL="debug"
   fi
   export LOG_LEVEL
   ```

5. Set the `SEND_FILE_MAX_AGE_DEFAULT` to `0` (disabled) if you're not in production, but a higher value if you are.

   ```bash .environment theme={null}
   if [ "$PLATFORM_ENVIRONMENT_TYPE" = "production" ]; then
     SEND_FILE_MAX_AGE_DEFAULT=31556926
   else
     SEND_FILE_MAX_AGE_DEFAULT=0
   fi
   export SEND_FILE_MAX_AGE_DEFAULT
   ```

6. Optional: You may also need to set a `SECRET_KEY` environment variable.
   It's used for securely signing the session cookie and can be used for any other security-related needs by extensions or your app.
   It usually is a long random string.

   Set the `SECRET_KEY` environment variable to leverage the [`PLATFORM_PROJECT_ENTROPY` variable](/docs/development/variables/use-variables#use-provided-variables) provided by Upsun Cloud:

   ```bash .environment theme={null}
   export SECRET_KEY="${PLATFORM_PROJECT_ENTROPY}"
   ```

   Your `.environment` file should now look similar to the following:

   ```bash .environment theme={null}
   # Set database environment variables
   export DB_HOST="$POSTGRESQL_HOST"
   export DB_PORT="$POSTGRESQL_PORT"
   export DB_PATH="$POSTGRESQL_PATH"
   export DB_USERNAME="$POSTGRESQL_USERNAME"
   export DB_PASSWORD="$POSTGRESQL_PASSWORD"
   export DB_SCHEME="postgresql"
   export DATABASE_URL="${DB_SCHEME}://${DB_USERNAME}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT}/${DB_PATH}"

   export FLASK_ENV="${PLATFORM_ENVIRONMENT_TYPE}"
   if [ "$PLATFORM_ENVIRONMENT_TYPE" = "production" ]; then
     FLASK_DEBUG=0
   else
     FLASK_DEBUG=1
    fi
   export FLASK_DEBUG
   if [ "$PLATFORM_ENVIRONMENT_TYPE" = "production" ]; then
     LOG_LEVEL="info"
   else
     LOG_LEVEL="debug"
   fi
   export LOG_LEVEL
   if [ "$PLATFORM_ENVIRONMENT_TYPE" = "production" ]; then
     SEND_FILE_MAX_AGE_DEFAULT=31556926
   else
     SEND_FILE_MAX_AGE_DEFAULT=0
   fi
   export SEND_FILE_MAX_AGE_DEFAULT
   export SECRET_KEY="${PLATFORM_PROJECT_ENTROPY}"
   ```

## 2. Configure static assets

You need to add some writable disk space to hold the static assets that `flask-static-digest` generates and `npm` builds.

To do so, define the `./<APP_NAME>:/static` directory as [a mount](/docs/configure-apps/image-properties/mounts).
In your app configuration, locate the section dedicated to mounts and update it as follows:

Replace `<APP_NAME>:` with the `app_name` you defined when creating your Flask project.

## 3. Install dependencies and builds

Instruct Upsun Cloud to automatically run `npm install` in addition to installing your Python dependencies
when building the application container.

To do so, customize your [build hook](/docs/configure-apps/hooks/hooks-comparison#build-hook).
In your app configuration, locate the section dedicated to it and update it as follows:

The Upsun Cloud CLI automatically added `pip install -r requirements.txt` to your build hook configuration when you
[configured your Upsun Cloud project](/docs/get-started/here/configure).

If you want `pip` to be upgraded first to the latest version, add `pip install --upgrade pip` to the above line.
Then, add `npm install`:

Note that if your project uses a different package manager, Upsun Cloud also supports [several other options](/docs/languages/python/dependencies).

## 4. Configure the deploy phase

Instruct Upsun Cloud to automatically run `npm run build` when building the application container.
To do so, customize your [deploy hook](/docs/configure-apps/hooks/hooks-comparison#deploy-hook).
In your app configuration, locate the section dedicated to it:

Add `npm run build`:

## 5. Configure the web server

[Configure the web server](/docs/configure-apps#configure-whats-served) running in front of your app to define how your app handles dynamic requests.
To do so, in your app configuration, locate the section dedicated to the web server:

To add a basic Flask server, replace the default information added by the Upsun Cloud CLI with `flask run -p $PORT`.
Also, change the `socket_family` value from `unix` to `tcp`:

You can now commit all of the above changes and push to Upsun Cloud.

```bash Terminal theme={null}
git add .
git commit -m "Add changes to complete my Upsun Cloud configuration"
git push
```

Note that if your Flask project requires a different web server,
Upsun Cloud also supports [several other options](/docs/languages/python/server), including Gunicorn, Daphne,
Uvicorn, and Hypercorn.

If you use Pip, make sure you add your chosen web server to your `requirements.txt` file.

## 6. Handle database migrations

### Prepare database migrations

If you have a new Flask project that uses [Flask-migrate](https://flask-migrate.readthedocs.io/en/latest/),
or an existing app but need to set up the initial migrations, you can do so using the database service you created earlier.

To do so, follow these steps.

1. Set up a virtual environment where your project can run:

   ```bash Terminal theme={null}
   python3 -m venv env && source venv/bin/activate
   ```

2. Just like in your build hook, update pip and install the requirements:

   ```bash Terminal theme={null}
   pip install --upgrade pip && pip install -r requirements.txt
   ```

3. Set up a way for your local instance of Flask to communicate with your database service:

   ```bash Terminal theme={null}
   upsun tunnel:open -y
   ```

   This opens an SSH tunnel to all the services for the app.
   You can use this connection to allow your local instance to communicate with live services as if they too were local.<br />
   To do so, you need to configure more environment variables.

4. Reopen your `.environment` file.
   Note the use of the `$PLATFORM_RELATIONSHIPS` environment variable to retrieve information about services and their credentials.<br />
   The tunnel you created gives you access to that same data,
   allowing you to generate a local `PLATFORM_RELATIONSHIPS` environment variable containing the same information.

   Set the following environment variable:

   ```bash .environment theme={null}
   export PLATFORM_RELATIONSHIPS="$(upsun tunnel:info --encode)"
   ```

   Since you now have this environmental variable set locally, you can reuse your `.environment` file for Upsun Cloud to recreate
   many of the other environmental variables you need to run locally.

5. Set the following environment variables as they aren't set via `PLATFORM_RELATIONSHIPS`:

   ```bash .environment theme={null}
   export PLATFORM_ENVIRONMENT_TYPE="production"
   export PORT=8888
   export PLATFORM_PROJECT_ENTROPY="$(openssl rand -base64 32)"
   ```

6. Source your `.environment` file to finish setting up all the environmental variables in your current bash:

   ```bash Terminal theme={null}
   source ./.environment
   ```

   You now have everything you need for Flask-Migrate to be able to connect to the database and generate your migration files.

### Generate database migrations

1. Initiate the migrations directory and prepare for the `migrate` command:

   ```bash Terminal theme={null}
   flask db init
   ```

2. Generate your migrations:

   ```bash Terminal theme={null}
   flask db migrate
   ```

3. Commit your generated migrations:

   ```bash Terminal theme={null}
   git add migrations/* && git commit -m "Adds migrations"
   ```

4. Instruct Upsun Cloud to run the Flask-migrate upgrade command when deploying
   so any migration changes are automatically applied.<br />
   To do so, re-open your `.upsun/config.yaml` file.
   Locate the `deploy` hook where you added `npm run build` previously and update it as follows:

5. Commit all your changes and push to Upsun Cloud.

   ```bash Terminal theme={null}
   git add .
   git commit -m "Add changes to complete my Upsun Cloud configuration"
   git push
   ```

## Further resources

### Documentation

* [Python documentation](/docs/languages/python)
* [Managing dependencies](/docs/languages/python/dependencies)
* [Configuring web servers](/docs/languages/python/server)

### Community content

* [Flask topics](https://support.platform.sh/hc/en-us/search?utf8=%E2%9C%93\&query=flask)
* [Python topics](https://support.platform.sh/hc/en-us/search?utf8=%E2%9C%93\&query=python)

### Blogs

* [Up(sun) and running with Django](https://upsun.com/blog/setting-up-django-on-upsun/)


# How to deploy
Source: https://developer.upsun.com/docs/get-started/stacks/index



Upsun aims to provide sane defaults out-of-the-box, while exposing a high degree of flexibility when you are configuring your projects, environments, and applications.
Because of this, you can deploy most frameworks on Upsun Cloud.
Below are some common examples sorted by programming language.

<Info>
  Before you start, check out the [Upsun Cloud demo app](https://console.upsun.com/projects/create-project) and the main [Getting started guide](/docs/get-started/here/setup).
  They provide all the core concepts and common commands you need to know before using the following materials.
</Info>

Pick your stack and follow a framework-specific guide.

<Tabs>
  <Tab title="All">
    <CardGroup>
      <Card title="Laravel" icon="laravel" href="/docs/get-started/stacks/laravel">PHP</Card>
      <Card title="Symfony" icon="symfony" href="/docs/get-started/stacks/symfony">PHP</Card>
      <Card title="Next.js" icon="react" href="/docs/get-started/stacks/nextjs">JavaScript</Card>
      <Card title="Express" icon="node-js" href="/docs/get-started/stacks/express">JavaScript</Card>
      <Card title="Django" icon="python" href="/docs/get-started/stacks/django">Python</Card>
      <Card title="Strapi" icon={<svg fill="currentColor" role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path d="M8.32 0c-3.922 0-5.882 0-7.1 1.219C0 2.438 0 4.399 0 8.32v7.36c0 3.922 0 5.882 1.219 7.101C2.438 24 4.399 24 8.32 24h7.36c3.922 0 5.882 0 7.101-1.219C24 21.562 24 19.601 24 15.68V8.32c0-3.922 0-5.882-1.219-7.101C21.562 0 19.601 0 15.68 0H8.32zm.41 7.28h7.83a.16.16 0 0 1 .16.16v7.83h-3.87v-3.71a.41.41 0 0 0-.313-.398l-.086-.012h-3.72V7.28zm-.5.25v3.87H4.553a.08.08 0 0 1-.057-.136L8.23 7.529zm.25 4.12h3.87v3.87H8.64a.16.16 0 0 1-.16-.16v-3.71zm4.12 4.12h3.87l-3.734 3.734a.08.08 0 0 1-.136-.057V15.77z"/></svg>} href="/docs/get-started/stacks/strapi">JavaScript</Card>
      <Card title="Flask" icon="beaker" href="/docs/get-started/stacks/flask">Python</Card>
      <Card title="AI Agents" icon="brain" href="/docs/get-started/ai/aiagent">New</Card>
      <Card title="MCP Servers" icon="server" href="/docs/get-started/ai/deploy-mcp">New</Card>
    </CardGroup>

    <Tip>
      Looking for WordPress, Drupal, Magento, Shopware, or Pimcore? Check out the [CMS guides in Tutorials](/tutorials/cms).
    </Tip>
  </Tab>

  <Tab title="PHP">
    <CardGroup>
      <Card title="Laravel" icon="laravel" href="/docs/get-started/stacks/laravel">PHP</Card>
      <Card title="Symfony" icon="symfony" href="/docs/get-started/stacks/symfony">PHP</Card>
    </CardGroup>

    <Tip>
      Looking for WordPress, Drupal, Magento, Shopware, or Pimcore? Check out the [CMS guides in Tutorials](/tutorials/cms).
    </Tip>
  </Tab>

  <Tab title="JavaScript">
    <CardGroup>
      <Card title="Next.js" icon="react" href="/docs/get-started/stacks/nextjs">JavaScript</Card>
      <Card title="Express" icon="node-js" href="/docs/get-started/stacks/express">JavaScript</Card>
      <Card title="Strapi" icon={<svg fill="currentColor" role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path d="M8.32 0c-3.922 0-5.882 0-7.1 1.219C0 2.438 0 4.399 0 8.32v7.36c0 3.922 0 5.882 1.219 7.101C2.438 24 4.399 24 8.32 24h7.36c3.922 0 5.882 0 7.101-1.219C24 21.562 24 19.601 24 15.68V8.32c0-3.922 0-5.882-1.219-7.101C21.562 0 19.601 0 15.68 0H8.32zm.41 7.28h7.83a.16.16 0 0 1 .16.16v7.83h-3.87v-3.71a.41.41 0 0 0-.313-.398l-.086-.012h-3.72V7.28zm-.5.25v3.87H4.553a.08.08 0 0 1-.057-.136L8.23 7.529zm.25 4.12h3.87v3.87H8.64a.16.16 0 0 1-.16-.16v-3.71zm4.12 4.12h3.87l-3.734 3.734a.08.08 0 0 1-.136-.057V15.77z"/></svg>} href="/docs/get-started/stacks/strapi">JavaScript</Card>
    </CardGroup>
  </Tab>

  <Tab title="Python">
    <CardGroup>
      <Card title="Django" icon="python" href="/docs/get-started/stacks/django">Python</Card>
      <Card title="Flask" icon="beaker" href="/docs/get-started/stacks/flask">Python</Card>
    </CardGroup>
  </Tab>

  <Tab title="AI / New">
    <CardGroup>
      <Card title="AI Agents" icon="brain" href="/docs/get-started/ai/aiagent">New</Card>
      <Card title="MCP Servers" icon="server" href="/docs/get-started/ai/deploy-mcp">New</Card>
    </CardGroup>
  </Tab>
</Tabs>

Find out more about the many [languages Upsun Cloud supports](/docs/languages).


# Deploy JavaScript apps on Upsun Cloud
Source: https://developer.upsun.com/docs/get-started/stacks/javascript

Choose a JavaScript framework and follow a step-by-step guide to deploy on Upsun Cloud.


Pick your JavaScript framework and follow a guide to deploy on Upsun Cloud.

<CardGroup>
  <Card title="Next.js" icon="react" href="/docs/get-started/stacks/nextjs">
    React framework.
  </Card>

  <Card title="Express" icon="node-js" href="/docs/get-started/stacks/express">
    Minimal Node.js framework.
  </Card>

  <Card title="Strapi" icon={<svg fill="currentColor" role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path d="M8.32 0c-3.922 0-5.882 0-7.1 1.219C0 2.438 0 4.399 0 8.32v7.36c0 3.922 0 5.882 1.219 7.101C2.438 24 4.399 24 8.32 24h7.36c3.922 0 5.882 0 7.101-1.219C24 21.562 24 19.601 24 15.68V8.32c0-3.922 0-5.882-1.219-7.101C21.562 0 19.601 0 15.68 0H8.32zm.41 7.28h7.83a.16.16 0 0 1 .16.16v7.83h-3.87v-3.71a.41.41 0 0 0-.313-.398l-.086-.012h-3.72V7.28zm-.5.25v3.87H4.553a.08.08 0 0 1-.057-.136L8.23 7.529zm.25 4.12h3.87v3.87H8.64a.16.16 0 0 1-.16-.16v-3.71zm4.12 4.12h3.87l-3.734 3.734a.08.08 0 0 1-.136-.057V15.77z"/></svg>} href="/docs/get-started/stacks/strapi">
    Headless CMS.
  </Card>
</CardGroup>

For more details on configuring Node.js, see the [Node.js documentation](/docs/languages/nodejs).


# Manage continuous observability with Upsun Blackfire
Source: https://developer.upsun.com/docs/get-started/stacks/laravel/blackfire

Set up a continuous observability strategy for your Laravel app with Upsun Blackfire.

[Upsun Blackfire](/docs/observability/application-metrics/blackfire) is the recommended solution
for monitoring and profiling web sites and apps.
Upsun Blackfire works seamlessly with any app built with Laravel.

Upsun Blackfire PHP SDK provides the following [integrations with
Laravel](https://docs.blackfire.io/php/integrations/laravel/index):

* [Laravel Artisan](https://docs.blackfire.io/php/integrations/laravel/artisan)
* [Laravel Horizon and queue services](https://docs.blackfire.io/php/integrations/laravel/horizon)
* [Laravel Tests](https://docs.blackfire.io/php/integrations/laravel/tests)
* [Laravel Octane](https://docs.blackfire.io/php/integrations/laravel/octane)

Please refer to the [Upsun Blackfire documentation](https://docs.blackfire.io/testing-cookbooks/tests#the-code-blackfire-yaml-code-file) to set up a `.blackfire.yml` configuration to enable custom [performance tests](https://docs.blackfire.io/testing-cookbooks/index)
and automated [builds](https://docs.blackfire.io/builds-cookbooks/index).


# Set up cron jobs
Source: https://developer.upsun.com/docs/get-started/stacks/laravel/crons

Understand how to configure Laravel cron jobs.


Cron jobs allow you to run scheduled tasks at specified times or intervals.

While you can run your own custom tasks, Laravel provides a scheduler to simplify the implementation.
To implement it, see the Laravel [Task Scheduling documentation](https://laravel.com/docs/master/scheduling).

## Set up a cron job

To set up a cron job, update your Upsun Cloud configuration as follows:

```yaml .upsun/config.yaml theme={null}
applications:
  myapp:
    [...]
    crons:
      snapshot:
        spec: * * * * *
        commands:
          start: |
            php artisan schedule:run >> /dev/null 2>&1
```

## Run cron jobs based on environment type

To run a command in a cron hook for specific environment types,
use the `PLATFORM_ENVIRONMENT_TYPE` environment variable:

```yaml .upsun/config.yaml theme={null}
applications:
  myapp:
    [...]
    crons:
      snapshot:
        spec: 0 5 * * *
        commands:
          start: |
            # only run for the production environment, aka main branch
            if [ "$PLATFORM_ENVIRONMENT_TYPE" = "production" ]; then
              php artisan schedule:run >> /dev/null 2>&1
            fi
```

## Run the Laravel scheduler every minute

Cron job execution on the default Upsun Cloud offering are limited to once every 5 minutes.
For more information, see the [documentation on crons](/docs/configure-apps/image-properties/crons).

However, you can add a [worker](/docs/configure-apps/image-properties/workers)
and specify a start command that [runs the scheduler every minute](https://laravel.com/docs/11.x/scheduling#running-the-scheduler-locally).
To do so, use the following configuration:

<Warning>
  <h4>Warning</h4>
  Web and worker containers don't share mount targets.
  You can't share files between those containers using the filesystem.
  To share data between containers, use [services](/docs/add-services).
</Warning>


# Configure environment variables
Source: https://developer.upsun.com/docs/get-started/stacks/laravel/environment-variables

Learn about the environment variables added by the Upsun Cloud CLI.


By default, Upsun Cloud exposes some [environment variables](/docs/development/variables/use-variables#use-provided-variables).

Laravel relies heavily on environment variables to configure application services (such as the database or the mailer).
Therefore, the default configuration generated by `upsun project:init` includes
the [environment variables for all the services](#service-environment-variables) connected to your app in the `.environment` file.

<Info>
  <h4>Tip</h4>
  You can tweak the `.environment` configuration to fit your needs and add specific project-level variables. You may need a variable to change per environment. If so, use the `upsun variable` command to add all the needed per-environment variables.
</Info>

## Default environment variables

Upsun Cloud automatically exposes [environment variables](/docs/development/variables/use-variables#use-provided-variables)
about the app and its infrastructure.

Assuming that MySQL, PostgreSQL, and Redis services have been added to your environment,
and that the app has been granted access to those services via the following [relationships](/docs/configure-apps/image-properties/relationships):

```yaml .upsun/config.yaml theme={null}
applications:
  myapp:
    [...]
    relationships:
      mysql: ...
      postgresql: ...
      redis: ...
```

You can transpose these variables to set up Laravel's default configuration in a `.environment` file:

```bash .environment theme={null}
# Set MySQL database environment variables
export DB_HOST="$MYSQL_HOST"
export DB_PORT="$MYSQL_PORT"
export DB_PATH="$MYSQL_PATH"
export DB_USERNAME="$MYSQL_USERNAME"
export DB_PASSWORD="$MYSQL_PASSWORD"
export DB_SCHEME="$MYSQL_SCHEME"
export DATABASE_URL="${DB_SCHEME}://${DB_USERNAME}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT}/${DB_PATH}"

# Or for PostgreSQL
export DB_HOST="$POSTGRESQL_HOST"
export DB_PORT="$POSTGRESQL_PORT"
export DB_PATH="$POSTGRESQL_PATH"
export DB_USERNAME="$POSTGRESQL_USERNAME"
export DB_PASSWORD="$POSTGRESQL_PASSWORD"
export DB_SCHEME="$POSTGRESQL_SCHEME"
export DATABASE_URL="${DB_SCHEME}://${DB_USERNAME}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT}/${DB_PATH}"

# Set Laravel-specific environment variables
export DB_CONNECTION="$DB_SCHEME"
export DB_DATABASE="$DB_PATH"

# Set Cache environment variables
export CACHE_HOST="$REDIS_HOST"
export CACHE_PORT="$REDIS_PORT"
export CACHE_SCHEME="$REDIS_SCHEME"
export CACHE_URL="${CACHE_SCHEME}://${CACHE_HOST}:${CACHE_PORT}"

# Set Redis environment variables
export REDIS_URL="$CACHE_URL"
```

## Service environment variables

Each exposed environment variable is prefixed by the relationship name.
For example, if you have the following relationships in your configuration:

```yaml .upsun/config.yaml theme={null}
applications:
  myapp:
    relationships:
      database:
        service: "securitydb"
        endpoint: "postgresql"
```

The environment variables for the database service is prefixed by `DATABASE_`,
which is the upper-cased version of the key defined in the relationship.
For example, you could have a `DATABASE_URL` environment variable.

<Warning>
  Environment variables aren't exposed when the build hook script is running,
  as services aren't available during the [build process](/docs/core-concepts/build-deploy#the-build).<br />
  To add specific variables available during the build, run `upsun variable:create`.
</Warning>

### Emails

Upsun Cloud provides a SMTP service for sending emails.
To configure email in Laravel, add the following mapping to your `.environment` file:

```bash .environment theme={null}
# Email
export MAIL_MAILER="smtp"
export MAIL_HOST="${PLATFORM_SMTP_HOST}"
export MAIL_PORT="25"
```

### HTTP

If your project has multiple apps,
the configuration is exposed via the following environment variables
(where `SOME_SERVICE` is the upper-cased version of the key defined in the relationship):

* `SOME_SERVICE_URL`: The full URL of the service
* `SOME_SERVICE_IP`: The HTTP service IP
* `SOME_SERVICE_PORT`: The HTTP service port
* `SOME_SERVICE_SCHEME`: The HTTP service scheme
* `SOME_SERVICE_HOST`: The HTTP service host

### MySQL/MariaDB

The [MySQL/MariaDB](/docs/add-services/mysql) configuration is exposed via the following environment variables
(where `DATABASE` is the upper-cased version of the key defined in the relationship above):

* `DATABASE_URL`: The database URL (in PHP or Go format depending on your app)
* `DATABASE_SERVER`: The database server
* `DATABASE_DRIVER`: The database driver
* `DATABASE_VERSION`: The database version
* `DATABASE_HOST`: The database host
* `DATABASE_PORT`: The database port
* `DATABASE_NAME`: The database name
* `DATABASE_DATABASE`: Alias for `DATABASE_NAME`
* `DATABASE_USERNAME`: The database username
* `DATABASE_PASSWORD`: The database password

<Note>
  <h4>Tip</h4>
  The database version and a default charset are included in the database URL.
  To override them, use the `DATABASE_VERSION` and `DATABASE_CHARSET` environment variables respectively.
</Note>

### PostgreSQL

The [PostgreSQL](/docs/add-services/postgresql) configuration is exposed via the following environment variables
(where `DATABASE` is the upper-cased version of the key defined in the relationship):

* `DATABASE_URL`: The database URL (in PHP or Go format depending on your app)
* `DATABASE_SERVER`: The database server
* `DATABASE_DRIVER`: The database driver
* `DATABASE_VERSION`: The database version
* `DATABASE_HOST`: The database host
* `DATABASE_PORT`: The database port
* `DATABASE_NAME`: The database name
* `DATABASE_DATABASE`: Alias for `DATABASE_NAME`
* `DATABASE_USERNAME`: The database username
* `DATABASE_PASSWORD`: The database password

<Note>
  <h4>Tip</h4>
  The database version and a default charset are included in the database URL.
  To override them, use the `DATABASE_VERSION` and `DATABASE_CHARSET` environment variables respectively.
</Note>

### Redis

The [Redis](/docs/add-services/redis) configuration is exposed via the following environment variables
(where `REDIS` is the upper-cased version of the key defined in the relationship):

* `REDIS_URL`: The Redis URL
* `REDIS_HOST`: The Redis host
* `REDIS_PORT`: The Redis port
* `REDIS_SCHEME`: The Redis scheme

You can specify the Redis client in your `.environment` file:

```bash .environment theme={null}
export REDIS_CLIENT="phpredis"
```

### Memcached

The [Memcached](/docs/add-services/memcached) configuration is exposed via the following environment variables
(where `CACHE` is the upper-cased version of the key defined in the relationship):

* `CACHE_HOST`
* `CACHE_PORT`
* `CACHE_IP`

### Elasticsearch

The [Elasticsearch](/docs/add-services/elasticsearch) configuration is exposed via the following environment variables
(where `ELASTICSEARCH` is the upper-cased version of the key defined in the relationship):

* `ELASTICSEARCH_URL`: The full URL of the Elasticsearch service
* `ELASTICSEARCH_HOST`: The Elasticsearch host
* `ELASTICSEARCH_PORT`: The Elasticsearch port
* `ELASTICSEARCH_SCHEME`: The Elasticsearch protocol scheme (`http` or `https`)

### RabbitMQ

The [RabbitMQ](/docs/add-services/rabbitmq) configuration is exposed via the following environment variables
(where `RABBITMQ` is the upper-cased version of the key defined in the relationship):

* `RABBITMQ_URL`: The RabbitMQ standardized URL
* `RABBITMQ_SERVER`: The RabbitMQ server
* `RABBITMQ_HOST`: The RabbitMQ host
* `RABBITMQ_PORT`: The RabbitMQ port
* `RABBITMQ_SCHEME`: The RabbitMQ scheme
* `RABBITMQ_USER`: The RabbitMQ username
* `RABBITMQ_USERNAME`: The RabbitMQ username
* `RABBITMQ_PASSWORD`: The RabbitMQ password

### MongoDB

The [MongoDB](/docs/add-services/mongodb) configuration is exposed via the following environment variables
(where `MONGODB` is the upper-cased version of the key defined in the relationship):

* `MONGODB_SERVER`
* `MONGODB_HOST`
* `MONGODB_PORT`
* `MONGODB_SCHEME`
* `MONGODB_NAME`
* `MONGODB_DATABASE`
* `MONGODB_USER`
* `MONGODB_USERNAME`
* `MONGODB_PASSWORD`

### InfluxDB

The [InfluxDB](/docs/add-services/influxdb) configuration is exposed via the following environment variables
(where `TIMEDB` is the upper-cased version of the key defined in the relationship):

* `TIMEDB_SCHEME`
* `TIMEDB_HOST`
* `TIMEDB_PORT`
* `TIMEDB_IP`

### Kafka

The [Apache Kafka](/docs/add-services/kafka) configuration is exposed via the following environment variables
(where `KAFKA` is the upper-cased version of the key defined in the relationship):

* `KAFKA_URL`
* `KAFKA_SCHEME`
* `KAFKA_HOST`
* `KAFKA_PORT`
* `KAFKA_IP`


# FAQ
Source: https://developer.upsun.com/docs/get-started/stacks/laravel/faq

Troubleshoot issues you might encounter using [Laravel](https://laravel.com/), a PHP framework on Upsun Cloud.


## How can I access my application logs?

To display the application log file (`/var/log/app.log` file), run the following command:

```bash theme={null}
upsun log app --tail
```

All the log messages generated by your app are sent to this `/var/log/app.log` file.
This includes language errors such as PHP errors, warnings, notices,
as well as uncaught exceptions.

The file also contains your application logs if you log on `stderr`.
This log doesn't include the default `laravel.log` located in `/storage`.

<Note>
  Upsun Cloud manages the `app.log` file for you.
  This is to prevent disks from getting filled and using very fast local drives instead of slower network disks.
  Make sure your apps always output their logs to `stderr`.
</Note>

With Laravel, you can change your logging configuration to use `memory` and stream `php://stderr`.
In your `config/logging.php` file, add or update the following configuration:

```php config/logging.php theme={null}
'memory' => [
    'driver' => 'monolog',
    'handler' => Monolog\Handler\StreamHandler::class,
    'with' => [
        'stream' => 'php://stderr',
    ],
    'processors' => [
        // Simple syntax...
        Monolog\Processor\MemoryUsageProcessor::class,

        // With options...
        [
           'processor' => Monolog\Processor\PsrLogMessageProcessor::class,
           'with' => ['removeUsedContextFields' => true],
       ],
    ],
],
```

<Warning>
  <h4>Warning</h4>
  If you log deprecations, make sure you **also** log them on `stderr`.
</Warning>

## What's this "`Oops! An Error Occurred`" message about?

The `Oops! An Error Occurred` message comes from your app and is automatically generated based on the Laravel error template.

### The server returned a "`500 Internal Server Error`"

If your app's working as expected locally but you see the previous error message on Upsun Cloud,
it usually means you have a configuration error or a missing dependency.

To fix this issue, search your application logs.
They likely contain an error message describing the root cause:

```bash theme={null}
upsun env:log app
  Reading log file azertyuiop-test-error-azerty--app@ssh.eu-5.platform.sh:/var/log/app.log
  [12-Jan-2026 11:22:08] NOTICE: fpm is running, pid 146
  [12-Jan-2026 11:22:08] NOTICE: ready to handle connections
  [12-Jan-2026 11:27:31] PHP Fatal error:  Uncaught Exception: [...]
  Stack trace: [...]
```

If the error occurs on a preview environment,
or on the main environment of a non-production project,
you can also enable Laravel's dev/debug mode to inspect the cause of the error
via the `APP_DEBUG` [environment variable](/docs/get-started/stacks/laravel/environment-variables) in your
`.environment` file or via [the CLI or Console](/docs/development/variables):

```bash .environment theme={null}
# Enable debug mode
export APP_DEBUG=1
# Disable debug mode
export APP_DEBUG=0
```

## Other issues

For other issues unrelated to Laravel, see [Troubleshoot development](/docs/troubleshooting/general).


# Get started
Source: https://developer.upsun.com/docs/get-started/stacks/laravel/get-started

See how to get started deploying Laravel on Upsun Cloud.


This guide provides instructions for deploying and working with Laravel on Upsun Cloud.

<GuidesRequirements name="Laravel" />

## 1. Create your Laravel app

1. To create a new Laravel project, run the following commands:

   ```bash Terminal theme={null}
   composer create-project laravel/laravel:^11.0 <PROJECT_NAME>
   cd <PROJECT_NAME>
   git init .
   ```

   Alternatively, you can deploy an **existing Laravel project**. To do so, `cd` into your Laravel repository root folder.

2. To generate a sensible default Upsun Cloud configuration,
   run the following command from within the project's directory:

   ```bash Terminal theme={null}
   upsun project:init
   ```

   The Upsun Cloud CLI detects a PHP & Laravel stack.
   Follow the prompts to specify a name for your project and select the needed services.
   While optional, it is recommended to add [Redis](/docs/add-services/redis) to your project to handle Laravel cache, queues & sessions.

   The `.upsun/config.yaml` and `.environment` configuration files are generated.

3. Enable the PHP extensions required by the services you selected.<br />
   For example, `pdo_mysql` is enabled by default, but you may need to enable others like `redis` or `pdo_pgsql`:

   ```yaml .upsun/config.yaml theme={null}
   applications:
     myapp:
       [...]
       runtime:
         extensions:
           - redis
           - pdo_pgsql
   ```

   See all the [available PHP extensions](/docs/languages/php/extensions).

4. Laravel requires an [encryption key](https://laravel.com/docs/master/encryption#gracefully-rotating-encryption-keys).<br />
   To generate the key locally, run `php artisan key:generate`.
   Copy the key from your local `.env` file into `.environment` as follows:

   ```bash .environment theme={null}
   export APP_KEY="base64:<APP_KEY>"
   ```

5. Add and commit your changes:

   ```bash Terminal theme={null}
   git add .upsun/config.yaml .environment
   git commit -m "Add Upsun Cloud configuration"
   ```

## 2. Create your Upsun Cloud project

To create a project on Upsun Cloud, run the following command from within the project's directory:

```bash Terminal theme={null}
upsun project:create --title <PROJECT_TITLE> --set-remote
```

The `--set-remote` flag sets the new project as the remote for this repository.

<Note>
  <h4>Tip</h4>
  You can link any repository to an existing Upsun Cloud project using the following command:

  ```bash Terminal theme={null}
  upsun project:set-remote <PROJECT_ID>
  ```
</Note>

## 3. Deploy your project

To deploy your project, run the following command:

```bash Terminal theme={null}
upsun push
```

During deployment, the logs from the Upsun Cloud API are displayed in your terminal so you can monitor progress.
To stop the display of the logs **without interrupting the deployment**,
use `CTRL+C` in your terminal.
To go back to displaying the logs, run `upsun activity:log`.

Congratulations, your first Laravel app has been deployed on Upsun Cloud!

<Info>
  <h4>Tip</h4>
  Now that your app is deployed in production mode,
  you can [set up a custom domain](/docs/domains/steps).
</Info>

## 4. Configure write access

The Upsun Cloud default configuration stipulates three writable folders in `.upsun/config.yaml`:

* `"/.config"`
* `"bootstrap/cache"`
* `"storage"`

If your application writes content outside of these default ones,
you can [set up mounts](/docs/configure-apps/image-properties/mounts).

## 5. Make changes to your project

Now that your project is deployed, you can start making changes to it.
For example, you might want to fix a bug or add a new feature.

In your project, the main branch always represents the production environment.
Other branches are for developing new features, fixing bugs, or updating the infrastructure.

To make changes to your project, follow these steps:

1. Create a new environment (a Git branch) to make changes without impacting production:

   ```bash Terminal theme={null}
   upsun branch feat-a
   ```

   This command creates a new local `feat-a` Git branch based on the main Git branch,
   and activates a related environment on Upsun Cloud.
   The new environment inherits the data (service data and assets) of its parent environment (the production environment here).

2. Make changes to your project.

   For example, edit the `resources/views/welcome.blade.php` template and make the following visual changes:

   ```html {location="resources/views/welcome.blade.php", no-copy="true"} theme={null}
   <meta name="viewport" content="width=device-width, initial-scale=1">
   -    <title>Laravel</title>
   +    <title>Laravel On Upsun Cloud</title>
   {/* Fonts */}
   ```

3. Add and commit your changes:

   ```bash Terminal theme={null}
   add .
   git commit -a -m "Update title"
   ```

4. Deploy your changes to the `feat-a` environment:

   ```bash Terminal theme={null}
   upsun deploy
   ```

   Note that each environment has its own domain name.
   To view the domain name of your new environment, run the following command:

   ```bash Terminal theme={null}
   upsun url --primary
   ```

5. Iterate by changing the code, committing, and deploying.
   When satisfied with your changes, merge them to the main branch, deploy,
   and remove the feature branch:

   ```bash Terminal theme={null}
   git checkout main
   git merge feat-a
   upsun environment:delete feat-a
   git branch -d feat-a
   upsun deploy
   ```

   Note that deploying to production is fast because the image built for the `feat-a` environment is reused.

   For a long running branch, keep the code up-to-date with the main branch by using `git merge main` or `git rebase main`.
   Also, keep the data in sync with the production environment by using `upsun env:sync`.

## 6. Optional: Use a third-party Git provider

When you choose to use a third-party Git hosting service,
the Upsun Cloud Git repository becomes a read-only mirror of the third-party repository.
All your changes take place in the third-party repository.

Add an integration to your existing third-party repository:

* [BitBucket](/docs/integrations/source/bitbucket)
* [GitHub](/docs/integrations/source/github)
* [GitLab](/docs/integrations/source/gitlab)


# Deploy Laravel on Upsun Cloud
Source: https://developer.upsun.com/docs/get-started/stacks/laravel/index

Complete the last required steps to successfully deploy Laravel on Upsun Cloud.


<Info>
  Before you start, check out the [Upsun Cloud demo app](https://console.upsun.com/projects/create-project) and the main [Getting started guide](/docs/get-started/here).
  They provide all of the core concepts and common commands you need to know before using the materials below.
</Info>

## Guide

<CardGroup>
  <Card title="1. Get started" icon="rocket" href="/docs/get-started/stacks/laravel/get-started">
    Deploy your first Laravel app on Upsun Cloud.
  </Card>

  <Card title="2. Environment variables" icon="key" href="/docs/get-started/stacks/laravel/environment-variables">
    Configure environment variables for Laravel.
  </Card>

  <Card title="3. Set up Redis" icon="database" href="/docs/get-started/stacks/laravel/setup-redis">
    Add Redis for caching and sessions.
  </Card>

  <Card title="4. Queues with Horizon" icon="list-checks" href="/docs/get-started/stacks/laravel/laravel-horizon">
    Handle queues with Laravel Horizon.
  </Card>

  <Card title="5. Cron jobs" icon="clock" href="/docs/get-started/stacks/laravel/crons">
    Set up cron jobs for scheduled tasks.
  </Card>

  <Card title="6. Upsun Blackfire" icon="gauge" href="/docs/get-started/stacks/laravel/blackfire">
    Manage continuous observability with Upsun Blackfire.
  </Card>

  <Card title="7. Laravel Telescope" icon="telescope" href="/docs/get-started/stacks/laravel/laravel-telescope">
    Debug with Laravel Telescope.
  </Card>

  <Card title="8. FAQ" icon="book-open" href="/docs/get-started/stacks/laravel/faq">
    Frequently asked questions.
  </Card>
</CardGroup>

## Further resources

### Documentation

* [PHP documentation](/docs/languages/php)

* [Extensions](/docs/languages/php/extensions)

* [Performance tuning](/docs/languages/php/tuning)

* [PHP-FPM sizing](/docs/languages/php/fpm)

* [Swoole on Upsun Cloud](/docs/languages/php/swoole)

* [Authenticated Composer](/docs/languages/php/composer-auth)

### Community content

* [Laravel topics](https://support.platform.sh/hc/en-us/search?utf8=%E2%9C%93\&query=laravel)

* [PHP topics](https://support.platform.sh/hc/en-us/search?utf8=%E2%9C%93\&query=php)

### Blogs

* [*Upsun Cloud: the missing PaaS to scale Laravel applications*](https://upsun.com/blog/paas-to-scale-laravel-apps/)


# Handle queues with Horizon
Source: https://developer.upsun.com/docs/get-started/stacks/laravel/laravel-horizon

Setting up Laravel Horizon


[Laravel Horizon](https://laravel.com/docs/master/horizon#main-content) provides an appealing dashboard and code-driven configuration
for your Laravel powered Redis queues.
Horizon allows you to monitor key metrics of your queue system,
such as job throughput, runtime, and job failures.

## 1. Add Laravel Horizon

<Warning>
  This procedure assumes you have followed the steps on [how to configure Redis and queues](/docs/get-started/stacks/laravel/setup-redis#5-use-redis-for-laravel-queues).
</Warning>

1. To add Laravel Horizon, run the following command:

   ```bash Terminal theme={null}
   composer require laravel/horizon && php artisan horizon:install
   ```

2. Add the `install` command to your `build` hook in your app configuration, so it's run on every deploy.

   ```yaml .upsun/config.yaml theme={null}
   applications:
     myapp:
       [...]
       hooks:
         build: |
           set -eux
           composer --no-ansi --no-interaction install --no-progress --prefer-dist --optimize-autoloader --no-dev
           php artisan horizon:install
   ```

## 2. Create a worker to run Horizon

To run Horizon on your project, you need to add a separate [worker](/docs/configure-apps/image-properties/workers).
To do so, use the following configuration:

```yaml .upsun/config.yaml theme={null}
applications:
  myapp:
    [...]
    workers:
      horizon:
        commands:
          start: |
            php artisan horizon
```

To enable the worker, push your changes to Upsun Cloud:

```bash Terminal theme={null}
git add .
git commit -m "Enable Laravel Horizon"
upsun push
```

A new container is started automatically.
It will spawn the Horizon process after the next deploy.

## 3. Access your Horizon dashboard

If you have restricted access to Horizon in your `HorizonServiceProvider.php`,
log in to your app through the web.
Then, go to `/horizon` to access your Horizon dashboard.

<img alt="Laravel Horizon Dashboard" />

## 4. Optional: Customize Horizon

Horizon handles jobs that are populated by the queue.
If you need to customize how Horizon works (queues, processes, etc.),
see the official [Laravel Horizon documentation](https://laravel.com/docs/master/horizon#main-content).

<Warning>
  <h4>Warning</h4>
  Web and worker containers don't share mount targets.
  You can't share files between those containers using the filesystem.
  To share data between containers, use [services](/docs/add-services).

  See more information on [workers](/docs/configure-apps/image-properties/workers).
</Warning>

Note that you can customize the resources of your Horizon worker container from the Upsun Cloud Console.

<img alt="Laravel Horizon Resources" />

For more information, see how to [configure resources](/docs/manage-resources/adjust-resources).


# Debug with Laravel Telescope
Source: https://developer.upsun.com/docs/get-started/stacks/laravel/laravel-telescope

Setting up Laravel Telescope for debugging Laravel


Laravel Telescope complements your local Laravel development environment.
With Telescope, get insight into the requests coming into your app, exceptions, log entries, database queries, queued jobs, mail, notifications, cache operations, scheduled tasks, variable dumps, and more.

To set up Laravel Telescope on your **non-production** environments,
follow these steps.

## 1. Create the APP\_DEBUG variable

To add the `APP_DEBUG` & `TELESCOPE_ENABLED` variables on your project, run the following commands:

```bash Terminal theme={null}
upsun variable:create --level environment --name env:APP_DEBUG --value false
upsun variable:create --level environment --name env:TELESCOPE_ENABLED --value false
```

Note that the default values for your main environment are set to `false`.
To override them on other non-production environments, run the following commands:

```bash Terminal theme={null}
upsun variable:update -e <ENVIRONMENT> --value true env:APP_DEBUG
upsun variable:update -e <ENVIRONMENT> --value true env:TELESCOPE_ENABLED
```

## 2. Add Telescope to your project

1. Run the following Composer command:

   ```bash Terminal theme={null}
   composer require laravel/telescope && php artisan telescope:install
   ```

2. Add the `install` command to your `build` hook in your app configuration,
   so it's run on every deploy.

   ```yaml .upsun/config.yaml theme={null}
   applications:
     myapp:
       [...]
       hooks:
         build: |
           set -eux
           composer --no-ansi --no-interaction install --no-progress --prefer-dist --optimize-autoloader --no-dev
           php artisan telescope:install
   ```

For more options and information on how to manage authentication for the dashboard,
see the [Laravel Telecope documentation](https://laravel.com/docs/master/telescope#installation).

## 3. Deploy the new release

To enable Telescope, push your changes to Upsun Cloud:

```bash Terminal theme={null}
git add .
git commit -m "Enable Laravel Horizon"
upsun push
```

You can now access the `/telescope` endpoint of your app.

<img alt="Laravel Horizon Dashboard" />

<Tip>
  Telescope uses a gate defined in `TelescopeServiceProvider.php` to authorize access to the dashboard.
  Check that the logic here matches your needs.
</Tip>


# Set up Redis
Source: https://developer.upsun.com/docs/get-started/stacks/laravel/setup-redis

Setting up Redis for cache, sessions & queues


With Laravel, you can use Redis to handle session storage, cache storage, and queues.

## 1. Add the Redis service

1. [Add the service](/docs/add-services#add-a-service) to your app configuration using the `services` top-level key:

   ```yaml .upsun/config.yaml theme={null}
   services:
     [...]
     redis:
       type: redis:7.0
   ```

2. To connect the service to your app, add the following relationship:

   ```yaml .upsun/config.yaml theme={null}
   applications:
     myapp:
       [...]
       relationships:
         redis:

   services:
     [...]
     redis:
       type: redis:7.0
   ```

## 2. Configure your Redis service

The [Redis](/docs/add-services/redis) configuration is exposed via the following environment variables
(where `REDIS` is the upper-cased version of the key defined in the relationship):

* `REDIS_URL`: The Redis URL
* `REDIS_HOST`: The Redis host
* `REDIS_PORT`: The Redis port
* `REDIS_SCHEME`: The Redis scheme

If the relationship is named `redis`, Laravel automatically detects these variables and configure its own Redis driver the right way.
If not, you can map the variables in the `.environment` file.

You can specify the Redis client in your `.environment` file:

```bash .environment theme={null}
export REDIS_CLIENT="phpredis"
```

<Warning>
  If using `phpredis`, make sure you add `redis` in the list of PHP `runtime` extensions in your `.upsun/config.yaml`:

  ```yaml .upsun/config.yaml theme={null}
  applications:
    myapp:
      [...]
      runtime:
        extensions:
          - redis
  ```
</Warning>

## 3. Store the Laravel cache in Redis

To enable cache storage in Redis, add the following environment variable to your `.environment` file:

```bash .environment theme={null}
export CACHE_STORE="redis"
```

## 4. Store Laravel sessions in Redis

Laravel relies on the `SESSION_DRIVER` variable to store sessions. Therefore, add the following environment variable to your `.environment` file:

```bash .environment theme={null}
export SESSION_DRIVER="redis"
```

## 5. Use Redis for Laravel queues

For a basic queueing system, configure the `QUEUE_CONNECTION` in your `.environment` file as follows:

```bash .environment theme={null}
export QUEUE_CONNECTION="redis"
```

For more information, see the [Laravel Queues documentation](https://laravel.com/docs/master/queues)
and Upsun Cloud's [Horizon configuration page](/docs/get-started/stacks/laravel/laravel-horizon).


# Deploy Next.js on Upsun Cloud
Source: https://developer.upsun.com/docs/get-started/stacks/nextjs

Complete the last required steps to successfully deploy Next.js on Upsun Cloud.


<Info>
  <h4>Note</h4>
  Before you start, check out the [Upsun Cloud demo app](https://console.upsun.com/projects/create-project) and the main [Getting started guide](/docs/get-started/here).
  They provide all of the core concepts and common commands you need to know before using the materials below.
</Info>

<GuidesRequirements name="Next.js" />

## 1. Create a Next.js app

To create your Next.js app, follow these steps.

1. Follow the Next.js [installation guide](https://nextjs.org/docs/getting-started/installation).
   To fast track the process, run the following commands:

   ```bash Terminal theme={null}
   npx create-next-app@latest myapp
   ```

2. To initialize the local Git repository and commit local files, run the following commands:

   ```bash Terminal theme={null}
   cd myapp
   git init
   git add .
   git commit -m "Init Next.js application."
   ```

<Info>
  You can view the running app locally by running `npm run dev`.
</Info>

## 2. Create a new project

To create a project on Upsun Cloud,
follow these steps.

<Note>
  <h4>Remember</h4>
  After creating your Upsun Cloud project, copy your new **project ID** for later use.
</Note>

<Tabs>
  <Tab title="Using the CLI">
    To create a new project with the Upsun Cloud CLI, use the following command and follow the prompts:

    ```bash Terminal theme={null}
    upsun project:create
    ```

    <Note>
      When creating a new project using the Upsun Cloud CLI command `project:create`,
      you are asked if you want to set the local remote to your new project. Enter **Yes (y)**.

      Your local source code is automatically linked to your newly created Upsun Cloud project
      through the creation of a `.upsun/local/project.yaml`.
      This file contains the corresponding `<projectId>` for the Upsun Cloud CLI to use,
      and sets a Git remote to `upsun`.
    </Note>
  </Tab>

  <Tab title="Using the Console">
    1. Create an organization or select an existing one.

    2. Click **Create from scratch**.

    3. Fill in details like the project name and [region](/docs/development/regions).

       <Note>
         You can define resources for your project later on, after your first push.
       </Note>

    4. To link your local source code to your new Upsun Cloud project,
       run the following command:

       ```bash Terminal theme={null}
       upsun project:set-remote <projectId>
       ```

       This command adds a new remote called `upsun` to your local Git repository,
       which is equivalent to the following commands:

       ```bash Terminal theme={null}
       git remote
       origin
       upsun
       ```

       It also creates a new `.upsun/local/project.yaml` file that contains the `<projectId>`
       for the `upsun` CLI to use.

       <Tip>
         If you forget your `<projectId>`, run the following command and find your project in the list:

         ```bash Terminal theme={null}
         upsun project:list
         ```
       </Tip>
  </Tab>
</Tabs>

## 3. Choose your Git workflow

You can use Upsun Cloud projects as a classic Git repository,
where you are able to push your source code in different ways,
using either the Git CLI or the Upsun Cloud CLI.
You can choose which way —or Git workflow— you want to use for your project from the following options:

* Your project source code is **hosted on an Upsun Cloud Git repository**
* Your project source code is **hosted on your own GitHub repository**

<Tabs>
  <Tab title="Upsun Cloud Git repository">
    For the rest of this guide, you will use the normal Git workflow (`git add . && git commit -m "message" && git push upsun`) to commit your source code changes to Git history.
    You will also use the Upsun Cloud CLI to deploy your [Upsun Cloud environment](/docs/environments) with the latest code updates.
  </Tab>

  <Tab title="GitHub repository">
    Upsun Cloud provides a [Github integration](/docs/integrations/source/github) that allows your Upsun Cloud project to be fully integrated with your Github repository.
    This enables you, as a developer, to use a normal Git workflow (`git add . && git commit -m "message" && git push`) to deploy your environment—with no need to connect to the Upsun Cloud Console.

    <Note>
      Make sure you complete the following steps before adding a [Github integration](/docs/integrations/source/github):

      1. Create a Git repository in your own organization following the relevant
         [Github repository creation guide](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-new-repository).

      2. Create a [Github integration](/docs/integrations/source/github).

      3. Add a Git remote to your local project, from the root of your Next.js directory.<br />
         To do so, run the following commands:

         ```bash Terminal theme={null}
         git remote add origin <urlOfYourOwnGitHubRepo>
         git add . && git commit -m "init next.js"
         git push origin
         ```
    </Note>
  </Tab>
</Tabs>

## 4. Configure your project

To host your Next.js application on Upsun Cloud,
you need to have a few YAML configuration files at the root of your project.
These files manage your app's behavior.
They are located in a `.upsun/` folder at the root of your source code
and structured in a similar way to this:

```text Example file structure theme={null}
myapp
├── .upsun
│   └── config.yaml
├── [.environment]
└── <project sources>
```

To generate these files, run the following command at the root of your project:

```{location="Terminal"} theme={null}
upsun project:init
```

Follow the prompts, and you should result in such a config file.

As an example, above is the minimum configuration needed to deploy a Next.js application on Upsun Cloud without any services.
Depending on your answers to the prompts, you may also have `relationships` and `services` defined.

To commit your new files, run the following commands:

```bash Terminal theme={null}
git add .
git commit -m "Add Upsun Cloud config files"
```

## 5. Deploy

And just like that, it’s time to deploy!

Depending on the Git workflow you chose at the beginning of this tutorial,
there are two ways to deploy your source code changes.

<Tabs>
  <Tab title="Using Upsun Cloud Git repository">
    You can push your code using the normal Git workflow (`git add . && git commit -m "message" && git push`).
    This pushes your source code changes to your `upsun` remote repository.
    Alternatively, you can use the following Upsun Cloud CLI command:

    ```bash Terminal theme={null}
    upsun push
    ```
  </Tab>

  <Tab title="Using third-party Git repository">
    When you choose to use a third-party Git hosting service, the Upsun Cloud Git
    repository becomes a read-only mirror of the third-party repository. All your
    changes take place in the third-party repository.

    Add an integration to your existing third-party repository:

    * [BitBucket](/docs/integrations/source/bitbucket)
    * [GitHub](/docs/integrations/source/github)
    * [GitLab](/docs/integrations/source/gitlab)

    If you are using an integration, on each code updates,
    use the normal Git workflow (`git add . && git commit -m "message" && git push`) to push your code to your external repository.
    To do so, run the following command:

    ```bash Terminal theme={null}
    git push origin
    ```

    Your GitHub, GitLab, or Bibucket integration process then automatically deploys changes to your environment.
    If you're pushing a new Git branch, a new environment is created.
  </Tab>
</Tabs>

Upsun Cloud then reads your configuration files,
and deploys your project using [default container resources](/docs/manage-resources/resource-init).

<Note>
  <h4>Resource sizing for Next.js</h4>
  Next.js applications typically require more resources than the platform defaults.
  If you encounter a [502 error](/docs/troubleshooting/502-errors) after deploying, your container may not have enough CPU or memory.

  Try increasing your app's resources by running the following command and, when prompted, selecting an application size of <code>0.5</code> or higher:

  ```bash Terminal theme={null}
  upsun resources:set
  ```

  For more details, see [Adjust resources](/docs/manage-resources/adjust-resources).
</Note>

If you don't want to use those default resources,
define your own [resource initialization strategy](/docs/manage-resources/resource-init#specify-a-resource-initialization-strategy),
or [amend those default container resources](/docs/manage-resources/adjust-resources) after your project is deployed.

Et voilà, your Next.js application is live!

<Info>
  <h4>Tip</h4>
  Each environment has its own domain name.
  To open the URL of your new environment, run the following command:

  ```bash Terminal theme={null}
  upsun environment:url --primary
  ```
</Info>

## 6. Make changes to your project

Now that your project is deployed, you can start making changes to it.
For example, you might want to fix a bug or add a new feature.

In your project, the `main` branch always represents the production environment.
Other branches are for developing new features, fixing bugs, or updating the infrastructure.

To make changes to your project, follow these steps:

1. Create a new environment (a Git branch) to make changes without impacting production:

   ```bash Terminal theme={null}
   upsun branch feat-a
   ```

   This command creates a new local `feat-a` Git branch based on the main Git branch,
   and activates a related environment on Upsun Cloud.
   The new environment inherits the data (service data and assets) of its parent environment (the production environment here).

2. Make changes to your project.
   For example, edit the `views/index.jade` file and make the following changes:

   ```diff {no-copy="true"} theme={null}
   diff --git a/views/index.jade b/views/index.jade
   index 3d63b9a..77aee43 100644
   --- a/views/index.jade
   +++ b/views/index.jade
   @@ -2,4 +2,4 @@ extends layout

    block content
      h1= title
   -  p Welcome to #{title}
   +  p Welcome to #{title} on Upsun Cloud
   ``

   ```

3. Commit your changes:

   ```bash Terminal theme={null}
   git add views/index.jade
   git commit -m "Update index page view."
   ```

4. Deploy your changes to the `feat-a` environment:

   ```bash Terminal theme={null}
   upsun push
   ```

5. Iterate by changing the code, committing, and deploying.
   When satisfied with your changes, merge them to the main branch,
   and remove the feature branch:

   ```bash Terminal theme={null}
   upsun merge
       Are you sure you want to merge feat-a into its parent, main? [Y/n] y
   upsun checkout main
   git pull upsun main
   upsun environment:delete feat-a
   git fetch --prune
   ```

   Note that deploying to production is fast because the image built for the `feat-a` environment is reused.

   For a long running branch, to keep the code up-to-date with the main branch, use `git merge main` or `git rebase main`.
   You can also keep the data in sync with the production environment by using `upsun env:sync`.

## Further resources

### Documentation

* [JavaScript/Node.js documentation](/docs/languages/nodejs)
* [Managing dependencies](/docs/languages/nodejs#dependencies)

### Community content

* [Next.js topics](https://support.platform.sh/hc/en-us/search?utf8=%E2%9C%93\&query=nextjs)
* [Node.js topics](https://support.platform.sh/hc/en-us/search?utf8=%E2%9C%93\&query=node)
* [JavaScript topics](https://support.platform.sh/hc/en-us/search?utf8=%E2%9C%93\&query=js)

### Blogs

* [A quick-start guide on hosting Next.js on Upsun Cloud](https://upsun.com/blog/setting-up-next-js-on-upsun/)


# Deploy PHP apps on Upsun Cloud
Source: https://developer.upsun.com/docs/get-started/stacks/php

Choose a PHP framework and follow a step-by-step guide to deploy on Upsun Cloud.


Pick your PHP framework and follow a guide to deploy on Upsun Cloud.

<CardGroup>
  <Card title="Laravel" icon="laravel" href="/docs/get-started/stacks/laravel">
    Full-stack PHP framework.
  </Card>

  <Card title="Symfony" icon="symfony" href="/docs/get-started/stacks/symfony">
    Flexible PHP framework.
  </Card>
</CardGroup>

<Tip>
  Looking for WordPress, Drupal, Magento, Shopware, or Pimcore? Check out the [CMS guides in Tutorials](/tutorials/cms).
</Tip>

For more details on configuring PHP, see the [PHP documentation](/docs/languages/php).


# Deploy Python apps on Upsun Cloud
Source: https://developer.upsun.com/docs/get-started/stacks/python

Choose a Python framework and follow a step-by-step guide to deploy on Upsun Cloud.


Pick your Python framework and follow a guide to deploy on Upsun Cloud.

<CardGroup>
  <Card title="Django" icon="python" href="/docs/get-started/stacks/django">
    Full-featured web framework.
  </Card>

  <Card title="Flask" icon="beaker" href="/docs/get-started/stacks/flask">
    Lightweight web framework.
  </Card>
</CardGroup>

For more details on configuring Python, see the [Python documentation](/docs/languages/python).


# Add a database to Strapi
Source: https://developer.upsun.com/docs/get-started/stacks/strapi/add-database

After your Strapi application is deployed on Upsun Cloud, you might want to add and configure a service to your application.


This guide will show you how to provision and connect to two different databases on Upsun Cloud:

* PostgreSQL
* Oracle MySQL

## 1. Branch

Like all updates to your Upsun Cloud projects, first create a new dedicated environment to test this change.

```bash theme={null}
git checkout -b upgrade-db
```

## 2. Install the Node.js package

<Tabs>
  <Tab title="PostgreSQL">
    ```bash theme={null}
    yarn add pg
    ```
  </Tab>

  <Tab title="Oracle MySQL">
    ```bash theme={null}
    yarn add mysql
    ```
  </Tab>
</Tabs>

## 3. Add a new service

Add a new service to your `.upsun/config.yaml` file:

## 4. Add a new relationship

Add a new relationship to your `.upsun/config.yaml` file to allow access to the new service

## 5. Update `.environment`

When you previously ran `upsun project:init`, the command generated some Strapi-specific environment variables:

```bash .environment theme={null}
# Set Strapi-specific environment variables
export DATABASE_HOST="$DB_HOST"
export DATABASE_PORT="$DB_PORT"
export DATABASE_NAME="$DB_PATH"
export DATABASE_USERNAME="$DB_USERNAME"
export DATABASE_PASSWORD="$DB_PASSWORD"
export DATABASE_SCHEME="$DB_SCHEME"

# Set secrets needed by Strapi, if they are not set
# Prefer setting these as project secret variables with upsun variable:create env:SECRET_NAME --sensitive=true
if [ -z "$ADMIN_JWT_SECRET" ]; then
  export ADMIN_JWT_SECRET="$PLATFORM_PROJECT_ENTROPY"
fi
if [ -z "$JWT_SECRET" ]; then
  export JWT_SECRET="$PLATFORM_PROJECT_ENTROPY"
fi
if [ -z "$API_TOKEN_SALT" ]; then
    export API_TOKEN_SALT="$PLATFORM_PROJECT_ENTROPY"
fi
if [ -z "$APP_KEYS" ]; then
    export APP_KEYS="$PLATFORM_PROJECT_ENTROPY"
fi
```

Upsun Cloud will actually generate service credentials automatically for you in the runtime container, so we don't need the first half of this file anymore.
Remove the first block (pertaining to `DATABASE` credentials).

Then, add a single additional variable that will set the `DATABASE_CLIENT` variable at the appropriate time:

<Tabs>
  <Tab title="PostgreSQL">
    ```bash .environment theme={null}
    # Set secrets needed by Strapi, if they are not set
    # Prefer setting these as project secret variables with upsun variable:create env:SECRET_NAME --sensitive=true
    if [ -z "$ADMIN_JWT_SECRET" ]; then
      export ADMIN_JWT_SECRET="$PLATFORM_PROJECT_ENTROPY"
    fi
    if [ -z "$JWT_SECRET" ]; then
      export JWT_SECRET="$PLATFORM_PROJECT_ENTROPY"
    fi
    if [ -z "$API_TOKEN_SALT" ]; then
        export API_TOKEN_SALT="$PLATFORM_PROJECT_ENTROPY"
    fi
    if [ -z "$APP_KEYS" ]; then
        export APP_KEYS="$PLATFORM_PROJECT_ENTROPY"
    fi

    # Switch to configure to the production database service _only_ at deploy time.
    if [ -z "$PLATFORM_ENVIRONMENT" ]; then
        export DATABASE_CLIENT="postgres"
    fi
    ```
  </Tab>

  <Tab title="Oracle MySQL">
    ```bash .environment theme={null}
    # Set secrets needed by Strapi, if they are not set
    # Prefer setting these as project secret variables with upsun variable:create env:SECRET_NAME --sensitive=true
    if [ -z "$ADMIN_JWT_SECRET" ]; then
      export ADMIN_JWT_SECRET="$PLATFORM_PROJECT_ENTROPY"
    fi
    if [ -z "$JWT_SECRET" ]; then
      export JWT_SECRET="$PLATFORM_PROJECT_ENTROPY"
    fi
    if [ -z "$API_TOKEN_SALT" ]; then
        export API_TOKEN_SALT="$PLATFORM_PROJECT_ENTROPY"
    fi
    if [ -z "$APP_KEYS" ]; then
        export APP_KEYS="$PLATFORM_PROJECT_ENTROPY"
    fi

    # Switch to configure to the production database service _only_ at deploy time.
    if [ -z "$PLATFORM_ENVIRONMENT" ]; then
        export DATABASE_CLIENT="mysql"
    fi
    ```
  </Tab>
</Tabs>

## 6. Push to the environment

Commit and push the changes to the Upsun Cloud environment:

```bash theme={null}
git commit -am "Add a new service"
git push origin upgrade-db
```

<Info>
  If you are using Upsun Cloud as your primary remote, you can use the `upsun branch` and `upsun push` commands directly.
  If instead you had already set up an integration to GitHub, GitLab or Bitbucket, make sure to open a pull/merge request to judge the revision.
</Info>


# Deploy Strapi on Upsun Cloud
Source: https://developer.upsun.com/docs/get-started/stacks/strapi/index

Complete the last required steps to successfully deploy Strapi on Upsun Cloud.


<Info>
  <h4>Note</h4>
  Before you start, check out the [Upsun Cloud demo app](https://console.upsun.com/projects/create-project) and the main [Getting started guide](/docs/get-started/here).
  They provide all of the core concepts and common commands you need to know before using the materials below.
</Info>

<GuidesRequirements name="Strapi" />

## 1. Create a Strapi project

To create your Strapi app, follow these steps.

1. Follow the Strapi [installation guide](https://docs.strapi.io/dev-docs/installation).<br />
   To fast track the process, run the following commands:

   ```bash Terminal theme={null}
   npx create-strapi-app@latest my-strapi-project --quickstart --no-run
   ```

   <Note>
     If the `create-strapi-app` script fails, run `export SHARP_IGNORE_GLOBAL_LIBVIPS=true`,
     remove the previous attempt (`rm -rf my-strapi-project`), and run the command again.
   </Note>

2. To initialize the local Git repository and commit local files, run the following commands:

   ```bash Terminal theme={null}
   cd my-strapi-project
   echo "\nhttp:" >> .gitignore
   git add .
   git commit -m "Init Strapi application."
   ```

   <Note>
     You can view the running app locally by running `yarn develop`.
     The local server will be visible at `localhost:1337`.
     You can create your first administrator user locally, but you will have to recreate that user once you've deployed to Upsun Cloud.
   </Note>

## 2. Create a new project

To create a project on Upsun Cloud,
follow these steps.

<Note>
  <h4>Remember</h4>
  After creating your Upsun Cloud project, copy your new **project ID** for later use.
</Note>

<Tabs>
  <Tab title="Using the CLI">
    To create a new project with the Upsun Cloud CLI, use the following command and follow the prompts:

    ```bash Terminal theme={null}
    upsun project:create
    ```

    <Note>
      When creating a new project using the Upsun Cloud CLI command `project:create`,
      you are asked if you want to set the local remote to your new project. Enter **Yes (y)**.

      Your local source code is automatically linked to your newly created Upsun Cloud project
      through the creation of a `.upsun/local/project.yaml`.
      This file contains the corresponding `<projectId>` for the Upsun Cloud CLI to use,
      and sets a Git remote to `upsun`.
    </Note>
  </Tab>

  <Tab title="Using the Console">
    1. Create an organization or select an existing one.

    2. Click **Create from scratch**.

    3. Fill in details like the project name and [region](/docs/development/regions).

       <Note>
         You can define resources for your project later on, after your first push.
       </Note>

    4. To link your local source code to your new Upsun Cloud project,
       run the following command:

       ```bash Terminal theme={null}
       upsun project:set-remote <projectId>
       ```

       This command adds a new remote called `upsun` to your local Git repository,
       which is equivalent to the following commands:

       ```bash Terminal theme={null}
       git remote
       origin
       upsun
       ```

       It also creates a new `.upsun/local/project.yaml` file that contains the `<projectId>`
       for the `upsun` CLI to use.

       <Tip>
         If you forget your `<projectId>`, run the following command and find your project in the list:

         ```bash Terminal theme={null}
         upsun project:list
         ```
       </Tip>
  </Tab>
</Tabs>

## 3. Choose your Git workflow

You can use Upsun Cloud projects as a classic Git repository,
where you are able to push your source code in different ways,
using either the Git CLI or the Upsun Cloud CLI.
You can choose which way —or Git workflow— you want to use for your project from the following options:

* Your project source code is **hosted on an Upsun Cloud Git repository**
* Your project source code is **hosted on your own GitHub repository**

<Tabs>
  <Tab title="Upsun Cloud Git repository">
    For the rest of this guide, you will use the normal Git workflow (`git add . && git commit -m "message" && git push upsun`) to commit your source code changes to Git history.
    You will also use the Upsun Cloud CLI to deploy your [Upsun Cloud environment](/docs/environments) with the latest code updates.
  </Tab>

  <Tab title="GitHub repository">
    Upsun Cloud provides a [Github integration](/docs/integrations/source/github) that allows your Upsun Cloud project to be fully integrated with your Github repository.
    This enables you, as a developer, to use a normal Git workflow (`git add . && git commit -m "message" && git push`) to deploy your environment—with no need to connect to the Upsun Cloud Console.

    <Note>
      Make sure you complete the following steps before adding a [Github integration](/docs/integrations/source/github):

      1. Create a Git repository in your own organization following the relevant [Github repository creation guide](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-new-repository).
      2. Create a [Github integration](/docs/integrations/source/github).
      3. Add a Git remote to your local project, from the root of your Strapi directory.<br />
         To do so, run the following commands:

         ```bash Terminal theme={null}
         git remote add origin <urlOfYourOwnGitHubRepo>
         git add . && git commit -m "init strapi"
         git push origin
         ```
    </Note>
  </Tab>
</Tabs>

## 4. Configure your project

To host your Strapi application on Upsun Cloud,
you need to have a few YAML configuration files at the root of your project.
These files manage your app's behavior.
They are located in a `.upsun/` folder at the root of your source code
and structured in a similar way to this:

```text Example file structure theme={null}
my-strapi-project
├── .upsun
│   └── config.yaml
├── [.environment]
└── <project sources>
```

To generate these files, run the following command at the root of your project:

```{location="Terminal"} theme={null}
upsun project:init
```

Follow the prompts.

To commit your new files, run the following commands:

```bash Terminal theme={null}
git add .
git commit -m "Add Upsun Cloud config files"
```

## 5. Deploy

And just like that, it’s time to deploy!

Depending on the Git workflow you chose at the beginning of this tutorial,
there are two ways to deploy your source code changes.

<Tabs>
  <Tab title="Using Upsun Cloud Git repository">
    You can push your code using the normal Git workflow (`git add . && git commit -m "message" && git push`). This pushes your source code changes to your `upsun` remote repository. Alternatively, you can use the following Upsun Cloud CLI command:

    ```bash Terminal theme={null}
    upsun push
    ```
  </Tab>

  <Tab title="Using a third-party Git repository">
    When you choose to use a third-party Git hosting service, the Upsun Cloud Git
    repository becomes a read-only mirror of the third-party repository. All your
    changes take place in the third-party repository.

    Add an integration to your existing third-party repository:

    * [BitBucket](/docs/integrations/source/bitbucket)
    * [GitHub](/docs/integrations/source/github)
    * [GitLab](/docs/integrations/source/gitlab)

    If you are using an integration, on each code updates,
    use the normal Git workflow (`git add . && git commit -m "message" && git push`) to push your code to your external repository.
    To do so, run the following command:

    ```bash Terminal theme={null}
    git push origin
    ```

    Your GitHub, GitLab, or Bibucket integration process then automatically deploys changes to your environment.
    If you're pushing a new Git branch, a new environment is created.
  </Tab>
</Tabs>

Upsun Cloud then reads your configuration files,
and deploys your project using [default container resources](/docs/manage-resources/resource-init).
If you don't want to use those default resources,
define your own [resource initialization strategy](/docs/manage-resources/resource-init#specify-a-resource-initialization-strategy),
or [amend those default container resources](/docs/manage-resources/adjust-resources) after your project is deployed.

Et voilà, your Strapi application is live!

<Info>
  <h4>Tip</h4>
  Each environment has its own domain name.
  To open the URL of your new environment, run the following command:

  ```bash Terminal theme={null}
  upsun environment:url --primary
  ```
</Info>

## 6. Make changes to your project

Now that your project is deployed, you can start making changes to it.
For example, you might want to fix a bug or add a new feature.

In your project, the `main` branch always represents the production environment.
Other branches are for developing new features, fixing bugs, or updating the infrastructure.

To make changes to your project, follow these steps:

1. Create a new environment (a Git branch) to make changes without impacting production:

   ```bash Terminal theme={null}
   upsun branch feat-a
   ```

   This command creates a new local `feat-a` Git branch based on the main Git branch,
   and activates a related environment on Upsun Cloud.
   The new environment inherits the data (service data and assets) of its parent environment (the production environment here).

2. Make changes to your project.<br />
   For example, you can create a new API and Collection (Content Type).
   To do so, run the following command:

   ```bash Terminal theme={null}
   npm run strapi -- generate content-type
   ```

   Then follow the prompts to set up the `Blog` API containing an `Article` Content Type (Collection):

   ```bash {location="Suggested responses", no-copy="true"} theme={null}
   ? Content type display name Article
   ? Content type singular name article
   ? Content type plural name articles
   ? Please choose the model type Collection Type
   ? Use draft and publish? Yes
   ? Do you want to add attributes? Yes
   ? Name of attribute title
   ? What type of attribute string
   ? Do you want to add another attribute? Yes
   ? Name of attribute body
   ? What type of attribute richtext
   ? Do you want to add another attribute? Yes
   ? Name of attribute image
   ? What type of attribute media
   ? Choose media type Single
   ? Do you want to add another attribute? No
   ? Where do you want to add this model? Add model to new API
   ? Name of the new API? blog
   ? Bootstrap API related files? Yes
   ✔  ++ /api/blog/content-types/article/schema.json
   ✔  +- /api/blog/content-types/article/schema.json
   ✔  ++ /api/blog/controllers/article.js
   ✔  ++ /api/blog/services/article.js
   ✔  ++ /api/blog/routes/article.js
   ```

   Verify that the new `Article` collection has been created.
   To do so, run the local server (`yarn develop`) again,
   and visit
   <a href="http://localhost:1337/admin/content-manager">[http://localhost:1337/admin/content-manager](http://localhost:1337/admin/content-manager)</a>.

   This results in the following changes:

   ```bash theme={null}
   $ git status
   On branch feat-a
   Changes not staged for commit:
     (use "git add <file>..." to update what will be committed)
     (use "git restore <file>..." to discard changes in working directory)
       modified:   types/generated/contentTypes.d.ts

   Untracked files:
     (use "git add <file>..." to include in what will be committed)
       src/api/blog/

   no changes added to commit (use "git add" and/or "git commit -a")
   ```

3. Commit your changes:

   ```bash Terminal theme={null}
   git add .
   git commit -m "Add Article collection"
   ```

4. Deploy your changes to the `feat-a` environment:

   ```bash Terminal theme={null}
   upsun push
   ```

   <Tip>
     Note that each environment has its own domain name.
     To open the URL of your new environment, run the following command:

     ```bash Terminal theme={null}
     upsun environment:url --primary
     ```
   </Tip>

5. Iterate by changing the code, committing, and deploying.<br />
   When satisfied with your changes, merge them to the main branch,
   and remove the feature branch:

   ```bash Terminal theme={null}
   upsun merge
       Are you sure you want to merge feat-a into its parent, main? [Y/n] y
   upsun checkout main
   git pull upsun main
   upsun environment:delete feat-a
   git fetch --prune
   ```

   Note that deploying to production is fast because the image built for the `feat-a` environment is reused.

   For a long running branch, to keep the code up-to-date with the main branch, use `git merge main` or `git rebase main`.
   You can also keep the data in sync with the production environment by using `upsun env:sync`.

## Further resources

### Documentation

* [JavaScript/Node.js documentation](/docs/languages/nodejs)
* [Managing dependencies](/docs/languages/nodejs#dependencies)
* [Add a database to Strapi](/docs/get-started/stacks/strapi/add-database)

### Community content

* [Strapi topics](https://support.platform.sh/hc/en-us/search?utf8=%E2%9C%93\&query=strapi)
* [Node.js topics](https://support.platform.sh/hc/en-us/search?utf8=%E2%9C%93\&query=node)
* [JavaScript topics](https://support.platform.sh/hc/en-us/search?utf8=%E2%9C%93\&query=js)

### Blogs

* [Up(sun) and running with Strapi: a seamless journey to a powerful decoupled headless CMS](https://upsun.com/blog/strapi-deployment-on-upsun/)


# Manage continuous observability with Upsun Blackfire
Source: https://developer.upsun.com/docs/get-started/stacks/symfony/blackfire

Set up a continuous observability strategy for your Symfony app with Upsun Blackfire.

[Upsun Blackfire](/docs/observability/application-metrics/blackfire) is the recommended solution
for monitoring and profiling web sites and apps.
Upsun Blackfire works seamlessly with any app built with Symfony.

Upsun Blackfire PHP SDK provides the following [integrations with
Symfony](https://blackfire.io/docs/php/integrations/symfony/index):

* [Symfony HTTPClient](https://blackfire.io/docs/php/integrations/symfony/http-client)
* [Symfony Messenger](https://blackfire.io/docs/php/integrations/symfony/messenger)
* [Symfony CLI Commands Monitoring](https://blackfire.io/docs/php/integrations/symfony/cli-commands-monitoring)
* [Symfony Functional Tests Production](https://blackfire.io/docs/php/integrations/symfony/functional-tests)

A `.blackfire.yaml` file is provided within the [Symfony Templates](https://github.com/symfonycorp/platformsh-symfony-template/blob/7.2/.blackfire.yaml)
to help you bootstrap the writing of custom [performance tests](https://blackfire.io/docs/testing-cookbooks/index)
and automated [builds](https://blackfire.io/docs/builds-cookbooks/index).


# Set up cron jobs
Source: https://developer.upsun.com/docs/get-started/stacks/symfony/crons

Understand how to configure Symfony cron jobs.


Cron jobs allow you to run scheduled tasks at specified times or intervals.
To set up a cron job, add a configuration similar to the following:

```yaml .upsun/config.yaml theme={null}
applications:
  myapp:
    crons:
      snapshot:
        spec: 0 5 * * *
        commands:
          start: |
            croncape symfony ...
```

To run a command in a cron hook for specific environment types,
use the `PLATFORM_ENVIRONMENT_TYPE` environment variable:

```yaml .upsun/config.yaml theme={null}
applications:
  myapp:
    crons:
      snapshot:
        spec: 0 5 * * *
        commands:
          start: |
            # only run for the production environment, aka main branch
            if [ "$PLATFORM_ENVIRONMENT_TYPE" = "production" ]; then
              croncape symfony ...
            fi
```

## Use croncape

When using the [Symfony integration](/docs/get-started/stacks/symfony/integration),
you can use `croncape` to get feedback through emails when something goes wrong.

To specify which email address `croncape` must send the feedback emails to,
add a `MAILTO` environment variable.
To do so, run the following command:

```bash theme={null}
symfony var:create -y --level=project --name=env:MAILTO --value=sysadmin@example.com
```

To ensure better reliability, `croncape` sends the emails using:

* `project-id@cron.noreply.platformsh.site` as the sender address (`project-id+branch@cron.noreply.platformsh.site` for non-main environments)
* the provided [Upsun CloudSMTP service](/docs/get-started/stacks/symfony/environment-variables#emails), even if you define your own `MAILER_*` environment variables

To use a custom SMTP and/or custom sender address, follow these steps:

1. To specify a sender address, define a [`MAILFROM` environment variable](/docs/get-started/stacks/symfony/environment-variables#symfony-environment-variables).

2. Define the mandatory [environment variables to use your own email service](/docs/get-started/stacks/symfony/environment-variables#emails).
   Note that only SMTP connections are supported.

3. To disable the provided SMTP service, run `symfony upsun:env:info enable_smtp false`.

<Info>
  To use `croncape`, SMTP must be enabled on the environment, where the [`PLATFORM_SMTP_HOST`](/docs/development/variables/use-variables#use-provided-variables) environment variable is accessible.
  This variable is available, and SMTP enabled, by default on all production environments.

  This is not the case for preview (non-production) environments, where it must be enabled with the command `symfony cloud:env:info enable_smtp true`.
</Info>


# Configure environment variables
Source: https://developer.upsun.com/docs/get-started/stacks/symfony/environment-variables

Learn about the environment variables added by the Symfony integration.


By default, Upsun Cloud exposes some [environment variables](/docs/development/variables/use-variables#use-provided-variables).
If you're using the [Symfony integration](/docs/get-started/stacks/symfony/integration),
more [infrastructure environment variables](#symfony-environment-variables) related to Symfony are defined.

As Symfony relies heavily on environment variables to configure application services (such as the database or the mailer DSN),
the Symfony integration automatically defines [environment variables for all the services](#service-environment-variables) connected to your app.

<Note>
  <h4>Tip</h4>
  The code that defines these additional environment variables is part of the open-source [Symfony CLI tool](https://symfony.com/download).
  Check the code for [infrastructure](https://github.com/symfony-cli/symfony-cli/blob/main/envs/remote.go#L139)
  and [service](https://github.com/symfony-cli/symfony-cli/blob/main/envs/envs.go#L110) environment variables on GitHub.
</Note>

## Symfony environment variables

Upsun Cloud exposes [environment variables](/docs/development/variables/use-variables#use-provided-variables)
about the app and its infrastructure.

The Symfony integration exposes more environment variables:

* `APP_ENV` is set to `prod` by default.
  You can manually override this value for a preview environment
  by setting the `SYMFONY_ENV` environment variable to `dev`, and remove it when done.

* `APP_DEBUG` is set to `0` by default.
  You can manually override this value for a preview environment
  by setting the `SYMFONY_DEBUG` environment variable to `1`, and remove it when done.

* `APP_SECRET` is set to the value of `PLATFORM_PROJECT_ENTROPY`, which is a random and unique value for all Upsun Cloud projects.
  It overrides the value configured in the `.env` file of your app.

* `MAILFROM` is set to a random value.
  This value is used as a `From` header when using [croncape](/docs/get-started/stacks/symfony/crons#use-croncape).

* `SYMFONY_IS_WORKER` is set to `1` when the container is running in the context of a worker
  (instead of the main application container).

* `SYMFONY_CACHE_DIR` (only available during the build hook execution):
  The absolute path to a subdirectory of your build cache directory.

  Note that the build cache directory is persisted between builds but **isn't** deployed.
  It’s a good place to store build artifacts, such as downloaded files that can be reused between builds.

  <Tip>
    This directory is shared by **all** builds on **all** branches.
    Make sure your [build hook](/docs/get-started/stacks/symfony/integration#hooks) accounts for that.
  </Tip>

  If you need to clear the build cache directory, run the `symfony upsun:project:clear-build-cache` command.

* `SYMFONY_PROJECT_DEFAULT_ROUTE_URL` (only defined at **runtime**): The default endpoint serving your project.
  Use this variable to avoid hard-coding domains that can be used to reach preview environments.
  Parts of the URL are also exposed as their own variables using the following syntax:
  `SYMFONY_PROJECT_DEFAULT_ROUTE_` followed by the name of the part (`SCHEME`, `DOMAIN`, `PORT`, and `PATH`).

  Guessing the default endpoint can prove difficult for multi-routes or multi-app projects.
  In such cases, the following preference order is used:

  1. Project-wide route defined only by `{default}` or `{all}` (no path)
  2. Project-wide route defined by `www.{default}` or `www.{all}` (no path)
  3. Route for the **current application** including `{default}` or `{all}` (might include a path)
  4. Route for the **current application** including `www.{default}` or `www.{all}` (might include a path)
  5. First route for the current application
  6. First route for the whole project

  When several routes match a rule, the first one wins, the user order is kept. There's no preference regarding protocols.

  <Tip>
    If you have a multi-app project containing several publicly reachable apps,
    you might need to determine the current application endpoint (for webhooks for example)
    and the project endpoint (to send emails for example).

    In this case, you can use an additional `SYMFONY_APPLICATION_DEFAULT_ROUTE_*` set of environment variables.
    The same rules are applied to determine their value, but only routes matching the current application are evaluated.
  </Tip>

## Service environment variables

When using the [Symfony integration](/docs/get-started/stacks/symfony/integration), information about services
are exposed via environment variables.

To list all of the exposed environment variables, run the following command:

```bash theme={null}
symfony ssh -- symfony var:export --multiline
```

Each exposed environment variable is prefixed by the relationship name.
For example, if you have the following [relationships](/docs/configure-apps/image-properties/relationships) in your configuration:

```yaml .upsun/config.yaml theme={null}
applications:
  myapp:
    relationships:
      database:
        service: securitydb
        endpoint: postgresql
```

The environment variables for the database service is prefixed by `DATABASE_`
which is the upper-cased version of the key defined in the relationship.
For example, you could have a `DATABASE_URL` environment variable.

Most environment variable names are derived from the relationship and service names.
But some are defined based on Symfony conventions, such as [`MAILER_DSN`](#emails).

<Warning>
  Environment variables aren't exposed when the build hook script is running
  as services aren't available during the [build process](/docs/core-concepts/build-deploy#the-build).
</Warning>

### Emails

The configuration is exposed via the following environment variables:

* `MAILER_ENABLED`: 1 if outgoing emails are enabled, 0 otherwise
* `MAILER_DSN`/`MAILER_URL`: The Symfony-compatible mailer URL
* `MAILER_HOST`: The SMTP server host
* `MAILER_PORT`: The SMTP server port
* `MAILER_TRANSPORT`: The SMTP transport mode (`smtp`)
* `MAILER_AUTH_MODE`: The SMTP auth mode (`plain`)
* `MAILER_USER`: The SMTP server user
* `MAILER_PASSWORD`: The SMTP server password

Symfony Mailer automatically uses the value of `MAILER_DSN`.

### HTTP

If your project has multiple apps,
the configuration is exposed via the following environment variables
(where `SOME_SERVICE` is the upper-cased version of the key defined in the relationship):

* `SOME_SERVICE_URL`: The full URL of the service
* `SOME_SERVICE_IP`: The HTTP service IP
* `SOME_SERVICE_PORT`: The HTTP service port
* `SOME_SERVICE_SCHEME`: The HTTP service scheme
* `SOME_SERVICE_HOST`: The HTTP service host

### MySQL/MariaDB

The [MySQL/MariaDB](/docs/add-services/mysql) configuration is exposed via the following environment variables
(where `DATABASE` is the upper-cased version of the key defined in the relationship above):

* `DATABASE_URL`: The database URL (in PHP or Go format depending on your app)
* `DATABASE_SERVER`: The database server
* `DATABASE_DRIVER`: The database driver
* `DATABASE_VERSION`: The database version
* `DATABASE_HOST`: The database host
* `DATABASE_PORT`: The database port
* `DATABASE_NAME`: The database name
* `DATABASE_DATABASE`: Alias for `DATABASE_NAME`
* `DATABASE_USERNAME`: The database username
* `DATABASE_PASSWORD`: The database password

<Note>
  <h4>Tip</h4>
  The database version and a default charset are included in the database URL.
  To override them, use the `DATABASE_VERSION` and `DATABASE_CHARSET` environment variables respectively.
</Note>

### PostgreSQL

The [PostgreSQL](/docs/add-services/postgresql) configuration is exposed via the following environment variables
(where `DATABASE` is the upper-cased version of the key defined in the relationship):

* `DATABASE_URL`: The database URL (in PHP or Go format depending on your app)
* `DATABASE_SERVER`: The database server
* `DATABASE_DRIVER`: The database driver
* `DATABASE_VERSION`: The database version
* `DATABASE_HOST`: The database host
* `DATABASE_PORT`: The database port
* `DATABASE_NAME`: The database name
* `DATABASE_DATABASE`: Alias for `DATABASE_NAME`
* `DATABASE_USERNAME`: The database username
* `DATABASE_PASSWORD`: The database password

<Note>
  <h4>Tip</h4>
  The database version and a default charset are included in the database URL.
  To override them, use the `DATABASE_VERSION` and `DATABASE_CHARSET` environment variables respectively.
</Note>

### Redis

The [Redis](/docs/add-services/redis) configuration is exposed via the following environment variables
(where `REDIS` is the upper-cased version of the key defined in the relationship):

* `REDIS_URL`: The Redis URL
* `REDIS_HOST`: The Redis host
* `REDIS_PORT`: The Redis port
* `REDIS_SCHEME`: The Redis scheme

### Memcached

The [Memcached](/docs/add-services/memcached) configuration is exposed via the following environment variables
(where `CACHE` is the upper-cased version of the key defined in the relationship):

* `CACHE_HOST`
* `CACHE_PORT`
* `CACHE_IP`

### Elasticsearch

The [Elasticsearch](/docs/add-services/elasticsearch) configuration is exposed via the following environment variables
(where `ELASTICSEARCH` is the upper-cased version of the key defined in the relationship):

* `ELASTICSEARCH_URL`: The full URL of the Elasticsearch service
* `ELASTICSEARCH_HOST`: The Elasticsearch host
* `ELASTICSEARCH_PORT`: The Elasticsearch port
* `ELASTICSEARCH_SCHEME`: The Elasticsearch protocol scheme (`http` or `https`)

### Solr

The [Apache Solr](/docs/add-services/solr) configuration is exposed via the following environment variables
(where `SOLR` is the upper-cased version of the key defined in the relationship):

* `SOLR_HOST`: The Solr host
* `SOLR_PORT`: The Solr port
* `SOLR_NAME`: The Solr name
* `SOLR_DATABASE`: An alias for `SOLR_NAME`

### RabbitMQ

The [RabbitMQ](/docs/add-services/rabbitmq) configuration is exposed via the following environment variables
(where `RABBITMQ` is the upper-cased version of the key defined in the relationship):

* `RABBITMQ_URL`: The RabbitMQ standardized URL
* `RABBITMQ_SERVER`: The RabbitMQ server
* `RABBITMQ_HOST`: The RabbitMQ host
* `RABBITMQ_PORT`: The RabbitMQ port
* `RABBITMQ_SCHEME`: The RabbitMQ scheme
* `RABBITMQ_USER`: The RabbitMQ username
* `RABBITMQ_USERNAME`: The RabbitMQ username
* `RABBITMQ_PASSWORD`: The RabbitMQ password

### MongoDB

The [MongoDB](/docs/add-services/mongodb) configuration is exposed via the following environment variables
(where `MONGODB` is the upper-cased version of the key defined in the relationship):

* `MONGODB_SERVER`
* `MONGODB_HOST`
* `MONGODB_PORT`
* `MONGODB_SCHEME`
* `MONGODB_NAME`
* `MONGODB_DATABASE`
* `MONGODB_USER`
* `MONGODB_USERNAME`
* `MONGODB_PASSWORD`

### InfluxDB

The [InfluxDB](/docs/add-services/influxdb) configuration is exposed via the following environment variables
(where `TIMEDB` is the upper-cased version of the key defined in the relationship):

* `TIMEDB_SCHEME`
* `TIMEDB_HOST`
* `TIMEDB_PORT`
* `TIMEDB_IP`

### Kafka

The [Apache Kafka](/docs/add-services/kafka) configuration is exposed via the following environment variables
(where `KAFKA` is the upper-cased version of the key defined in the relationship):

* `KAFKA_URL`
* `KAFKA_SCHEME`
* `KAFKA_HOST`
* `KAFKA_PORT`
* `KAFKA_IP`


# FAQ
Source: https://developer.upsun.com/docs/get-started/stacks/symfony/faq

Troubleshoot issues you might encounter using [Symfony](https://www.symfony.com/), a PHP framework on Upsun Cloud.


## Why is `DATABASE_URL` not defined during the build hook?

During the build hook, services are not available to avoid breaking the
application that is still live. That is why the Symfony integration does not
expose environment variables during the build hook.

The `cache:clear` command does not need to connect to the database by default,
except if you are using the Doctrine ORM and the database engine version is not
set in your configuration.

The version information can be set in your `.env` file or in the
`doctrine.yaml` configuration file. The only important pieces of information there are
the database engine and the version; everything else will be ignored.

Note that the environment variables are available in the deploy hook.

## How can I access my application logs?

To display the application log file (`/var/log/app.log` file), run the following command:

```bash theme={null}
symfony env:log app --tail
```

All the log messages generated by your app are sent to this `/var/log/app.log` file.
This includes language errors such as PHP errors, warnings, notices,
as well as uncaught exceptions.
The file also contains your application logs if you log on `stderr`.

Note that Upsun Cloud manages the `/var/log/app.log` file for you.
This is to prevent disks from getting filled and using very fast local drives instead of slower network disks.
Make sure your apps always output their logs to `stderr`.

If you use Monolog, add the following configuration to your `config/packages/prod/monolog.yaml` file:

```gitignore theme={null}
--- a/config/packages/prod/monolog.yaml
+++ b/config/packages/prod/monolog.yaml
@@ -11,7 +11,7 @@ monolog:
            members: [nested, buffer]
        nested:
            type: stream
-            path: "%kernel.logs_dir%/%kernel.environment%.log"
+            path: php://stderr
            level: debug
        buffer:
            type: buffer
```

<Warning>
  <h4>Warning</h4>
  If you log deprecations, make sure you **also** log them on `stderr`.
</Warning>

## What's this "Oops! An Error Occurred" message about?

The *Oops! An Error Occurred* message comes from your app and is automatically generated based on the Symfony error template.

### The server returned a "500 Internal Server Error"

<img alt="A 500 error page in production mode" />

If your app's working as expected locally but you see the previous error message on Upsun Cloud,
it usually means you have a configuration error or a missing dependency.

To fix this issue, search your application logs.
They likely contain an error message describing the root cause:

```bash theme={null}
symfony env:log app
  Reading log file azertyuiop-test-error-azerty--app@ssh.eu-5.platform.sh:/var/log/app.log
  [12-Jan-2026 11:22:08] NOTICE: fpm is running, pid 146
  [12-Jan-2026 11:22:08] NOTICE: ready to handle connections
  [12-Jan-2026 11:27:31] PHP Fatal error:  Uncaught Exception: [...]
  Stack trace: [...]
```

If the error occurs on a preview environment,
or on the main environment of a non-production project,
you can also enable Symfony's dev/debug mode to inspect the cause of the error:

```bash theme={null}
# Enable debug mode
symfony env:debug
# Disable debug mode
symfony env:debug --off
```

### The server returned a "404 Not Found"

By default, new Symfony apps come without controllers, which means there's no homepage to show.
As a result, when you run your project locally, the following welcome page is displayed:

<img alt="The default Symfony welcome page in development mode" />

But when you run your project on Upsun Cloud, the following error is displayed instead:

<img alt="A 404 error page in production mode" />

This is because Upsun Cloud runs in production mode, leading Symfony to show a generic 404 error.
To fix this issue, [create your first Symfony page](https://symfony.com/doc/current/page_creation.html).

If you've already created a custom homepage, make sure you perform the following actions:

1. Commit all your files.
2. Run the `symfony push` command and check that the deployment is successful.

## Other issues

For other issues unrelated to Symfony, see [Troubleshoot development](/docs/troubleshooting/general).


# Get started
Source: https://developer.upsun.com/docs/get-started/stacks/symfony/get-started

See how to get started deploying Symfony on Upsun Cloud.


Upsun Cloud is the official [Symfony](https://symfony.com/) PaaS.
This guide provides instructions for deploying, and working with, Symfony on Upsun Cloud.

<GuidesRequirements name="Symfony" />

<Note>
  The Symfony CLI wraps the [Upsun Cloud CLI](/cli) with added features related to Symfony.
  So when using Symfony, you can replace `upsun <command>` by `symfony upsun:<command>` in all of your commands.
</Note>

## 1. Create your Symfony app

To get familiar with Upsun Cloud, create a new Symfony project from scratch.
The present tutorial uses the [Symfony Demo](https://symfony.com/doc/current/setup.html#the-symfony-demo-application) app as an example :

```bash Terminal theme={null}
symfony new <PROJECT_NAME> --demo --upsun
cd <PROJECT_NAME>
```

The `--demo` flag pulls the [Symfony Demo skeleton](https://github.com/symfony/demo).<br />
The `--upsun` flag automatically generates the Upsun Cloud configuration file.

<Note>
  Alternatively, you can deploy an **existing Symfony project**.
  To do so, follow these steps:

  1. To generate a sensible default Upsun Cloud configuration,
     run the following command from within the project's directory:

     ```bash Terminal theme={null}
     symfony project:init --upsun
     ```

     This generates the `.upsun/config.yaml` and `php.ini` configuration files.

  2. Add and commit your changes:

     ```bash Terminal theme={null}
     git add .upsun/config.yaml php.ini
     git commit -m "Add Upsun Cloud configuration"
     ```
</Note>

## 2. Create your Upsun Cloud project

To create a project on Upsun Cloud, run the following command from within the project's directory:

```bash Terminal theme={null}
symfony upsun:create --title PROJECT_TITLE --set-remote
```

The `--set-remote` flag sets the new project as the remote for this repository.

<Note>
  <h4>Tip</h4>
  You can link any repository to an existing Upsun Cloud project using the following command:

  ```bash Terminal theme={null}
  symfony upsun:set-remote <PROJECT_ID>
  ```
</Note>

## 3. Deploy your project

To deploy your project, run the following command:

```bash Terminal theme={null}
symfony upsun:deploy
```

During deployment, the logs from the Upsun Cloud API are displayed in your terminal so you can monitor progress.
To stop the display of the logs **without interrupting the deployment**,
use `CTRL+C` in your terminal.
To go back to displaying the logs, run `symfony upsun:activity:log`.

Congratulations, your first Symfony app has been deployed on Upsun Cloud!

<Info>
  <h4>Tip</h4>
  Now that your app is deployed in production mode,
  you can define a custom domain for your live website.
  To do so, see how to [set up a custom domain on Upsun Cloud](/docs/administration/web/configure-project#domains),
  or run the following command:

  ```bash Terminal theme={null}
  symfony upsun:domain:add <YOUR_DOMAIN>
  ```
</Info>

## 4. Make changes to your project

Now that your project is deployed, you can start making changes to it.
For example, you might want to fix a bug or add a new feature.

In your project, the main branch always represents the production environment.
Other branches are for developing new features, fixing bugs, or updating the infrastructure.

To make changes to your project, follow these steps:

1. Create a new environment (a Git branch) to make changes without impacting production:

   ```bash Terminal theme={null}
   symfony upsun:branch feat-a
   ```

   This command creates a new local `feat-a` Git branch based on the main Git branch,
   and activates a related environment on Upsun Cloud.
   The new environment inherits the data (service data and assets) of its parent environment (the production environment here).

2. Make changes to your project.

   For example, if you created a Symfony Demo app,
   edit the `templates/default/homepage.html.twig` template and make the following visual changes:

   ```html {location="templates/default/homepage.html.twig", no-copy="true"} theme={null}
   {% block body %}
       <div class="page-header">
   -        <h1>{{ 'title.homepage'|trans|raw }}</h1>
   +        <h1>Welcome to the Upsun Cloud Demo</h1>
       </div>

       <div class="row">

   ```

3. Add and commit your changes:

   ```bash Terminal theme={null}
   git commit -a -m "Update text"
   ```

4. Deploy your changes to the `feat-a` environment:

   ```bash Terminal theme={null}
   symfony upsun:deploy
   ```

   Note that each environment has its own domain name.
   To view the domain name of your new environment, run the following command:

   ```bash Terminal theme={null}
   symfony upsun:url --primary
   ```

5. Iterate by changing the code, committing, and deploying.
   When satisfied with your changes, merge them to the main branch, deploy,
   and remove the feature branch:

   ```bash Terminal theme={null}
   git checkout main
   git merge feat-a
   symfony environment:delete feat-a
   git branch -d feat-a
   symfony upsun:deploy
   ```

   Note that deploying to production is fast because the image built for the `feat-a` environment is reused.

   For a long running branch, keep the code up-to-date with the main branch by using `git merge main` or `git rebase main`.
   Also, keep the data in sync with the production environment by using `symfony upsun:env:sync`.

## 5. Optional: Use a third-party Git provider

When you choose to use a third-party Git hosting service,
the Upsun Cloud Git repository becomes a read-only mirror of the third-party repository.
All your changes take place in the third-party repository.

Add an integration to your existing third-party repository:

* [BitBucket](/docs/integrations/source/bitbucket)
* [GitHub](/docs/integrations/source/github)
* [GitLab](/docs/integrations/source/gitlab)


# Deploy Symfony on Upsun Cloud
Source: https://developer.upsun.com/docs/get-started/stacks/symfony/index

Complete the last required steps to successfully deploy Symfony on Upsun Cloud.


<Info>
  Before you start, check out the [Upsun Cloud demo app](https://console.upsun.com/projects/create-project) and the main [Getting started guide](/docs/get-started/here).
  They provide all of the core concepts and common commands you need to know before using the materials below.
</Info>

## Guide

<CardGroup>
  <Card title="1. Get started" icon="rocket" href="/docs/get-started/stacks/symfony/get-started">
    Deploy your first Symfony app on Upsun Cloud.
  </Card>

  <Card title="2. Symfony integration" icon="puzzle" href="/docs/get-started/stacks/symfony/integration">
    Configure the Symfony integration.
  </Card>

  <Card title="3. Environment variables" icon="key" href="/docs/get-started/stacks/symfony/environment-variables">
    Configure environment variables for Symfony.
  </Card>

  <Card title="4. Workers" icon="cpu" href="/docs/get-started/stacks/symfony/workers">
    Configure workers for background processing.
  </Card>

  <Card title="5. Cron jobs" icon="clock" href="/docs/get-started/stacks/symfony/crons">
    Set up cron jobs for scheduled tasks.
  </Card>

  <Card title="6. Upsun Blackfire" icon="gauge" href="/docs/get-started/stacks/symfony/blackfire">
    Manage continuous observability with Upsun Blackfire.
  </Card>

  <Card title="7. Local development" icon="laptop" href="/docs/get-started/stacks/symfony/local">
    Set up your local development environment.
  </Card>

  <Card title="8. FAQ" icon="book-open" href="/docs/get-started/stacks/symfony/faq">
    Frequently asked questions.
  </Card>

  <Card title="9. Symfony CLI Tips" icon="terminal" href="/docs/get-started/stacks/symfony/symfony-cli-tips">
    Tips for using the Symfony CLI with Upsun Cloud.
  </Card>
</CardGroup>

## Further resources

### Documentation

* [PHP documentation](/docs/languages/php)

* [Extensions](/docs/languages/php/extensions)

* [Performance tuning](/docs/languages/php/tuning)

* [PHP-FPM sizing](/docs/languages/php/fpm)

* [Swoole on Upsun Cloud](/docs/languages/php/swoole)

* [Authenticated Composer](/docs/languages/php/composer-auth)

### Community content

* [Symfony topics](https://support.platform.sh/hc/en-us/search?utf8=%E2%9C%93\&query=symfony)

* [PHP topics](https://support.platform.sh/hc/en-us/search?utf8=%E2%9C%93\&query=php)

### Videos

* [Refactoring monolith to multi-app](https://youtu.be/5hApjWiTO1M?feature=shared)
* [Upsun Cloud: From zero to scaling hero](https://youtu.be/FEFBUomV5aY?feature=shared)


# Symfony integration
Source: https://developer.upsun.com/docs/get-started/stacks/symfony/integration

Learn how to use the Symfony integration for a better Upsun Cloud experience.


Symfony has a special integration with Upsun Cloud that makes it easier to use Upsun Cloud for Symfony projects.

**When using the Symfony integration, you are contributing financially to the Symfony project.**

The Symfony integration is automatically enabled when:

* You run the `symfony new` command with the `--upsun` option

* You run `symfony project:init --upsun` on an existing project to automatically
  generate the Upsun Cloud configuration

If you already have an Upsun Cloud configuration without the Symfony
integration, enable it by adding the following configuration:

```yaml .upsun/config.yaml theme={null}
applications:
  app:
    hooks:
      build: |
        set -x -e

        curl -fs https://get.symfony.com/cloud/configurator | bash

        # ...
```

The **configurator** enables the following integration:

* It installs some helper scripts that you can use as the [default build and deploy hook scripts](#hooks):
  * [`symfony-build`](#symfony-build)
  * [`symfony-deploy`](#symfony-deploy)
  * [`php-ext-install`](#php-ext-install)

* It adds some [extra tools](#tools)

* It defines [additional infrastructure environment
  variables](/docs/get-started/stacks/symfony/environment-variables#symfony-environment-variables) and
  [environment variables for all
  services](/docs/get-started/stacks/symfony/environment-variables#service-environment-variables)

## Tools

The **configurator** (`curl -fs https://get.symfony.com/cloud/configurator | bash`) is a script specially crafted for Upsun Cloud.
It ensures that projects are always using the latest version of the following tools:

* [croncape](/docs/get-started/stacks/symfony/crons#use-croncape) for cron feedback
* [Symfony CLI](https://symfony.com/download)
* [Composer](https://getcomposer.org/download/)

## Hooks

The `hooks` section defines the scripts that Upsun Cloud runs at specific times of an application lifecycle:

* The [build hook](/docs/configure-apps/hooks/hooks-comparison#build-hook) is run during the build process
* The [deploy hook](/docs/configure-apps/hooks/hooks-comparison#deploy-hook) is run during the deployment process
* The [post-deploy hook](/docs/configure-apps/hooks/hooks-comparison#post-deploy-hook) is run after the deploy hook,
  once the application container starts accepting connections

Here's the default `hooks` section optimized for Symfony projects:

```yaml .upsun/config.yaml theme={null}
applications:
  app:
    hooks:
      build: |
        set -x -e

        curl -s https://get.symfony.com/cloud/configurator | bash

        symfony-build

      deploy: |
        set -x -e

        symfony-deploy
```

<Note>
  <h4>Warning</h4>
  As each hook is executed as a single script, a hook is considered as failed only if the final command fails.
  To have your hooks fail on the first failed command, start your scripts with `set -e`.
</Note>

For more information, see [Hooks](/docs/configure-apps/hooks/hooks-comparison).

To gain a better understanding of how hooks relate to each other when building and deploying an app,
see the [Upsun Cloud philosophy](/docs/core-concepts/philosophy).

<Note>
  <h4>Tip</h4>
  During the `deploy` or `post_deploy` hooks, you can execute actions for a specific environment type only.
  To do so, in your `.upsun/config.yaml`file,
  use the `PLATFORM_ENVIRONMENT_TYPE` [environment variable](/docs/development/variables)) in a condition:

  ```yaml .upsun/config.yaml theme={null}
  applications:
    myapp:
      hooks:
        deploy: |
          if [ "PLATFORM_ENVIRONMENT_TYPE" != "production" ]; then
            symfony console app:dev:anonymize
          fi
  ```
</Note>

### symfony-build

**symfony-build** is the script that builds a Symfony app in an optimized way for Upsun Cloud.
Use it as the main build script in your `build` hook.

**symfony-build** performs the following actions:

* Removes the development frontend file (Symfony \<4)
* Installs PHP extensions through the [`php-ext-install` script](#php-ext-install)
* Installs application dependencies using Composer
* Optimizes the autoloader
* Builds the Symfony cache in an optimized way to limit the time it takes to deploy
* Installs the JavaScript dependencies via npm or Yarn
* Builds the production assets using Encore

To override the flags used by Composer, use the `$COMPOSER_FLAGS` environment variable:

```yaml .upsun/config.yaml theme={null}
applications:
  myapp:
    hooks:
      build: |
        set -x -e

        curl -s https://get.symfony.com/cloud/configurator | bash

        COMPOSER_FLAGS="--ignore-platform-reqs" symfony-build
```

When installing dependencies, the script automatically detects if the app is using npm or Yarn.

To disable the JavaScript dependencies and asset building,
set `NO_NPM` or `NO_YARN` to `1` depending on your package manager.

To customize Node/npm/Yarn behaviors,
prefix the `symfony-build` script with the following environment variables:

* `NODE_VERSION`:  to pinpoint the Node version that nvm is going to install.
  The default value is `--lts`.
* `YARN_FLAGS`: flags to pass to `yarn install`.
  There is no default value.

### symfony-deploy

Use **symfony-deploy** as the main deploy script in the `deploy` hook.
It only works if you're using the [`symfony-build` script](#symfony-build) in your `build` hook.

**symfony-deploy** performs the following actions:

* Replaces the Symfony cache with the cache generated during the build hook
* Migrates the database when the Doctrine migration bundle is used

### php-ext-install

You can use the **php-ext-install** script to compile and install PHP extensions
not provided out of the box by Upsun Cloud,
or when you need a specific version of an extension.
The script is written specifically for Upsun Cloud to ensure fast and reliable setup during the build step.

**php-ext-install** currently supports three ways of fetching sources:

* From [PECL](https://pecl.php.net/): `php-ext-install redis 5.3.2`
* From a URL: `php-ext-install redis https://github.com/phpredis/phpredis/archive/5.3.2.tar.gz`
* From a Git repository: `php-ext-install redis https://github.com/phpredis/phpredis.git 5.3.2`

To ensure your app can be built properly, run `php-ext-install` after the [configurator](#tools)
but before [symfony-build](#symfony-build):

```yaml .upsun/config.yaml theme={null}
applications:
  myapp:
    hooks:
      build: |
        set -x -e

        curl -s https://get.symfony.com/cloud/configurator | bash

        php-ext-install redis 5.3.2

        symfony-build
```

When installing [PECL](https://pecl.php.net/) PHP extensions, you can configure
them directly as *variables* instead:

```yaml .upsun/config.yaml theme={null}
applications:
  myapp:
    variables:
      php-ext:
        redis: 5.3.2
```

<Note>
  The source code is cached between builds so compilation is skipped if it's already been done.
  Changing the source of downloads or the version invalidates this cache.
</Note>

### Advanced Node configuration

If you need to use the Node installation setup by [symfony-build](#symfony-build),
use the following configuration:

```yaml .upsun/config.yaml theme={null}
applications:
  myapp:
    hooks:
      build: |
        set -x -e

        curl -s https://get.symfony.com/cloud/configurator | bash

        symfony-build

        # Setup everything to use the Node installation
        unset NPM_CONFIG_PREFIX
        export NVM_DIR="${SPLATFORM_APP_DIR}/.nvm"
        set +x && . "${NVM_DIR}/nvm.sh" use --lts && set -x
        # Starting from here, everything is setup to use the same Node
        yarn encore dev
```

If you want to use two different Node versions,
use the following configuration instead:

```yaml .upsun/config.yaml theme={null}
applications:
  myapp:
    hooks:
      build: |
        set -x -e

        curl -s https://get.symfony.com/cloud/configurator | bash

        symfony-build

        cd web/js_app
        unset NPM_CONFIG_PREFIX
        export NVM_DIR="${PLATFORM_APP_DIR}/.nvm"

        NODE_VERSION=8 yarn-install

        # Setup everything to use the Node installation
        set +x && . "${NVM_DIR}/nvm.sh" use 8 && set -x

        # Starting from here, everything is setup to use Node 8
        yarn build --environment=prod
```


# Local development
Source: https://developer.upsun.com/docs/get-started/stacks/symfony/local

Sync Upsun Cloud with your local environments to start contributing.


When you develop a Symfony project, a significant amount of work takes place
locally rather than on an active Upsun Cloud environment. You want to ensure
that the process of local development is as close as possible to a deployed
environment.

You can achieve this through various approaches. For example, you can use
Symfony Server with tethered data.

To do so, when testing changes locally, you can connect your locally running
Symfony Server to service containers on an active Upsun Cloud environment.

This methodology has several advantages:

* It avoids installing anything on your local machine but PHP;
* It ensures that you are using the same versions of all services on your local
  machine and in production.

<Warning>
  <h4>Warning</h4>
  Never use this method on the **main** environment as changes made on your local
  machine will impact production data.
</Warning>

## Before you begin

You need:

* A local copy of the repository for a project running on Upsun Cloud.
  You can clone an integrated source repository and set the remote branch.
  To do so, run `symfony cloud:project:set-remote PROJECT_ID`.
* The [Symfony CLI](https://symfony.com/download)

## 1. Start your Symfony Server

To start your [Symfony
Server](https://symfony.com/doc/current/setup/symfony_server.html) locally and
display your Symfony app, run the following command:

```bash theme={null}
symfony server:start -d
symfony open:local
```

This starts the Symfony Server and opens the app in your local browser.

## 2. Create the tethered connection

1. Create a new environment off of production:

   ```bash theme={null}
   symfony branch new-feature main
   ```

2. Open an SSH tunnel to the new environment's services:

   ```bash theme={null}
   symfony tunnel:open
   ```

   This command returns the addresses for SSH tunnels to all of your services:

   ```bash theme={null}
   symfony tunnel:open
       SSH tunnel opened to rediscache at: redis://127.0.0.1:30000
       SSH tunnel opened to database at: pgsql://main:main@127.0.0.1:30001/main

       Logs are written to: /Users/acmeUser/.platformsh/tunnels.log

       List tunnels with: symfony tunnels
       View tunnel details with: symfony tunnel:info
       Close tunnels with: symfony tunnel:close

       Save encoded tunnel details to the PLATFORM_RELATIONSHIPS variable using:
       export PLATFORM_RELATIONSHIPS="$(symfony tunnel:info --encode)"
   ```

3. To expose Upsun Cloud services to your Symfony app, run the following
   command:

   ```bash theme={null}
   symfony var:expose-from-tunnel
   ```

   This automatically configures your local Symfony app to use all your
   remote Upsun Cloud services (remote database, remote Redis component, etc.).

   To check that you're now using remote data and components from Upsun Cloud,
   reload your local app within your browser.

4. When you've finished your work,
   close the tunnels to your services by running the following command:

   ```bash theme={null}
   symfony var:expose-from-tunnel --off
   symfony tunnel:close --all -y
   ```


# Symfony CLI Tips
Source: https://developer.upsun.com/docs/get-started/stacks/symfony/symfony-cli-tips

Find out about the most useful commands when using the Symfony CLI.


The [Symfony CLI](https://symfony.com/download) allows you to interact with your project from the command line.

It wraps the [Upsun Cloud CLI](/cli) with added features related to Symfony.
So when using Symfony, you can replace `upsun <command>` by `symfony upsun:<command>` in all of your commands.

## Useful Symfony CLI commands

* Open the web administration Console:

  ```bash theme={null}
  symfony upsun:web
  ```

* Open the URL of the current environment:

  ```bash theme={null}
  symfony upsun:url
  ```

* Open an SSH connection to your environment:

  ```bash theme={null}
  symfony upsun:ssh
  ```

* Configure a project for Upsun Cloud:

  ```bash theme={null}
  symfony project:init --upsun
  ```

* Get a list of all the domains:

  ```bash theme={null}
  symfony upsun:domains
  ```

* Create a new environment:

  ```bash theme={null}
  symfony upsun:branch new-branch
  ```

* Get a list of all the environments:

  ```bash theme={null}
  symfony upsun:environments
  ```

* Push code to the current environment:

  ```bash theme={null}
  symfony upsun:push
  ```

* Get a list of all the active projects:

  ```bash theme={null}
  symfony upsun:projects
  ```

* Add a user to the project:

  ```bash theme={null}
  symfony upsun:user:add
  ```

* List variables:

  ```bash theme={null}
  symfony upsun:variables
  ```

### Useful commands when using Symfony with a database

* Create a local dump of the remote database:

  ```bash theme={null}
  symfony upsun:db:dump --relationship database
  ```

* Run an SQL query on the remote database:

  ```bash theme={null}
  symfony upsun:sql 'SHOW TABLES'
  ```

* Import a local SQL file into a remote database:

  ```bash theme={null}
  symfony upsun:sql < my_database_backup.sql
  ```


# Configure workers
Source: https://developer.upsun.com/docs/get-started/stacks/symfony/workers

Understand how to configure Symfony workers.


Workers (or consumers) are a great way to off-load processing in the background
to make an app as fast as possible.
You can implement workers in Symfony smoothly thanks to the [Messenger component](https://symfony.com/doc/current/components/messenger.html).

To deploy a worker, add an entry under the `workers` section [in your app configuration](/docs/configure-apps):

```yaml .upsun/config.yaml theme={null}
applications:
  myapp:
    workers:
      mails:
        commands:
          start: symfony console messenger:consume --time-limit=60 --memory-limit=128M
```

Note that the `symfony` binary is available when you use the [Symfony
integration](/docs/get-started/stacks/symfony/integration) in your Upsun Cloud app configuration.

On Upsun Cloud, worker containers run the exact same code as the web container.
The container image is built only once and deployed multiple times in its own container alongside the web container.
The *build* hook and dependencies might not vary but,
as these containers are independent, they can be customized the same way using common properties.
The values defined for the main container are used as default values.

<Note>
  <h4>Tip</h4>
  When the container is running in the context of a worker, the
  `SYMFONY_IS_WORKER` environment variable is defined and set to `1`.
</Note>

The `commands.start` key is required.
It specifies the command you can use to launch the application worker.
If the command specified by the `start` key terminates, it's restarted automatically.

For more information, see [Workers](/docs/configure-apps/image-properties/workers).

<Note>
  <h4>Warning</h4>
  Web and worker containers don't share mounts targets.
  So you can't share files between those containers using the filesystem.
  To share data between containers, use [services](/docs/add-services).
</Note>


# Glossary
Source: https://developer.upsun.com/docs/glossary/index



## Active environment

An environment that's deployed.
See how to [activate an environment](/docs/environments/deactivate-environment#reactivate-an-environment).

## Apex domain

An apex domain is a domain name that doesn't include a subdomain.

For example, `example.com` is an apex domain and `www.example.com` is a subdomain.

## Billing account

The legal entity or individual responsible for charges. Holds the name, country, and tax ID (companies and public sector only). One billing account can contain multiple billing profiles.

Account types:

* **Individual**: For personal use or trial accounts.
* **Company**: For incorporated companies or legal entities.
* **Public sector**: For government owned or funded entities.

## Billing profile

Belongs to one billing account and defines a payment method, currency, and billing address. Use it to map organizations to different invoicing setups — each profile is invoiced for the aggregate of all its linked organizations.

## Branch

Branching an environment means creating a new branch in the Git repository and an exact copy of that environment.

The new environment includes all of the parent environment's:

* Code
* Running services and their configuration (only copies, not the data)
* Data that's stored on disk (databases, uploaded files, and so on)

This means that when you branch an environment, you also branch the complete infrastructure.

When you branch an environment, three things happen:

* A new branch is created in Git.
* Your apps are rebuilt on the new branch, if necessary.
  (This is skipped if the same code with the same [variables](/docs/development/variables) has been built for any environment.)
* The new branch is deployed.

To create a new branch from an existing environment:

<Tabs>
  <Tab title="In the Console">
    1. Navigate to the environment you want to branch from.
    2. Click <BranchIcon /> **Branch**.
    3. Enter a name for the new branch.
    4. Select which environment type it should be.
    5. Click **Create branch**.
  </Tab>

  <Tab title="Using the CLI">
    Run:

    ```bash theme={null}
    upsun branch <NEW_BRANCH_NAME> <PARENT_BRANCH_NAME>
    ```

    To define the environment type for the branch, include `--type <ENVIRONMENT_TYPE>`.

    For example, to create the branch `develop` as a [preview environment](#preview-environment) ([development type](#environment-type)) from the branch `main`, run:

    ```bash theme={null}
    upsun branch develop main --type development
    ```
  </Tab>
</Tabs>

<Warning>
  <h4>Warning</h4>
  If you're using a [source integration](/docs/integrations/source),
  running this command results in an error stating that the operation is not available.

  This is because when a source integration is enabled,
  all branching and merging must be managed through the upstream repository to avoid merge conflicts.
</Warning>

## Cluster

Every active environment is deployed as a cluster,
which is a collection of independent containers
representing the different services that make up your web application.
That may include a database container, an Elasticsearch container,
a container for your application, and more.
They're always deployed together as a single unit.

## Deprecated versions

Older versions of languages and services eventually reach the end of their lives.
This means they stop getting security and other updates and may have security vulnerabilities.

When that happens, the versions in Upsun Cloud are deprecated.
This means you can still use them in your project, but they aren't fully secure.
It's also possible they'll stop working at some point.

If you're using a deprecated version, you should upgrade to a supported version as soon as possible.

## Drush

Drush is a command-line shell and scripting interface for Drupal.

## Endpoint

An endpoint is a named set of credentials to give access to other apps and services in your project.

## Environment

An [environment](/docs/environments) is a standalone copy of your site,
complete with code, data, and running services.
Your production environment comes from the [default branch](/docs/environments#default-environment)
and you can set up any other branch as a testing environment.

## Environment type

Upsun Cloud offers three environment types:

* Your **production environment** is your live site.
* A **development environment** is an isolated environment where you can safely develop new features without affecting production.
* A **staging environment** has a similar configuration to your production environment (but usually with less resources for cost optimization).
  It is useful to perform user acceptance testing in a production-like setting.

The phrase "[preview environment](#preview-environment)" can apply to both a development or staging environment,
as it merely describes a non-production environment.

Find out more about [user roles on each environment type](/docs/administration/users#environment-type-roles).

## First Project Incentive

To help you get started Upsun Cloud offers a monthly \$19 USD perk called the First Project Incentive.

### How do I apply this perk?

Whether you are a new or existing customer, ***no action is needed***. Just visit the billing section of your organization to see it applied.

### Why don't I see the full amount applied to my bill?

There are two reasons why you may not see the full amount applied to your bill.

1. The First Project Incentive is prorated. If your billing cycle has started mid-month, it will be reflected in the amount applied to your bill.
2. Your bill can never be less than $0. For example, if your total bill for the month is $10, the First Project Incentive will only apply up to \$10.

## Inactive environment

An environment that isn't deployed.
It has no data of its own and no running services.
If you reactivate it, it copies data from its parent.

See how to [deactivate an environment](/docs/environments/deactivate-environment).

## Live environment

A publicly accessible environment that's deployed from the Production branch under a production plan.

## MB

MB stands for megabyte, which means 1,000,000 bytes.
This unit is based on powers of 10.

Some reporting tools, such as those used by the [CLI](/cli),
use binary megabytes, also known as mebibytes and abbreviated as MiB.
This unit is based on powers of 2 and so 1 MiB equals 1024<sup>2</sup> or 1,048,576 bytes.
So 1 MB is less than 1 MiB.

So you may see differences in the numbers you configure for a disk (in MB)
and the values reported when you check disk size with tools that report in MiB.

## Merge

Merging an environment means copying any code changes from that environment into its parent environment
and redeploying the parent.

When you merge an environment, three things happen:

* Any code changes are merged via Git to the parent branch.
* Your apps rebuilt on the parent branch, if necessary.
  (This is skipped if the same code with the same [variables](/docs/development/variables) has been built for any environment.)
* The parent branch is deployed.

## PaaS

A Platform as a Service is an end-to-end hosting solution
that includes workflow tools, APIs, and other functionality above and beyond basic hosting.
The best example is Upsun Cloud(although we're a little biased).

## Preview environment

*Related terms: [Environment type](#environment-type)*

A preview environment is a non-production environment you can use to develop and/or test changes without affecting production.<br />
A preview environment can either be a development environment or a staging environment.
Preview environments have an identical software configuration to your production hardware but reduced hardware specs.
They are useful to perform user acceptance testing.

To learn more, see [Branch](#branch) also in this glossary.

## Production plan

## Project

A [project](/docs/projects) is the site that you’re working on.
Each project corresponds to one Git repository.
A project can contain multiple apps that run in their own isolated containers.
Each branch of a project can be deployed in its own environment.

## Route

A *route* is information that tells the Upsun Cloud [*router*](#router) how incoming web requests should be handled and which app container (or destination) should respond.

Routes are defined in the `.routes` top-level key in your project’s configuration file (for example, .upsun/config.yaml), and they map specific URLs or domains to one of the following actions:
Routes map specific URLs or domains to one of the following actions:

* `upstream` sends the request to a specific application container
* `redirect` sends the request to another route or URL (for example, redirecting `www` to non-www)
* `proxy` forwards requests to an external service outside the project

See the [examples](/docs/routes#examples) in the "Define routes" topic.

## Router

The *router* is the traffic director of your Upsun Cloud environment: it handles routing logic, basic caching, and traffic entry, and directs traffic to the correct container or containers based on the [*routes*](#route) that you define in your `.upsun/config.yaml` file.

## Sync

Synchronizing an environment means copying changes from a parent into a child environment
and then redeploying the child environment.
You can synchronize only the code, only the data (databases, files), or both.

Be aware that sync has the same process and same concerns as [backups](/docs/environments/backup#backups-and-downtime).

Sync is only available if your branch has no unmerged commits and can be fast-forwarded.

It's good practice to take a backup of your environment before synchronizing it.

## Transport Layer Security (TLS)

TLS is the successor of Secure Socket Layer (SSL).
It provides the cryptographic "S" in HTTPS.
It's often still referred to as SSL
even though it has mostly replaced SSL for online encrypted connections.

## Trial

When you create your first organization on Upsun Cloud, you are also activating your trial for that organization.
This trial grants you a certain amount of time and resources to try out the Upsun Cloud platform, and comes with the following restrictions:

1. A trial lasts for **15 days**, which starts automatically from creating your first organization.
2. A trial allows for **one (1)** active [project](#project) at a time.
3. For a trial project, the trial allows for **two (2)** [active environments](#active-environment).
4. A trial allows for a maximum of **one (1)** [task](/docs/configure-apps/tasks) definition, with only **one (1)** task instance able to run at a time.
5. [Object storage](/docs/manage-resources/object-storage) isn't available on trial projects.
6. At the organization level, there is a limit on the amount of [resources available to your project](/docs/manage-resources):

   * 4.5 CPUs
   * 12 GB RAM
   * 20 GB storage

   This cap applies to all resource usage, including tasks.

If your trial ends before adding payment details, there are additional things to keep in mind:

* When a trial expires, both the organization and the project are suspended.
* Projects where no code has been pushed are deleted **1 day** after a trial expires.
* Projects where code *has* been pushed are deleted **5 days** after the trial expires.
* Even with the trial expiration, organizations and user accounts are preserved, [rather than deleted](/docs/core-concepts/get-support#delete-your-account).


# Example: Discord
Source: https://developer.upsun.com/docs/integrations/activity/discord



The following example activity script posts a message to a Discord channel every time it's triggered.

To use it, follow these steps:

1. In your Discord administrative interface, [create a new Discord webhook](https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks).
   Give it a name and specify the channel where it should post messages.
   Copy the URL for the webhook.
2. Replace `DISCORD_URL` in the following script with your webhook URL.
3. Paste the code into a `.js` file.
4. Add it as a new [script integration](/docs/integrations/activity#installing).

   Specify which events should trigger it using the `--events` flag.
   Optionally specify environments with the `--environments` flag.

Now, any activities that meet the events/environment criteria you specified are reported to Discord.

Once you have it working, you're free to modify the code below as desired.
For more on the message format, see the [Discord webhook API reference](https://discord.com/developers/docs/resources/webhook#execute-webhook).

```javascript theme={null}
/**
 * Sends a message to Discord.
 *
 * To control what events trigger it, use the --events switch in
 * the Upsun Cloud CLI.
 *
 * @param {string} title
 *   The title of the message block to send.
 * @param {string} message
 *   The message body to send.
 */
function sendDiscordMessage(title, message) {
  const url = DISCORD_URL;

  const messageTitle =
    title + (new Date().getDay() === 5) ? " (On a Friday! :calendar:)" : "";

  const body = {
    content: messageTitle,
    embeds: [
      {
        description: message,
      },
    ],
  };

  const resp = fetch(url, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
  });

  if (!resp.ok) {
    console.log("Sending Discord message failed: " + resp.body.text());
  }
}

sendDiscordMessage(activity.text, activity.log);
```

Common properties you may want to send to Discord (in the last line of the script) include:

* `activity.text`: A brief, one-line statement of what happened.
* `activity.log`: The complete build and deploy log output, as it would be seen in the Console log screen.

For more properties, see the [activity reference](/docs/integrations/activity/reference).


# Activity scripts
Source: https://developer.upsun.com/docs/integrations/activity/index

Upsun Cloud supports custom scripts that can fire in response to any activity. These scripts allow you to take arbitrary actions in response to actions in your project, such as when it deploys, when a new branch is created, etc.


## Installing

Activity scripts are configured as integrations.
That means they're at the *project level*, not at the level of an individual environment.
While you can store the scripts in your Git repository for access, they have no effect there.

To install a new activity script, use [`integration:add` command](/cli/reference#integrationadd) from the [Upsun Cloud CLI](/cli).

```bash theme={null}
upsun integration:add --type script --file ./my_script.js
```

That installs and enables the `my_script.js` file as an activity script on the current project.

Don't run the `integration:add` command a second time,
or it installs a second integration with the same code.

## Updating

To update an existing activity script, follow these steps:

1. Get the activity script's ID by running the following command:

   ```bash theme={null}
   upsun integrations
   ```

   This returns something like the following:

   ```bash theme={null}
   +---------------+--------------+--------------+
   | ID            | Type         | Summary      |
   +---------------+--------------+--------------+
   | nadbowmhd67do | script       | ...          |
   | rcqf6b69jdcx6 | health.email | From:        |
   |               |              | To: #admins  |
   +---------------+--------------+--------------+
   ```

2. Update the integration by running the following command:

   ```bash theme={null}
   upsun integration:update --file ./my_script.js <SCRIPT_ID>
   ```

   This [`integration:update` command](/cli/reference#integrationupdate) updates the integration in place, permanently overwriting the previous version.

3. Test the activity script update by [triggering a redeployment](/cli/reference#environmentredeploy) with the following command:

   ```bash theme={null}
   upsun redeploy
   ```

## Removing

To disable an activity script, follow these steps:

1. Get the activity script's ID by running the following command:

   ```bash theme={null}
   upsun integrations
   ```

   This returns something like the following:

   ```bash theme={null}
   +---------------+--------------+--------------+
   | ID            | Type         | Summary      |
   +---------------+--------------+--------------+
   | nadbowmhd67do | script       | ...          |
   | rcqf6b69jdcx6 | health.email | From:        |
   |               |              | To: #admins  |
   +---------------+--------------+--------------+
   ```

2. [Delete the integration](/cli/reference#integrationdelete) by running the following command:

   ```bash theme={null}
   upsun integration:delete <SCRIPT_ID>
   ```

## Debugging

Get activity logs by running the following command:

```bash theme={null}
upsun integration:activities
```

Every time your activity script runs it generates a new log entry, including the output from the script.
Any output produced by `console.log` is available in the activity log, which is the recommended way to debug scripts.

See the [activity log](/docs/integrations/overview#debug-integrations) documentation for further details.

To get a more readable output of a variable you're trying to debug, you can make `JSON.stringify` use human-friendly formatting.

```javascript theme={null}
console.log(JSON.stringify(project, null, 2));
```

## Configuring scripts

There are many types of activity to which a script could respond.
By default, it will activate only after a successful `git push` operation.
That trigger is configurable via command line switches when adding or updating a script.

For example, to have a script trigger any time an environment is activated or deactivated, run:

```bash theme={null}
upsun integration:update --events='environment.activate,environment.deactivate' <SCRIPT_ID>
```

A complete list of possible events is available in the [Activity script type documentation](/docs/integrations/activity/reference#type).
Any of those Activity Script types can be added to the `--events=event1,event2,...` option.

Scripts can also trigger only when an action reaches a [given state](/docs/integrations/activity/reference#state), such as `pending`, `in_progress`, `complete`, `cancelled`, or `scheduled`.
The default is only when they reach `complete`.
To have a script execute when a synchronize action first starts, for example, you would run:

```bash theme={null}
upsun integration:update --events=environment.synchronize --states=in_progress <SCRIPT_ID>
```

It's also possible to restrict scripts to certain environments by name.
Most commonly, that's used to have them execute only for your production environment or for all other environments.

The following example executes only for backup actions on the `production` environment:

```bash theme={null}
upsun integration:update --events=environment.backup --environments=production <SCRIPT_ID>
```

As a general rule, it's better to have an activity script only execute on the specific events and branches you're interested in
rather than firing on all activities and then filtering out undesired use cases in the script itself.

## Activity script variables

Some activities don't have access to [project and environment variables](/docs/development/variables#variable-types).
In this case, to avoid hardcoding sensitive variables (such as API tokens) and therefore prevent security breaches,
add a variable to your activity script.

You can add activity script variables through the Upsun Cloud CLI.
Activity script variables are only visible in the activity script itself,
inside the `variables` variable.

### Add an activity script variable

To add a variable to your activity script at the integration level,
use the following `POST` request:

```bash theme={null}
POST /api/projects/<PROJECT_ID>/integrations/<INTEGRATION_ID>/variables
```

You get a payload similar to the following:

```json theme={null}
{
  "name": "string",
  "attributes": {
    "property1": "string",
    "property2": "string"
  },
  "value": "string",
  "is_json": true,
  "is_sensitive": true
}
```

### Delete or patch an activity script variable

To delete an activity script variable,
use the following `DELETE` request:

```
DELETE /api/projects/<PROJECT_ID>/integrations/<INTEGRATION_ID>/variables
```

You can also patch your activity script variable.
To do so, send the same request using the `PATCH` method instead of the `DELETE` one.

### List an activity script variable

To list all your activity script variables at the integration level,
use the following `GET` request:

```
GET /api/projects/<PROJECT_ID>/integrations/<INTEGRATION_ID>/variables
```

## Available APIs

Activity scripts can be written in ES2021 and don't support installing additional packages.
There are a series of [utility functions you can reuse](/docs/integrations/activity/utility)
as well as the following libraries, APIs, and global variables to facilitate building out custom functionality.

### `underscore.js`

[`Underscore.js`](https://github.com/jashkenas/underscore) is available out-of-the-box to make writing Activity scripts more pleasant.
See [Underscore's documentation](https://underscorejs.org/) for available functions and utilities.

### `activity`

Every activity script has a global variable `activity` that contains detailed information about the activity,
including embedded, JSON-ified versions of the routes configuration and relevant `.upsun/config.yaml` files.
The `activity` variable is the same as the [webhook payload](/docs/integrations/activity/webhooks).
See the documentation there for details and a complete example.

Several of the utility functions below work by pulling out common portions of the `activity` object.

### `project`

The `project` global variable includes information about the project subscription itself.
That includes its ID and name, how many users are associated with the project, its SSH public key, and various other values.
An example of this object is below:

```json theme={null}
{
  "attributes": {},
  "created_at": "2026-03-15T19:50:09.514267+00:00",
  "default_domain": null,
  "description": "",
  "id": "azertyuiopqsdfghjklm",
  "owner": "...",
  "region": "eu-1.upsun.com",
  "repository": {
    "client_ssh_key": "ssh-rsa ...",
    "url": "azertyuiopqsdfghjklm@git.eu-1.upsun.com:kqyhl5f5nuzky.git"
  },
  "status": {
    "code": "provisioned",
    "message": "ok"
  },
  "subscription": {
    "environments": 3,
    "included_users": 1,
    "license_uri": "...",
    "plan": "development",
    "restricted": false,
    "storage": 5120,
    "subscription_management_uri": "...",
    "suspended": false,
    "user_licenses": 1
  },
  "timezone": "Europe/Dublin",
  "title": "Activity script examples",
  "updated_at": "2026-04-21T17:15:35.526498+00:00"
}
```

### Storage API

Activity scripts have access to a limited key/value storage API to persist values from one execution to another.
The API is similar to the JavaScript `LocalStorage` API.

```javascript theme={null}
// Access the storage API.
// It isn't pre-required.
var storage = require("storage");

// Retrieve a stored value. If the value isn't set it will return null.
var counter = storage.get('counter') || 0;

if (counter) {
    // Generate debug output.
    console.log("Counter is: " + counter);
}

// Write a value into the storage. Only string-safe values are supported.
// To save an object or array, run JSON.stringify() on it first.
storage.set('counter', counter + 1);

// Remove a value completely.
storage.remove('counter');

// Remove all values in storage, unconditionally.
storage.clear();
```

### Fetch API

Activity scripts support a modified version of the browser "Fetch API" for issuing HTTP requests.
Unlike the typical browser version, however, they only support synchronous requests.
That means the return value of `fetch()` is a `Response`, not a `Promise` for one.
The returned `Response` is also a bit different: only the `ok`, `status` and `statusText` properties
as well as the `text` and `json` methods are available.
Note that because of the synchronous nature of our `fetch` implementation,
the `Response.text` and `Response.json` methods are also synchronous,
so they directly return a `string` and an `object`, respectively.
The API is otherwise essentially the same as that [in the MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch).

For instance, this example sends a GET request every time it executes:

```javascript theme={null}
var resp = fetch("http://example.com/site-deployed");

// The fetch call above being synchronous, we can directly access resp properties.
// resp.ok is true if the response was a 2xx, false otherwise.
if (!resp.ok) {
    console.log("Well that didn't work.");
}
```

While this example sends a POST request with a JSON string as the body:

```javascript theme={null}
var body = JSON.stringify({
  "some": "value",
});

var resp = fetch("http://example.com/", {
    method: "POST",
    headers: {
        'Content-Type': 'application/json',
    },
    body: body,
  }
)
if (!resp.ok) {
    console.log("Couldn't POST.");
} else {
  // resp.json() is synchronous so this will log an object, not `Promise { <pending> }`
  console.log(resp.json());
}
```

For more `fetch()` options, see the [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch).

### Cryptographic API

A minimalist cryptographic API is also available to activity scripts.
Its main use is for signing requests to 3rd party APIs.

The `crypto.createHmac()` function allows you to create a secure HMAC hash and digest.

```javascript theme={null}
var h = crypto.createHmac("sha256", "foo");
h.update("bar");
h.digest("hex")
```

* The available hashing functions are `'sha256'`, `'sha1'` and `'md5'` as hashing functions.
* The available digest formats are `'base64'`, `'hex'` or `''` (empty).
  An empty digest will yield a byte string.

For example, if you wanted to call an AWS API, you would calculate the signature like so:

```Javascript theme={null}
function HMAC(key, value) {
  var h = crypto.createHmac("sha256", key);
  h.update(value);
  return h.digest();
}
var kSecret = "wJalrXUtnFEMI/K7MDENG+bPxRfiCYEXAMPLEKEY";
HMAC(HMAC(HMAC(HMAC("AWS4" + kSecret,"20260830"),"us-east-1"),"iam"),"aws4_request");
```

> Example taken from the [AWS documentation for signing API requests](https://docs.aws.amazon.com/general/latest/gr/sigv4-calculate-signature.html).


# Activity reference
Source: https://developer.upsun.com/docs/integrations/activity/reference

A reference of the properties found in various activities.

Activities log changes to your project,
including when you deploy your app,
when you [push code](#push), and when a [cron job is run](#cron).

To automate your workflows, you can parse and react to the activity's JSON object
through [activity scripts](/docs/integrations/activity).

## Activity schema

Every activity has a corresponding JSON object containing all information for that activity,
including timestamps, configuration, and sometimes logs.
In practice, you can ignore much of the JSON object's content.
The most commonly used values are documented in this reference.

The response differs depending on the activity and doesn't always include all fields.

### Example response

The following is a shortened example of a response for an [environment sync activity](/docs/glossary#sync).
You can also see [complete examples of responses](#examples).

### `id`

A unique `id` value to identify the activity itself.

### `*_at`

`created_at`, `started_at`, `updated_at`, `cancelled_at`, `completed_at`, and `expires_at` are all timestamps in UTC.
For when a given activity occurred, use `completed_at`.
You can use these properties to calculate the duration of the activity.
To calculate the timing for steps in the activity, see the [`timings` property](#timings).

### `parameters`

The `parameters` property includes detailed information about what triggered the activity,
such as the user, the impacted environment, the git commits, or the cron commands.
The response changes based on the activity.

### `project`

The ID of the project in which the activity took place.
Use this value to distinguish multiple projects sent the same URL.

Different from [`project` activities](#type).

### `type`

The type of the activity in one of the following categories:

* [Project](#project-activity-types)
* [Environment](#environment-activity-types)
* [Integration](#integration-activity-types)
* [Maintenance](#maintenance-activity-types)

#### `project` activity types

Activities that happened on a given project.
The following table presents the possible activity types:

| Name | Description |
| - | - |
| `project.clear_build_cache` | The build cache is cleared. |
| `project.create` | A new project is created. |
| `project.metrics.enable` | A metric from the [continuous profiling](/docs/observability) has been enabled. |
| `project.metrics.update` | A metric from the [continuous profiling](/docs/observability) has been updated. |
| `project.metrics.disable` | A metric from the [continuous profiling](/docs/observability) has been disabled. |
| `project.modify.title` | The project title has changed. |
| `project.variable.create` | A new [project variable](/docs/administration/web/configure-project#variables) has been created. The value is visible only if the variable is not [set as sensitive](/docs/development/variables/set-variables#variable-options). |
| `project.variable.delete` | A [project variable](/docs/administration/web/configure-project#variables) has been deleted. |
| `project.variable.update` | A [project variable](/docs/administration/web/configure-project#variables) has been modified. |

#### `environment` activity types

Activities that happened on an environment.
The following table presents the possible activity types:

| Name | Description |
| - | - |
| `environment.activate` | The environment has been made [active](/docs/glossary#active-environment). |
| `environment.backup` | A user triggered a [backup](/docs/environments/backup). |
| `environment.backup.delete` | A user deleted a [backup](/docs/environments/backup). |
| `environment.branch` | A [new branch](/docs/environments#create-environments) has been created via the CLI, Console, or API. A branch created via Git shows up as `environment.push`. |
| `environment.certificate.renewal` | An environment's SSL certificate has been [renewed](/docs/routes/https#certificate-renewals). |
| `environment.cron` | A [cron job](/docs/configure-apps/image-properties/crons) has completed. |
| `environment.deactivate` | An environment has been made [inactive](/docs/glossary#inactive-environment). |
| `environment.delete` | An environment's code was deleted through Git. |
| `environment.domain.create` | A new [domain](/docs/administration/web/configure-project#domains) has been associated with the environment. |
| `environment.domain.delete` | A [domain](/docs/administration/web/configure-project#domains) associated with the environment has been removed. |
| `environment.domain.update` | A [domain](/docs/administration/web/configure-project#domains) associated with the environment has been updated, such as having its SSL certificate modified. |
| `environment.initialize` | The [default branch](/docs/environments#default-environment) of the project has just been initialized with its first commit. |
| `environment.merge` | An environment was [merged](/docs/glossary#merge) through the CLI, Console, or API. A basic Git merge doesn't trigger this activity. |
| `environment.merge-pr` | A Pull Request/Merge Request was merged through the CLI, Console, or API. A basic Git merge doesn't trigger this activity. |
| `environment.operation` | A [source operation](/docs/configure-apps/runtime-operations) has been triggered |
| `environment.pause` | An environment has been [paused](/docs/environments#pause-an-environment). |
| `environment.push` | A user [pushed](/cli/reference#environmentpush) code to a branch, either existing or new. |
| `environment.redeploy` | An environment was [redeployed](/cli/reference#environmentredeploy). |
| `environment.restore` | A user restored a [backup](/docs/environments/backup). |
| `environment.resume` | An inactive environment was [resumed](/docs/environments#resume-a-paused-environment) |
| `environment.resources.update` | The resources allocated to the environment [have been updated](/docs/manage-resources/adjust-resources). |
| `environment.route.create` | A new [route](/docs/administration/web/configure-environment#routes) has been created through the API. Edits made using Git to the `.upsun/config.yaml` file don't trigger this activity. |
| `environment.route.delete` | A [route](/docs/administration/web/configure-environment#routes) has been deleted through the API. Edits made using Git to the `.upsun/config.yaml` file don't trigger this activity. |
| `environment.route.update` | A [route](/docs/administration/web/configure-environment#routes) has been modified through the API. Edits made using Git to the `.upsun/config.yaml` file don't trigger this activity. |
| `environment.source-operation` | A [source operation](/docs/configure-apps/source-operations) has been triggered. |
| `environment.synchronize` | An environment has had its data and/or code replaced with the data and/or code from its parent environment. |
| `environment.task` | A [task](/docs/configure-apps/tasks) run has completed. |
| `environment.update.http_access` | [HTTP access rules](/docs/administration/web/configure-environment#http-access-control) for an environment have been modified. |
| `environment.update.restrict_robots` | The option to [hide from search engines](/docs/environments/search-engine-visibility) has been enabled or disabled for an environment. |
| `environment.update.smtp` | Email sending has been enabled or disabled for an environment. |
| `environment.variable.create` | A [new variable](/docs/development/variables/set-variables#variable-options) has been created. The value is visible only if the variable is not [set as sensitive](/docs/development/variables/set-variables#variable-options). |
| `environment.variable.delete` | A [variable](/docs/development/variables/set-variables#variable-options) has been deleted. |
| `environment.variable.update` | A [variable](/docs/development/variables/set-variables#variable-options) has been modified. |

#### `integration` activity types

Activities that relate to an integration.
The following table presents the possible activity types:

| Name | Description |
| - | - |
| `integration.bitbucket.fetch` | A fetch has been triggered on your [Bitbucket Cloud](/docs/integrations/source/bitbucket#bitbucket-cloud) repository. |
| `integration.bitbucket.register_hooks` | An integration hook has been registered with [Bitbucket Cloud](/docs/integrations/source/bitbucket#bitbucket-cloud). |
| `integration.bitbucket_server.fetch` | A fetch has been triggered on your [Bitbucket Server](/docs/integrations/source/bitbucket#bitbucket-server) repository. |
| `integration.bitbucket_server.register_hooks` | An integration hook has been registered with [Bitbucket Server](/docs/integrations/source/bitbucket#bitbucket-server). |
| `integration.github.fetch` | A fetch has been triggered on your [GitHub](/docs/integrations/source/github) repository. |
| `integration.gitlab.fetch` | A fetch has been triggered on your [GitLab](/docs/integrations/source/gitlab) repository. |
| `integration.health.email` | A [health notification](/docs/integrations/notifications) was sent by email. |
| `integration.health.pagerduty` | A [health notification](/docs/integrations/notifications) was sent to PagerDuty. |
| `integration.health.slack` | A [health notification](/docs/integrations/notifications) was sent to Slack. |
| `integration.health.webhook` | A [health notification](/docs/integrations/notifications) was sent to a webhook. |
| `integration.script` | An [activity script](/docs/integrations/activity) has been triggered. |
| `integration.webhook` | A [webhook](/docs/integrations/activity/webhooks) was triggered. |

#### `maintenance` activity types

Activities that relate to a maintenance.
The following table presents the possible types:

| Name | Description |
| - | - |
| `maintenance.upgrade` | An upgrade is triggered for API Server and Metrics Server |
| `environment.maintenance.redeploy` | A [maintenance window](/docs/core-concepts/build-deploy#maintenance-window) redeploys an environment to apply pending service image updates |

### `environments`

An array listing the environments that were involved in the activity.
It's usually only a single value representing one environment.

### `state`

The current state of the activity.
Its value can be `pending`, `in_progress`, `complete`, `cancelled`, or `scheduled`.

### `completion_percent`

What percentage of the activity is complete.

### `result`

Whether or not the activity completed successfully.
If it did, the value is `success`.
Note that certain activities, such as deploy hooks,
can be marked as successful activities even if some commands failed.

### `timings`

The amount of time required by the activity.

It can include the following properties:

| Name | Description |
| - | - |
| `wait` | The delay if a command is set to wait before being executed. |
| `build` | The execution time for the build hook. |
| `deploy` | The execution time for the deploy hook. |
| `execute` | The execution time for your script or cron job. |

### `log`

A human-friendly record of what happened in the activity.
The log shouldn't be parsed for data as its structure isn't guaranteed.

### `description`

A short machine-readable description of the activity.

### `text`

A short human-readable description of the activity.

### `payload`

Contains settings and details related to the completed activity.
Its content varies based on the activity type.

| Name | Description |
| - | - |
| `payload.user` | The user that triggered the activity. For details on its properties, see the [`user` payload](#user-payload). |
| `payload.environment` | The environment affected by the activity. For details on its properties, see the [`environment` payload](#environment-payload). |
| `payload.commits` | A list of changes with their Git metadata. |
| `payload.commits_count` | The number of Git commits. |
| `payload.deployment` | Information about the deployed environment. For details on its properties, see the [`deployment` payload](#deployment-payload). |
| `payload.project` | Information about the project. For details on its properties, see the [`project` payload](#project-payload). |

#### `user` payload

Contains information about the Upsun Cloud user that triggered the activity.

| Name | Description |
| - | - |
| `payload.user.created_at` | The date the user was created. |
| `payload.user.display_name` | The user's name in a human-friendly format. |
| `payload.user.id` | The user's ID. |
| `payload.user.updated_at` | The date the user was last updated. |

#### `environment` payload

Contains information about the environment associated with the activity,
including its settings, state, and deployment.
The following table presents the most notable properties of the environment:

| Name | Description |
| - | - |
| `payload.environment.name` | The environment name. |
| `payload.environment.type` | The [environment type](/docs/administration/users#environment-type-roles). |
| `payload.environment.head_commit` | The ID of the environment's latest Git commit. |
| `payload.environment.edge_hostname` | The URL you should target when setting up a [custom domain](/docs/domains/steps). |

Different from [`environment` activities](#type).

#### `project` payload

Contains information about the project associated with the activity,
including plan details, timezone, and region.
The following table presents the most notable properties of the project:

| Name | Description |
| - | - |
| `payload.project.timezone` | Your project's [timezone](/docs/projects/change-project-timezone). |
| `payload.project.region` | Your project's [region](/docs/development/regions#regions). |
| `payload.project.title` | Your project's name. |
| `payload.project.subscription` | All of the details about your project's [plan](/docs/administration/pricing). |

Different from [`project` activities](#type).

#### `deployment` payload

Contains information about the deployed environment, if one is associated with the activity.
The following table presents the most notable properties of the deployment:

| Name | Description |
| - | - |
| `payload.deployment.routes` | All the URLs connected to the environment. The list includes redirects. To exclude redirects, find objects whose `type` is `upstream`. |
| `payload.deployment.services` | All the services on your environment. |
| `payload.deployment.variables` | All the [variables for the environment](/docs/development/variables). |

The `payload.deployment` property includes the configuration extracted from the following sources:

* Your [app configuration](/docs/configure-apps)
* Your [routes](/docs/routes)
* Your [services](/docs/add-services)

## Maximum activities and parallelism

Project activities are distributed across separate queues,
which enables *two* simultaneous activities to occur in parallel across your environments.
For a given environment, only one activity can run at a time.
Those queues include the following types of activities:

| Name | Description |
| - | - |
| `default` | The most common activities on repositories (pushes, merges) and environments (syncs, redeployments). |
| `integrations` | Source and webhook integration activities. |
| `backup` | Backup activities. |
| `cron` | Cron activities. |

Production activities are prioritized across all queues.
When an activity for the production environment is triggered, it's placed at the top of the queue.
This makes it unlikely that activities on preview environments block activities for the production environment for long,
though there may be a temporary wait.

## Examples

The response is often usually long, so the following examples are shortened using ellipses.
Remember that the response differs depending on the activity and not all fields are always available.

To test responses, [set up a webhook](/docs/integrations/activity/webhooks#setup).

### Cron

When a cron job is triggered, the activity contains all the [job's information](/docs/configure-apps/image-properties/crons).
The following example response was triggered by a setting
where the cron is scheduled to run every five minutes (`5 * * * *`)
with the command `sleep 60 && echo sleep-60-finished && date` and times out after 86,400 seconds.

To get details about the configured cron job, see the `parameters` property:

```json {no-copy="true"} theme={null}
...
  "parameters": {
    "user": "admin",
    "cluster": "abcdefgh1234567-main-abcd123",
    "environment": "main",
    "application": "app",
    "cron": "saybye",
    "spec": {
      "spec": "5 * * * *",
      "commands": {
        "start": "sleep 60 && echo sleep-60-finished && date",
        "stop": null
      },
      "shutdown_timeout": null,
      "timeout": 86400
    }
...
```

The following example shows the full activity response to a cron job:

```json {no-copy="true"} theme={null}
{
  "id": "ypalrypnezbye",
  "_links": {
    "self": {
      "href": "https://eu-3.upsun.com/api/projects/abcdefgh1234567/activities/ypalrypnezbye"
    },
    "log": {
      "href": "/api/projects/abcdefgh1234567/activities/ypalrypnezbye/log"
    }
  },
  "created_at": "2026-12-13T16:06:08.081312+00:00",
  "updated_at": null,
  "type": "environment.cron",
  "parameters": {
    "user": "admin",
    "cluster": "abcdefgh1234567-main-abcd123",
    "environment": "main",
    "application": "app",
    "cron": "saybye",
    "spec": {
      "spec": "5 * * * *",
      "commands": {
        "start": "sleep 60 && echo sleep-60-finished && date",
        "stop": null
      },
      "shutdown_timeout": null,
      "timeout": 86400
    }
  },
  "project": "abcdefgh1234567",
  "environments": [
    "main"
  ],
  "state": "complete",
  "result": "success",
  "started_at": "2026-12-13T16:06:08.258090+00:00",
  "completed_at": "2026-12-13T16:07:09.658339+00:00",
  "completion_percent": 100,
  "cancelled_at": null,
  "timings": {
    "wait": 0,
    "execute": 61.244
  },
  "log": "hello world\nTue Jan 01 16:07:09 UTC 2026",
  "payload": {
    "user": {
      "id": "admin",
      "created_at": "2026-12-13T16:06:08.066085+00:00",
      "updated_at": null,
      "display_name": "Upsun Cloud Bot"
    },
    "project": {
      "id": "abcdefgh1234567",
      "created_at": "2026-03-22T15:47:28.739099+00:00",
      "updated_at": "2026-12-01T09:42:19.860188+00:00",
      "attributes": {},
      "title": "php-test",
      "description": "",
      "owner": "c9926428-44dc-4b10-be03-a26dd43b44c1",
      "namespace": "upsun",
      "organization": "01FF4NBNVMMDWP1NVK0G4EGJW0",
      "default_branch": "main",
      "status": {
        "code": "provisioned",
        "message": "ok"
      },
      "timezone": "Europe/Dublin",
      "region": "eu-3.upsun.com",
      "repository": {
        "url": "abcdefgh1234567@git.eu-3.upsun.com:abcdefgh1234567.git",
        "client_ssh_key": "ssh-rsa aaaaaaabbbbbbbcccccccddddddd abcdefgh1234567@upsun"
      },
      "default_domain": null,
      "subscription": {
        "license_uri": "https://accounts.upsun.com/api/v1/licenses/2291467",
        "plan": "development",
        "environments": 3,
        "storage": 5120,
        "included_users": 1,
        "subscription_management_uri": "https://console.upsun.com-/users/abcd12345/billing/plan/12345678",
        "restricted": false,
        "suspended": false,
        "user_licenses": 1
      }
    },
    "environment": {
      "id": "main",
      "created_at": "2026-03-22T15:47:43.750880+00:00",
      "updated_at": "2026-11-29T16:16:37.085719+00:00",
      "name": "main",
      "machine_name": "main-abcd123",
      "title": "Main",
      "attributes": {},
      "type": "production",
      "parent": null,
      "default_domain": null,
      "clone_parent_on_create": true,
      "deployment_target": "local",
      "is_pr": false,
      "status": "active",
      "enable_smtp": true,
      "restrict_robots": true,
      "edge_hostname": "main-abcd123-abcdefgh1234567.eu-3.platformsh.site",
      "deployment_state": {
        "last_deployment_successful": true,
        "last_deployment_at": "2026-11-29T16:16:37.085609+00:00",
        "crons": {
          "enabled": true,
          "status": "running"
        }
      },
      "resources_overrides": {},
      "last_active_at": "2026-12-13T15:07:10.862854+00:00",
      "last_backup_at": null,
      "project": "abcdefgh1234567",
      "is_main": true,
      "is_dirty": false,
      "has_code": true,
      "head_commit": "6aac318907b50252976c47e4e62ed95d438af0ea",
      "merge_info": {
        "commits_ahead": 0,
        "commits_behind": 0,
        "parent_ref": null
      },
      "has_deployment": true
    },
    "cron": "saybye"
  },
  "description": "<user data-id=\"admin\">Upsun Cloud Bot</user> ran cron <strong>saybye</strong>",
  "text": "Upsun Cloud Bot ran cron **saybye**",
  "expires_at": "2026-01-12T16:06:08.081293+00:00"
}
```

### Push

A push activity contains several properties.
The `commits` property contains everything related to the Git push that triggered the activity:

```json {no-copy="true"} theme={null}
...
    "commits": [
      {
        "sha": "2bab04e050279ac078d5d34016f5dd9c466e948d",
        "author": {
          "email": "cloeweber@example.com",
          "name": "Cloé Weber",
          "date": 1671032461
        },
        "parents": [
          "6aac318907b50252976c47e4e62ed95d438af0ea"
        ],
        "message": "Add cron"
      }
    ],
...
```

The `environment` property contains the settings for the environment that was pushed to:

```json {no-copy="true"} theme={null}
...
    "environment": {
      "id": "main",
      "created_at": "2026-03-22T15:47:43.750880+00:00",
      "updated_at": "2026-11-29T16:16:37.085719+00:00",
      "name": "main",
      "machine_name": "main-abcd123",
      "title": "Main",
      "attributes": {},
      "type": "production",
      "parent": null,
      "default_domain": null,
      "clone_parent_on_create": true,
      "deployment_target": "local",
      "is_pr": false,
      "status": "active",
      "enable_smtp": true,
      "restrict_robots": true,
      "edge_hostname": "main-abcd123-abcdefgh1234567.eu-3.platformsh.site",
      "deployment_state": {
        "last_deployment_successful": true,
        "last_deployment_at": "2026-11-29T16:16:37.085609+00:00",
        "crons": {
          "enabled": true,
          "status": "sleeping"
        }
      },
      "resources_overrides": {},
      "last_active_at": "2026-12-13T16:07:09.788910+00:00",
      "last_backup_at": null,
      "project": "abcdefgh1234567",
      "is_main": true,
      "is_dirty": false,
      "has_code": true,
      "head_commit": "6aac318907b50252976c47e4e62ed95d438af0ea",
      "merge_info": {
        "commits_ahead": 0,
        "commits_behind": 0,
        "parent_ref": null
      },
      "has_deployment": true
    },
...
```

The `deployment` property contains the settings for the deployment,
including the [image type](/docs/configure-apps/app-reference/single-runtime-image#type) and
[resource allocation](/docs/manage-resources/adjust-resources).

The following example shows a shortened excerpt of the `deployment` property:

```json {no-copy="true"} theme={null}
...
 "deployment": {
      "id": "current",
      "created_at": "2026-03-22T15:48:05.396979+00:00",
      "updated_at": "2026-12-14T15:41:57.264813+00:00",
      "cluster_name": "abcdefgh1234567-main-abcd123",
      "project_info": {
          "deployment": {
      "id": "current",
      "created_at": "2026-03-22T15:48:05.396979+00:00",
      "updated_at": "2026-12-14T15:41:57.264813+00:00",
      "cluster_name": "abcdefgh1234567-main-abcd123",
      "project_info": {
        "name": "abcdefgh1234567",
        "settings": {
          "initialize": {
            "values": {
              "initialize": true,
              "start": false,
              "base": {
                "files": [],
                "profile": "PHP",
                "config": null,
                "repository": "https://github.com/platformsh-templates/php.git@master",
                "title": "PHP"
              }
            }
          },
          ...
          "application_config_file": ".upsun/config.yaml",
          "project_config_dir": ".upsun/",
          ...
          "development_service_size": "S",
          "development_application_size": "S",
          "enable_certificate_provisioning": true,
          "certificate_style": "ecdsa",
          "certificate_renewal_activity": true,
          ...
          "cron_minimum_interval": 5,
          "cron_maximum_jitter": 20,
          "concurrency_limits": {
            "internal": null,
            "integration": 4,
            "backup": 2,
            "cron": 10,
            "default": 2
          },
          ...
          "build_resources": {
            "cpu": 1,
            "memory": 2048
          },
          ...
          "max_allowed_routes": 50000,
          "max_allowed_redirects_paths": 50000,
          "enable_incremental_backups": true,
          ...
        }
      },
...
```

The following example shows the full activity response to a Git push:


# Example: Slack
Source: https://developer.upsun.com/docs/integrations/activity/slack



The following example activity script posts a message to a Slack channel every time it's triggered.

To use it, follow these steps:

1. In your Slack administrative interface, [create a new Slack webhook](https://api.slack.com/messaging/webhooks).
   You get a URL starting with `https://hooks.slack.com/`.
2. Replace `SLACK_URL` in the following script with your webhook URL.
3. Paste the code into a `.js` file.
4. Add it as a new [script integration](/docs/integrations/activity#installing).

   Specify which events should trigger it using the `--events` flag.
   Optionally specify environments with the `--environments` flag.

Now, any activities that meet the events/environment criteria you specified are reported to Slack.

Once you have it working, you're free to modify the code below as desired.
For formatting more complex messages, see the [Slack messaging documentation](https://api.slack.com/messaging/composing/layouts).

```javascript theme={null}
/**
 * Sends a color-coded formatted message to Slack.
 *
 * To control what events trigger it, use the --events switch in
 * the Upsun Cloud CLI.
 *
 * @param {string} title
 *   The title of the message block to send.
 * @param {string} message
 *   The message body to send.
 */
function sendSlackMessage(title, message) {
  const url = SLACK_URL;

  if (!message) {
    // No message. Don't send it.
    return;
  }

  const messageTitle =
    title + ((new Date().getDay() === 5) ? " (On a Friday! :calendar:)" : "");

  const color = activity.result === "success" ? "#66c000" : "#ff0000";

  const body = {
    attachments: [
      {
        title: messageTitle,
        text: message,
        color: color,
      },
    ],
  };

  const resp = fetch(url, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
  });

  if (!resp.ok) {
    console.log("Sending slack message failed: " + resp.body.text());
  }
}

sendSlackMessage(activity.text, activity.log);
```

Common properties you may want to send to Slack (in the last line of the script) include:

* `activity.text`: A brief, one-line statement of what happened.
* `activity.log`: The complete build and deploy log output, as it would be seen in the Console log screen.

For more properties, see the [activity reference](/docs/integrations/activity/reference).


# Utility routines
Source: https://developer.upsun.com/docs/integrations/activity/utility

The following utility routines can help simplify common tasks in your activity scripts. They're free to copy, modify, bend, fold, spindle, and mutilate as needed for your own scripts. They also demonstrate some common patterns for working with the `activity` and `project` data structures.


## Route access

```javascript theme={null}
/**
 * Returns just those routes that point to a valid upstream.
 *
 * This method is similar to routes(), but filters out redirect routes that are rarely
 * useful for app configuration. If desired it can also filter to just those routes
 * whose upstream is a given application name. To retrieve routes that point to the
 * current application where the code is being run, use:
 *
 * routes = getUpstreamRoutes(applicationName);
 *
 * @param {string} [appName]
 *   The name of the upstream app on which to filter, if any.
 * @return {object}
 *   An object map of route definitions. The generated URLs of the routes are added as a "url" key.
 */
function getUpstreamRoutes(appName) {
  return Object.entries(activity.payload.deployment.routes).reduce(
    (upstreams, [url, route]) =>
      route.type === "upstream" &&
      (!appName || appName === route.upstream.split(":")[0])
        ? {
            ...upstreams,
            [url]: {
              ...route,
              url,
            },
          }
        : upstreams,
    {}
  );
}
```

```javascript theme={null}
/**
 * Returns the primary route.
 *
 * The primary route is the one marked primary in `.upsun/config.yaml`, or else
 * the first non-redirect route in that file if none are marked.
 *
 * @return {object}
 *   The route definition. The generated URL of the route is added as a "url" key.
 */
function getPrimaryRoute() {
  return Object.entries(activity.payload.deployment.routes).reduce(
    (primary, [url, route]) =>
      route.primary
        ? {
            ...route,
            url,
          }
        : primary,
    {}
  );
}
```

```javascript theme={null}
/**
 * Returns the route definition that has the specified id.
 *
 * Note: If no route ID was specified in .upsun/config.yaml then it will not be possible
 * to look up a route by ID.
 *
 * @param {string} id
 *   The ID of the route to load.
 * @return {object}
 *   The route definition. The generated URL of the route is added as a "url" key.
 * @throws {Error}
 *   If there is no route by that ID, an exception is thrown.
 */
function getRoute(id) {
  const found = Object.entries(activity.payload.deployment.routes).reduce(
    (foundRoute, [url, route]) =>
      route.id === id
        ? {
            ...route,
            url,
          }
        : foundRoute,
    null
  );

  if (found === null) {
    throw new Error(`No such route id found: ${id}`);
  }

  return found;
}
```


# Webhooks
Source: https://developer.upsun.com/docs/integrations/activity/webhooks

Webhooks allow you to host a script yourself externally that receives the same payload as an activity script and responds to the same events, but can be hosted on your own server in your own language.


## Setup

```bash theme={null}
upsun integration:add --type=webhook --url=<URL_TO_RECEIVE_JSON>
```

The webhook URL receives a POST message for every activity that's triggered.
The message contains complete information about the entire state of the project at that time.

It's possible to set the integration to only send certain activity types, or only activities on certain branches.
The CLI prompts you to specify which to include or exclude.
Leave at the default values to get all events on all environments in a project.

For testing purposes, you can generate a URL from a service such as [webhook.site](https://webhook.site/)
and use the generated URL as `<URL_TO_RECEIVE_JSON>`.

## Authentication

You can sign webhook payloads so that your receiving application can verify they genuinely come from Upsun Cloud.
To do so, provide a shared secret key when creating or updating the integration:

```bash theme={null}
upsun integration:add --type=webhook --url=<URL_TO_RECEIVE_JSON> --shared-key=<SECRET_KEY>
```

To update the key on an existing integration:

```bash theme={null}
upsun integration:update <INTEGRATION_ID> --shared-key=<SECRET_KEY>
```

Use a long, random string as the secret key (for example, the output of `openssl rand -base64 32`).

### How it works

When a shared key is configured, every webhook request includes an `X-JWS-Signature` HTTP header
containing a [JSON Web Signature](https://datatracker.ietf.org/doc/html/rfc7515) (JWS).
The webhook body itself remains a standard JSON payload — the signature is separate.

The signature uses the following scheme:

* **Algorithm:** HS256 (HMAC-SHA256 with the shared key)
* **Format:** JWS Compact Serialization with a **detached, unencoded payload** per [RFC 7797](https://datatracker.ietf.org/doc/html/rfc7797)
* **JWS protected header:** `{"alg":"HS256","b64":false,"crit":["b64"]}`

Because the payload is detached and unencoded (`b64:false`), the `X-JWS-Signature` value has the form:

```text theme={null}
<base64url-encoded-header>..<base64url-encoded-signature>
```

Note the **two dots with nothing between them** — the payload slot is empty because the payload is sent in the POST body rather than embedded in the JWS token.

### Verifying the signature

To verify a webhook request:

1. Read the raw POST body **as bytes** exactly as received on the wire and preserve it unchanged (this is the JSON payload).
2. Read the `X-JWS-Signature` header.
3. Parse the JWS protected header and signature from the header value (the string in the form `<base64url-encoded-header>..<base64url-encoded-signature>`). Then, do one of the following:
   * Use a JWS library that supports RFC 7797 detached, unencoded payloads (`b64:false`) and pass the raw body bytes from step 1 as the detached payload.
   * Manually compute the JWS signing input as `<base64url-encoded-header>.<raw-body-bytes>` and verify the HS256 MAC over this signing input with your shared key.
4. Verify the signature using HS256 with your shared key, treating the raw body bytes from step 1 as the payload. Do **not** try to build a new compact JWS string by inserting the raw body between the two dots.
5. If verification fails, reject the request (for example, respond with `401`).

> Signature verification depends on the exact bytes of the HTTP request body. Do **not** parse and re-serialize the JSON (which can change whitespace or key order) before verifying; always verify against the original raw body bytes as received.

## Webhook schema

See the [activity script](/docs/integrations/activity/reference) reference for a description of the webhook payload.

## Validate the integration

To verify your integration is functioning properly, run the following [CLI command](/docs/integrations/overview#validate-integrations):

```bash theme={null}
upsun integration:validate
```


# Fastly CDN
Source: https://developer.upsun.com/docs/integrations/fastly-cdn

The Fastly CDN integration provides a centralized interface within the Upsun Cloud Console to oversee your edge traffic, manage cache, edit access control lists (ACLs), and tune performance without switching platforms. You can also manage dynamic configuration by using Edge Dictionaries.


## Install the Fastly CDN plugin

1. Go to [https://console.upsun.com/-/add-plugin](https://console.upsun.com/-/add-plugin) and click **Add plugin**.
2. Enter the plugin manifest URL [https://fastsun.plugins.pltfrm.sh/manifest.json](https://fastsun.plugins.pltfrm.sh/manifest.json) and click **Create**.

**Tip:** You can also [click here](https://console.upsun.com/-/add-plugin?manifest=https%253A%252F%252Ffastsun.plugins.pltfrm.sh%252Fmanifest.json) to install directly in the Upsun Cloud Console.

## Manage and monitor your CDN traffic

The Fastly CDN integration provides a centralized interface within the Upsun Cloud Console to oversee your edge traffic, manage cache, and tune performance without switching platforms.

### Access the Fastly dashboard

1. In the Upsun Cloud [Console](https://console.upsun.com), navigate to the project and environment you want to monitor.

   **Note:** To view summarized monthly *project-level* traffic, including CDN bandwidth and CDN requests, see the **Traffic this month** section of a project page (make sure no environment is selected).

2. On the **Fastly CDN** tab, log in with your Fastly credentials (Service ID and API token).

   * If you have a Fastly subscription, you can retrieve your credentials directly from the Fastly interface.

   * If you purchased Fastly through Upsun Cloud, you can retrieve your credentials by running `upsun ssh "printenv | grep FASTLY"` in your terminal, or by [opening a support ticket](https://support.upsun.com/hc/en-us/requests/new?ticket_form_id=35294051960082).

   Your Fastly credentials are stored securely within your browser and are never transmitted to Upsun Cloud.

### Track real-time and historical performance

The dashboard provides two levels of visibility into how your site is performing at the edge:

* **Real-time metrics:** Monitor current traffic spikes, request rates, and global delivery status as it happens.

* **Historical metrics:** Use the date picker to analyze trends over weeks or months. You can toggle specific metrics on the graph to isolate data like cache hit ratios, 4xx/5xx error rates, and total bandwidth.

The image below shows a sample historical metrics tab for a selected environment:

<img alt="Image showing the Fastly CDN historical metrics tab in the Upsun Cloud Console" />

## Manage dynamic configuration with Edge Dictionaries

Edge Dictionaries allow you to store key-value pairs at the CDN level to control site behavior in real-time. This integration enables you to update configurations (such as feature flags, redirects, or header values) instantly, without a full code redeploy or VCL version change. This can be helpful, for example, to block a bot attack or quickly update a site banner.

With this integration, you can:

* **Update instantly:** Add, edit, or delete items via the UI or API for immediate effect.
* **Secure secrets:** Use write-only dictionaries to store sensitive API keys that are accessible to your logic but hidden from view.
* **Maintain consistency:** Leverage built-in validation and a management workflow that mirrors Fastly ACLs.

### Example: Use a Dictionary for a maintenance toggle

Instead of hard-coding a maintenance mode in your application, you can use an Edge Dictionary (for example, named `site_config`) to toggle a "Maintenance Mode" page at the edge.

1. Define the dictionary: Create a dictionary named `site_config` and add a `maintenance_enabled` key with a value of `true` or `false`.

2. Add the VCL Logic: Add the following snippet to your Fastly configuration to check the dictionary value on every request:

   ```
   sub vcl_recv {
     # Check if the 'maintenance_enabled' key is set to 'true' in the dictionary
     if (table.lookup(site_config, "maintenance_enabled") == "true") {
       # Send a 503 Service Unavailable response immediately
       error 601 "Maintenance";
     }
   }

   sub vcl_error {
     if (obj.status == 601) {
       set obj.status = 503;
       set obj.response = "Service Unavailable";
       synthetic {"
         <html>
           <body>
             <h1>We'll be back soon!</h1>
             <p>Our site is currently undergoing scheduled maintenance.</p>
           </body>
         </html>
       "};
       return(deliver);
     }
   }
   ```

Related information:

* [How to create a custom maintenance page in Fastly](https://devcenter.upsun.com/posts/fastly-maintenance/#create-fastly-configuration) - this Upsun Cloud Dev Center article also describes how to create a Fastly configuration.
* [Fastly Next-Gen Web Application Firewall (WAF)](/docs/security/fastly-waf)


# Health notifications
Source: https://developer.upsun.com/docs/integrations/notifications

Configure health notifications for disk space and inode usage alerts. Route warning and critical threshold events to email, Slack, PagerDuty, or webhooks.


## Notification types

Notifications include the steps to take to resolve the issue.

### Low-disk warning

Upsun Cloud monitors disk space usage on all applications and services in your cluster.

* When available disk space drops below 20% or 4 GB, whichever is smaller, a warning notification is generated.
* When available disk space drops below 10% or 2 GB, whichever is smaller, a critical notification is generated.
* When available disk space returns above 20% or 4 GB, whichever is smaller, an all-clear notification is generated.

### Low-inode warning

Inodes are filesystem metadata entries that store information about files and directories.
Each file, directory, or symlink consumes one inode, regardless of its size. Running out of inodes prevents
the creation of new files even when disk space is available.

Upsun Cloud monitors inode usage on all applications and services in your cluster.

* When available inodes drop below 20% of the total available, a warning notification is generated.
* When available inodes drop below 10% of the total available, a critical notification is generated.
* When available inodes return above 20% of the total available, an all-clear notification is generated.

Notifications are generated every 5 minutes, so there may be a brief delay between when the threshold is crossed and when the notification is triggered.

## Configuring notifications

By default, Upsun Cloud emails low-disk and low-inode notifications to [project admins](/docs/administration/users#project-roles).

As a project admin, you can also:

* Configure the sending of health notifications through other channels (for example, via Slack or PagerDuty) as described in this topic.
* Use the CLI to [add](/cli/reference#integrationadd) and [manage](/cli/reference#integrationupdate) health notifications.

### Email notifications

A notification can trigger an email to be sent from an address of your choosing to one or more addresses of your choosing.

You can view an email notification by running `upsun integration:get`.

```bash theme={null}
upsun integration:get
+--------------+---------------+
| Property     | Value         |
+--------------+---------------+
| id           | abcdefghijklm |
| type         | health.email  |
| role         |               |
| from_address |               |
| recipients   | - '#admins'   |
+--------------+---------------+
```

To edit the `recipients` that receive the default email notification, use the `integration:update` command.

```bash theme={null}
upsun integration:update abcdefghijklm --recipients you@example.com
```

The `recipients` field may be any valid email address, or one of the following special values.

* `#admins` maps to all project admins and up.
* `#viewers` maps to everyone with access to the project.

To add a new email notification, register a `health.email` integration as follows:

```bash theme={null}
upsun integration:add --type health.email --recipients them@example.com --recipients others@example.com
```

You must specify one or more `recipients`, each as its own switch.

The default `from-address` points to the "Upsun Cloud Bot".

You can also configure a custom `--from-address`. The `--from-address` is whatever address you want the email to appear to be from. It is completely fine to use the same email address for both `from-address` and `recipients`. Note that depending on the configuration of the recipient mail server (including SPF and DKIM DNS entries) when using a custom `from-address`, the email can be marked as spam or lost.

### Slack notifications

A notification can trigger a message to be posted to a Slack channel via a [Slack app](https://api.slack.com/apps).

#### 1. Optional: Create a Slack app

<Note>
  If you are already have a Slack app, you can jump to [enabling notifications](#2-enable-notifications).
</Note>

1. Open the [Slack API website](https://api.slack.com/) and go to **Your apps**.
2. Click **Create an App**.
3. Choose if you want to build your app from scratch, or via [an app manifest](https://api.slack.com/concepts/manifests).
4. Give your app a name.
5. Select a workspace to install your app in.
   <Note>
     If you are not an admin of the selected workspace, request approval to install your app there.
   </Note>
6. Click **Create App**.

#### 2. Enable notifications

1. Open the [Slack API website](https://api.slack.com/) and go to **Your apps**.

2. Go to **Features** > **OAuth & Permissions** in the sidebar.

3. Scroll down to the **Scopes** area and select **User Token Scopes**.

4. Click **Add an OAuth Scope** to add the `chat:write` scope.

   <img alt="Slack app scopes" />

5. Go to **Settings** > **Install app** in the sidebar.

   <Note>
     If you are *not* an admin of the workspace, you need to provide a link to install the app into the workspace and onto a channel.

     Once the app is approved and installed, a **User OAuth Token** is provided in your app settings.
     Copy the token, and use it in the next step.
   </Note>

6. Using the **User OAuth Token**, run the following command:

   ```bash theme={null}
   upsun integration:add --type health.slack --token <USER_OAUTH_TOKEN> --channel <CHANNEL_NAME> --project <PROJECT_ID>
   ```

   For example, if you want your Slack app to post messages in the `project-notifications` channel, write the channel name in the command as you would reference it within Slack:

   ```bash theme={null}
   upsun integration:add --type health.slack ... --channel '#project-notifications' ...
   ```

7. When the integration is successfully configured, Upsun Cloud then sends an initial message to the channel.

<Info>
  <h4>Bot users vs. Slack apps</h4>
  Previously, Upsun Cloud allowed for the configuration of health notifications sent to Slack via *bot users* and their associated API tokens.
  As of June 2024, Slack has deprecated bot users, and integrations must be configured using Slack apps as described above.

  If you already have defined an integration using a bot user API token, it will continue to work properly, though you should consider upgrading your processes to the above settings to avoid any future retirement.
</Info>

### PagerDuty notifications

A notification can trigger a message to be sent via PagerDuty, if you are using that service.
First, create a new PagerDuty "[integration](https://support.pagerduty.com/docs/services-and-integrations)" that uses the Events API v2.
Copy the "Integration Key" as known as the "routing key" for the integration.

Now register a `health.pagerduty` integration as follows:

```bash theme={null}
upsun integration:add --type health.pagerduty --routing-key YOUR_ROUTING_KEY
```

Any notification will now trigger an alert in PagerDuty.

## Validate the integration

You can then verify that your integration is functioning properly [using the CLI](/docs/integrations/overview#validate-integrations) command

```bash theme={null}
upsun integration:validate
```


# External Integrations
Source: https://developer.upsun.com/docs/integrations/overview

Upsun Cloud can be integrated with external services.


Upsun Cloud supports native integrations with multiple services, first and foremost Git hosting services such as GitHub, GitLab, or Bitbucket.
You can continue to use those tools for your development workflow, and have Upsun Cloud environments created automatically for your pull requests and branches.

## List active integrations

With the CLI, you can list all your active integrations using the following command:

```bash theme={null}
upsun integrations
```

You get output similar to the following:

```bash theme={null}
+---------------+-------------+-------------------------------------------------------------------------------------+
| ID            | Type        | Summary                                                                             |
+---------------+-------------+-------------------------------------------------------------------------------------+
| abcdefghijklm | github      | Repository: platformsh/platformsh-docs                                              |
|               |             | Hook URL:                                                                           |
|               |             | https://eu-3.platform.sh/api/projects/123abcdefgh3i/integrations/abcdefghijklm/hook |
+---------------+-------------+-------------------------------------------------------------------------------------+
```

## Validate integrations

Once your integration has been configured, you can check that it's working as expected.
To do so, follow these steps:

1. Run the `upsun integration:validate` command.
2. When prompted, select the integration you want to validate:

   ```bash theme={null}
   Enter a number to choose an integration:
     [0] 5aut2djgt6kdd (health.slack)
     [1] a6535j9qp4sl8 (github)
    > 1
   ```

   You get output similar to:

   ```bash theme={null}
   Validating the integration a6535j9qp4sl8 (type: github)...
   The integration is valid.
   ```

## Debug integrations

When integrations run, they trigger "activities."  Activities are actions that happen on Upsun Cloud, and they get logged.

Usually these are triggered nearly instantaneously on the webhook endpoint.
These activities may be delayed due to the external services having latency.

Those logs are available via the CLI.
In most cases they aren't necessary but may be useful for debugging an integration if it is misbehaving for some reason.

There are a handful of CLI commands available, all under the `integrations` section.

### List all activities

To list all the updates triggered by [activities](/docs/integrations/activity/reference) on a given project and integration,
follow these steps:

1. Run the `upsun integration:activities` command.
2. When prompted, select an integration.

   ```bash theme={null}
   Enter a number to choose an integration:
     [0] dxr45hfldrkoe (webhook)
     [1] n2ukd4p7qofg4 (health.email)
     [2] c4opi5tjv3yfd (github)
   > 2
   ```

   You get output similar to the following:

   ```bash theme={null}
   Activities on the project Upsun Cloud | Docs (6b2eocegfkwwg), integration c4opi5tjv3yfd (github):
   +---------------+---------------------------+-------------------------------------------------------------+----------+---------+
   | ID            | Created                   | Description                                                 | State    | Result  |
   +---------------+---------------------------+-------------------------------------------------------------+----------+---------+
   | 6456zmdtoykxa | 2026-04-14T16:38:09-05:00 | Fetching from https://github.com/platformsh/platformsh-docs | complete | success |
   | wcwp34yjvydgk | 2026-04-14T16:35:22-05:00 | Fetching from https://github.com/platformsh/platformsh-docs | complete | success |
   | w2bp3oa5xbfoe | 2026-04-14T16:33:13-05:00 | Fetching from https://github.com/platformsh/platformsh-docs | complete | success |
   | uqqvdyxmcdmsa | 2026-04-14T16:31:45-05:00 | Fetching from https://github.com/platformsh/platformsh-docs | complete | success |
   | 7x3wefhh4fwqc | 2026-04-14T16:30:36-05:00 | Fetching from https://github.com/platformsh/platformsh-docs | complete | success |
   | a46aah3ga65gc | 2026-04-14T16:29:46-05:00 | Fetching from https://github.com/platformsh/platformsh-docs | complete | success |
   | r7erid2jlixgi | 2026-04-14T16:24:50-05:00 | Fetching from https://github.com/platformsh/platformsh-docs | complete | success |
   | ieufk3vvde5oc | 2026-04-14T16:24:49-05:00 | Fetching from https://github.com/platformsh/platformsh-docs | complete | success |
   | bc7ghg36ty4ea | 2026-04-14T15:30:17-05:00 | Fetching from https://github.com/platformsh/platformsh-docs | complete | success |
   | 4qojtv7a6rk2w | 2026-04-14T15:27:26-05:00 | Fetching from https://github.com/platformsh/platformsh-docs | complete | success |
   +---------------+---------------------------+-------------------------------------------------------------+----------+---------+
   ```

You may also specify an integration to display in the command line directly: `upsun integration:activities c4opi5tjv3yfd`.

The ID is an internal identifier for the activity event.
The Description field is an arbitrary string of text produced by the integration code.
The State and Result fields indicate if the activity completed successfully, failed for some reason, or is currently in progress.

See the `--help` output of the command for more options.

### Show detailed information on an activity

To show detailed information on a specific activity,
run the following command:

```bash theme={null}
upsun integration:activity:log <INTEGRATION_ID> <ACTIVITY_ID> -t
```

The `-t` option specifies that timestamps must be included in the display of the results.

You get output similar to the following:

```bash theme={null}
Integration ID: ceopz5tgj3yfc
Activity ID: 6456zmdtoykxa
Type: integration.github.fetch
Description: Fetching from https://github.com/platformsh/platformsh-docs
Created: 2026-04-15T08:44:07-05:00
State: complete
Log:
[2026-04-15T13:44:17-05:00] Waiting for other activities to complete
[2026-04-15T13:46:07-05:00] Fetching from GitHub repository platformsh/platformsh-docs
[2026-04-15T13:46:09-05:00]   No changes since last fetch
[2026-04-15T13:46:09-05:00]
[2026-04-15T13:46:09-05:00] Synchronizing branches
[2026-04-15T13:46:09-05:00]
[2026-04-15T13:46:09-05:00] Synchronizing pull requests
[2026-04-15T13:46:59-05:00]
[2026-04-15T13:46:59-05:00] W: No changes found, scheduling a retry..
```

That shows the full output of the activity, including timestamps.
That can be especially helpful if trying to determine why an integration isn't behaving as expected.

See the `--help` output of the command for more options.

If you omit the activity ID (the second random-seeming string), the command will default to the most recent activity recorded.


# Integrate with Bitbucket
Source: https://developer.upsun.com/docs/integrations/source/bitbucket

See how to manage your Upsun Cloud environments directly from your Bitbucket repository.

If you have code in a Bitbucket repository, you might want to connect it to an Upsun Cloud project.
This means you can keep your Bitbucket workflows
and treat the Bitbucket repository as the source of truth for your code.

Your Upsun Cloud project becomes a mirror of your Bitbucket repository.
This means you shouldn't push code directly to Upsun Cloud.
Any changes you push directly get overwritten by the integration when changes happen in the Bitbucket repository.

When you set up an integration with Bitbucket, it automates the following processes for you:

* Creating a new environment when a branch is created or a pull request is opened.
* Rebuilding the environment when new code is pushed to Bitbucket.
* Deleting the environment when a pull request is merged.

You can set up an integration with either Bitbucket Cloud
or a self-hosted [Bitbucket Server](https://confluence.atlassian.com/bitbucketserver/).

## Before you begin

To manage source integrations, you need to be a [project admin](/docs/administration/users).

You also need a Bitbucket Cloud or Bitbucket Server repository with working code.

## Bitbucket Cloud

### 1. Create an OAuth consumer

To integrate your Upsun Cloud project with an existing Bitbucket Cloud repository,
[create an OAuth consumer](https://support.atlassian.com/bitbucket-cloud/docs/use-oauth-on-bitbucket-cloud/):

<img alt="A screenshot of how to setup the Bitbucket OAuth consumer" />

<Info>
  Be sure to define the above as a *private* consumer by checking the **This is a private consumer** box.
</Info>

The **Callback URL** isn't important in this case.
You can set it to `http://localhost`.

Copy the **Key** and **Secret** for your consumer.

### 2. Enable the Cloud integration

To enable the integration, use either the [CLI](/cli) or the [Console](/docs/administration/web).

<Tabs>
  <Tab title="Using the CLI">
    Run the following command:

    ```bash theme={null}
    upsun integration:add \
      --project <PROJECT_ID> \
      --type bitbucket \
      --repository <OWNER/REPOSITORY> \
      --key <CONSUMER_KEY> \
      --secret <CONSUMER_SECRET>
    ```

    * `PROJECT_ID` is the ID of your Upsun Cloud project.
    * `OWNER/REPOSITORY` is the name of your repository in Bitbucket.
    * `CONSUMER_KEY` is the key of the [OAuth consumer you created](#1-create-an-oauth-consumer).
    * `CONSUMER_SECRET` is the secret of the [OAuth consumer you created](#1-create-an-oauth-consumer).

    For example, if your repository is located at `https://bitbucket.org/platformsh/platformsh-docs`,
    the command is similar to the following:

    ```bash theme={null}
    upsun integration:add \
      --project abcdefgh1234567 \
      --type bitbucket \
      --repository platformsh/platformsh-docs \
      --key abc123 \
      --secret abcd1234 \
    ```
  </Tab>

  <Tab title="In the Console">
    1. Select the project where you want to enable the integration.
    2. Click **<SettingsIcon /> Settings**.
    3. Under **Project settings**, click **Integrations**.
    4. Click **+ Add integration**.
    5. Under **Bitbucket**, click **+ Add**.
    6. Complete the form with:
       * The repository in the form `owner/repository`
       * The [key and secret you generated](#1-create-an-oauth-consumer)
    7. Check that the other options match what you want.
    8. Click **Add integration**.
  </Tab>
</Tabs>

In both the CLI and Console, you can choose from the following options:

| CLI flag | Default | Description |
| - | - | - |
| `fetch-branches` | `true` | Whether to mirror and update branches on Upsun Cloud and create inactive environments from them. When enabled, merging on an Upsun Cloud environment isn't possible. That is, merging environments must be done on the source repository rather than on the Upsun Cloud project. See note below for details related to this flag and synchronizing code from a parent environment. |
| `prune-branches` | `true` | Whether to delete branches from Upsun Cloud that don't exist in the Bitbucket repository. When enabled, branching (creating environments) must be done on the source repository rather than on the Upsun Cloud project. Branches created on Upsun Cloud that are not on the source repository will not persist and will be quickly pruned. Automatically disabled when fetching branches is disabled. |
| `build-pull-requests` | `true` | Whether to track all pull requests and create active environments from them, which builds the pull request. |
| `resync-pull-requests` | `false` | Whether to sync data from the parent environment on every push to a pull request. |
| `resources-init` | `default` (production/staging), `minimum` (development) | To [specify a resource initialization strategy](/docs/manage-resources/resource-init#environment-branch) for new environments created by the integration. By default, production and staging environments use `default`, and development environments use `minimum`. Using the CLI, pass a single value (`minimum`, `default`, `manual`, or `parent`) to override the strategy for development environments — production and staging always use `default`. To set all three types independently, use the API. `parent` is not available for production. See [available resource initialization strategies](/docs/manage-resources/resource-init#specify-a-resource-initialization-strategy). |

<Note>
  To [keep your repository clean](/docs/core-concepts/best-practices/clean-repository) and avoid performance issues, make sure you enable both the `fetch-branches` and `prune-branches` options.
</Note>

#### 3. Validate the integration

Verify that your integration is functioning properly [using the CLI](/docs/integrations/overview#validate-integrations):

```bash theme={null}
upsun integration:validate
```

##### Add the webhook manually

If the integration was added with the correct permissions, the necessary webhook is added automatically.
If you see a message that the webhook wasn't added, add one manually.

To configure a webhook on a Bitbucket repository,
you need to have Admin [user permissions](https://support.atlassian.com/bitbucket-cloud/docs/manage-webhooks/).

1. Get the webhook URL by running this command: `upsun integration:get --property hook_url`.
2. Copy the returned URL.
3. Follow the [Bitbucket instructions to create a webhook](https://support.atlassian.com/bitbucket-cloud/docs/manage-webhooks/#Create-webhooks)
   using the URL you copied.
   Make sure to update the triggers to include all pull request events except comments and approval.

You can now start pushing code, creating new branches,
and opening pull requests
directly in your Bitbucket repository.
Your Upsun Cloud environments are automatically created and updated.

## Bitbucket Server

### 1. Generate a token

To integrate your Upsun Cloud project with a repository on a Bitbucket Server instance,
you first need to create an access token associated with your account.

[Generate a token](https://confluence.atlassian.com/display/BitbucketServer/HTTP+access+tokens).
and give it at least read access to projects and admin access to repositories.
Copy the token.

### 2. Enable the Server integration

To enable the integration, use either the [CLI](/cli) or the [Console](/docs/administration/web).

<Tabs>
  <Tab title="Using the CLI">
    Run the following command:

    ```bash theme={null}
    upsun integration:add \
      --project PROJECT_ID \
      --type bitbucket_server \
      --repository OWNER/REPOSITORY \
      --username BITBUCKET_USERNAME \
      --token BITBUCKET_SERVER_ACCESS_TOKEN \
      --bitbucket-url BITBUCKET_SERVER_URL
    ```

    * `PROJECT_ID` is the ID of your Upsun Cloud project.
    * `OWNER/REPOSITORY` is the name of the repository in Bitbucket server.
    * `BITBUCKET_SERVER_ACCESS_TOKEN` is the [token you generated](#1-generate-a-token).
    * `BITBUCKET_SERVER_URL` is the URL for your Bitbucket server.

    For example, if your repository is located at `https://example.com/platformsh/platformsh-docs`,
    the command is similar to the following:

    ```bash theme={null}
    upsun integration:add \
      --project abcdefgh1234567 \
      --type bitbucket_server \
      --repository platformsh/platformsh-docs \
      --username user@example.com \
      --token abc123 \
      --bitbucket-url https://example.com
    ```
  </Tab>

  <Tab title="In the Console">
    1. Select the project where you want to enable the integration.
    2. Click **Settings**.
    3. Under **Project settings**, click **Integrations**.
    4. Click **+ Add integration**.
    5. Under **Bitbucket server**, click **+ Add**.
    6. Complete the form with:
       * Your server URL
       * Your Bitbucket username
       * The [token you generated](#1-generate-a-token)
       * The Bitbucket server project name
       * The repository in the form `owner/repository`
    7. Check that the other options match what you want.
    8. Click **Add integration**.
  </Tab>
</Tabs>

In both the CLI and Console, you can choose from the following options:

| CLI flag | Default | Description |
| - | - | - |
| `fetch-branches` | `true` | Whether to mirror and update branches on Upsun Cloud and create inactive environments from them. |
| `prune-branches` | `true` | Whether to delete branches from Upsun Cloud that don't exist in the Bitbucket server repository. Automatically disabled when fetching branches is disabled. |
| `build-pull-requests` | `true` | Whether to track all pull requests and create active environments from them, which builds the pull request. |
| `pull-requests-clone-parent-data` | `true` | Whether to clone data from the parent environment when creating a pull request environment. |

To [keep your repository clean](/docs/core-concepts/best-practices/clean-repository) and avoid performance issues,
make sure you enable both the `fetch-branches` and `prune-branches` options.

#### 3. Validate the integration

Verify that your integration is functioning properly [using the CLI](/docs/integrations/overview#validate-integrations):

```bash theme={null}
upsun integration:validate
```

##### Add the webhook manually

If the integration was added with the correct permissions, the necessary webhook is added automatically.
If you see a message that the webhook wasn't added, add one manually.

To configure a webhook on a Bitbucket repository,
you need to have Admin [user permissions](https://support.atlassian.com/bitbucket-cloud/docs/manage-webhooks/).

1. Get the webhook URL by running this command: `upsun integration:get --property hook_url`.
2. Copy the returned URL.
3. Follow the [Bitbucket instructions to create a webhook](https://confluence.atlassian.com/bitbucketserver076/managing-webhooks-in-bitbucket-server-1026535073.html#ManagingwebhooksinBitbucketServer-creatingwebhooksCreatingwebhooks)
   using the URL you copied.
   Send all events except comments and approval.

You can now start pushing code, creating new branches,
and opening pull requests
directly in your Bitbucket repository.
Your Upsun Cloud environments are automatically created and updated.

## Environment parent and status

When a **branch** is created in Bitbucket,
an environment is created in Upsun Cloud with the default branch as its parent.
It starts as an [inactive environment](/docs/glossary#inactive-environment) with no data or services.

When a **pull request** is opened in Bitbucket,
an environment is created in Upsun Cloud with the pull request's target branch as its parent.
It starts as an [active environment](/docs/glossary#active-environment) with a copy of its parent's data.

## Source of truth

When you add an integration, your Bitbucket repository is considered to be the source of truth for the project.
Your Upsun Cloud project is only a mirror of that repository and you can only push commits to Bitbucket.

To clone your code, follow these steps:

<Tabs>
  <Tab title="Using the CLI">
    Run the following command:

    ```bash theme={null}
    upsun get PROJECT_ID
    ```
  </Tab>

  <Tab title="Using Git">
    1. In the Console, open the project you want to clone.
    2. Click **Code**.
    3. Click **Git**.
    4. Run the command you find using Git.
  </Tab>
</Tabs>

When you do this, you're cloning from your integrated Bitbucket repository,
if you have the [appropriate access to do so](/docs/integrations/source/troubleshoot).

### Sync, fetch, and prune

An integration from your source repository to Upsun Cloud establishes that:

* your source repository is the source of truth, where Git operations occur
* Upsun Cloud is a mirror of that repository, provisioning infrastructure according to configuration, and orchestrating environments according to the branch structure of your source repository

Actions that take place on Upsun Cloud don't affect commits on your source repository.
Because of this, your source repository integration enables both `fetch-branches` (track branches on your source repository) and `prune-branches` (delete branches that don't exist on your source repository) by default.
You can change these settings but it is recommended to keep them.

When enabled by default, you are limited by design as to what actions can be performed within the context of an Upsun Cloud project with a source repository integration:

| Action | Observation | Recommendation |
| - | - | - |
| Branch from parent | Running [`environment:branch`](/cli/reference#environmentbranch) with the CLI, or selecting **Branch** in Console produces a new child environment, but it's deleted shortly after automatically. | Contribute to your source repository itself by creating a branch and pull request. When the PR has been opened, a new environment will be provisioned for it. |
| Merge in parent | Running [`environment:merge`](/cli/reference#environmentmerge) with the CLI fails locally, and the **Merge** option in Console is not clickable. | Review and merge pull requests and/or branches on your source repository. |
| Merge into child (sync code) | Running [`environment:synchronize`](/cli/reference#environmentsynchronize) with the CLI fails locally, and the **Sync** option in Console won't allow you to include `code` in that sync. | Perform the merge locally from a matching branch on your source repository. For example, clone the most recent parent (`git pull origin parent-branch`), switch to the pull request branch (`git checkout ga-staging`), and then merge the parent into the current branch (`git merge main`). |

## Pull request URLs

When a pull request is deployed, the integration reports the primary URL for the deployed environment.
So you get a link to the deployed environment right in the pull request.

If you have multiple routes,
ensure the correct one is reported by [specifying the primary route](/docs/routes#route-configuration-reference).


# Integrate with GitHub
Source: https://developer.upsun.com/docs/integrations/source/github

See how to manage your Upsun Cloud environments directly from your GitHub repository.

If you have code in a GitHub repository, you might want to connect it to an Upsun Cloud project.
This means you can keep your GitHub workflows
and treat the GitHub repository as the source of truth for your code.

Your Upsun Cloud project becomes a mirror of your GitHub repository.
This means you shouldn't push code directly to Upsun Cloud.
Any changes you push directly get overwritten by the integration when changes happen in the GitHub repository.

When you set up an integration with GitHub, it automates the following processes for you:

* Creating a new environment when a branch is created or a pull request is opened.
* Rebuilding the environment when new code is pushed to GitHub.
* Deleting the environment when a pull request is merged.

## Before you begin

To manage source integrations, you need to be a [project admin](/docs/administration/users).

You also need a GitHub repository with working code.

## 1. Generate a token

To integrate your Upsun Cloud project with an existing GitHub repository,
you need to [generate a new token](https://github.com/settings/tokens/new).
You can generate a classic personal access token,
or a [fine-grained personal access token](https://github.blog/changelog/2022-10-18-introducing-fine-grained-personal-access-tokens/)
for even greater control over the permissions you grant.

For the integration to work,
your GitHub user needs to have permission to push code to the repository.

When you set up or update an integration, it also needs permission to manage its webhooks.
This means your user needs to be a repository admin to create the integration.
You can remove this permission after setup.

Make sure you give your token a description.

If you're generating a classic personal access token,
ensure the token has the appropriate scopes based on what you want to do:

| Scope | Purpose |
| - | - |
| `admin:repo_hook` | To create webhooks for events in repositories. Always needed. |
| `public_repo` | To integrate with public repositories. |
| `repo` | To integrate with your private repositories. |
| `repo` and `read:org` | To integrate with private repositories in organizations you belong to. |

If you're generating a fine-grained personal access token,
ensure the token has the right [repository permissions](https://docs.github.com/en/rest/overview/permissions-required-for-fine-grained-personal-access-tokens?apiVersion=2022-11-28)
for the integration to work:

| Permission | Access level |
| - | - |
| `Commit statuses` | Read and write |
| `Contents` | Read and write |
| `Metadata` | Read-only |
| `Pull request` | Read and write |
| `Webhooks` | Read and write |

After you've set the needed scopes or permissions,
generate and copy your token.

## 2. Enable the integration

To enable the integration, use either the [CLI](/cli) or the [Console](/docs/administration/web).

<Tabs>
  <Tab title="Using the CLI">
    Run the following command:

    ```bash theme={null}
    upsun integration:add \
      --project <PROJECT_ID> \
      --type github \
      --repository <OWNER/REPOSITORY>" /> \
      --token <GITHUB_ACCESS_TOKEN> \
      --base-url <GITHUB_URL>
    ```

    * `PROJECT_ID` is the ID of your Upsun Cloud project.
    * `OWNER/REPOSITORY` is the name of your repository in GitHub.
    * `GITHUB_ACCESS_TOKEN` is the [token you generated](#1-generate-a-token).
    * `GITHUB_URL` is the base URL for your GitHub server if you self-host.
      If you use the public `https://github.com`, omit the `--base-url` flag when running the command.

    For example, if your repository is located at `https://github.com/platformsh/platformsh-docs`,
    the command is similar to the following:

    ```bash theme={null}
    upsun integration:add \
      --project abcdefgh1234567 \
      --type github \
      --repository platformsh/platformsh-docs \
      --token abc123
    ```
  </Tab>

  <Tab title="In the Console">
    1. Select the project where you want to enable the integration.
    2. Click **<SettingsIcon /> Settings**.
    3. Under **Project settings**, click **Integrations**.
    4. Click **+ Add integration**.
    5. Under **GitHub**, click **+ Add**.
    6. Add the [token you generated](#1-generate-a-token).
    7. Optional: If your GitHub project isn't hosted at `github.com`, enter your GitHub custom domain.
    8. Click **Continue**.
    9. Choose the repository to use for the project.
    10. Check that the other options match what you want.
    11. Click **Add integration**.
  </Tab>
</Tabs>

In both the CLI and Console, you can choose from the following options:

| CLI flag | Default | Description |
| - | - | - |
| `fetch-branches` | `true` | Whether to mirror and update branches on Upsun Cloud and create inactive environments from them. When enabled, merging on an Upsun Cloud environment isn't possible. That is, merging environments must be done on the source repository rather than on the Upsun Cloud project. See note below for details related to this flag and synchronizing code from a parent environment. |
| `prune-branches` | `true` | Whether to delete branches from Upsun Cloud that don't exist in the GitHub repository. When enabled, branching (creating environments) must be done on the source repository rather than on the Upsun Cloud project. Branches created on Upsun Cloud that are not on the source repository will not persist and will be quickly pruned. Automatically disabled when fetching branches is disabled. |
| `build-pull-requests` | `true` | Whether to track all pull requests and create active environments from them, which builds the pull request. |
| `build-draft-pull-requests` | `true` | Whether to also track and build draft pull requests. Automatically disabled when pull requests aren't built. |
| `pull-requests-clone-parent-data` | `true` | Whether to clone data from the parent environment when creating a pull request environment. |
| `build-pull-requests-post-merge` | `false` | Whether to build what would be the result of merging each pull request. Turning it on forces rebuilds any time something is merged to the target branch. |
| `resources-init` | `default` (production/staging), `minimum` (development) | To [specify a resource initialization strategy](/docs/manage-resources/resource-init#environment-branch) for new environments created by the integration. By default, production and staging environments use `default`, and development environments use `minimum`. Using the CLI, pass a single value (`minimum`, `default`, `manual`, or `parent`) to override the strategy for development environments — production and staging always use `default`. To set all three types independently, use the API. `parent` is not available for production. See [available resource initialization strategies](/docs/manage-resources/resource-init#specify-a-resource-initialization-strategy). |

To [keep your repository clean](/docs/core-concepts/best-practices/clean-repository) and avoid performance issues, make sure you enable both the `fetch-branches` and `prune-branches` options.

### 3. Validate the integration

Verify that your integration is functioning properly [using the CLI](/docs/integrations/overview#validate-integrations):

```bash theme={null}
upsun integration:validate
```

#### Add the webhook manually

If the integration was added with the correct permissions, the necessary webhook is added automatically.
If you see a message that the webhook wasn't added, add one manually.

To configure a webhook on a GitHub repository,
you need to have Admin [user permissions](https://docs.github.com/en/organizations/managing-user-access-to-your-organizations-repositories/repository-roles-for-an-organization#permissions-for-each-role).

1. Get the webhook URL by running this command: `upsun integration:get --property hook_url`.
2. Copy the returned URL.
3. In your GitHub repository, click **Settings** > **Webhooks** > **Add webhook**.
4. In the **Payload URL** field, paste the URL you copied.
5. For the content type, select **application/json**.
6. Select **Send me everything**.
7. Click **Add webhook**.

You can now start pushing code, creating new branches,
and opening pull requests
directly in your GitHub repository.
Your Upsun Cloud environments are automatically created and updated.

## Environment parent and status

When a **branch** is created in GitHub,
an environment is created in Upsun Cloud with the default branch as its parent.
It starts as an [inactive environment](/docs/glossary#inactive-environment) with no data or services.

When a **pull request** is opened in GitHub,
an environment is created in Upsun Cloud with the pull request's target branch as its parent.
It starts as an [active environment](/docs/glossary#active-environment) with a copy of its parent's data.

## Source of truth

When you add an integration, your GitHub repository is considered to be the source of truth for the project.
Your Upsun Cloud project is only a mirror of that repository and you can only push commits to GitHub.

To clone your code, follow these steps:

<Tabs>
  <Tab title="Using the CLI">
    Run the following command:

    ```bash theme={null}
    upsun get PROJECT_ID
    ```
  </Tab>

  <Tab title="Using Git">
    1. In the Console, open the project you want to clone.
    2. Click **Code**.
    3. Click **Git**.
    4. Run the command you find using Git.
  </Tab>
</Tabs>

When you do this, you're cloning from your integrated GitHub repository,
if you have the [appropriate access to do so](/docs/integrations/source/troubleshoot).

### Sync, fetch, and prune

An integration from your source repository to Upsun Cloud establishes that:

* your source repository is the source of truth, where Git operations occur
* Upsun Cloud is a mirror of that repository, provisioning infrastructure according to configuration, and orchestrating environments according to the branch structure of your source repository

Actions that take place on Upsun Cloud don't affect commits on your source repository.
Because of this, your source repository integration enables both `fetch-branches` (track branches on your source repository) and `prune-branches` (delete branches that don't exist on your source repository) by default.
You can change these settings but it is recommended to keep them.

When enabled by default, you are limited by design as to what actions can be performed within the context of an Upsun Cloud project with a source repository integration:

| Action | Observation | Recommendation |
| - | - | - |
| Branch from parent | Running [`environment:branch`](/cli/reference#environmentbranch) with the CLI, or selecting **Branch** in Console produces a new child environment, but it's deleted shortly after automatically. | Contribute to your source repository itself by creating a branch and pull request. When the PR has been opened, a new environment will be provisioned for it. |
| Merge in parent | Running [`environment:merge`](/cli/reference#environmentmerge) with the CLI fails locally, and the **Merge** option in Console is not clickable. | Review and merge pull requests and/or branches on your source repository. |
| Merge into child (sync code) | Running [`environment:synchronize`](/cli/reference#environmentsynchronize) with the CLI fails locally, and the **Sync** option in Console won't allow you to include `code` in that sync. | Perform the merge locally from a matching branch on your source repository. For example, clone the most recent parent (`git pull origin parent-branch`), switch to the pull request branch (`git checkout ga-staging`), and then merge the parent into the current branch (`git merge main`). |

## Pull request URLs

When a pull request is deployed, the integration reports the primary URL for the deployed environment.
So you get a link to the deployed environment right in the pull request.

If you have multiple routes,
ensure the correct one is reported by [specifying the primary route](/docs/routes#route-configuration-reference).


# Integrate with GitLab
Source: https://developer.upsun.com/docs/integrations/source/gitlab

See how to manage your Upsun Cloud environments directly from your GitLab repository.

If you have code in a GitLab repository, you might want to connect it to an Upsun Cloud project.
This means you can keep your GitLab workflows
and treat the GitLab repository as the source of truth for your code.

Your Upsun Cloud project becomes a mirror of your GitLab repository.
This means you shouldn't push code directly to Upsun Cloud.
Any changes you push directly get overwritten by the integration when changes happen in the GitLab repository.

When you set up an integration with GitLab, it automates the following processes for you:

* Creating a new environment when a branch is created or a merge request is opened.
* Rebuilding the environment when new code is pushed to GitLab.
* Deleting the environment when a merge request is merged.

## Before you begin

To manage source integrations, you need to be a [project admin](/docs/administration/users).

You also need a GitLab repository with working code.

<Note>
  If your GitLab instance is not accessible from the public internet, configure a [GitLab CI/CD pipeline](#optional-use-a-gitlab-cicd-pipeline) that pushes code to Upsun Cloud and manages environments via the Upsun Cloud API. This method provides full deployment control while keeping your GitLab instance isolated.
</Note>

## 1. Generate a token

To integrate your Upsun Cloud project with an existing GitLab repository,
generate a [project access token](https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html#create-a-project-access-token).
Ensure the token has the following scopes:

* `api` to access your API
* `read_repository` to read the repository

For the integration to work, your GitLab user needs push access to the repository and to configure a webhook on a GitLab repository, you need to have Maintainer or Owner user permissions.

Copy the token.

<Note>
  To create a project access token, you need to have a [sufficient GitLab license tier](https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html).
  If you don't see **Access Tokens** under **Settings**, upgrade your GitLab tier.
  Alternatively, you can create a [personal access token](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html),
  but that's attached to a specific user rather than the project as a whole
  and grants more permissions.
</Note>

## 2. Enable the integration

To enable the integration, use either the [CLI](/cli) or the [Console](/docs/administration/web).

<Tabs>
  <Tab title="Using the CLI">
    Run the following command:

    ```bash theme={null}
    upsun integration:add \
      --project <PROJECT_ID> \
      --type gitlab \
      --server-project <PROJECT/SUBPROJECT> \
      --token <GITLAB_ACCESS_TOKEN> \
      --base-url <GITLAB_URL>
    ```

    * `PROJECT_ID` is the ID of your Upsun Cloud project.
    * `PROJECT/SUBPROJECT` is the name of your repository in GitLab.
    * `GITLAB_ACCESS_TOKEN` is the [token you generated](#1-generate-a-token).
    * `GITLAB_URL` is the base URL for your GitLab server if you self-host.
      If you use the public `https://gitlab.com`, omit the `--base-url` flag when running the command.

    For example, if your repository is located at `https://gitlab.com/platformsh/platformsh-docs`,
    the command is similar to the following:

    ```bash theme={null}
    upsun integration:add \
      --project abcdefgh1234567 \
      --type gitlab \
      --server-project platformsh/platformsh-docs \
      --token abc123
    ```
  </Tab>

  <Tab title="In the Console">
    1. Select the project where you want to enable the integration.
    2. Click **<SettingsIcon /> Settings**.
    3. Under **Project settings**, click **Integrations**.
    4. Click **+ Add integration**.
    5. Under **GitLab**, click **+ Add**.
    6. Add the [token you generated](#1-generate-a-token).
    7. Optional: If your GitLab project isn't hosted at `gitlab.com`, enter your GitLab custom domain.
    8. Click **Continue**.
    9. Choose the repository to use for the project.
    10. Check that the other options match what you want.
    11. Click **Add integration**.
  </Tab>
</Tabs>

In both the CLI and Console, you can choose from the following options:

| CLI flag | Default | Description |
| - | - | - |
| `fetch-branches` | `true` | Whether to mirror and update branches on Upsun Cloud and create inactive environments from them. When enabled, merging on an Upsun Cloud environment isn't possible. That is, merging environments must be done on the source repository rather than on the Upsun Cloud project. See note below for details related to this flag and synchronizing code from a parent environment. |
| `prune-branches` | `true` | Whether to delete branches from Upsun Cloud that don't exist in the GitLab repository. When enabled, branching (creating environments) must be done on the source repository rather than on the Upsun Cloud project. Branches created on Upsun Cloud that are not on the source repository will not persist and will be quickly pruned. Automatically disabled when fetching branches is disabled. |
| `build-merge-requests` | `true` | Whether to track all merge requests and create active environments from them, which builds the merge request. |
| `build-wip-merge-requests` | `true` | Whether to also track and build draft merge requests. Automatically disabled when merge requests aren't built. |
| `merge-requests-clone-parent-data` | `true` | Whether to clone data from the parent environment when creating a merge request environment. |
| `resources-init` | `default` (production/staging), `minimum` (development) | To [specify a resource initialization strategy](/docs/manage-resources/resource-init#environment-branch) for new environments created by the integration. By default, production and staging environments use `default`, and development environments use `minimum`. Using the CLI, pass a single value (`minimum`, `default`, `manual`, or `parent`) to override the strategy for development environments — production and staging always use `default`. To set all three types independently, use the API. `parent` is not available for production. See [available resource initialization strategies](/docs/manage-resources/resource-init#specify-a-resource-initialization-strategy). |

To [keep your repository clean](/docs/core-concepts/best-practices/clean-repository) and avoid performance issues, make sure you enable both the `fetch-branches` and `prune-branches` options.

### 3. Validate the integration

Verify that your integration is functioning properly [using the CLI](/docs/integrations/overview#validate-integrations):

```bash theme={null}
upsun integration:validate
```

#### Add the webhook manually

If the integration was added with the correct permissions, the necessary webhook is added automatically.
If you see a message that the webhook wasn't added, add one manually.

To configure a webhook on a GitLab repository,
you need to have Maintainer or Owner [user permissions](https://docs.gitlab.com/ee/user/permissions.html).

1. Get the webhook URL by running this command: `upsun integration:get --property hook_url`.
2. Copy the returned URL.
3. In your GitLab repository, click **Settings** > **Webhooks**.
4. In the **URL** field, paste the URL you copied.
5. Under **Trigger**, select **Push events** and **Merge request events**.
6. Click **Add webhook**.

You can now start pushing code, creating new branches,
and opening merge requests
directly in your GitLab repository.
Your Upsun Cloud environments are automatically created and updated.

## Environment parent and status

When a **branch** is created in GitLab,
an environment is created in Upsun Cloud with the default branch as its parent.
It starts as an [inactive environment](/docs/glossary#inactive-environment) with no data or services.

When a **merge request** is opened in GitLab,
an environment is created in Upsun Cloud with the merge request's target branch as its parent.
It starts as an [active environment](/docs/glossary#active-environment) with a copy of its parent's data.

## Source of truth

When you add an integration, your GitLab repository is considered to be the source of truth for the project.
Your Upsun Cloud project is only a mirror of that repository and you can only push commits to GitLab.

To clone your code, follow these steps:

<Tabs>
  <Tab title="Using the CLI">
    Run the following command:

    ```bash theme={null}
    upsun get PROJECT_ID
    ```
  </Tab>

  <Tab title="Using Git">
    1. In the Console, open the project you want to clone.
    2. Click **Code**.
    3. Click **Git**.
    4. Run the command you find using Git.
  </Tab>
</Tabs>

When you do this, you're cloning from your integrated GitLab repository,
if you have the [appropriate access to do so](/docs/integrations/source/troubleshoot).

### Sync, fetch, and prune

An integration from your source repository to Upsun Cloud establishes that:

* your source repository is the source of truth, where Git operations occur
* Upsun Cloud is a mirror of that repository, provisioning infrastructure according to configuration, and orchestrating environments according to the branch structure of your source repository

Actions that take place on Upsun Cloud don't affect commits on your source repository.
Because of this, your source repository integration enables both `fetch-branches` (track branches on your source repository) and `prune-branches` (delete branches that don't exist on your source repository) by default.
You can change these settings but it is recommended to keep them.

When enabled by default, you are limited by design as to what actions can be performed within the context of an Upsun Cloud project with a source repository integration:

| Action | Observation | Recommendation |
| - | - | - |
| Branch from parent | Running [`environment:branch`](/cli/reference#environmentbranch) with the CLI, or selecting **Branch** in Console produces a new child environment, but it's deleted shortly after automatically. | Contribute to your source repository itself by creating a branch and pull request. When the PR has been opened, a new environment will be provisioned for it. |
| Merge in parent | Running [`environment:merge`](/cli/reference#environmentmerge) with the CLI fails locally, and the **Merge** option in Console is not clickable. | Review and merge pull requests and/or branches on your source repository. |
| Merge into child (sync code) | Running [`environment:synchronize`](/cli/reference#environmentsynchronize) with the CLI fails locally, and the **Sync** option in Console won't allow you to include `code` in that sync. | Perform the merge locally from a matching branch on your source repository. For example, clone the most recent parent (`git pull origin parent-branch`), switch to the pull request branch (`git checkout ga-staging`), and then merge the parent into the current branch (`git merge main`). |

## Merge request URLs

When a merge request is deployed, the integration reports the primary URL for the deployed environment.
So you get a link to the deployed environment right in the merge request.

If you have multiple routes,
ensure the correct one is reported by [specifying the primary route](/docs/routes#route-configuration-reference).

## Optional: use a GitLab CI/CD pipeline

If your GitLab instance is not accessible from the internet (e.g. air-gapped or behind a firewall), the GitLab integration process outlined above, based on incoming webhooks, might not be the best option to use.

Instead, [set up a push-based GitLab CI/CD pipeline](https://devcenter.upsun.com/posts/gitlab-push-solution/) that pushes code to Upsun Cloud and manages environments using the Upsun Cloud API. This setup allows you to:

* Deploy to production on `main` branch updates
* Create preview environments for Merge Requests
* Clean up environments when branches or MRs are removed
* Keep your GitLab instance fully private

<Tip>
  <h4>Detailed walkthrough</h4>
  For a detailed tutorial of how this works, with code samples and rationale, see this blog post: [Synchronize your air-gapped GitLab](https://devcenter.upsun.com/posts/gitlab-push-solution/).

  You can also find a complete working example of how this works in the Upsun Cloud [GitHub snippets repository](https://github.com/upsun/snippets/tree/main/examples/gitlab-ci).
</Tip>


# Source integrations
Source: https://developer.upsun.com/docs/integrations/source/index

See how to maintain your code in a third-party repository that's linked to your Upsun Cloud project.

A source integration links your Upsun Cloud project to a third-party Git repository (GitHub, GitLab, or Bitbucket),
making that repository the source of truth. Upsun Cloud mirrors the repository and manages environments
based on your repository's branch and pull request activity. For example:

* When you open a pull request, Upsun Cloud spins up an identical preview environment that reflects the contents of the pull request.
* After you push code to your external repository, Upsun Cloud mirrors the updated code and redeploys the affected environments.

This integration enables you to keep your code and CI/CD workflows on your Git provider of choice and use Upsun Cloud for deployment.

<Warning>
  If you connect an external repo to Upsun Cloud, do not push code directly to Upsun Cloud: push to your external repository.

  Upsun Cloud overwrites any changes pushed to it directly in order to mirror the external repository.
</Warning>

<CardGroup>
  <Card title="Bitbucket" icon="git-branch" href="/docs/integrations/source/bitbucket">
    Manage your Upsun Cloud environments directly from your Bitbucket repository.
  </Card>

  <Card title="GitHub" icon="github" href="/docs/integrations/source/github">
    Manage your Upsun Cloud environments directly from your GitHub repository.
  </Card>

  <Card title="GitLab" icon="gitlab" href="/docs/integrations/source/gitlab">
    Manage your Upsun Cloud environments directly from your GitLab repository.
  </Card>

  <Card title="Troubleshoot" icon="wrench" href="/docs/integrations/source/troubleshoot">
    Resolve access rights issues with integrated repositories.
  </Card>
</CardGroup>


# Resolve access issues with source integrations
Source: https://developer.upsun.com/docs/integrations/source/troubleshoot

Learn how to troubleshoot access rights for integrated repositories.

If you [add a user](/docs/administration/users#add-a-user-to-a-project) to an Upsun Cloud project,
but you haven’t added them to the remote repository on GitHub, GitLab, or Bitbucket,
they can't clone the project locally.

That user might try to clone the repository using the CLI with the following command:

```bash theme={null}
upsun get <PROJECT_ID>
```

In this case, the user gets an error similar to the following:

```txt {no-copy="true"} theme={null}
Failed to connect to the Git repository: git@github.com:organization/repository.git
Please make sure you have the correct access rights and the repository exists.
```

## Solution: Check external repository access rights

To enable the user to clone the repository,
grant them the correct access rights for the integrated repository.


# C#/.NET Core
Source: https://developer.upsun.com/docs/languages/dotnet

Upsun Cloud supports deploying .NET applications by allowing developers to define a build process and pass its variables to the .NET Core build environment.


<DisclaimerNix />

## Supported versions

You can select the major and minor version.

Patch versions are applied periodically for bug fixes and other maintenance updates. By default, you get the latest available patches each time you deploy. If your project has a [maintenance window](/docs/core-concepts/build-deploy#maintenance-window) configured, Upsun Cloud applies patches only during that window. Upsun Cloud may still apply urgent or critical fixes outside of the maintenance window.

* <span>10.0</span>
* <span>8.0</span>

## Deprecated versions

The following versions are still available in your projects,
but they're at their end of life and are no longer receiving security updates from upstream.

*No deprecated versions.*

To ensure your project remains stable in the future, switch to a [supported version](#supported-versions).

## Retired versions

The following versions have been retired and are no longer available.
If your project uses a retired version, you must update to a [supported version](#supported-versions).

* <span>7.0</span>
* <span>6.0</span>
* <span>5.0</span>
* <span>3.1</span>
* <span>2.2</span>
* <span>2.1</span>
* <span>2.0</span>

### Specify the language

To use .Net Core, specify `dotnet` as your [app's `type`](/docs/configure-apps/app-reference/single-runtime-image#type):

For example:

## Building the application

To build basic applications in .NET containers, it's enough to use the [`dotnet publish` command](https://docs.microsoft.com/en-us/dotnet/core/tools/dotnet-publish)
with the default [framework-dependent deployment](https://docs.microsoft.com/en-us/dotnet/core/deploying/#publish-framework-dependent):

where `PLATFORM_OUTPUT_DIR` is the output directory for compiled languages available at build time.

Typically, .NET Core builds start a collection of build servers, which are helpful for repeated builds.
On Upsun Cloud, however, if this process isn't disabled,
the build process doesn't finish until the idle timeout is reached.

As a result, you should include `-p` toggles that disable the Razor compiler for dynamic CSHTML pages (`UseRazorBuildServer`)
and the .NET MSBuild compiler (`UseSharedCompilation`).

If you want multiple builds for your application,
make sure to call `dotnet build-server shutdown` at the end of your build hook.

## Running the application

.NET Core applications should be started using the `web.commands.start` directive in `.upsun/config.yaml`.
This ensures that the command starts at the right moment and stops gracefully when a redeployment needs to be executed.
Also, should the program terminate for any reason, it's automatically restarted.
Note that the start command *must* run in the foreground.

Incoming requests are passed to the application using either a TCP (default) or Unix socket.
The application must use the [appropriate environment variable](/docs/configure-apps/image-properties/web#where-to-listen) to determine the URI to listen on.
For a TCP socket ([recommended](https://go.microsoft.com/fwlink/?linkid=874850)), the application must listen on `http://127.0.0.1`,
using the `PORT` environment variable.

There is an Nginx server sitting in front of your application.
Serving static content via Nginx is recommended, as this allows you to control headers (including cache headers)
and also has marginal performance benefits.

Note that HTTPS is also terminated at the Nginx proxy,
so the `app.UseHttpsRedirection();` line in `Startup.cs` should be removed.
To force HTTPS-only, refer to the [routes documentation](/docs/routes/https#enable-https).

The following example configures an environment to serve the static content folders commonly found in [ASP.NET MVC](https://dotnet.microsoft.com/apps/aspnet/mvc) templates using Nginx,
while routing other traffic to the .NET application.

You can also route all requests to the application unconditionally:

<RepoList lang="dotnet" />


# Elixir
Source: https://developer.upsun.com/docs/languages/elixir

Upsun Cloud supports building and deploying applications written in Elixir. There is no default flavor for the build phase, but you can define it explicitly in your build hook. Upsun Cloud Elixir images support both committed dependencies and download-on-demand. The underlying Erlang version is 22.0.7.

<DisclaimerNix />

## Supported versions

You can select the major and minor version.

Patch versions are applied periodically for bug fixes and other maintenance updates. By default, you get the latest available patches each time you deploy. If your project has a [maintenance window](/docs/core-concepts/build-deploy#maintenance-window) configured, Upsun Cloud applies patches only during that window. Upsun Cloud may still apply urgent or critical fixes outside of the maintenance window.

* <span>1.20</span>

## Deprecated versions

The following versions are still available in your projects,
but they're at their end of life and are no longer receiving security updates from upstream.

* <span>1.19</span>
* <span>1.18</span>

To ensure your project remains stable in the future,
switch to a [supported version](#supported-versions).

## Retired versions

The following versions have been retired and are no longer available.
If your project uses a retired version, you must update to a [supported version](#supported-versions).

* <span>1.15</span>
* <span>1.14</span>
* <span>1.13</span>
* <span>1.12</span>
* <span>1.11</span>
* <span>1.10</span>
* <span>1.9</span>

### Specify the language

To use Elixir, specify `elixir` as your [app's `type`](/docs/configure-apps/app-reference/single-runtime-image#type):

For example:

## Built-in variables

Upsun Cloud exposes relationships and other configuration as [environment variables](/docs/development/variables).
Most notably, it allows a program to determine at runtime what HTTP port it should listen on
and what the credentials are to access [other services](/docs/add-services).

To get the `PORT` environment variable (the port on which your web application is supposed to listen) you would:

```elixir theme={null}
String.to_integer(System.get_env("PORT") || "8888")
```

Some of the environment variables are in JSON format and are base64 encoded. You would need to import a JSON parsing library such as [JSON](https://hexdocs.pm/json/readme.html) or [Poison](https://hexdocs.pm/poison/api-reference.html) to read those. (There is an example for doing this to decode the `PLATFORM_RELATIONSHIPS` environment variable in the section [below](#accessing-services-manually).)

<Note>
  <h4>Tip</h4>
  Remember `config/prod.exs` is evaluated at **build time** and has no access to runtime configuration. Use `config/releases.exs` to configure your runtime environment.
</Note>

## Building and running the application

If you are using Hex to manage your dependencies, you need to specify the `MIX_ENV` environment variable:

The `SECRET_KEY_BASE` variable is generated automatically based on the [`PLATFORM_PROJECT_ENTROPY` variable](/docs/development/variables/use-variables#use-provided-variables).
You can change it.

Include in your build hook the steps to retrieve a local Hex and `rebar`, and then run `mix do deps.get, deps.compile, compile` on your application to build a binary.

<Note>
  That build hook works for most cases and assumes that your `mix.exs` file is located at [your app root](/docs/configure-apps/app-reference/single-runtime-image#root-directory).
</Note>

Assuming `mix.exs` is present at your app root and your build hook matches the above,
you can then start it from the `web.commands.start` directive.

The following basic app configuration is sufficient to run most Elixir applications.

Note that there is still an Nginx proxy server sitting in front of your application. If desired, certain paths may be served directly by Nginx without hitting your application (for static files, primarily) or you may route all requests to the Elixir application unconditionally, as in the example above.

## Dependencies

The recommended way to handle Elixir dependencies on Upsun Cloud is using Hex.
You can commit a `mix.exs` file in your repository and the system downloads the dependencies in your `deps` section using the build hook above.

```elixir theme={null}
  defp deps do
    [
	  {:platformshconfig, "~> 0.1.0"}
    ]
  end
```

## Accessing Services

You can access service credentials to connect to [managed services](/docs/add-services) from environment variables present in the application container.
Consult each of the individual service documentation to see how to retrieve and surface credentials into your application.

* [ClickHouse](/docs/add-services/clickhouse#usage-example)
* [Elasticsearch](/docs/add-services/elasticsearch#usage-example)
* [Gotenberg](/docs/add-services/gotenberg#usage-example)
* [Headless Chrome](/docs/add-services/headless-chrome#usage-example)
* [InfluxDB](/docs/add-services/influxdb#usage-example)
* [Kafka](/docs/add-services/kafka#usage-example)
* [MariaDB/MySQL](/docs/add-services/mysql#usage-example)
* [Memcached](/docs/add-services/memcached#usage-example)
* [mercure](/docs/add-services/mercure#usage-example)
* [mongodb](/docs/add-services/mongodb#usage-example)
* [Network Storage](/docs/add-services/network-storage#usage-example)
* [OpenSearch](/docs/add-services/opensearch#usage-example)
* [PostgreSQL](/docs/add-services/postgresql#usage-example)
* [RabbitMQ](/docs/add-services/rabbitmq#usage-example)
* [Redis](/docs/add-services/redis#usage-example)
* [Solr](/docs/add-services/solr#usage-example)
* [Valkey](/docs/add-services/valkey#usage-example)
* [Varnish](/docs/add-services/varnish#usage-example)
* [Vault KMS](/docs/add-services/vault#usage-example)
* [Chroma](/tutorials/self-hosted/chroma#3-use-the-relationship-in-your-application)
* [Qdrant](/tutorials/self-hosted/qdrant#4-use-the-relationship-in-your-application)

### Accessing Services Manually

The services configuration is available in the environment variable `PLATFORM_RELATIONSHIPS`.

Given a [relationship](/docs/configure-apps/image-properties/relationships) defined in `.upsun/config.yaml`:

Assuming you have in `mix.exs` the Poison library to parse JSON:

```elixir theme={null}
  defp deps do
    [
      {:poison, "~> 3.0"}
    ]
  end
```

And assuming you use `ecto` you could put in `config/config.exs`:

```elixir theme={null}
relationships = Poison.decode!(Base.decode64!(System.get_env("PLATFORM_RELATIONSHIPS")))
[postgresql_config | _tail] = relationships["postgresql"]

config :my_app, Repo,
  database: postgresql_config["path"],
  username: postgresql_config["username"],
  password: postgresql_config["password"],
  hostname: postgresql_config["host"]
```

and setup Ecto during the deploy hook:

```yaml .upsun/config.yaml theme={null}
applications:
  myapp:
    hooks:
      deploy: |
        mix do ecto.setup
```

## View application instance details

To understand how an application's instances are distributed, you can view the instance details in the project's `/run/peers.json` file. To learn more, see [View application instance details](/docs/manage-resources/adjust-resources#view-application-instance-details) in the "Resource configuration" topic.


# Go
Source: https://developer.upsun.com/docs/languages/go

Upsun Cloud supports building and deploying applications written in Go using Go modules. They're compiled during the Build hook phase, and support both committed dependencies and download-on-demand.

<DisclaimerNix />

## Supported versions

You can select the major and minor version.

Patch versions are applied periodically for bug fixes and other maintenance updates. By default, you get the latest available patches each time you deploy. If your project has a [maintenance window](/docs/core-concepts/build-deploy#maintenance-window) configured, Upsun Cloud applies patches only during that window. Upsun Cloud may still apply urgent or critical fixes outside of the maintenance window.

* <span>1.27</span>
* <span>1.26</span>

### Specify the language

To use Go, specify `golang` as your [app's `type`](/docs/configure-apps/app-reference/single-runtime-image#type):

For example:

## Deprecated versions

The following versions are still available in your projects,
but they're at their end of life and are no longer receiving security updates from upstream.

*No deprecated versions.*

To ensure your project remains stable in the future, switch to a [supported version](#supported-versions).

## Retired versions

The following versions have been retired and are no longer available.
If your project uses a retired version, you must update to a [supported version](#supported-versions).

* <span>1.25</span>
* <span>1.24</span>
* <span>1.23</span>
* <span>1.22</span>
* <span>1.21</span>
* <span>1.20</span>
* <span>1.19</span>
* <span>1.18</span>
* <span>1.17</span>
* <span>1.16</span>
* <span>1.15</span>
* <span>1.14</span>
* <span>1.13</span>
* <span>1.12</span>
* <span>1.11</span>
* <span>1.10</span>

## Go toolchain auto download

Even though you select a specific version of Go, starting in Go 1.21, the `go` command will automatically download and use a different toolchain version as requested by the `toolchain` directive in `go.mod`, or the `GOTOOLCHAIN` environmental variable (see [Go Toolchains](https://go.dev/doc/toolchain)).

<Note>
  Still, it is important to keep your chosen version of Go updated in your yaml configuration file. This will ensure that you are using the most up to date software for your projects.
</Note>

## Go modules

The recommended way to handle Go dependencies on Upsun Cloud is using Go module support in Go 1.11 and later. That allows the build process to use `go build` directly without any extra steps, and you can specify an output executable file of your choice. (See the examples below.)

## Building and running the application

Assuming your `go.mod` and `go.sum` files are present in your repository, your application can be built with the command `go build`, to produce a working executable. You can then start it from the `web.commands.start` directive. Note that the start command *must* run in the foreground. If the program terminates for any reason it is automatically restarted.

The following basic `.upsun/config.yaml` file is sufficient to run most Go applications.

Note that there is still an Nginx proxy server sitting in front of your application.
If desired, certain paths may be served directly by Nginx without hitting your application (for static files, primarily)
or you may route all requests to the Go application unconditionally, as in the example above.

## Accessing services

To access various [services](/docs/add-services) with Go, see the following examples. The individual service pages have more information on configuring each service.

You can access service credentials to connect to [managed services](/docs/add-services) from environment variables present in the application container.
Consult each of the individual service documentation to see how to retrieve and surface credentials into your application.

* [ClickHouse](/docs/add-services/clickhouse#usage-example)
* [Elasticsearch](/docs/add-services/elasticsearch#usage-example)
* [Gotenberg](/docs/add-services/gotenberg#usage-example)
* [Headless Chrome](/docs/add-services/headless-chrome#usage-example)
* [InfluxDB](/docs/add-services/influxdb#usage-example)
* [Kafka](/docs/add-services/kafka#usage-example)
* [MariaDB/MySQL](/docs/add-services/mysql#usage-example)
* [Memcached](/docs/add-services/memcached#usage-example)
* [mercure](/docs/add-services/mercure#usage-example)
* [mongodb](/docs/add-services/mongodb#usage-example)
* [Network Storage](/docs/add-services/network-storage#usage-example)
* [OpenSearch](/docs/add-services/opensearch#usage-example)
* [PostgreSQL](/docs/add-services/postgresql#usage-example)
* [RabbitMQ](/docs/add-services/rabbitmq#usage-example)
* [Redis](/docs/add-services/redis#usage-example)
* [Solr](/docs/add-services/solr#usage-example)
* [Valkey](/docs/add-services/valkey#usage-example)
* [Varnish](/docs/add-services/varnish#usage-example)
* [Vault KMS](/docs/add-services/vault#usage-example)
* [Chroma](/tutorials/self-hosted/chroma#3-use-the-relationship-in-your-application)
* [Qdrant](/tutorials/self-hosted/qdrant#4-use-the-relationship-in-your-application)

<RepoList lang="golang" />


# Languages
Source: https://developer.upsun.com/docs/languages/index

We sure do support a lot of runtimes.

Upsun Cloud supports a wide range of languages and runtimes for building and deploying your applications.

<CardGroup>
  <Card title="C#/.NET Core" icon="code" href="/docs/languages/dotnet">
    Deploy .NET applications on Upsun Cloud.
  </Card>

  <Card title="Elixir" icon="code" href="/docs/languages/elixir">
    Deploy Elixir applications on Upsun Cloud.
  </Card>

  <Card title="Go" icon="code" href="/docs/languages/go">
    Deploy Go applications on Upsun Cloud.
  </Card>

  <Card title="Java" icon="coffee" href="/docs/languages/java">
    Deploy Java applications with migration guides and tuning tips.
  </Card>

  <Card title="JavaScript/Node.js" icon="js" href="/docs/languages/nodejs">
    Deploy Node.js applications with debugging and version management.
  </Card>

  <Card title="PHP" icon="php" href="/docs/languages/php">
    Deploy PHP applications with extensions, tuning, and more.
  </Card>

  <Card title="Python" icon="python" href="/docs/languages/python">
    Deploy Python applications with dependency and server configuration.
  </Card>

  <Card title="Ruby" icon="gem" href="/docs/languages/ruby">
    Deploy Ruby applications on Upsun Cloud.
  </Card>

  <Card title="Rust" icon="rust" href="/docs/languages/rust">
    Deploy Rust applications on Upsun Cloud.
  </Card>
</CardGroup>


# Java
Source: https://developer.upsun.com/docs/languages/java/index

Java is a general-purpose programming language, and one of the most popular in the world today. Upsun Cloud supports Java runtimes that can be used with build management tools such as Gradle, Maven, and Ant.

<DisclaimerNix />

## Supported versions

You can select the major version. But the latest compatible minor version is applied automatically and can’t be overridden.

Patch versions are applied periodically for bug fixes and other maintenance updates. By default, you get the latest available patches each time you deploy. If your project has a [maintenance window](/docs/core-concepts/build-deploy#maintenance-window) configured, Upsun Cloud applies patches only during that window. Upsun Cloud may still apply urgent or critical fixes outside of the maintenance window.

### OpenJDK versions:

* <span>25</span>
* <span>21</span>

These versions refer to the headless packages of OpenJDK.
To save space and reduce potential vulnerabilities, they don't contain GUI classes, which can't be used on the server.

## Deprecated versions

The following versions are still available in your projects,
but they're at their end of life and are no longer receiving security updates from upstream.

*No deprecated versions.*

To ensure your project remains stable in the future, switch to a [supported version](#supported-versions).

## Retired versions

The following versions have been retired and are no longer available.
If your project uses a retired version, you must update to a [supported version](#supported-versions).

* <span>19</span>
* <span>18</span>
* <span>17</span>
* <span>14</span>
* <span>13</span>
* <span>12</span>
* <span>11</span>
* <span>8</span>

### Specify the language

To use Java, specify `java` as your [app's `type`](/docs/configure-apps/app-reference/single-runtime-image#type):

For example:

## Support build automation

Upsun Cloud supports the most common project management tools in the Java ecosystem, including:

* [Gradle](https://gradle.org/)
* [Maven](https://maven.apache.org/)
* [Ant](https://ant.apache.org/)

### Manage Maven versions

Java containers come with a version of Maven already installed.
You may need to use a specific different version to manage your project.
If the version you need differs from the version on your container, you can install the specific version that you need.

Add something like the following to your [app configuration](/docs/configure-apps):

## Other JVM languages

It’s worth remembering that the JVM by its specification [doesn't read Java code](https://docs.oracle.com/javase/specs/jvms/se8/html/index.html), but bytecode. So within the JVM, it’s possible to [run several languages](https://en.wikipedia.org/wiki/List_of_JVM_languages). Upsun Cloud supports several of them, such as Kotlin, Groovy, and Scala, so long as that language works with any build automation that Upsun Cloud supports.

| Article | Link |
| - | - |
| Kotlin and Spring | [Source](https://github.com/platformsh-templates/spring-kotlin) |
| [Scala and Spring](https://dzone.com/articles/spring-scala-cloud-psh) | [Source](https://github.com/platformsh-examples/scala) |

<Note>
  While the table above shows examples for Platform.sh rather than for Upsun Cloud, the same rules apply with only slight changes in configuration.
</Note>

## Accessing services

You can access service credentials to connect to [managed services](/docs/add-services) from environment variables present in the application container.
Consult each of the individual service documentation to see how to retrieve and surface credentials into your application.

* [ClickHouse](/docs/add-services/clickhouse#usage-example)
* [Elasticsearch](/docs/add-services/elasticsearch#usage-example)
* [Gotenberg](/docs/add-services/gotenberg#usage-example)
* [Headless Chrome](/docs/add-services/headless-chrome#usage-example)
* [InfluxDB](/docs/add-services/influxdb#usage-example)
* [Kafka](/docs/add-services/kafka#usage-example)
* [MariaDB/MySQL](/docs/add-services/mysql#usage-example)
* [Memcached](/docs/add-services/memcached#usage-example)
* [mercure](/docs/add-services/mercure#usage-example)
* [mongodb](/docs/add-services/mongodb#usage-example)
* [Network Storage](/docs/add-services/network-storage#usage-example)
* [OpenSearch](/docs/add-services/opensearch#usage-example)
* [PostgreSQL](/docs/add-services/postgresql#usage-example)
* [RabbitMQ](/docs/add-services/rabbitmq#usage-example)
* [Redis](/docs/add-services/redis#usage-example)
* [Solr](/docs/add-services/solr#usage-example)
* [Valkey](/docs/add-services/valkey#usage-example)
* [Varnish](/docs/add-services/varnish#usage-example)
* [Vault KMS](/docs/add-services/vault#usage-example)
* [Chroma](/tutorials/self-hosted/chroma#3-use-the-relationship-in-your-application)
* [Qdrant](/tutorials/self-hosted/qdrant#4-use-the-relationship-in-your-application)

<RepoList lang="java" />


# Moving a Java application to Upsun Cloud
Source: https://developer.upsun.com/docs/languages/java/migration



<DisclaimerNix />

It is common to have a Java application that you want to migrate to Upsun Cloud.
Upsun Cloud supports several styles of Java application, such as monolith, microservices, stateful, and stateless.

## Minimum Requirement

To run a Java application at Upsun Cloud you need:

* [A supported Java version](/docs/languages/java#supported-versions)
* [A build management tool](/docs/languages/java#support-build-automation)
  * [Gradle](https://docs.gradle.org/current/userguide/gradle_wrapper.html)
  * [Maven](https://maven.apache.org/)
  * [Maven Wrapper](https://www.baeldung.com/maven-wrapper)
  * [Ant](https://ant.apache.org/)
* A Git Repository:
  * [GitHub](/docs/integrations/source/github)
  * [BitBucket](/docs/integrations/source/bitbucket)
  * [GitLab](/docs/integrations/source/gitlab)
  * The default Git repository provided by Upsun Cloud

<Note>
  A container application can't be bigger than **8 GB** of memory.
  For more details, see [tuning](/docs/languages/java/tuning).
</Note>

## Monolith/Single Application

To start a Java application, you need to understand the [Upsun Cloud structure](/docs/core-concepts/structure).
You will need to configure your [application](/docs/configure-apps), [routes](/docs/routes),
and [services](/docs/add-services).

### Application

1. [A Java version](/docs/languages/java#supported-versions), e,g.: `java:<VERSION>`.
2. [Hooks define what happens when building the application](/docs/configure-apps/hooks). This build process typically generates an executable file such as a uber-jar. For example, `mvn clean package`.
3. [The commands key defines the command to launch the application](/docs/configure-apps/image-properties/web#web-commands). For example,  `java -jar file.jar`.
4. In the start's command needs to receive the port where the application will execute thought the `PORT` environment. That's best when your app follows the port bind principle. For example, `java -jar jar --port=$PORT`.

<Note>
  Be aware that after the build, it creates a read-only system. You have the [mount option to create a writable folder](/docs/configure-apps/image-properties/mounts).
</Note>

### Route

1. It defines the application will link in the route. For example,`"myapp:http"`.

<Note>
  Application instances have a limited amount of memory at build time, which has a maximum of 8 GB.
  At runtime that limit depends on your plan and configuration.
  A stateless application can be scaled horizontally to multiple application instances using Varnish in a [load balancer](https://support.platform.sh/hc/en-us/community/posts/16439676899474) configuration.
</Note>

<Note>
  Application instances have a limited amount of memory at build time, which has a maximum of 8 GB.
  At runtime that limit depends on [the resources you have defined for your application container](/docs/manage-resources) using `upsun resources:set`.
  A stateless application can be scaled horizontally to multiple application instances with `upsun resources:set` or by using Varnish in a [load balancer](https://support.platform.sh/hc/en-us/community/posts/16439676899474) configuration.
</Note>

## Microservices

You have the option to use several languages in microservices. If you're using Java there are several options to aggregate these services into a microservices:

* [Maven Modules](https://maven.apache.org/guides/mini/guide-multiple-modules.html)
* [Gradle Multi-project](https://guides.gradle.org/creating-multi-project-builds/)
* [Git submodules](/docs/development/submodules)

[Upsun Cloud supports multiple applications](/docs/configure-apps/multi-app) and there are two options:

* One application YAML file to each application
* Aggregate all applications in a single file with an `.upsun/config.yaml` file

| Article | Content |
| - | - |
| [Microservices in the cloud, part two](https://devcenter.upsun.com/posts/microservices-in-the-cloud-part-two/) | [Source](https://github.com/EventosJEspanol/latin-america-micro-profile) |
| [Microservices in the cloud, part one](https://upsun.com/blog/) | [Source](https://github.com/EventosJEspanol/latin-america-micro-profile) |
| [Multiple Applications](https://support.platform.sh/hc/en-us/community/posts/16439649733010) | [Source](https://github.com/platformsh-examples/tomcat-multi-app) |
| [Configure multi-applications with `.upsun/config.yaml`](https://support.platform.sh/hc/en-us/community/posts/16439676928274) | [Source](https://github.com/platformsh-examples/tomcat-multi-app-applications) |

<Note>
  You can load balance to some or [all applications in the project cluster](https://support.platform.sh/hc/en-us/community/posts/16439662235026).

  While the table above shows examples for Upsun Fixed rather than for Upsun Flex, the same rules apply with only slight changes in configuration.
</Note>

## Access to managed services

Upsun Cloud provides [managed services](/docs/add-services) such as databases, cache, and search engines.
However, you can use an external database or other services during a transition process. To maintain security, you must ensure that your external service (e.g., your external database or a third-party API)
is configured to accept connections from Upsun Cloud’s outbound IP addresses.

When applications need to access a *managed* service, it is important to include the [`relationships` key](/docs/configure-apps/image-properties/relationships).
By default an application may not talk to any other container without a `relationship` explicitly allowing access.

The most common mechanisms for connecting to a managed service are listed below.

### Overwrite

If you are using a framework that follows the [Twelve-Factor App](https://12factor.net/) methodology, particularly the [third point](https://12factor.net/config), you can configure the application directly from environment variables.
Examples of such frameworks include Spring, Eclipse MicroProfile Config, Quarkus, and Micronauts.

Service credentials are available within the [service environment variables](/docs/development/variables#service-environment-variables), or the [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables).

<Tabs>
  <Tab title="Service environment variables">
    Assuming the relationship `postgresql` is configured to grant access to a PostgreSQL service container, you can map the automatically generated environment variable (`POSTGRESQL_HOST`) to whatever your application expects to use:

    ```bash .environment theme={null}
    export DB_HOST="$POSTGRESQL_HOST"
    ```

    This sets environment variables with the names your app needs,
    and the values from [service environment variables](/docs/development/variables#service-environment-variables).
  </Tab>

  <Tab title="`PLATFORM_RELATIONSHIPS` environment variable">
    This variable is a base64-encoded JSON object with keys of the relationship name and values of arrays of relationship endpoint definitions.

    Upsun Cloud supports the [`jq` tool](https://stedolan.github.io/jq/), which allows to extract information from this JSON.

    ```bash .environment theme={null}
    export DB_HOST="$(echo "$PLATFORM_RELATIONSHIPS" | base64 --decode | jq -r '.postgresql[0].host')"
    ```

    This sets environment variables with names your app needs and the values from [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables).
  </Tab>
</Tabs>

| Article | Source |
| - | - |
| [Spring Data MongoDB](https://support.platform.sh/hc/en-us/community/posts/16439654854802) | [Source](https://github.com/platformsh-examples/java-overwrite-configuration/tree/master/spring-mongodb) |
| [Jakarta EE/MicroProfile Config](https://support.platform.sh/hc/en-us/community/posts/16439700735122) | [Source](https://github.com/platformsh-examples/java-overwrite-configuration/tree/master/jakarta-nosql) |
| [Spring Data JPA](https://support.platform.sh/hc/en-us/community/posts/16439669562130) | [Source](https://github.com/platformsh-examples/java-overwrite-configuration/tree/master/spring-jpa) |
| [Payara JPA](https://support.platform.sh/hc/en-us/community/posts/16439658290194) | [Source](https://github.com/platformsh-examples/java-overwrite-configuration/blob/master/payara/README) |

<Note>
  While the table above shows examples for Upsun Fixed rather than for Upsun Flex, the same rules apply with only slight changes in configuration.
</Note>

To reduce the number of lines in the application file and to make it cleaner,
you have the option to move the variable environment to another file: a [`.environment` file](/docs/development/variables/set-variables#set-variables-via-script).

**Example:**

You can obtain relationship information through the [service environment variables](/docs/development/variables#service-environment-variables) themselves,
or through the [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables).
Say your application has a relationship named `postgresql` to a database service named `postgresql`:

<Tabs>
  <Tab title="Service environment variables">
    ```bash .environment theme={null}
    export DB_HOST="${POSTGRESQL_HOST}"
    export DB_PASSWORD="${POSTGRESQL_PASSWORD}"
    export DB_USER="${POSTGRESQL_USERNAME}"
    export DB_DATABASE="${POSTGRESQL_PATH}"
    export JDBC="jdbc:postgresql://${HOST}/${DATABASE}"
    export JAVA_MEMORY="-Xmx$(jq .info.limits.memory /run/config.json)m"
    export JAVA_OPTS="$JAVA_MEMORY -XX:+ExitOnOutOfMemoryError"
    ```

    This sets environment variables with the names your app needs,
    and the values from [service environment variables](/docs/development/variables#service-environment-variables).
  </Tab>

  <Tab title="`PLATFORM_RELATIONSHIPS` environment variable">
    This `PLATFORM_RELATIONSHIPS` variable is a base64-encoded JSON object with keys of the relationship name and values of arrays of relationship endpoint definitions.

    Upsun Cloud supports the [`jq` tool](https://stedolan.github.io/jq/), which allows to extract information from this JSON.

    ```bash .environment theme={null}
    export DB_HOST="$(echo "$PLATFORM_RELATIONSHIPS" | base64 --decode | jq -r ".postgresql[0].host')"
    export DB_PASSWORD="$(echo "$PLATFORM_RELATIONSHIPS" | base64 --decode | jq -r ".postgresql[0].password')"
    export DB_USER="$(echo "$PLATFORM_RELATIONSHIPS" | base64 --decode | jq -r ".postgresql[0].username')"
    export DB_DATABASE="$(echo "$PLATFORM_RELATIONSHIPS" | base64 --decode | jq -r ".postgresql[0].path')"
    export JDBC="jdbc:postgresql://${HOST}/${DATABASE}"
    export JAVA_MEMORY="-Xmx$(jq .info.limits.memory /run/config.json)m"
    export JAVA_OPTS="$JAVA_MEMORY -XX:+ExitOnOutOfMemoryError"
    ```

    This sets environment variables with names your app needs and the values from [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables).
  </Tab>
</Tabs>

This `.environment` file can interact to each application file.

**Example:**


# Performance tuning Java
Source: https://developer.upsun.com/docs/languages/java/tuning



<DisclaimerNix />

There are a number of settings that can be adjusted for each application to optimize its performance on Upsun Cloud.

## Memory limits

The JVM generally requires specifying a maximum memory size it is allowed to use, using the `Xmx` parameter.
That should be set based on the available memory on the application container, which varies with its size.

To extract the container-scaled value on the command line, use `$(jq .info.limits.memory /run/config.json)`.

You should also set the `ExitOnOutOfMemoryError`.
When you enable this option, the JVM exits on the first occurrence of an out-of-memory error.
Upsun Cloud will restart the application automatically.

These are the recommended parameters for running a Java application. Thus, the command to use to start a Java application is:

```bash theme={null}
java -jar -Xmx$(jq .info.limits.memory /run/config.json)m -XX:+ExitOnOutOfMemoryError //The rest of the arguments and the jar file.
```

## Garbage collection

When migrating the application to a cloud environment, it is often essential to analyze the Garbage Collector's log and behavior. For this, there are two options:

* Placing the log into the Upsun Cloud `/var/log/app.log` file (which captures `STDOUT`).
* Creating a log file specifically for the GC.

To use the `STDOUT` log, you can add the parameter `-XX: + PrintGCDetails`, E.g.:

```bash theme={null}
java -jar -Xmx$(jq .info.limits.memory /run/config.json)m -XX:+ExitOnOutOfMemoryError -XX:+PrintGCDetails //The rest of the arguments and the jar file.
```

Java supports a number of different garbage collection strategies.
Which one is optimal for your application varies depending on your available memory, Java version, and application profile.
Determining which is best for your application is out of scope, but the main options and how to enable them are:

| Name | Command  Flag | Description |
| - | :-: | -: |
| Serial Garbage Collector | -XX:+UseSerialGC | This is the simplest GC implementation, as it basically works with a single thread. |
| Parallel Garbage Collector | -XX:+UseParallelGC | Unlike Serial Garbage Collector, this uses multiple threads for managing heap space. But it also freezes other application threads while performing GC. |
| CMS Garbage Collector | -XX:+USeParNewGC | The Concurrent Mark Sweep (CMS) implementation uses multiple garbage collector threads for garbage collection. It's for applications that prefer shorter garbage collection pauses, and that can afford to share processor resources with the garbage collector while the application is running. |
| G1 Garbage Collector | -XX:+UseG1GC | Garbage First, G1, is for applications running on multiprocessor machines with large memory space. |

The default strategy on Java 9 and later is G1.
The GC strategy to use can be set in the start line with:

### Serial

```bash theme={null}
java -jar -Xmx$(jq .info.limits.memory /run/config.json)m -XX:+ExitOnOutOfMemoryError -XX:+PrintGCDetails -XX:+UseSerialGC //The rest of the arguments and the jar file.
```

### Parallel Garbage Collector

```bash theme={null}
java -jar -Xmx$(jq .info.limits.memory /run/config.json)m -XX:+ExitOnOutOfMemoryError -XX:+PrintGCDetails -XX:+UseParallelGC //The rest of the arguments and the jar file.
```

### CMS Garbage Collector

```bash theme={null}
java -jar -Xmx$(jq .info.limits.memory /run/config.json)m -XX:+ExitOnOutOfMemoryError -XX:+PrintGCDetails -XX:+USeParNewGC //The rest of the arguments and the jar file.
```

### G1

```bash theme={null}
java -jar -Xmx$(jq .info.limits.memory /run/config.json)m -XX:+ExitOnOutOfMemoryError -XX:+PrintGCDetails -XX:+UseG1GC //The rest of the arguments and the jar file.
```

## Java 8 Optimization

Ideally, all applications should run the latest LTS release of the JVM at least.
That is currently Java 11.
Java 11 has a number of performance improvements, particularly on container-based environments such as Upsun Cloud.

However, in many cases, this isn't possible.
If you are still running on Java 8 there are two additional considerations.

The default garbage collector for Java 8 is Parallel GC.
In most cases G1 will offer better performance.
We recommend enabling it, as above.

Furthermore, there is the `UseStringDeduplication` flag which works to eliminate duplicate `String`s within the GC process.
That flag can save between 13% to 30% of memory, depending on application. However, this can impact on the pause time of your app.

```bash theme={null}
java -jar -Xmx$(jq .info.limits.memory /run/config.json)m -XX:+UseG1GC -XX:+UseStringDeduplication -XX:+ExitOnOutOfMemoryError -XX:+PrintGCDetails
```

## References

* [Introduction to Garbage Collection Tuning](https://docs.oracle.com/en/java/javase/14/gctuning/introduction-garbage-collection-tuning.html#GUID-326EB4CF-8C8C-4267-8355-21AB04F0D304)


# Debugging
Source: https://developer.upsun.com/docs/languages/nodejs/debug



<DisclaimerNix />

Effectively debugging web apps takes effort,
especially when an HTTP request goes through multiple layers before reaching your web app.
Follow the steps below to debug a specific app.

You can choose to debug in an environment deployed to Upsun Cloud
or with your app running locally but connected to deployed services.
In either case, make sure to debug in a preview environment.

For more general information, see how to [troubleshoot development](/docs/troubleshooting/general).

## 1. Create a new environment

Start by creating a new environment completely isolated from production but with the same data for debugging:

```bash theme={null}
upsun branch debug-branch
```

## 2. Get access

<Tabs>
  <Tab title="Remote">
    Access your app container via [SSH](/docs/development/ssh):

    ```bash theme={null}
    upsun ssh
    ```
  </Tab>

  <Tab title="Local">
    To access deployed apps and services, open tunnels to everything your app has relationships with:

    ```bash theme={null}
    upsun tunnel:open
    ```

    In the same terminal, set the relevant environment variables:

    ```bash theme={null}
    export PLATFORM_RELATIONSHIPS="$(upsun tunnel:info --encode)"
    export PORT=8888
    ```
  </Tab>
</Tabs>

## 3. Run your app in inspect mode

<Tabs>
  <Tab title="Remote">
    Stop the current process and restart it in inspect mode:

    ```bash theme={null}
    sv stop app
    node --inspect <START_FILE>
    ```
  </Tab>

  <Tab title="Local">
    In the same terminal as the previous step, run the following command:

    ```bash theme={null}
    node --inspect <START_FILE>
    ```
  </Tab>
</Tabs>

Replace `<START_FILE>` with the file defined for [your app's `start` command](/docs/languages/nodejs#4-start-your-app).

You get output something like this:

```bash theme={null}
Debugger listening on ws://127.0.0.1:9229/10701e5d-d627-4180-a967-d47a924c93c0
For help, see: https://nodejs.org/en/docs/inspector
Listening on port 8888
```

## 4. (If debugging remotely) Forward the debugger port locally

In another terminal, create an SSH tunnel that forwards to the 9229 port:

```bash theme={null}
ssh -N -L 9229:localhost:9229 $(upsun ssh --pipe)
```

## 5. Connect the debugger

You can now connect the debugger as if you were debugging a local application.
See examples with some common tools:

<Tabs>
  <Tab title="Using Chrome developer tools">
    Go to `chrome://inspect`.
    Find your running app under the `Remote Target` list.
    Click **inspect** to start the debugger.
  </Tab>

  <Tab title="Using Visual Studio Code">
    Use the `Node.js: Attach` debugger option.

    If you haven't created the option:

    1. On the **Run and Debug** tab, click `create a launch.json file`.
    2. Select `Node.js` as the environment.
    3. In the `configurations` array, start IntelliSense (usually <kbd>ctrl</kbd>+<kbd>space</kbd>).
    4. Select `Node.js: Attach`.
    5. Make sure the port is the same as in [step 4 above](#4-if-debugging-remotely-forward-the-debugger-port-locally).

    Once you have the option:

    In the **Run and Debug** tab, select `Attach` from the menu and click **Start Debugging** (the green arrow).

    See more on [Node.js debugging in Visual Studio Code](https://code.visualstudio.com/docs/nodejs/nodejs-debugging).
  </Tab>
</Tabs>

Now when you load the site at your deployed URL (if debugging remote) or localhost (if debugging locally),
the local debugger you've attached is called.

Set breakpoints:

<Tabs>
  <Tab title="Remote">
    In the JavaScript files from your remote site:
    On the **Run and Debug** tab under **Loaded Scripts** find `Attach: Remote Process` > `/app`.
  </Tab>

  <Tab title="Local">
    Directly in your source files.
  </Tab>
</Tabs>

## Other issues

### pm2 process manager blocks other processes

If you're using the [`pm2` process manager](https://github.com/unitech/pm2) to start your app from a script,
you might find it daemonizes itself and blocks other processes (such as backups) by constantly respawning.
This may happen even if you use the `--no-daemon` flag.

Instead of using a script, call `pm2 start` directly in your [`start` command](/docs/languages/nodejs#4-start-your-app).


# JavaScript/Node.js
Source: https://developer.upsun.com/docs/languages/nodejs/index

Get started creating JavaScript apps with Node.js on Upsun Cloud.

<DisclaimerNix />

Node.js is a popular asynchronous JavaScript runtime.
Deploy scalable Node.js apps of all sizes on Upsun Cloud.
You can also develop a microservice architecture mixing JavaScript and other apps with [multi-app projects](/docs/configure-apps/multi-app).

## Active versions

See [Image statuses](/docs/core-concepts/upgrade-runtimes-services#image-statuses) for what Active means.

You can select the major version. But the latest compatible minor version is applied automatically and can’t be overridden.

Patch versions are applied periodically for bug fixes and other maintenance updates. By default, you get the latest available patches each time you deploy. If your project has a [maintenance window](/docs/core-concepts/build-deploy#maintenance-window) configured, Upsun Cloud applies patches only during that window. Upsun Cloud may still apply urgent or critical fixes outside of the maintenance window.

* <span>26</span>
* <span>24</span>
* <span>22</span>

### Specify the language

To use Node.js, specify `nodejs` as your [app’s type](/docs/configure-apps/app-reference/single-runtime-image#type):

For example:

To use a specific version in a container with a different language, [use a version manager](/docs/languages/nodejs/node-version).

## Sunset versions

The following versions are still available in your projects, including code pushes, but new projects can't use them.
These versions are decommissioned 180 calendar days after entering Sunset. The exact decommission date is shown on your project's Overview page and on the relevant activity in the **Activity** panel. See [Image statuses](/docs/core-concepts/upgrade-runtimes-services#image-statuses) for what each status means.

* <span>20</span>
* <span>18</span>
* <span>16</span>
* <span>15</span>
* <span>14</span>
* <span>12</span>
* <span>10</span>
* <span>8.9</span>
* <span>8</span>
* <span>6.10</span>
* <span>6.9</span>
* <span>6.8</span>
* <span>6.6</span>
* <span>6.3</span>
* <span>6.2</span>
* <span>6</span>
* <span>4.7</span>
* <span>4.6</span>
* <span>4.5</span>
* <span>4.4</span>
* <span>4.3</span>
* <span>4.2</span>
* <span>4</span>
* <span>0.12</span>

## Decommissioned versions

The following versions have been decommissioned and are no longer available. See [Image statuses](/docs/core-concepts/upgrade-runtimes-services#image-statuses) for what each status means.
If your project uses a decommissioned version, you must update to an [active version](#active-versions).

*No decommissioned versions.*

## Usage example

To use JavaScript with Node.js on Upsun Cloud, configure your [app configuration](/docs/configure-apps)
(a complete example is included at the end).

### 1. Specify the version

Choose a version from the [list of active versions](#active-versions)
and add it to your app configuration:

### 2. Specify any global dependencies

Add the following to your app configuration:

These are now available as commands, the same as installing with `npm install -g`.

### 3. Build your app

Include any commands needed to build and setup your app in the `hooks`, as in the following example:

### 4. Start your app

Specify a command to start serving your app (it must be a process running in the foreground):

### 5. Listen on the right port

Make sure your Node.js application is configured to listen over the port given by the environment.

```js theme={null}
// Load the http module to create an http server.
const http = require('http');
const PORT = process.env.PORT || 8888;

const server = http.createServer(function (request, response) {
    response.writeHead(200, {"Content-Type": "application/json"});
    response.end("Hello world!");
});

// Listen on the port from the Upsun Cloud configuration
server.listen(PORT, () => {
  console.log(`Server is listening on port: ${PORT}`);
});
```

### Complete example

A complete basic app configuration looks like the following:

## Dependencies

By default, Upsun Cloud assumes you're using npm as a package manager.
If your code has a `package.json`, the following command is run as part of the default [build flavor](/docs/configure-apps/app-reference/single-runtime-image#build):

```bash theme={null}
npm prune --userconfig .npmrc && npm install --userconfig .npmrc
```

This means you can specify configuration in a `.npmrc` file in [your app root](/docs/configure-apps/app-reference/single-runtime-image#root-directory).

### Use Yarn as a package manager

To switch to Yarn to manage dependencies, follow these steps:

1. Turn off the default use of npm:

2) Specify the version of Yarn you want:

   ```json package.json theme={null}
   {
     ...
     "packageManager": "yarn@3.2.1"
   }
   ```

What you do next depends on the versions of Yarn and Node.js you want.

<Tabs>
  <Tab title="Yarn 3.x and Node.js 16+">
    3. Use Corepack to run Yarn in your build hook:
  </Tab>

  <Tab title="Yarn 3.x and Node.js < 16">
    3. Enable Corepack (which is opt-in):

    4) Use Corepack to run Yarn in your build hook:
  </Tab>

  <Tab title="Yarn < 3">
    3. Add Yarn as a global dependency:

    4) Install dependencies in the `build` hook:
  </Tab>
</Tabs>

### Use Bun as a package manager

<Info title="Availability">
  <a href="https://devcenter.upsun.com/posts/bun-support-is-here/">Bun is available as a runtime and package manager</a> for Node.js <strong>version 20 or above</strong>. Choose one of the [active versions](#active-versions) rather than the minimum supported version.
</Info>

To switch to Bun to manage dependencies,
use the following configuration:

```yaml .upsun/config.yaml theme={null}
applications:
  # The name of your app.
  myapp:
  # Choose an active Node.js version.
    type: 'nodejs:26'
    # Override the default Node.js build flavor.
    build:
      flavor: none
    # Use Bun to install the dependencies.
    hooks:
      build: bun install
```

#### Use Bun as a runtime

You can even [use Bun as a runtime](https://devcenter.upsun.com/posts/bun-support-is-here/) by adjusting the `start` command as follows:

```yaml .upsun/config.yaml theme={null}
applications:
  # The name of your app.
  myapp:
    # Choose an active Node.js version.
    type: 'nodejs:26'
    # Override the default Node.js build flavor.
    build:
      flavor: none
    # Use Bun to install the dependencies.
    hooks:
      build: bun install
    # In the start command replace node with Bun.
    web:
      commands:
        start: 'bun app.js'
```

## Connecting to services

You can access service credentials to connect to [managed services](/docs/add-services) from environment variables present in the application container.
Consult each of the individual service documentation to see how to retrieve and surface credentials into your application.

* [ClickHouse](/docs/add-services/clickhouse#usage-example)
* [Elasticsearch](/docs/add-services/elasticsearch#usage-example)
* [Gotenberg](/docs/add-services/gotenberg#usage-example)
* [Headless Chrome](/docs/add-services/headless-chrome#usage-example)
* [InfluxDB](/docs/add-services/influxdb#usage-example)
* [Kafka](/docs/add-services/kafka#usage-example)
* [MariaDB/MySQL](/docs/add-services/mysql#usage-example)
* [Memcached](/docs/add-services/memcached#usage-example)
* [mercure](/docs/add-services/mercure#usage-example)
* [mongodb](/docs/add-services/mongodb#usage-example)
* [Network Storage](/docs/add-services/network-storage#usage-example)
* [OpenSearch](/docs/add-services/opensearch#usage-example)
* [PostgreSQL](/docs/add-services/postgresql#usage-example)
* [RabbitMQ](/docs/add-services/rabbitmq#usage-example)
* [Redis](/docs/add-services/redis#usage-example)
* [Solr](/docs/add-services/solr#usage-example)
* [Valkey](/docs/add-services/valkey#usage-example)
* [Varnish](/docs/add-services/varnish#usage-example)
* [Vault KMS](/docs/add-services/vault#usage-example)
* [Chroma](/tutorials/self-hosted/chroma#3-use-the-relationship-in-your-application)
* [Qdrant](/tutorials/self-hosted/qdrant#4-use-the-relationship-in-your-application)

<RepoList lang="nodejs" />

## Frameworks

All major Javascript/Node.js web frameworks can be deployed on Upsun Cloud.
See dedicated guides for deploying and working with them:

* [Express](/docs/get-started/stacks/express)
* [Next.js](/docs/get-started/stacks/nextjs)
* [Strapi](/docs/get-started/stacks/strapi)


# Manage Node.js versions
Source: https://developer.upsun.com/docs/languages/nodejs/node-version

See how to manage different Node.js versions in your Upsun Cloud containers."

<DisclaimerNix />

Each Upsun Cloud container image includes a specific language in a specific version.
A set of dependencies is also provided based on that language version.
This ensures that your application container is as small and efficient as possible.

Therefore, by default, when you use an Upsun Cloud container image,
you use the Node.js version that's included in that image, if any.

If you want to use a different Node.js version, use a version manager to install it yourself.
You can use one of the following version managers:

* [Use `n`](#use-n)
* [Use `nvm`](#use-nvm)

Both of the recommendations use a `.nvmrc` file to specify the desired Node.js version.
You could also specify a different file or use [environment variables](/docs/development/variables).

## Use `n`

The [`n` package](https://github.com/tj/n) works for various Unix-like systems,
including Windows Subsystem for Linux.

1. Add the desired Node.js version to your environment using `.nvmrc`, `.n-node-version`, `.node-version`, or `package.json`.

<Tabs>
  <Tab title=".nvmrc">
    Create a `.nvmrc` file in [your app root](/docs/configure-apps/app-reference/single-runtime-image#root-directory):

    ```yaml .nvmrc theme={null}
    v16.13.2
    ```
  </Tab>

  <Tab title=".n-node-version/.node-version">
    Create a `.n-node-version` or `.node-version` file in [your app root](/docs/configure-apps/app-reference/single-runtime-image#root-directory):

    ```yaml .n-node-version or .node-version theme={null}
    16.13.2
    ```
  </Tab>

  <Tab title="package.json">
    Add an `engines.node` property to your `package.json`.
    This property accepts either an exact version or a range:

    ```json package.json theme={null}
    {
      "engines": {
        "node": ">=0.10.3 <15"
      }
    }
    ```
  </Tab>
</Tabs>

2. Add it as a dependency:

Adding it as a dependency ensures it's cached for future builds.

3. Set the location of the `n` files using the `N_PREFIX` environment variable:

4) Install the specified version of Node.js in a [`build` hook](/docs/configure-apps/hooks/hooks-comparison#build-hook):

Now your hooks should be able to use the specified version of Node.js.
You can verify this by running `node -v`.

Your final app configuration should look something like this:

## Use `nvm`

[Node Version Manager (`nvm`)](https://github.com/nvm-sh/nvm) is a bash script for managing Node.js versions.

You can use it to:

* Make a specific version available in the build and optionally the runtime container.
* Control the specific versions to be installed with [environment variables](/docs/development/variables),
  meaning you can also have different versions in different environments.

To use `nvm`, follow these steps:

1. Define which `nvm` version to use using an [environment variable](/docs/development/variables).
   Add it to your [app configuration](/docs/configure-apps):

2) Define your desired Node.js version using an environment variable.

   For your base version, set it in your app configuration:

To get different versions in different environments, [set environment-specific variables](/docs/development/variables/set-variables#create-environment-specific-variables).

3. Add a `.nvm` directory to your cache in your [build hook](/docs/configure-apps/hooks):

<Note>
  Instead of using a symlink between your cache and application directories,
  you might need to copy the content of `$PLATFORM_CACHE_DIR/.nvm` into `$PLATFORM_APP_DIR/.nvm` manually.
  To do so, run the following command:

  ```bash theme={null}
  rsync -av $PLATFORM_CACHE_DIR/.nvm $PLATFORM_APP_DIR
  ```
</Note>

4. Use the cache directory and install based on the variables if not present:

5) Optional: To use the specified Node.js version in the runtime container and not just the build,
   activate `nvm` via [script](/docs/development/variables/set-variables#set-variables-via-script):

   ```bash .environment theme={null}
   unset NPM_CONFIG_PREFIX
   export NVM_DIR="$PLATFORM_APP_DIR/.nvm"
   [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
   ```

   Your final app configuration should look something like the following:


# Authenticated Composer repositories
Source: https://developer.upsun.com/docs/languages/php/composer-auth

Allow Composer to authenticate against a private third-party Composer repository and download PHP packages from it.

<DisclaimerNix />

[Packagist](https://packagist.org/) is the primary Composer repository for public PHP packages.
But you can also have Composer download PHP packages from a private, third-party Composer repository.
To make sure Composer has the necessary credentials to do so,
follow the instructions on this page.

## Before you begin

You need:

* An Upsun Cloud project using [PHP](/docs/languages/php) and Composer
* Credentials to access a private third-party Composer repository
* The [Upsun Cloud CLI](/cli)

## 1. Declare a private Composer repository

To allow Composer to download packages from a private third-party repository,
declare the repository in your Composer setup.

## 2. Set up Composer authentication using a variable

To allow Composer to successfully authenticate when accessing the declared private repository,
set an [`env:COMPOSER_AUTH` variable](/docs/development/variables) for your project.

To do so, run the following command:

The [`env:` prefix](/docs/development/variables#top-level-environment-variables) means that the variable is exposed
as its own Unix environment variable.
The `--visible-runtime false` and `--visible-build true` flags mean the variable is available to Composer only during the build.

## 3. Clear your project's build cache

For security reasons, make sure that the authentication credentials aren't cached in your project's build container.
To do so, run the following command:

```bash theme={null}
upsun project:clear-build-cache
```

## Access dependencies downloaded from a private repository

When you download a dependency from a private third-party Composer repository,
that dependency is usually hosted in a [private Git repository](/docs/development/private-repository).
Access to private Git repositories is restricted through the use of SSH keys.
But most private Composer tools mirror tagged releases of dependencies
and serve them directly without hitting the Git repository.
To avoid having to authenticate against a remote Git repository,
make sure your dependencies specify tagged releases.


# Extensions
Source: https://developer.upsun.com/docs/languages/php/extensions

See what PHP extensions are available with each PHP version on Upsun Cloud.

<Info>
  You can use the [Upsun Cloud composable image](/docs/configure-apps/app-reference/composable-image) to install multiple runtimes and tools in your application container.
  When using the composable image, see how you can:

  * [Manage PHP extensions](/docs/configure-apps/app-reference/composable-image#php-extensions-and-python-packages)
  * [Modify your PHP runtime](/docs/languages/php#modify-your-php-runtime-when-using-the-composable-image)
</Info>

PHP has a number of [extensions](https://pecl.php.net/) developed by members of the community.
Some of them are available for Upsun Cloud containers.

You can define the PHP extensions you want to enable or disable:

You can also [include configuration options](/docs/configure-apps/app-reference/single-runtime-image#extensions) for specific extensions.

The following table shows all extensions that are available (●) and on by default (✔).
You can turn on the available ones with the `extensions` key
and turn off those on by default with the `disabled_extensions` key.

<div>
  <div><div><div><span><span>✔</span> Default (enabled)</span><span><span>◆</span> Built-in</span><span><span>●</span> Available</span></div></div><div><table><thead><tr><th>Extension</th><th>Description</th><th>8.5</th><th>8.4</th><th>8.3</th><th>8.2</th><th>8.1</th><th>8.0</th><th>7.4</th><th>7.3</th><th>7.2</th><th>7.1</th><th>7.0</th><th>5.6</th><th>5.5</th><th>5.4</th></tr></thead><tbody><tr><td><code>amqp</code></td><td>RabbitMQ/AMQP messaging client.</td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td /><td /><td /></tr><tr><td><code>apc</code></td><td>Legacy APC opcode/user cache.</td><td /><td /><td /><td /><td /><td /><td /><td /><td /><td /><td /><td /><td /><td><span>●</span></td></tr><tr><td><code>apcu</code></td><td>In-memory user data cache (APCu).</td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td></tr><tr><td><code>apcu\_bc</code></td><td>Backward-compatibility layer for APCu.</td><td /><td /><td /><td /><td /><td /><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td /><td /><td /></tr><tr><td><code>applepay</code></td><td>PHP extension for applepay support.</td><td /><td /><td /><td /><td /><td /><td><span>●</span></td><td><span>●</span></td><td /><td><span>●</span></td><td><span>●</span></td><td /><td /><td /></tr><tr><td><code>bcmath</code></td><td>Arbitrary precision mathematics.</td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td /><td /><td /></tr><tr><td><code>blackfire</code></td><td>Blackfire profiling probe.</td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td></tr><tr><td><code>bz2</code></td><td>bzip2 compression support.</td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>●</span></td><td /><td /><td /></tr><tr><td><code>calendar</code></td><td>Calendar conversion functions.</td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td /><td /><td /></tr><tr><td><code>ctype</code></td><td>Character type checking functions.</td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td /><td /><td /></tr><tr><td><code>curl</code></td><td>HTTP and network requests via libcurl.</td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td></tr><tr><td><code>datadog-profiling</code></td><td>Datadog continuous profiler.</td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td /><td /><td /><td /><td /><td /><td /><td /><td /><td /></tr><tr><td><code>dba</code></td><td>DBA key-value database abstraction.</td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td /><td /><td /></tr><tr><td><code>dom</code></td><td>DOM XML document manipulation.</td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td /><td /><td /></tr><tr><td><code>enchant</code></td><td>Spell checking via Enchant.</td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td></tr><tr><td><code>event</code></td><td>High-performance event loop bindings.</td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td /><td /><td /><td /></tr><tr><td><code>exif</code></td><td>Read image EXIF metadata.</td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td /><td /><td /></tr><tr><td><code>ffi</code></td><td>Foreign Function Interface (C libraries).</td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td /><td /><td /><td /><td /><td /><td /></tr><tr><td><code>fileinfo</code></td><td>MIME type and file metadata detection.</td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td /><td /><td /></tr><tr><td><code>ftp</code></td><td>FTP client functions.</td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td /><td /><td /></tr><tr><td><code>gd</code></td><td>Image creation and manipulation (GD).</td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td></tr><tr><td><code>gearman</code></td><td>Gearman job queue client/worker.</td><td /><td /><td /><td /><td /><td /><td /><td /><td /><td /><td /><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td></tr><tr><td><code>geoip</code></td><td>IP geolocation lookups.</td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td></tr><tr><td><code>gettext</code></td><td>Native gettext i18n support.</td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td /><td /><td /></tr><tr><td><code>gmp</code></td><td>Big integer arithmetic (GMP).</td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td></tr><tr><td><code>gnupg</code></td><td>GnuPG encryption/signature support.</td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td /><td /><td /><td /><td /><td /><td /><td /></tr><tr><td><code>grpc</code></td><td>gRPC client/server support.</td><td><span>●</span></td><td><span>●</span></td><td /><td /><td /><td /><td /><td /><td /><td /><td /><td /><td /><td /></tr><tr><td><code>http</code></td><td>PHP extension for http support.</td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td /><td /><td /><td /><td /><td><span>●</span></td></tr><tr><td><code>iconv</code></td><td>Character set conversion.</td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td /><td /><td /></tr><tr><td><code>igbinary</code></td><td>Compact binary serializer.</td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td /><td /><td /></tr><tr><td><code>imagick</code></td><td>Image processing with ImageMagick.</td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td></tr><tr><td><code>imap</code></td><td>IMAP/POP3/NNTP mail access.</td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td></tr><tr><td><code>interbase</code></td><td>Firebird/InterBase database driver.</td><td /><td /><td /><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td></tr><tr><td><code>intl</code></td><td>Internationalization (ICU) features.</td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td></tr><tr><td><code>ioncube</code></td><td>ionCube loader support.</td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td /><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td /><td /><td /></tr><tr><td><code>json</code></td><td>JSON encode/decode functions.</td><td><span>◆</span></td><td><span>◆</span></td><td><span>◆</span></td><td><span>◆</span></td><td><span>◆</span></td><td><span>◆</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>●</span></td><td /></tr><tr><td><code>ldap</code></td><td>LDAP directory access.</td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td></tr><tr><td><code>lz4</code></td><td>LZ4 compression support.</td><td><span>●</span></td><td><span>●</span></td><td /><td /><td /><td /><td /><td /><td /><td /><td /><td /><td /><td /></tr><tr><td><code>lzf</code></td><td>LZF compression support.</td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td /><td /><td /><td /><td /><td /><td /><td /><td /><td /><td /></tr><tr><td><code>mailparse</code></td><td>Email/MIME parsing utilities.</td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td /><td /><td /></tr><tr><td><code>mbstring</code></td><td>Multibyte string functions.</td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td /><td /><td /></tr><tr><td><code>mcrypt</code></td><td>Legacy mcrypt encryption functions.</td><td /><td /><td /><td /><td /><td /><td /><td /><td /><td><span>●</span></td><td><span>●</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td></tr><tr><td><code>memcache</code></td><td>Memcache client extension.</td><td /><td /><td /><td /><td /><td /><td /><td /><td /><td /><td /><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td></tr><tr><td><code>memcached</code></td><td>Memcached client extension.</td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td></tr><tr><td><code>mongo</code></td><td>Legacy MongoDB driver.</td><td /><td /><td /><td /><td /><td /><td /><td /><td /><td /><td /><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td></tr><tr><td><code>mongodb</code></td><td>MongoDB driver.</td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td /><td /><td /></tr><tr><td><code>msgpack</code></td><td>MessagePack serialization.</td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td /><td /></tr><tr><td><code>mssql</code></td><td>Legacy Microsoft SQL Server driver.</td><td /><td /><td /><td /><td /><td /><td /><td /><td /><td /><td /><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td></tr><tr><td><code>mysql</code></td><td>Legacy MySQL driver.</td><td /><td /><td /><td /><td /><td /><td /><td /><td /><td /><td /><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td></tr><tr><td><code>mysqli</code></td><td>MySQL improved driver.</td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td></tr><tr><td><code>mysqlnd</code></td><td>MySQL native driver.</td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td></tr><tr><td><code>newrelic</code></td><td>New Relic PHP agent.</td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td /><td /></tr><tr><td><code>oauth</code></td><td>OAuth client utilities.</td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td /><td /><td /></tr><tr><td><code>odbc</code></td><td>ODBC database connectivity.</td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td></tr><tr><td><code>opcache</code></td><td>Bytecode cache and optimizer.</td><td><span>◆</span></td><td><span>◆</span></td><td><span>◆</span></td><td><span>◆</span></td><td><span>◆</span></td><td><span>◆</span></td><td><span>◆</span></td><td><span>◆</span></td><td><span>◆</span></td><td><span>◆</span></td><td><span>◆</span></td><td><span>◆</span></td><td><span>◆</span></td><td><span>✔</span></td></tr><tr><td><code>openswoole</code></td><td>OpenSwoole async networking/server.</td><td /><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td /><td /><td /><td /><td /><td /><td /><td /><td /><td /></tr><tr><td><code>opentelemetry</code></td><td>OpenTelemetry tracing/metrics SDK.</td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td /><td /><td /><td /><td /><td /><td /><td /><td /><td /></tr><tr><td><code>pdo</code></td><td>PHP Data Objects core.</td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td></tr><tr><td><code>pdo\_dblib</code></td><td>PDO driver for FreeTDS/MSSQL/Sybase.</td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td></tr><tr><td><code>pdo\_firebird</code></td><td>PDO driver for Firebird.</td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td /><td /><td /><td /><td /><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td></tr><tr><td><code>pdo\_mysql</code></td><td>PDO driver for MySQL/MariaDB.</td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td></tr><tr><td><code>pdo\_odbc</code></td><td>PDO driver for ODBC.</td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td></tr><tr><td><code>pdo\_pgsql</code></td><td>PDO driver for PostgreSQL.</td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td></tr><tr><td><code>pdo\_sqlite</code></td><td>PDO driver for SQLite.</td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td></tr><tr><td><code>pdo\_sqlsrv</code></td><td>PDO driver for SQL Server.</td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td /><td /><td /></tr><tr><td><code>pecl-http</code></td><td>PHP extension for pecl-http support.</td><td /><td /><td /><td /><td /><td /><td /><td /><td /><td /><td /><td><span>●</span></td><td><span>●</span></td><td /></tr><tr><td><code>pgsql</code></td><td>PostgreSQL driver.</td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td></tr><tr><td><code>phar</code></td><td>PHAR archive support.</td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td /><td /><td /></tr><tr><td><code>pinba</code></td><td>PHP extension for pinba support.</td><td /><td /><td /><td /><td /><td /><td /><td /><td /><td /><td /><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td></tr><tr><td><code>posix</code></td><td>POSIX process and system functions.</td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td /><td /><td /></tr><tr><td><code>propro</code></td><td>PHP extension for propro support.</td><td /><td /><td /><td /><td /><td /><td><span>●</span></td><td><span>●</span></td><td /><td /><td /><td><span>●</span></td><td /><td /></tr><tr><td><code>protobuf</code></td><td>Protocol Buffers support.</td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td /><td /><td /><td /><td /><td /><td /><td /><td /></tr><tr><td><code>pspell</code></td><td>Spell checking via Pspell/Aspell.</td><td /><td /><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td></tr><tr><td><code>raphf</code></td><td>PHP extension for raphf support.</td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td /><td /><td /><td><span>●</span></td><td /><td /></tr><tr><td><code>rdkafka</code></td><td>Apache Kafka client (librdkafka).</td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td /><td /><td /><td /><td /><td /><td /><td /><td /></tr><tr><td><code>readline</code></td><td>Interactive readline support.</td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td></tr><tr><td><code>recode</code></td><td>PHP extension for recode support.</td><td /><td /><td /><td /><td /><td /><td /><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td></tr><tr><td><code>redis</code></td><td>Redis client extension.</td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td></tr><tr><td><code>shmop</code></td><td>Shared memory operations.</td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td /><td /><td /></tr><tr><td><code>simplexml</code></td><td>SimpleXML parsing API.</td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td /><td /><td /></tr><tr><td><code>snappy</code></td><td>Snappy compression support.</td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td /><td /><td /><td /><td /><td /><td /><td /><td /><td /><td /></tr><tr><td><code>snmp</code></td><td>SNMP protocol support.</td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td></tr><tr><td><code>soap</code></td><td>SOAP client/server support.</td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td /><td /><td /></tr><tr><td><code>sockets</code></td><td>Low-level socket API.</td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td /><td /><td /></tr><tr><td><code>sodium</code></td><td>Modern cryptography (libsodium).</td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td /><td /><td /><td /><td /></tr><tr><td><code>sourceguardian</code></td><td>PHP extension for sourceguardian support.</td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td /><td /><td /></tr><tr><td><code>spplus</code></td><td>PHP extension for spplus support.</td><td /><td /><td /><td /><td /><td /><td /><td /><td /><td /><td /><td /><td><span>●</span></td><td><span>●</span></td></tr><tr><td><code>sqlite3</code></td><td>SQLite3 driver.</td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td></tr><tr><td><code>sqlsrv</code></td><td>Microsoft SQL Server driver.</td><td /><td /><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td /><td /><td /></tr><tr><td><code>ssh2</code></td><td>SSH2 and SFTP support.</td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td></tr><tr><td><code>swoole</code></td><td>Async networking and coroutine server.</td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td /><td /><td /><td /><td /><td /><td /><td /><td /><td /></tr><tr><td><code>sybase</code></td><td>PHP extension for sybase support.</td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td /><td /><td /></tr><tr><td><code>sysvmsg</code></td><td>System V message queue support.</td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td /><td /><td /></tr><tr><td><code>sysvsem</code></td><td>System V semaphore support.</td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td /><td /><td /></tr><tr><td><code>sysvshm</code></td><td>System V shared memory support.</td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td /><td /><td /></tr><tr><td><code>tideways</code></td><td>PHP extension for tideways support.</td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td /><td /><td /></tr><tr><td><code>tideways\_xhprof</code></td><td>PHP extension for tideways\_xhprof support.</td><td /><td /><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td /><td /><td /></tr><tr><td><code>tidy</code></td><td>HTML/XML cleanup and repair.</td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td></tr><tr><td><code>tokenizer</code></td><td>PHP tokenizer functions.</td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td /><td /><td /></tr><tr><td><code>uuid</code></td><td>UUID generation and handling.</td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td /><td /><td /><td /></tr><tr><td><code>uv</code></td><td>libuv event loop bindings.</td><td /><td><span>●</span></td><td><span>●</span></td><td /><td /><td /><td /><td /><td /><td /><td /><td /><td /><td /></tr><tr><td><code>wddx</code></td><td>WDDX serialization support.</td><td /><td /><td /><td /><td /><td /><td /><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td /><td /><td /></tr><tr><td><code>xcache</code></td><td>Legacy opcode/user cache.</td><td /><td /><td /><td /><td /><td /><td /><td /><td /><td /><td /><td /><td><span>●</span></td><td><span>●</span></td></tr><tr><td><code>xdebug</code></td><td>Debugging and code coverage tools.</td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td></tr><tr><td><code>xhprof</code></td><td>Function-level profiler.</td><td /><td /><td /><td /><td /><td /><td /><td /><td /><td /><td /><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td></tr><tr><td><code>xml</code></td><td>Core XML parser support.</td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td /><td /><td /></tr><tr><td><code>xmlreader</code></td><td>Streaming XML reader.</td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td /><td /><td /></tr><tr><td><code>xmlrpc</code></td><td>XML-RPC protocol support.</td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td></tr><tr><td><code>xmlwriter</code></td><td>Streaming XML writer.</td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td /><td /><td /></tr><tr><td><code>xsl</code></td><td>XSLT transformations.</td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td></tr><tr><td><code>yaml</code></td><td>YAML parsing and emitting.</td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td /><td /><td /><td /></tr><tr><td><code>zbarcode</code></td><td>PHP extension for zbarcode support.</td><td /><td /><td /><td /><td /><td /><td /><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td><span>●</span></td><td /><td /><td /></tr><tr><td><code>zip</code></td><td>ZIP archive support.</td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td><span>✔</span></td><td /><td /><td /></tr><tr><td><code>zstd</code></td><td>Zstandard compression support.</td><td><span>●</span></td><td><span>●</span></td><td /><td /><td /><td /><td /><td /><td /><td /><td /><td /><td /><td /></tr></tbody></table></div></div>
</div>

<PHPExtensionsTable />

Some built-in modules are always on:

* `date`
* `filter`
* `hash`
* `json` (from 8.0)
* `libxml`
* `openssl`
* `pcntl`
* `pcre`
* `Reflection`
* `session`
* `SPL`
* `standard`
* `Zend OPcache` (from 5.5)
* `zlib`

To see a complete list of the compiled PHP extensions, run the following [CLI command](/cli):

```bash theme={null}
upsun ssh "php -m"
```

## Custom PHP extensions

It's possible to use an extension not listed here,
but it takes slightly more work.

### Using PIE (PHP Installer for Extensions)

[PIE](https://www.php.net/manual/en/install.pie.intro.php) is the official PHP extension installer, replacing the deprecated PECL.
You can use PIE to compile and install extensions from source during the [build hook](/docs/configure-apps/hooks/hooks-comparison#build-hook).

The following example installs [Xdebug](https://xdebug.org/) (a Zend extension) and [PhpRedis](https://github.com/phpredis/phpredis) (a standard extension) using PIE:

This approach works as follows:

1. **Download PIE**: The PIE phar is downloaded into `/app/.global/bin/`, which is on the `PATH`.
2. **Install the extensions**: The `INSTALL_ROOT` environment variable redirects the compiled `.so` files under `/app/.global/` instead of the read-only system directory `/usr/lib/php/`.
3. **Enable the extensions**: A `php.ini` file is created at the [app root](/docs/configure-apps/app-reference/single-runtime-image#root-directory) to load each extension using its full path.

<Note>
  For Zend extensions such as Xdebug, use `zend_extension=` in the `php.ini` file.
  For standard extensions such as Redis, use `extension=` instead.
</Note>

You can find available PIE packages on [Packagist](https://packagist.org/) by searching for packages of type `php-ext`.

### Using a pre-compiled `.so` file

Alternatively, you can download a pre-compiled `.so` file for the extension:

1. Download the `.so` file for the extension as part of your build hook using `curl` or similar.
   It can also be added to your Git repository if the file isn't publicly downloadable,
   but committing large binary blobs to Git is generally not recommended.

2. Load the extension using an absolute path by [customizing the PHP settings](/docs/languages/php#customize-php-settings).
   For example, if the extension is named `spiffy.so` and is in your [app root](/docs/configure-apps/app-reference/single-runtime-image#root-directory),
   your configuration looks like the following:


# PHP-FPM sizing
Source: https://developer.upsun.com/docs/languages/php/fpm

Learn how to adjust the maximum number of PHP-FPM workers for your app

<DisclaimerNix />

PHP-FPM helps improve your app's performance
by maintaining pools of workers that can process PHP requests.
This is particularly useful when your app needs to handle a high number of simultaneous requests.

By default, Upsun Cloud automatically sets a maximum number of PHP-FPM workers for your app.
This number is calculated based on three parameters:

* The container memory: the amount of memory you can allot for PHP processing
  depending on [your defined application resources](/docs/manage-resources).
* The request memory: the amount of memory an average PHP request is expected to require.
* The reserved memory: the amount of memory you need to reserve for tasks that aren't related to requests.
  The number is calculated as follows: <img alt="The sum of container memory minus reserved memory divided by request memory" />

Note that when the resulting number is a decimal,
it's rounded up to set the maximum number of workers.
Also, the minimum number of PHP-FPM workers is 2.

<Note>
  To ensure that Upsun Cloud doesn't add more workers than the CPU can handle,
  a CPU limit applies as soon as the number of set workers equals or exceeds 25.
  This limit is calculated as follows: `number of vCPU cores * 5`.

  For example, if you have a 2XL container with 8 CPU cores,
  you can have up to 40 workers as long as you have sufficient memory.
</Note>

To adjust the maximum number of PHP-FPM workers depending on your app's needs, follow the instructions on this page.

## Before you begin

You need:

* An up-and-running web app in PHP, complete with [PHP-FPM](https://www.php.net/manual/en/install.fpm.php)
* The [Upsun Cloud CLI](/cli)

Note that the memory settings mentioned on this page are different from the [`memory_limit` PHP setting](/docs/languages/php).
The `memory_limit` setting is the maximum amount of memory a single PHP process can use
before it's automatically terminated.

## 1. Estimate the optimal request memory for your app

To determine what the optimal request memory is for your app,
you can refer to your PHP access logs.
Run a command similar to:

```bash theme={null}
upsun log --lines 5000 php.access | awk '{print $6}' | sort -n | uniq -c
```

This command takes into account the last 5,000 requests that reached PHP-FPM.
You can adjust this number depending on the amount of traffic on your site.

In the output, you can see how many requests used how much memory, in KB.
For example:

```bash theme={null}
    2654 2048
    431  4096
    584  8192
    889  10240
    374  12288
     68  46384
```

The output shows that:

* The majority of requests peaked at 2,048 KB of memory.
* Most other requests used up to around 10 MB of memory.
* A few requests used up to around 12 MB of memory.
* Only 68 requests peaked at around 46 MB of memory.

In this situation, you might want to be cautious
and [set your request memory](#2-adjust-the-maximum-number-of-php-fpm-workers) to 12 MB.
Setting a lower request memory presents a risk of allowing more concurrent requests.
This can result in memory swapping and latencies.

## 2. Adjust the maximum number of PHP-FPM workers

By default, the request memory is set to 45 MB
and the reserved memory is set to 70 MB.
These values allow most programs to run,
but you can amend them to fit your needs.

To do so, adjust your [app configuration](/docs/configure-apps).
Under `runtime` in the [`sizing_hints` setting](/docs/configure-apps/app-reference/single-runtime-image#sizing-hints),
set the values for `reserved_memory` and `request_memory`.

For example,
if you estimate your [optimal request memory](#1-estimate-the-optimal-request-memory-for-your-app) to be 35 MB
and your reserved memory to be 80 MB,
you can use:

Note that the minimum value for the `request_memory` key is 10 MB
and the minimum value for the `reserved_memory` key is 70 MB.
If you set lower values,
they're automatically overridden with those minimums.

To check the maximum number of PHP-FPM workers available to your app,
run the following command, where `children` refers to PHP-FPM workers:

```bash theme={null}
upsun ssh "grep -e '^pm.max_children' /etc/php/*/fpm/php-fpm.conf"
```

You get output similar to the following:

```bash theme={null}
pm.max_children = 5
```


# FrankenPHP
Source: https://developer.upsun.com/docs/languages/php/frankenphp

Run PHP applications on Upsun Cloud using FrankenPHP, a modern PHP application server built on Caddy.

[FrankenPHP](https://frankenphp.dev/) is a modern PHP application server designed as a high-performance alternative to traditional PHP-FPM setups. It combines a native PHP runtime with an HTTP server, reducing orchestration overhead while enabling new execution models that can significantly improve performance.

FrankenPHP is particularly well-suited for modern PHP frameworks and applications that want faster request handling, simpler infrastructure, and optional support for long-running workers.

## Why FrankenPHP?

Traditional PHP deployments rely on multiple moving parts: a web server, PHP-FPM, and external process management. FrankenPHP simplifies this architecture by embedding PHP execution directly into the server. Some key features include:

* Faster startup times and reduced per-request overhead compared to [PHP-FPM](/docs/languages/php/fpm).
* A modern architecture that works for contemporary PHP runtimes and frameworks.
* Fewer services to configure and maintain.
* Support for a worker-based execution model that avoids re-booting the application on every request.

### Execution modes

FrankenPHP supports two distinct execution modes. Choosing the right mode depends on your application’s architecture and tolerance for stateful execution.

#### Classic mode

Classic mode behaves similarly to [PHP-FPM](/docs/languages/php/fpm) and is the recommended default for most applications.

* Each request runs in a clean, isolated environment
* No application state is shared between requests
* Lifecycle expectations are identical to PHP-FPM
* Safe for existing PHP applications without modification

In this mode, FrankenPHP provides performance and architectural improvements while preserving the [stateless](#stateless-execution-php-fpm-and-classic-mode) execution model.

#### Worker mode

Worker mode enables long-running PHP worker processes that handle multiple requests over their lifetime.

* The application is booted once and kept in memory
* Subsequent requests reuse the already-loaded application
* Significantly reduced cold-start overhead
* Higher throughput and faster response times

This mode introduces [stateful](#stateful-execution-worker-mode) execution.

### Understanding Worker modes

#### Stateless execution (PHP-FPM and Classic mode)

In traditional PHP execution models every request starts from a clean slate, the application boots, handles the request, then shuts down and there are no variables, objects, or internal state persist between requests.

This guarantees isolation and predictability, but it comes with unavoidable overhead as the full boot and teardown cycle happens on every request.

#### Stateful execution (Worker mode)

With Stateful execution in Worker mode, the application is booted once. It remains in memory and handles many requests and internal state persists unless explicitly reset. This improves performance dramatically, but introduces new risks. For example, in a stateful environment:

* Mutated variables may leak into later requests
* Static properties and singletons persist
* Cached data may become stale or invalid
* Connection pools or services may behave unexpectedly

These issues do not occur in stateless PHP-FPM setups.

<Note>
  Aplications not explicitly designed for long-running workers may require manual state resets between requests, careful handling of static properties and global variables, explicit cleanup logic and auditing of caching and service lifecycles.

  Tools like [Laravel Octane](https://laravel.com/docs/master/octane) or the [Symfony FrankenPHP Runtime](https://github.com/php-runtime/frankenphp-symfony) are designed to manage this environment safely. They often serve clones of the application or reset the container state between requests to prevent variables from leaking.
</Note>

### Observability and profiling

FrankenPHP is well supported by [Upsun Blackfire](/docs/observability/application-metrics/blackfire), making it easy to profile and monitor performance in both Classic and Worker modes.

<Note>
  See the [Upsun Blackfire](https://docs.blackfire.io/php/integrations/frankenphp) documentation for FrankenPHP integration.
</Note>

## Configuration

FrankenPHP is available as a package in Upsun Cloud composable stacks.

<DisclaimerNix />

### Classic mode configuration

### Worker mode configuration

### Using the latest FrankenPHP version

You can request FrankenPHP from the Nix unstable channel to access the latest available version.

```yaml .upsun/config.yaml theme={null}
stack:
  packages:
    - package: frankenphp
      channel: unstable
```

### Choosing the right mode

* Use [Classic mode](#classic-mode) if you want safety, predictability, and drop-in compatibility with existing PHP applications.
* Use [Worker mode](#worker-mode) if you need maximum performance and are prepared to manage application state explicitly.

Both modes are fully supported on Upsun Cloud, allowing you to choose the execution model that best fits your application.

## Related content

* [Upsun Blackfire FrankenPHP documentation](https://docs.blackfire.io/php/integrations/frankenphp)
* [Up(Sun) and running with FrankenPHP](https://upsun.com/blog/upsun-and-running-with-frankenphp/)
* [How we scaled live connections for 1200 developers at SymfonyCon](https://devcenter.upsun.com/posts/how-we-scaled-live-connections-for-1200-developers-at-symfonycon/#starting-with-frankenphp-the-documentation-gap)


# PHP
Source: https://developer.upsun.com/docs/languages/php/index

Deploy PHP apps on Upsun Cloud using PHP-FPM, FrankenPHP, or Swoole. Configure PHP extensions, tune FPM worker settings, enable Xdebug for debugging, and manage dependencies with Composer.

<Info>
  You can now use the Upsun Cloud [composable image](/docs/configure-apps/app-reference/composable-image) to install runtimes and tools in your application container.
  To find out more about this feature, see the [dedicated documentation page](/docs/configure-apps/app-reference/composable-image).<br />
  Also, see how you can [modify your PHP runtime when using the composable image](#modify-your-php-runtime-when-using-the-composable-image).
</Info>

## Supported versions

You can select the major and minor version.

Patch versions are applied periodically for bug fixes and other maintenance updates. By default, you get the latest available patches each time you deploy. If your project has a [maintenance window](/docs/core-concepts/build-deploy#maintenance-window) configured, Upsun Cloud applies patches only during that window. Upsun Cloud may still apply urgent or critical fixes outside of the maintenance window.

* <span>8.5</span>
* <span>8.4</span>

Note that from PHP versions 7.1 to 8.1, the images support the Zend Thread Safe (ZTS) version of PHP.

### Specify the language

To use PHP, specify `php` as your [app's `type`](/docs/configure-apps/app-reference/single-runtime-image#type):

For example:

## Deprecated versions

The following versions are still available in your projects,
but they're at their end of life and are no longer receiving security updates from upstream.

* <span>8.3</span>
* <span>8.2</span>

To ensure your project remains stable in the future, switch to a [supported version](#supported-versions).

## Retired versions

The following versions have been retired and are no longer available.
If your project uses a retired version, you must update to a [supported version](#supported-versions).

* <span>8.1</span>
* <span>8.0</span>
* <span>7.4</span>
* <span>7.3</span>
* <span>7.2</span>
* <span>7.1</span>
* <span>7.0</span>
* <span>5.6</span>
* <span>5.5</span>
* <span>5.4</span>

## Usage example

Configure your app to use PHP on Upsun Cloud.

### 1. Specify the version

Choose a [supported version](#supported-versions)
and add it to your [app configuration](/docs/configure-apps):

### 2. Serve your app

To serve your app, define what (and how) content should be served by setting the [`locations` parameter](/docs/configure-apps/image-properties/web#locations).

Usually, it contains the two following (optional) keys:

* `root` for the document root,
  the directory to which all requests for existing `.php` and static files (such as `.css`, `.jpg`) are sent.
* `passthru` to [define a front controller](/docs/configure-apps/web/php-basic#set-different-rules-for-specific-locations) to handle nonexistent files.
  The value is a file path relative to the [app root](/docs/configure-apps/image-properties/source).

  <Note>
    For enhanced security, when setting `passthru` to `true`, you might also want to add the following configuration:

    1. Set `scripts` to `false`.
       This prevents PHP scripts from being executed from the specified location.

    2. Set `allow` to `false`.
       By default, when PHP scripts aren't executed, their source code is delivered.
       Setting `allow` to `false` allows you to keep the source code of your PHP scripts confidential.
  </Note>

Adjust the `locations` block to fit your needs.

In the following example, all requests made to your site's root (`/`) are sent to the `public` directory
and nonexistent files are handled by `app.php`:

See how to [create a basic PHP app with a front controller](/docs/configure-apps/web/php-basic).
To have more control, you can define rules to specify which files you want to allow [from which location](/docs/configure-apps/web/php-basic#set-different-rules-for-specific-locations).

### Complete example

A complete basic app configuration looks like the following:

## Dependencies

Up to PHP version 8.1, it's assumed that you're using [Composer](https://getcomposer.org/) 1.x to manage dependencies.
If you have a `composer.json` file in your code, the default [build flavor is run](/docs/configure-apps/app-reference/single-runtime-image#build):

```bash theme={null}
composer --no-ansi --no-interaction install --no-progress --prefer-dist --optimize-autoloader
```

Adding a dependency to the [dependencies block](/docs/configure-apps/app-reference/single-runtime-image#dependencies) makes it available globally.
So you can then use included dependencies as commands within your app container.
You can add multiple global dependencies to the dependencies block, such as [Node.js](/docs/languages/nodejs#2-specify-any-global-dependencies).

If you want to have more control over Composer or if you don't want to use Composer at all, adapt the [build flavor](#change-the-build-flavor).
You can also use a [private, authenticated third-party Composer repository](/docs/languages/php/composer-auth).

### Change the build flavor

If you need more control over the dependency management,
you can either use your custom build flavor
or interact with Composer itself through [its environment variables](https://getcomposer.org/doc/03-cli#environment-variables).

You can remove the default build flavor and run your own commands for complete control over your build.
Set the build flavor to `none` and add the commands you need to your `build` hook, as in the following example:

That installs production dependencies with Composer but not development dependencies.
The same can be achieved by using the default build flavor and [adding the `COMPOSER_NO_DEV` variable](/docs/development/variables/set-variables).

See more on [build flavors](/docs/configure-apps/app-reference/single-runtime-image#build).

### Alternative repositories

In addition to the standard `dependencies` format,
you can specify alternative repositories for Composer to use as global dependencies.
So you can install a forked version of a global dependency from a custom repository.

To install from an alternative repository:

1. Set an explicit `require` block:

This is equivalent to `composer require platform/client 2.x-dev`.

2. Add the repository to use:

That installs `platformsh/client` from the specified repository URL as a global dependency.

### Configure security blocking

When building a PHP app, Upsun Cloud runs `composer install`, which runs the latest available Composer version.

By default, PHP builds fail if a dependency in a project has a known vulnerability. A PHP build might also fail if a dependency is abandoned.

**The best practice is to upgrade the dependencies** to reduce security risks and to catch issues sooner. However, you can configure the level of security blocking by defining the following keys in the `.dependencies.php.config` section of your `.upsun/config.yaml` file.

| Key | Description |
| - | - |
| `audit.block-insecure` | Default is `true`. **Important: Upsun recommends keeping this default setting and upgrading affected dependencies to reduce security risks.** |
| `audit.block-abandoned` | Default is `false`; set to `true` for even stricter security. Ignored if `audit.block-insecure` is `false`. |
| `audit.ignore` | Array of specific advisories to ignore; see example below. |
| `audit.ignore-severity` | Ignore vulnerabilities based on their severity rating (`low`/`medium`/`high`). See the example below.<br />For each rating, include an `apply` key with one of these values:<ul><li>`all` to ignore everything for this rating</li><li>`block` to ignore this severity level for blocking builds (but still flag findings in audit reports)</li><li>`audit` to ignore this severity level in audit reports (but still block builds)</li></ul> |

Examples:

Related information:

* [Troubleshooting PHP builds that now fail](/docs/languages/php#configure-security-blocking)

### Additional Composer schema properties

In addition to [alternate repositories](#alternative-repositories), other
[Composer schema properties](https://getcomposer.org/doc/04-schema) can be added to the global dependencies. For
example, one of your dependencies may be a plugin where you need to explicitly whitelist it as an
[allowed-plugin](https://getcomposer.org/doc/06-config#allow-plugins).

To add additional composer schema properties:

1. Set an explicit `require` block:

2) Add each additional property as a block at the same indentation as the `require` block:

## Connect to services

You can access service credentials to connect to [managed services](/docs/add-services) from environment variables present in the application container.
Consult each of the individual service documentation to see how to retrieve and surface credentials into your application.

* [ClickHouse](/docs/add-services/clickhouse#usage-example)
* [Elasticsearch](/docs/add-services/elasticsearch#usage-example)
* [Gotenberg](/docs/add-services/gotenberg#usage-example)
* [Headless Chrome](/docs/add-services/headless-chrome#usage-example)
* [InfluxDB](/docs/add-services/influxdb#usage-example)
* [Kafka](/docs/add-services/kafka#usage-example)
* [MariaDB/MySQL](/docs/add-services/mysql#usage-example)
* [Memcached](/docs/add-services/memcached#usage-example)
* [mercure](/docs/add-services/mercure#usage-example)
* [mongodb](/docs/add-services/mongodb#usage-example)
* [Network Storage](/docs/add-services/network-storage#usage-example)
* [OpenSearch](/docs/add-services/opensearch#usage-example)
* [PostgreSQL](/docs/add-services/postgresql#usage-example)
* [RabbitMQ](/docs/add-services/rabbitmq#usage-example)
* [Redis](/docs/add-services/redis#usage-example)
* [Solr](/docs/add-services/solr#usage-example)
* [Valkey](/docs/add-services/valkey#usage-example)
* [Varnish](/docs/add-services/varnish#usage-example)
* [Vault KMS](/docs/add-services/vault#usage-example)
* [Chroma](/tutorials/self-hosted/chroma#3-use-the-relationship-in-your-application)
* [Qdrant](/tutorials/self-hosted/qdrant#4-use-the-relationship-in-your-application)

## PHP settings

You can configure your PHP-FPM runtime configuration by specifying the [runtime in your app configuration](/docs/configure-apps/app-reference/single-runtime-image#runtime).

In addition to changes in runtime, you can also change the PHP settings.
Some commonly used settings are:

| Name | Default | Description |
| - | - | - |
| `max_execution_time` | `300` | The maximum execution time, in seconds, for your PHP scripts and apps. A value of `0` means there are no time limits. |
| `max_file_uploads` | `20` | The maximum number of files that can be uploaded in each request. |
| `max_input_time` | `60` | The maximum time in seconds that your script is allowed to receive input (such as for file uploads). A value of `-1` means there are no time limits. |
| `max_input_vars` | `1000` | The maximum number of input variables that are accepted in each request. |
| `memory_limit` | `128M` | The memory limit, in megabytes, for PHP. Ensure that the PHP memory limit is set to a lower value than your environment's memory. |
| `post_max_size` | `64M` | The maximum size, in megabytes, per uploaded file. To upload larger files, increase the value. |
| `zend.assertions` | `-1` | Assertions are optimized and have no impact at runtime. Set assertions to `1` for your local development system. [See more on assertions](https://www.php.net/manual/en/regexp.reference.assertions). |
| `opcache.memory_consumption` | `64` | The number of megabytes available for [the OPcache](/docs/languages/php/tuning#opcache-preloading). For large apps with many files, increase this value. |
| `opcache.validate_timestamps` | `On` | If your app doesn't generate compiled PHP, you can [disable this setting](/docs/languages/php/tuning#disable-opcache-timestamp-validation). |

### Retrieve the default values

To retrieve the default PHP values, run the following [CLI command](/cli):

```bash theme={null}
upsun ssh "php --info"
```

To get specific default values, use grep.
For example, to get the value for `opcache.memory_consumption`, run the following command:

```bash theme={null}
upsun ssh "php --info" | grep opcache.memory_consumption
```

### Retrieve the settings

To see the settings used on your environment:

1. Find the PHP configuration files with the following [CLI command](/cli):

   ```bash theme={null}
   upsun ssh "php --ini"
   ```

   The output is something like the following:

   ```bash theme={null}
   Configuration File (php.ini) Path: /etc/php/8.0-zts/cli
   Loaded Configuration File:         /etc/php/8.0-zts/cli/php.ini
   Scan for additional .ini files in: /etc/php/8.0-zts/cli/conf.d
   Additional .ini files parsed:      (none)
   ```

2. Display the configuration file by adapting the following command with the output from step 1:

   ```bash theme={null}
   upsun ssh "cat <LOADED_CONFIGURATION_FILE_PATH>"
   ```

### Customize PHP settings

You can customize PHP values for your app in two ways.
The recommended method is to use variables.

<Tabs>
  <Tab title="Using variables">
    Set variables to override PHP settings for a given environment using the [CLI](/cli).

    For example, to set the PHP memory limit to 256 MB on a specific environment, run the following CLI command:

    ```bash theme={null}
    upsun variable:create --level environment \
        --prefix php --name memory_limit \
        --value 256M --environment <ENVIRONMENT_NAME> \
        --no-interaction
    ```

    For more information, see how to use [PHP-specific variables](/docs/development/variables#php-specific-variables).
  </Tab>

  <Tab title="Using `php.ini`">
    You can provide a custom `php.ini` file at the [app root](/docs/configure-apps/app-reference/single-runtime-image#root-directory).
    Using this method isn't recommended since it offers less flexibility and is more error-prone.
    Consider using variables instead.

    For example, to change the PHP memory limit, use the following configuration:

    ```ini php.ini theme={null}
    memory_limit = 256M
    ```
  </Tab>
</Tabs>

If you're using [PHP-CLI](#execution-mode),
you need to take into account the default settings of PHP-CLI when you customize your PHP settings.
The default settings of PHP-CLI can't be overwritten and are the following:

```text theme={null}
max_execution_time=0
max_input_time=-1
memory_limit=-1
```

### Disable functions for security

A common recommendation for securing PHP installations is disabling built-in functions frequently used in remote attacks.
By default, Upsun Cloud doesn't disable any functions.

If you're sure a function isn't needed in your app, you can disable it.

For example, to disable `pcntl_exec` and `pcntl_fork`, add the following to your [app configuration](/docs/configure-apps):

Common functions to disable include:

| Name | Description |
| - | - |
| `create_function` | This function has been replaced by anonymous functions and shouldn't be used anymore. |
| `exec`, `passthru`, `shell_exec`, `system`, `proc_open`, `popen` | These functions allow a PHP script to run a bash shell command. Rarely used by web apps except for build scripts that might need them. |
| `pcntl_*` | The `pcntl_*` functions are responsible for process management. Most of them cause a fatal error if used within a web request. Cron tasks or workers may need them. Most are usually safe to disable. |
| `curl_exec`, `curl_multi_exec` | These functions allow a PHP script to make arbitrary HTTP requests. If you're using HTTP libraries such as Guzzle, don't disable them. |
| `show_source` | This function shows a syntax highlighted version of a named PHP source file. Rarely useful outside of development. |

## Execution mode

PHP has two execution modes you can choose from:

* The command line interface mode (PHP-CLI) is the mode used for command line scripts and standalone apps.
  This is the mode used when you're logged into your container via SSH, for [crons](/docs/configure-apps/image-properties/crons),
  and usually also for [alternate start commands](#alternate-start-commands).
  To use PHP-CLI, run your script with `php <PATH_TO_SCRIPT>`,
  where `<PATH_TO_SCRIPT>` is a file path relative to the [app root](/docs/configure-apps/app-reference/single-runtime-image#root-directory).
* The Common Gateway Interface mode (PHP-CGI) is the mode used for web apps and web requests.
  This is the default mode when the `start` command isn't explicitly set.
  To use PHP-CGI, run your script with a symlink: `/usr/bin/start-php-app <PATH_TO_SCRIPT>`,
  where `<PATH_TO_SCRIPT>` is a file path relative to the [app root](/docs/configure-apps/app-reference/single-runtime-image#root-directory).
  With PHP-CGI, PHP is run using the FastCGI Process Manager (PHP-FPM).

## Alternate start commands

To specify an alternative process to run your code, set a `start` command.
For more information about the start command, see the [web commands reference](/docs/configure-apps/image-properties/web#web-commands).

By default, start commands use PHP-CLI.
Find out how and when to use each [execution mode](#execution-mode).

Note that the `start` command must run in the foreground and is executed before the [deploy hook](/docs/configure-apps/hooks/hooks-comparison).
That means that PHP-FPM can't run simultaneously with another persistent process
such as [ReactPHP](https://github.com/platformsh-examples/platformsh-example-reactphp)
or [Amp](https://github.com/platformsh-examples/platformsh-example-amphp).
If you need multiple processes, they have to run in separate containers.

See some generic examples on how to use alternate start commands:

<Tabs>
  <Tab title="Run a custom script">
    1. Add your script in a PHP file.

    2. Specify an alternative `start` command by adapting the following:

    ```yaml .upsun/config.yaml theme={null}
    applications:
      # The name of the app container. Must be unique within a project.
      myapp:
        # The location of the application's code.
        web:
          commands:
            start: /usr/bin/start-php-app
    ```
  </Tab>

  <Tab title="Run a custom web server">
    1. Add your web server's code in a PHP file.

    2. Specify an alternative `start` command by adapting the following:

    ```yaml .upsun/config.yaml theme={null}
    applications:
      # The name of the app container. Must be unique within a project.
      myapp:
        # The location of the application's code.
        web:
          commands:
            start: /usr/bin/start-php-app
    ```

    3. Configure the container to listen on a TCP socket:

    ```yaml .upsun/config.yaml theme={null}
    applications:
      # The name of the app container. Must be unique within a project.
      myapp:
        # The location of the application's code.
        web:
          upstream:
            socket_family: tcp
            protocol: http
    ```

    When you listen on a TCP socket, the `$PORT` environment variable is automatically set.
    See more options on how to [configure where requests are sent](/docs/configure-apps/image-properties/web#upstream).
    You might have to configure your app to connect via the `$PORT` TCP socket,
    especially when using web servers such as [Swoole](/docs/languages/php/swoole) or [Roadrunner](https://github.com/roadrunner-server/roadrunner).

    4. Optional: Override redirects to let the custom web server handle them:

    ```yaml .upsun/config.yaml theme={null}
    applications:
      # The name of the app container. Must be unique within a project.
      myapp:
        # The location of the application's code.
        locations:
          "/":
            passthru: true
            scripts: false
            allow: false
    ```
  </Tab>

  <Tab title="Run specific tasks">
    To execute runtime-specific tasks (such as clearing cache) before your app starts, follow these steps:

    1. Create a separate shell script that includes all the commands to be run.

    2. Specify an alternative `start` command by adapting the following:

    `<PATH_TO_SCRIPT>` is the bash script created in step 1.
    `<PATH_TO_SCRIPT>` is a file path relative to the [app root](/docs/configure-apps/app-reference/single-runtime-image#root-directory).
  </Tab>
</Tabs>

## Foreign function interfaces

PHP 7.4 introduced support for [foreign function interfaces (FFIs)](https://en.wikipedia.org/wiki/Foreign_function_interface).
FFIs allow your PHP program to call routines or use services written in C or Rust.

Note: FFIs are only intended for advanced use cases.
Use with caution.

If you are using C code, you need `.so` library files.
Either place these files directly in your repository or compile them in a makefile using `gcc` in your [build hook](/docs/configure-apps/hooks/hooks-comparison#build-hook).
Note: The `.so` library files shouldn't be located in a publicly accessible directory.

If you are compiling Rust code, use the build hook to [install Rust](https://doc.rust-lang.org/stable/book/ch01-01-installation.html).

To leverage FFIs, follow these steps:

1. [Enable and configure OPcache preloading](/docs/languages/php/tuning#enable-opcache-preloading).

2. Enable the FFI extension:

3) Make sure that your [preload script](/docs/languages/php/tuning#opcache-preloading) calls the `FFI::load()` function.
   Using this function in preload is considerably faster than loading the linked library on each request or script run.

4) If you are running FFIs from the command line,
   enable the preloader by adding the following configuration:

5. Run your script with the following command:

   ```bash theme={null}
   php <CLI_SCRIPT>
   ```

<RepoList lang="php" />

## Frameworks

All major PHP web frameworks can be deployed on Upsun Cloud.
See dedicated guides for deploying and working with them:

* [Laravel](/docs/get-started/stacks/laravel)
* [Symfony](/docs/get-started/stacks/symfony)

## Modify your PHP runtime when using the composable image

<Warning>
  This section is only relevant when using the Upsun Cloud [composable image](/docs/configure-apps/app-reference/composable-image).
</Warning>

The following table presents the possible modifications you can make to your PHP primary runtime using the `stack.runtimes` key in a composable image.

For example, `extensions` are enabled under `.applications.frontend.stack.runtimes[0]["php@8.5"].extensions` for PHP 8.5).
See the [example](#example-php-configuration) below for more details.

<Note>
  The PHP-FPM service starts automatically only when PHP is the primary runtime.
</Note>

| Name | Type | Description |
| - | - | - |
| `extensions` | List of `string`s OR [extensions definitions](/docs/configure-apps/app-reference/composable-image#php-extensions-and-python-packages) | [PHP extensions](/docs/languages/php/extensions) to enable. |
| `disabled_extensions` | List of `string`s | [PHP extensions](/docs/languages/php/extensions) to disable. |
| `request_terminate_timeout` | `integer` | The timeout (in seconds) for serving a single request after which the PHP-FPM worker process is killed. |
| `sizing_hints` | A [sizing hints definition](#php-fpm-service-sizing-hints) | The assumptions for setting the number of workers in your PHP-FPM runtime. |
| `xdebug` | An Xdebug definition | The setting to turn on [Xdebug](/docs/languages/php/xdebug). |

### PHP-FPM service sizing hints

The following table shows the properties that can be set in `sizing_hints`:

| Name | Type | Default | Minimum | Description |
| - | - | - | - | - |
| `request_memory` | `integer` | 45 | 10 | The average memory consumed per request in MB. |
| `reserved_memory` | `integer` | 70 | 70 | The amount of memory reserved in MB. |

See more about [PHP-FPM workers and sizing](/docs/languages/php/fpm).

### Example PHP configuration

Here is an example configuration:

<Note>
  You can also set your [app's runtime timezone](/docs/configure-apps/timezone).
</Note>


# Custom Redis versions
Source: https://developer.upsun.com/docs/languages/php/redis



<DisclaimerNix />

[Redis](/docs/add-services/redis) is a popular structured key-value service, supported by Upsun Cloud.
It's frequently used for caching.

## Install PhpRedis

The [PhpRedis](https://github.com/phpredis/phpredis) extension is available on Upsun Cloud's PHP container images.
The extension has been known to break its API between versions when removing deprecated functionality.
The version available on each application image is the latest available at the time that PHP version was built,
which if your app is sensitive to PhpRedis versions may not be ideal.

It may happen that the version of the PhpRedis extension available for your PHP version
isn't compatible with your app and upgrading your app isn't feasible.
If so, use the following script as an alternative to download and compile a precise version of the extension.

<Warning>
  Do *not* use this approach unless you really need to.
  Using the provided PhpRedis extension is preferred in the majority of cases.
</Warning>

To ease the installation of a customer version of PhpRedis, use a [PhpRedis install script](https://github.com/platformsh/snippets/blob/main/src/install-phpredis.sh).
Invoke this script from your build hook, specifying a version.
Any tagged version of the library is acceptable:

## Install Relay

Relay is a [Redis](/docs/add-services/redis) client
similar to [PhpRedis](https://github.com/phpredis/phpredis) and
[Predis](https://github.com/predis/predis).
It's intended to be a drop-in replacement for those libraries.

That PHP extension is also a shared in-memory cache like APCu. All retrieved keys are held in the PHP master process’ memory, which is shared across all FPM workers.

That means if the FPM Worker #1 fetches the `users:count` key from Redis,
all other FPM workers instantaneously retrieve that key from Relay without having to communicate with Redis.

To ease the installation of a customer version of Relay, use the [Relay install script](https://github.com/platformsh/snippets/blob/main/src/install-relay.sh).
Invoke this script from your build hook, specifying a version.
Any tagged version of the library is acceptable:

## Change extension or version

To change the Redis extension or the version you are using, update the build hook and clear the build cache: `upsun project:clear-build-cache`.

The new version is *not* be used until you clear the build cache.

There's no need to declare the extension in the `runtime` block.
That's only for pre-built extensions.

## What these scripts do

1. Download the Relay/PhpRedis source code.
2. Check out the version specified in the build hook.
3. Compile the extension.
4. Copy the resulting `relay.so`/`redis.so` file to [your app root](/docs/configure-apps/app-reference/single-runtime-image#root-directory).
5. Add a line to the `php.ini` file in your app root to enable the extension, creating the file if necessary.

If the script doesn't find a `$PLATFORM_CACHE_DIR` directory defined, it exits silently.
So if you run the build hook locally, it has no effect.


# Swoole
Source: https://developer.upsun.com/docs/languages/php/swoole

Use the Swoole extension on Upsun Cloud to run PHP applications with coroutine-based async networking.

<DisclaimerNix />

Swoole is a PHP extension that extends PHP core with a coroutine based asynchronous network application framework designed for building large scale concurrent systems.

Unlike PHP-FPM’s stateless operating, Swoole relies on establishing persistent connections with every user, sending and receiving data in real-time.

[Swoole](https://github.com/swoole/swoole-src) and [Open Swoole](https://openswoole.com/) are two forked libraries pursuing that goal.

<Note>
  The `swoole` and `openswoole` extensions are [available by default](/docs/languages/php/extensions) on Upsun Cloud PHP 8.2 Upsun Cloud containers.
</Note>

For other versions of PHP, you can install both extensions manually by following the instructions on this page.<br />
You need:

* PHP 7.3+ for Swoole
* PHP 7.4.0+ for Open Swoole
* The [Swoole installation script](https://raw.githubusercontent.com/platformsh/snippets/main/src/install_swoole.sh).
  <Note>
    Currently, the installation script is compatible with PHP \<=8.0.<br />It is **not** compatible with PHP 8.3,
    and the `swoole` and `openswoole` extensions are **not** available on Upsun Cloud PHP 8.3 containers yet.
  </Note>

## Install

Install the PHP extension for Swoole or Open Swoole during the build.

Take advantage of an [installation script](https://raw.githubusercontent.com/platformsh/snippets/main/src/install_swoole.sh).
You need to pass 2 parameters:

* Which Swoole project to use: `openswoole` or `swoole`
* Which version to install

## Use

Override the default web server with a [custom start command](/docs/languages/php#alternate-start-commands).
Octane should listen on a TCP socket.


# Troubleshoot PHP
Source: https://developer.upsun.com/docs/languages/php/troubleshoot

Learn how to troubleshoot common issues in PHP.

<DisclaimerNix />

For more general information, see how to [troubleshoot development](/docs/troubleshooting/general).

## Previously successful PHP builds now fail

When building a PHP app, Upsun Cloud runs `composer install`, which by default runs the latest available Composer version.

Composer version 2.9 introduces an Automatic Security Blocking feature, which is enabled by default and does the following:

* If a dependency in the project has a known vulnerability, Composer fails the installation/update.
* If a dependency is abandoned, Composer can optionally fail the installation.

If advisories were published after the most recent PHP app deployment, the build might fail, even if the PHP dependencies have not changed.

**In this scenario, the best practice is to upgrade the affected dependencies** to maintain a strong security posture and address vulnerabilities. However, you can configure the level of blocking by using the `.dependencies.php.config.audit.*` keys described in the [Configure security blocking](/docs/languages/php#configure-security-blocking) section of the PHP topic.

**Important: Upsun advises against disabling security blocking.** However, as a last resort, the feature can be disabled as a workaround while you fix issues with dependencies.

## Server reached `max_children`

If the server is receiving more concurrent requests than it has PHP processes allocated,
you encounter a message like the following:

```text {location="/var/log/app.log", no-copy="true"} theme={null}
WARNING: [pool web] server reached max_children setting (2), consider raising it
```

This means some requests have to wait until another finishes.
Upsun Cloud sets the number of workers based on the available memory of your container
and the estimated average memory size of each process.

You have two ways to increase the number of workers:

* Adjust the [worker sizing hints](/docs/languages/php/fpm) for your project.
* Add [additional resources](/docs/manage-resources) with the `upsun resources:set` command

## Execution timeout

If your PHP app can't handle the amount of traffic or is slow,
you encounter a message like the following:

```text {location="/var/log/app.log", no-copy="true"} theme={null}
WARNING: [pool web] child 120, script '/app/public/index.php' (request: "GET /index.php") execution timed out (358.009855 sec), terminating
```

This means your PHP process is running longer than allowed.
You can adjust the `max_execution_time` value in `php.ini`,
but there is still a hard cap of 5 minutes on any web request.

The most common causes of a timeout are an infinite loop (which is a bug that you should fix)
or the work itself requires a long time to complete.
For the latter case, you should consider putting the task into a background job.

The following command identifies the 20 slowest requests in the past hour,
which can provide an indication of what code paths to investigate.

```bash theme={null}
grep $(date +%Y-%m-%dT%H --date='-1 hours') /var/log/php.access.log | sort -k 4 -r -n | head -20
```

If you see that the processing time of certain requests is slow (such as taking longer than 1000 ms),
you should consider a [continuous observability solution](/docs/observability/application-metrics)
to monitor your app and help you improve the performance issue.

Full access to [Upsun Blackfire](/docs/observability/application-metrics/blackfire) is bundled with your PHP and Python Upsun Cloud projects.

Otherwise, you may check if the following options are applicable:

* Find the most visited pages and see if they can be cached and/or put behind a CDN.
  Refer to [how caching works](/docs/routes/cache).
* Add [additional resources](/docs/manage-resources) with the `upsun resources:set` command

## Troubleshoot a crashed PHP process

If your PHP process crashed with a segmentation fault,
you encounter a message like the following:

```text {location="/var/log/app.log", no-copy="true"} theme={null}
WARNING: [pool web] child 112 exited on signal 11 (SIGSEGV) after 7.405936 seconds from start
```

Either a PHP extension is hitting a segmentation fault or your PHP app code is crashing.
Review recent changes in your app and try to find the root cause.
You might want to use a tool such as [Xdebug](/docs/languages/php/xdebug) for quicker troubleshooting.

## Troubleshoot a killed PHP process

If your PHP process is killed by the kernel,
you encounter a message like the following:

```text {location="/var/log/app.log", no-copy="true"} theme={null}
WARNING: [pool web] child 429 exited on signal 9 (SIGKILL) after 50.938617 seconds from start
```

That means the memory usage of your container exceeds the limit that's been allocated, so the kernel kills the offending process.
To solve this issue, try the following approaches:

* Check if the memory usage of your app is as expected and try to optimize it.
* Use [sizing hints](/docs/languages/php/fpm) to reduce the amount of PHP workers, which reduces the memory footprint.
* Add [additional resources](/docs/manage-resources) with the `upsun resources:set` command

## Restart PHP processes stuck during a build or deployment

If your [build or deployment is running longer than expected](/docs/troubleshooting/general#stuck-build-or-deployment),
it might be because of a PHP process getting stuck.

To restart your PHP processes, run the following command in your app container:

```bash theme={null}
pkill -f php-fpm
```

## Resource temporarily unavailable

If all PHP workers are busy,
you encounter a message like the following:

```text {location="/var/log/error.log", no-copy="true"} theme={null}
connect() to unix:/run/app.sock failed (11: Resource temporarily unavailable)
```

This can be because too many requests are coming in at once
or the requests are taking too long to be processed (such as with calls to external third-party servers without timeouts).

To address the issue, you can:

* Lower the memory consumption of each request so that the amount of PHP workers gets automatically raised.
  This can be customized with the `runtime.sizing_hints.request_memory` key in your `.upsun/config.yaml` file.
  For more details, consult [PHP-FPM sizing](/docs/languages/php/fpm).
* Add a [CDN](/docs/domains/cdn).
* Set up [HTTP caching](/docs/core-concepts/best-practices/http-caching).
* Follow the global [performance tuning recommendations](/docs/languages/php/tuning).
* Remove stale plugins and extensions when using a CMS.
* Add [additional resources](/docs/manage-resources) with the `upsun resources:set` command


# PHP performance tuning
Source: https://developer.upsun.com/docs/languages/php/tuning



<DisclaimerNix />

Once your app is up and running it still needs to be kept fast.
Upsun Cloud offers a wide degree of flexibility in how PHP behaves,
but that does mean you may need to take a few steps to ensure your site is running optimally.

The following recommendations are guidelines only.
They're also listed in about the order to investigate them.

## Upgrade to PHP 8

To make a PHP-based site run faster, the first step is to upgrade the PHP version.
Upgrading the PHP version might require changes to your app.
For more details and recommendations, see the [PHP migration guides](https://www.php.net/manual/en/migration80.php).

To change your PHP version, change the [`type` in your app configuration](/docs/configure-apps/app-reference/single-runtime-image#type).
Before merging to production, test the change on a branch and make sure that your app is working as expected.

## Optimize the FPM worker count

PHP-FPM uses a fixed number of simultaneous worker processes to handle incoming requests.
If more simultaneous requests are received than the number of workers,
then some requests wait until worker processes are available.

The default worker count is set to a conservative default value.
To determine and set the optimal value for your app, see [PHP-FPM sizing](/docs/languages/php/fpm).

## OPcache preloading

OPcache preloading loads selected files into shared memory,
making their content (functions, classes) globally available for requests.
It also removes the need to include these files later.
When OPcache is correctly configured, it can result in significant improvements to both CPU and memory usage.

Consult your framework's documentation to see
if there are recommendations for optimal preload configuration or ready-to-use preload scripts.

OPcache is only available on PHP 7.4+ and uses PHP-CGI.
If your PHP version doesn't support OPcache, this is a good reason to upgrade.

Note that the only way to clear the preload cache is by [restarting PHP-FPM](#restart-php-fpm).

If you have [disabled OPcache timestamp validation](#disable-opcache-timestamp-validation),
you need to clear the OPcache explicitly on deployment (which can be done by restarting PHP-FPM).

### Enable OPcache preloading

To enable preloading, add a variable that specifies a preload script:

`<PRELOAD_SCRIPT>` is a file path relative to the [app root](/docs/configure-apps/app-reference/single-runtime-image#root-directory).
It may be any PHP script that calls `opcache_compile_file()`.

The following example uses a `preload.php` file as the preload script.
This script loads all `.php` files in the `vendor` directory (and subdirectories):

```php preload.php theme={null}
<?php
$directory = new RecursiveDirectoryIterator(getenv('PLATFORM_APP_DIR') . '/vendor');
$iterator = new RecursiveIteratorIterator($directory);
$regex = new RegexIterator($iterator, '/^.+\.php$/i', RecursiveRegexIterator::GET_MATCH);

foreach ($regex as $key => $file) {
    // This is the important part!
    opcache_compile_file($file[0]);
}
```

### Configure OPcache

OPcache needs to be tuned before production usage and can be configured the [same way as PHP](/docs/languages/php#customize-php-settings).

Let the app run for a while before tuning OPcache
since the preload script may change some of the configuration.

#### Set the maximum number of cached files

`opcache.max_accelerated_files` is the maximum number of files that OPcache can cache at once.
If this value is lower than the number of files in the app,
the cache becomes less effective because it starts [thrashing](https://en.wikipedia.org/wiki/Thrashing_\(computer_science\)).

To determine the maximum number of files to cache, follow these steps:

1. Connect to the container via SSH using the [CLI](/docs/development/ssh)
   by running `upsun ssh`.

2. Determine roughly how many `.php` files your app has by running this command from [your app root](/docs/configure-apps/app-reference/single-runtime-image#root-directory):

   ```bash theme={null}
   find . -type f -name '*.php' | wc -l
   ```

   Note that the returned valued is an approximation.
   Some apps have PHP code in files that don't end in `.php` or files that are generated at runtime.

3. Set `opcache.max_accelerated_files` to a value slightly higher than the returned number.
   PHP automatically rounds the value up to the next highest prime number.

An example configuration:

#### Set memory consumption

`opcache.memory_consumption` is the total memory (in megabytes) that OPcache can use with FastCGI.
If the app uses more than this, the cache starts [thrashing](https://en.wikipedia.org/wiki/Thrashing_\(computer_science\)) and becomes less effective.

Determining the optimal limit to memory consumption requires executing code via a web request to get adequate statistics.
[CacheTool](https://github.com/gordalina/cachetool) is an open-source tool to help you get the statistics.

To determine the total amount of memory to use, follow these steps:

1. Connect to the container via SSH using the [CLI](/docs/development/ssh)
   by running `upsun ssh`.
2. Change to the `/tmp` directory (or any other non-web-accessible writable directory) with `cd /tmp`.
3. Download CacheTool with `curl -sLO https://github.com/gordalina/cachetool/releases/latest/download/cachetool.phar`.
4. Make CacheTool executable with `chmod +x cachetool.phar`.
5. Check the OPcache status for FastCGI commands by running the following command:

   ```bash theme={null}
   php cachetool.phar opcache:status --fcgi=$SOCKET
   ```

   The `--fcgi=$SOCKET` option ensures the PHP-FPM process on the server connects through the right socket.
6. Analyze the output to determine the optimal value for `opcache.memory_consumption`.
   The most important values from CacheTool's output are the following:

   * `Memory used`
   * `Memory free`
   * `Oom restarts` (out of memory restarts)
     If the value is different than 0, you don't have enough memory allocated to OPcache.

   If `Memory free` is too low or `Oom Restarts` too high,
   set a higher value for memory consumption.
7. Set `opcache.memory_consumption`.
   Note: The unit for `opcache.memory_consumption` is megabytes.

   An example configuration:

8) [Restart PHP-FPM](#restart-php-fpm) and make sure that OPcache works as expected by rerunning CacheTool
   with the following command:

   ```bash theme={null}
   php cachetool.phar opcache:status --fcgi=$SOCKET
   ```

9) Remove CacheTool by deleting the `cachetools.phar` file with `rm -rf cachetools.phar`.

### Disable OPcache timestamp validation

By default, OPcache checks that the cached version of a file is always up-to-date.
This means that every time a cached file is used, OPcache compares it to the file on disk.
If that file has changed, it gets reloaded and re-cached.
This allows to support apps that generate compiled PHP code from user configuration.

If you know your code isn't going to change outside a new deployment,
you can disable that check and get a small performance improvement.

Timestamp validation can be disabled by adding the following variable to your [app configuration](/docs/configure-apps):

When you have disabled OPcache timestamp validation,
you need to explicitly clear OPcache on deployment by [restarting PHP-FPM](#restart-php-fpm).

Note: If your app generates PHP code at runtime based on user configuration, don't disable timestamp validation.
Doing so would prevent updates to the generated code from being loaded.

## Restart PHP-FPM

To force a restart of PHP-FPM:

1. Connect to your app container via SSH using the [CLI](/docs/development/ssh) by running `upsun ssh`.
2. Run `pkill -f -u "$(whoami)" php-fpm`.

## Optimize your code

To optimize your app, consider using a [profiler](/docs/observability/application-metrics).
A profiler helps determine what slow spots can be found and addressed and helps improve performance.

<PerformanceAgentMention />


# Using Xdebug
Source: https://developer.upsun.com/docs/languages/php/xdebug



<DisclaimerNix />

[Xdebug](https://xdebug.org/) is a real-time debugger extension for PHP.
While usually used for local development, it can also be helpful for debugging aberrant behavior on the server.

As configured on Upsun Cloud, it avoids any runtime overhead for non-debug requests, even in production, and only allows connections via SSH tunnels to avoid any security issues.

Note that Xdebug runs only on your app containers.
So you can't use it for [worker containers](/docs/configure-apps/workers).

Also, note that if you use a [custom start command](/docs/languages/php#alternate-start-commands),
Xdebug is automatically disabled.

## Before you begin

The following table shows the PHP versions where Xdebug is available (●).

<MetaExtensionPhp />

You also need:

* The Upsun Cloud [CLI](/cli)
* A Xdebug-compatible IDE installed on your machine.
  For setup instructions, consult your IDE's Xdebug documentation, such as that for [PHPStorm](https://www.jetbrains.com/help/phpstorm/configuring-xdebug.html).

## 1. Set up Xdebug

Xdebug runs as a second PHP-FPM process used only for debugging requests, leaving the normal process unaffected.

To enable Xdebug, add the following to your [app configuration](/docs/configure-apps/app-reference/single-runtime-image):

`<YOUR_KEY>` can be any arbitrary alphanumeric string.

When that key is defined, Upsun Cloud starts a second PHP-FPM process on the container that's identically configured but also has Xdebug enabled.
Only incoming requests that have an Xdebug cookie or query parameter set are forwarded to the debug PHP-FPM process.
All other requests are directed to the normal PHP-FPM process and thus have no performance impact.

If you have enabled the [router cache](/docs/routes/cache),
you need to explicitly add the Xdebug cookie (`XDEBUG_SESSION`) to the cookie allowlist.
Depending on the cookies already listed, the result should look similar to the following:

Xdebug has several configuration options available.
They can be set the same way as any other [PHP setting](/docs/languages/php#php-settings).
For a full list of available options, consult the [Xdebug documentation](https://xdebug.org/docs/).

## 2. Use Xdebug

### Open a tunnel

To open an SSH tunnel to the server from a local checkout of your app, run the following [CLI command](/cli) :

```bash theme={null}
upsun environment:xdebug
```

That SSH tunnel allows your IDE and the server to communicate debug information securely.

By default, Xdebug operates on port `9003`.
Generally, it's best to configure your IDE to use that port.
To use an alternate port, use the `--port` flag.

To close the tunnel and terminate the debug connection, press <kbd>Ctrl</kbd> + <kbd>C</kbd>.

### Install an Xdebug helper

While Xdebug can be triggered from the browser by adding a special query parameter, the preferred way is to use a browser plugin helper.
Helpers are available for [Firefox](https://addons.mozilla.org/en-US/firefox/addon/xdebug-helper-for-firefox/)
and [Chrome](https://chrome.google.com/webstore/detail/xdebug-helper/eadndfjplgieldjbigjakmdgkmoaaaoc).
Their respective plugin pages document how to trigger them when needed.

## 3. Configure your IDE

Follow the instructions for your IDE, such as those for [PHPStorm](https://www.jetbrains.com/help/phpstorm/configuring-xdebug.html).

The common steps for setup usually include:

1. Configuring the Xdebug debug port and making sure it's set to the expected value (`9003` as default or the value you chose with `--port` when opening the tunnel).
2. Making sure that external connections are allowed.
3. Adding a new server for your Upsun Cloud environment.
   The Host should be the hostname of the environment on Upsun Cloud you are debugging.
   The Port should always be `443` and the Debugger set to `Xdebug`.
4. Ensuring path mappings is enabled.
   This lets you define what remote paths on the server correspond to what path on your local machine.
   In the majority of cases you can just define [your app root](/docs/configure-apps/app-reference/single-runtime-image#root-directory)
   to map to `myapp`.
5. Listening for connections.
6. Starting debugging. While in listen mode, start the `upsun xdebug` tunnel.
   Use the Xdebug helper plugin for your browser to enable debugging.
   Set a break point in your app, then load a page in your browser.
   The request should pause at the break point and allow you to examine the running app.


# Manage Python dependencies
Source: https://developer.upsun.com/docs/languages/python/dependencies

See how to manage Python dependencies with different package managers.

<DisclaimerNix />

You can manage Python packages in different ways.
Python images come with pip installed,
but they're flexible enough so you can choose what package manager you want.
This article describes how to configure major package management tools.

This package management is different from global dependencies (packages available as commands),
which you can add in your [app configuration](/docs/configure-apps).
See more about [managing global dependencies](/docs/languages/python#package-management).

## Pip

[pip](https://pip.pypa.io/en/stable/) is the primary package installer for Python
and comes installed on every Python container.
You can use it to install packages from the Python Package Index and other locations.

To manage packages with pip,
commit a `requirements.txt` file with all of the dependencies needed for your app.
Then install the packages in your [`build` hook](/docs/configure-apps/hooks),
such as by running the following command: `pip install -r requirements.txt`.

The following sections present ideas to keep in mind to ensure repeatable deployments on Upsun Cloud.

### pip version

The version of pip on Python containers gets updated regularly.
But it isn't guaranteed to be the latest version or the version that matches your local environment.
You might want to define a specific version of pip in your deployments to further enforce repeatable builds.

To do so, modify your [app configuration](/docs/configure-apps), as in the following examples:

### pip freeze

You can write `requirements.txt` files in various ways.
You can specify anything from the latest major to a specific patch version in a [requirement specifier](https://pip.pypa.io/en/stable/reference/requirement-specifiers/).
Use `pip freeze` before committing your requirements to pin specific package versions.
This ensures repeatable builds on Upsun Cloud with the same packages.

## Pipenv

[Pipenv](https://pipenv.pypa.io/en/latest/) is a package manager for Python
that creates and manages a virtual environment for Python projects.
Dependencies are tracked and defined within a `Pipfile`.
It also generates a `Pipfile.lock` file to produce repeatable installs.

You can specify the latest or a specific version of Pipenv
in your deployments to ensure repeatable builds.
Because Pipenv depends on pip, you might want to also specify the pip version.

## UV

[uv](https://docs.astral.sh/uv/) is an extremely fast Python package and project
manager, written in Rust.

## Poetry

[Poetry](https://python-poetry.org/docs/) is a tool for dependency management and packaging in Python.
It allows you to declare the libraries your project depends on and manages them for you.
Poetry offers a lock file to ensure repeatable installs and can build your project for distribution.
It also creates and manages virtual environments to keep project work isolated from the rest of your system.

To set up Poetry on Upsun Cloud, follow these steps:

1. Configure your virtual environment by setting two variables in your [app configuration](/docs/configure-apps).

   * [`POETRY_VIRTUALENVS_IN_PROJECT`](https://python-poetry.org/docs/configuration/#virtualenvsin-project):
     Setting this to `true` places the virtual environment at the root of the app container: `/app/.venv`.
   * [`POETRY_VIRTUALENVS_CREATE`](https://python-poetry.org/docs/configuration/#virtualenvscreate):
     Setting this to `true` ensures that the same virtual environment created during the build hook is reused in subsequent steps.

   Set the variables as follows:

2) Install Poetry.
   You can specify the latest or a specific version of Poetry in your deployments to ensure repeatable builds.

3. Make Poetry available outside the build hook.
   Although step 2 updated the `PATH` to make Poetry available during the build hook,
   it isn't enough to make it available at subsequent stages.

   To use Poetry in a start command, a deploy hook, or during SSH sessions,
   update the `PATH` in a [`.environment` file](/docs/development/variables/set-variables#set-variables-via-script).

   ```text .environment theme={null}
   # Updates PATH when Poetry is used, making it available during deploys, start commands, and SSH.
   if [ -n "$POETRY_VERSION" ]; then
     export PATH="/app/.local/bin:$PATH"
   fi
   ```


# Python
Source: https://developer.upsun.com/docs/languages/python/index

Get started creating Python apps on Upsun Cloud.

<DisclaimerNix />

Python is a general purpose scripting language often used in web development.
You can deploy Python apps on Upsun Cloud using a server or a project such as [uWSGI](https://uwsgi-docs.readthedocs.io/en/latest/).

## Supported versions

You can select the major and minor version.

Patch versions are applied periodically for bug fixes and other maintenance updates. By default, you get the latest available patches each time you deploy. If your project has a [maintenance window](/docs/core-concepts/build-deploy#maintenance-window) configured, Upsun Cloud applies patches only during that window. Upsun Cloud may still apply urgent or critical fixes outside of the maintenance window.

* <span>3.14</span>

### Specify the language

To use Python, specify `python` as your [app's type](/docs/configure-apps/app-reference/single-runtime-image#type):

For example:

## Deprecated versions

The following versions are still available in your projects,
but they're at their end of life and are no longer receiving security updates from upstream.

* <span>3.13</span>
* <span>3.12</span>
* <span>3.11</span>

To ensure your project remains stable in the future, switch to a [supported version](#supported-versions).

\* This version doesn't receive any updates at all.
You are strongly recommended to upgrade to a supported version.

## Retired versions

The following versions have been retired and are no longer available.
If your project uses a retired version, you must update to a [supported version](#supported-versions).

* <span>3.10</span>
* <span>3.9</span>
* <span>3.8</span>
* <span>3.7</span>
* <span>3.6</span>
* <span>3.5</span>
* <span>2.7</span>

## Usage example

### Run your own server

You can define any server to handle requests.
Once you have it configured, add the following configuration to get it running on Upsun Cloud:

1. Specify one of the [supported versions](#supported-versions):

2) Install the requirements for your app.

3. Define the command to start your web server:

You can choose from many web servers such as Daphne, Gunicorn, Hypercorn, and Uvicorn.
See more about [running Python web servers](/docs/languages/python/server).

### Use uWSGI

You can also use [uWSGI](https://uwsgi-docs.readthedocs.io/en/latest/) to manage your server.
Follow these steps to get your server started.

1. Specify one of the [supported versions](#supported-versions):

2) Define the conditions for your web server:

3. Create configuration for uWSGI such as the following:

   ```ini config/uwsgi.ini theme={null}
   [uwsgi]
   # Unix socket to use to talk with the web server
   # Uses the variable defined in the configuration in step 2
   socket = $(SOCKET)
   protocol = http

   # the entry point to your app
   wsgi-file = app.py
   ```

   Replace `app.py` with whatever your file is.

4. Install the requirements for your app.

5) Define the entry point in your app:

   ```python theme={null}
   # You can name the function differently and pass the new name as a flag
   # start: "uwsgi --ini conf/uwsgi.ini --callable <NAME>"
   def application(env, start_response):

       start_response('200 OK', [('Content-Type', 'text/html')])
       return [b"Hello world from Upsun Cloud"]
   ```

## Package management

Your app container comes with pip pre-installed.
For more about managing packages with pip, Pipenv, and Poetry,
see how to [manage dependencies](/docs/languages/python/dependencies).

To add global dependencies (packages available as commands),
add them to the `dependencies` in your [app configuration](/docs/configure-apps/app-reference/single-runtime-image#dependencies):

For example, to use `pipenv` to manage requirements and a virtual environment, add the following:

## Connect to services

The following examples show how to access various [services](/docs/add-services) with Python.
For more information on configuring a given service, see the page for that service.

You can access service credentials to connect to [managed services](/docs/add-services) from environment variables present in the application container.
Consult each of the individual service documentation to see how to retrieve and surface credentials into your application.

* [ClickHouse](/docs/add-services/clickhouse#usage-example)
* [Elasticsearch](/docs/add-services/elasticsearch#usage-example)
* [Gotenberg](/docs/add-services/gotenberg#usage-example)
* [Headless Chrome](/docs/add-services/headless-chrome#usage-example)
* [InfluxDB](/docs/add-services/influxdb#usage-example)
* [Kafka](/docs/add-services/kafka#usage-example)
* [MariaDB/MySQL](/docs/add-services/mysql#usage-example)
* [Memcached](/docs/add-services/memcached#usage-example)
* [mercure](/docs/add-services/mercure#usage-example)
* [mongodb](/docs/add-services/mongodb#usage-example)
* [Network Storage](/docs/add-services/network-storage#usage-example)
* [OpenSearch](/docs/add-services/opensearch#usage-example)
* [PostgreSQL](/docs/add-services/postgresql#usage-example)
* [RabbitMQ](/docs/add-services/rabbitmq#usage-example)
* [Redis](/docs/add-services/redis#usage-example)
* [Solr](/docs/add-services/solr#usage-example)
* [Valkey](/docs/add-services/valkey#usage-example)
* [Varnish](/docs/add-services/varnish#usage-example)
* [Vault KMS](/docs/add-services/vault#usage-example)
* [Chroma](/tutorials/self-hosted/chroma#3-use-the-relationship-in-your-application)
* [Qdrant](/tutorials/self-hosted/qdrant#4-use-the-relationship-in-your-application)

## Sanitizing data

By default, data is inherited automatically by each child environment from its parent.
If you need to sanitize data in preview environments for compliance,
see how to [sanitize databases](/docs/development/sanitize-db).

## Frameworks

All major Python web frameworks can be deployed on Upsun Cloud.
See dedicated guides for deploying and working with them:

* [Django](/docs/get-started/stacks/django)
* [Flask](/docs/get-started/stacks/flask)


# Manage Python versions in non-Python containers
Source: https://developer.upsun.com/docs/languages/python/python-version

See how to manage different Python versions in your Upsun Cloud containers.

<DisclaimerNix />

You may need to use a specific version of Python that isn't available in an app container for a different language.
For example, a container might have a long-term support version, while you want the latest version.

In such cases, use the [Pyenv version manager](https://github.com/pyenv/pyenv)
to install the specific version you want to use.

1. Add your target Python version as a [variable](/docs/development/variables):

2) Add Pyenv in a [`build` hook](/docs/configure-apps/hooks/hooks-comparison#build-hook):

Now your build hook can use the specified version of Python.
You can verify this by running `python --version`.

If you want this Python version to be available in the runtime environment, follow these steps:

1. Copy Pyenv to your runtime environment at the end of your build hook:

2) Create an [`.environment` file](/docs/development/variables/set-variables#set-variables-via-script):

   ```bash theme={null}
   touch .environment
   ```

3) Update the PATH for the runtime environment:

   ```yaml .environment theme={null}
   export PATH=/app/.pyenv/bin:/app/.pyenv/shims:$PATH
   ```

Now the specified Python version is used in the runtime environment.


# Web servers
Source: https://developer.upsun.com/docs/languages/python/server

See how to start your apps as you wish with ASGI and WSGI servers.

<DisclaimerNix />

The Python ecosystem offers a number of web servers that can be used to deploy to Upsun Cloud.
The following examples deploy a Django project named `myapp`.
They assume a `myapp/wsgi.py` or `myapp/asgi.py` file  with a callable `application`.
Adjust the examples to fit your framework and app.

## Gunicorn

[Gunicorn](https://docs.gunicorn.org/) is a Python WSGI HTTP Server for Unix
that operates on a pre-fork worker model.
The Gunicorn server is broadly compatible with various web frameworks, light on server resource usage, and fast.

To deploy with Gunicorn on Upsun Cloud,
use one of the following examples to update your [app configuration](/docs/configure-apps).

The examples vary based on both your package manager (Pip, Pipenv, or Poetry)
and whether your app listens on a TCP (default) or Unix (for running behind a proxy server) socket.
For more information on upstream sockets and protocols, see the [application reference](/docs/configure-apps/image-properties/web#upstream).

The snippets below assume that Gunicorn has been added as a dependency to your `requirements.txt`, `Pipfile.lock`, or `poetry.lock`.

### Gunicorn workers

These examples define four worker processes with `-w 4`.
For more details on what you can configure, see the [Gunicorn documentation](https://docs.gunicorn.org/en/stable/faq.html#worker-processes).

Workers can also be defined with a custom [worker class](https://docs.gunicorn.org/en/latest/settings.html#worker-class),
such as [Uvicorn](https://www.uvicorn.org/#running-with-gunicorn), [gevent](https://www.gevent.org/),
or [Tornado](https://www.tornadoweb.org/).

For example, to add a Uvicorn worker class to the pip example for Unix,
adjust the start command to the following:

## Daphne

[Daphne](https://github.com/django/daphne) is a HTTP, HTTP2 ,and WebSocket protocol server for ASGI and ASGI-HTTP,
developed to power Django Channels.

To deploy with Daphne on Upsun Cloud,
use one of the following examples to update your [app configuration](/docs/configure-apps).

The examples vary based on both your package manager (Pip, Pipenv, or Poetry)
and whether your app listens on a TCP (default) or Unix (for running behind a proxy server) socket.
For more information on upstream sockets and protocols, see the [application reference](/docs/configure-apps/image-properties/web#upstream).

The snippets below assume that Daphne has been added as a dependency to your `requirements.txt`, `Pipfile.lock`, or `poetry.lock`.

## Uvicorn

[Uvicorn](https://www.uvicorn.org/) is an ASGI web server implementation for Python.

To deploy with Uvicorn on Upsun Cloud,
use one of the following examples to update your [app configuration](/docs/configure-apps).

The examples vary based on both your package manager (Pip, Pipenv, or Poetry)
and whether your app listens on a TCP (default) or Unix (for running behind a proxy server) socket.
For more information on upstream sockets and protocols, see the [application reference](/docs/configure-apps/image-properties/web#upstream).

The snippets below assume that Uvicorn has been added as a dependency to your `requirements.txt`, `Pipfile.lock`, or `poetry.lock`.

### Uvicorn workers

These examples define four worker processes with `-w 4`.
For more recommendations on this and other settings, see the [Uvicorn documentation](https://www.uvicorn.org/settings/#timeouts).

Instead of the `-w` flag, you can also use the `WEB_CONCURRENCY` variable.
See how to [set variables](/docs/development/variables/set-variables).

## Hypercorn

[Hypercorn](https://hypercorn.readthedocs.io/) is an ASGI and WSGI web server inspired by Gunicorn.

To deploy with Hypercorn on Upsun Cloud,
use one of the following examples to update your [app configuration](/docs/configure-apps).

The examples vary based on both your package manager (Pip, Pipenv, or Poetry)
and whether your app listens on a TCP (default) or Unix (for running behind a proxy server) socket.
For more information on upstream sockets and protocols, see the [application reference](/docs/configure-apps/image-properties/web#upstream).

The snippets below assume that Hypercorn has been added as a dependency to your `requirements.txt`, `Pipfile.lock`, or `poetry.lock`.

### Hypercorn workers

These examples define four worker processes with `-w 4`.
For more details on what you can configure, see the [Hypercorn documentation](https://hypercorn.readthedocs.io/en/latest/how_to_guides/configuring.html).

Workers can also be defined with a custom [worker class](https://hypercorn.readthedocs.io/en/latest/how_to_guides/configuring.html#configuration-options),
such as Asyncio, Uvloop, or Trio.

For example, to add a Asyncio worker class to the pip example for Unix,
adjust the start command to the following:


# Ruby
Source: https://developer.upsun.com/docs/languages/ruby

Upsun Cloud supports deploying any Ruby application. Your application can use any Ruby application server such as Puma or Unicorn and deploying a Rails or a Sinatra app is very straight forward.


<DisclaimerNix />

## Supported versions

You can select the major and minor version.

Patch versions are applied periodically for bug fixes and other maintenance updates. By default, you get the latest available patches each time you deploy. If your project has a [maintenance window](/docs/core-concepts/build-deploy#maintenance-window) configured, Upsun Cloud applies patches only during that window. Upsun Cloud may still apply urgent or critical fixes outside of the maintenance window.

### Ruby

* <span>4.0</span>
* <span>3.4</span>
* <span>3.3</span>

### Specify the language

To use Ruby, specify `ruby` as your [app's `type`](/docs/configure-apps/app-reference/single-runtime-image#type):

For example:

## Deprecated versions

The following versions are still available in your projects,
but they're at their end of life and are no longer receiving security updates from upstream.

*No deprecated versions.*

To ensure your project remains stable in the future, switch to a [supported version](#supported-versions).

## Retired versions

The following versions have been retired and are no longer available.
If your project uses a retired version, you must update to a [supported version](#supported-versions).

* <span>3.2</span>
* <span>3.1</span>
* <span>3.0</span>
* <span>2.7</span>
* <span>2.6</span>
* <span>2.5</span>
* <span>2.4</span>
* <span>2.3</span>

## Puma based Rails configuration

This example uses Puma to run a Ruby application.
You could use any Ruby application server such as Unicorn.

Configure the `.upsun/config.yaml` file with a few key settings as listed below.
A complete example is included at the end of this section.

1. Specify the language of your application (available versions are listed above):

2) Set up environment variables.

   Rails runs by default on a preview environment.
   You can change the Rails/Bundler via those environment variables,
   some of which are defaults on Upsun Cloud.

The `SECRET_KEY_BASE` variable is generated automatically based on the
[`PLATFORM_PROJECT_ENTROPY`
variable](/docs/development/variables/use-variables#use-provided-variables) but you can change it.

Based on TARGET\_RUBY\_VERSION, we recommand to set on your Gemfile so next
PATCH release of ruby doesn't fail the build:

```ruby theme={null}
ruby ENV["TARGET_RUBY_VERSION"] || File.read(File.join(File.dirname(__FILE__), ".ruby-version")).strip
```

3. Build your application with the build hook.

   Assuming you have your dependencies stored in the `Gemfile` at [your app root](/docs/configure-apps/app-reference/single-runtime-image#root-directory),
   create a hook like the following:

These are installed as your project dependencies in your environment.
You can also use the `dependencies` key to install global dependencies.
These can be Ruby, Python, NodeJS, or PHP libraries.

If you have assets, it's likely that you need NodeJS/yarn.

4. Configure the command to start serving your application (this must be a foreground-running process) under the `web` section:

This assumes you have Puma as a dependency in your Gemfile:

```ruby theme={null}
gem "puma", ">= 5.0"
```

5. Define the web locations your application is using:

This configuration sets the web server to handle HTTP requests at `/static`
to serve static files stored in `/app/static/` folder.
Everything else is forwarded to your application server.

6. Create any Read/Write mounts.

   The root file system is read only.
   You must explicitly describe writable mounts.

This setting allows your application writing temporary files to `/app/tmp`,
logs stored in `/app/log`, and active storage in `/app/storage`.

You can define other read/write mounts (your application code itself being deployed to a read-only file system).
Note that the file system is persistent and when you backup your cluster these mounts are also backed up.

7. Then, setup the routes to your application in `.upsun/config.yaml`.

   ```yaml .upsun/config.yaml theme={null}
   applications:
     ...

   routes:
     "https://{default}/":
       type: upstream
       upstream: "myapp:http"
   ```

### Complete app configuration

Here is a complete `.upsun/config.yaml` file:

## Configuring services

This example assumes there is a MySQL instance.
To configure it, [create a service](/docs/add-services) such as the following:

## Connecting to services

Once you have a service, link to it in your [app configuration](/docs/configure-apps):

By using the following Ruby function calls, you can obtain the database details.

```ruby theme={null}
require "base64"
require "json"
relationships= JSON.parse(Base64.decode64(ENV['PLATFORM_RELATIONSHIPS']))
```

This should give you something like the following:

```json theme={null}
{
  "mysql" : [
    {
      "path" : "main",
      "query" : {
        "is_master" : true
      },
      "port" : 3306,
      "username" : "user",
      "password" : "",
      "host" : "mysql.internal",
      "ip" : "246.0.241.50",
      "scheme" : "mysql"
    }
  ]
}
```

For Rails, you can use the standard Rails `config/database.yml` with the values found with the snippet provided before.

## Other tips

* To speed up boot you can use the [Bootsnap gem](https://github.com/Shopify/bootsnap)
  and configure it with the local `/tmp`:

  ```ruby config/boot.rb theme={null}
  Bootsnap.setup(cache_dir: "/tmp/cache")
  ```

* For garbage collection tuning, you can read [this article](https://shopify.engineering/17489064-tuning-rubys-global-method-cache)
  and look for [discourse configurations](https://github.com/discourse/discourse_docker/blob/b259c8d38e0f42288fd279c9f9efd3cefbc2c1cb/templates/web.template.yml#L8)

* New images are released on a regular basis to apply security patches. While the minor version will not change (as you are specifying it in the `type` property), the patch version will be updated. You may encounter this kind of error:

  ```
  bundler: failed to load command: puma (/app/vendor/bundle/ruby/3.2.0/bin/puma)
  /app/.global/gems/bundler-2.4.22/lib/bundler/definition.rb:447:in `validate_ruby!': Your Ruby version is 3.2.9, but your Gemfile specified 3.2.8 (Bundler::RubyVersionMismatch)
  ```

  To avoid issues when such updates are performed, use

  ```ruby theme={null}
  ruby ENV["TARGET_RUBY_VERSION"] || File.read(File.join(File.dirname(__FILE__), ".ruby-version")).strip
  ```

  in your `Gemfile`, where `TARGET_RUBY_VERSION` has been defined as above.

<RepoList lang="ruby" />

## Troubleshooting

By default, deployments have `BUNDLE_DEPLOYMENT=1` to ensure projects have a `Gemfile.lock` file.
This is safer for version yank issues and other version upgrade breakages.

You may encounter an error like the following during a build:

```txt {no-copy="true"} theme={null}
W: bundler: failed to load command: rake (/app/.global/bin/rake)
W: /app/.global/gems/bundler-2.3.5/lib/bundler/resolver.rb:268:in `block in verify_gemfile_dependencies_are_found!': Could not find gem 'rails (= 5.2.6)' in locally installed gems. (Bundler::GemNotFound)
```

To resolve this error:

1. Run `bundle install` with the same `ruby` and `bundler` versions defined in your `.upsun/config.yaml` file.
2. Push the `Gemfile.lock` to your repository.


# Rust
Source: https://developer.upsun.com/docs/languages/rust

Upsun Cloud supports building and deploying applications written in Rust. Dependencies are managed with Cargo, and apps are built using `cargo build` during the build hook and started with a custom web command.

<DisclaimerNix />

Upsun Cloud supports building and deploying applications written in Rust.

## Supported versions

You can select the major version. But the latest compatible minor version is applied automatically and can’t be overridden.

Patch versions are applied periodically for bug fixes and other maintenance updates. By default, you get the latest available patches each time you deploy. If your project has a [maintenance window](/docs/core-concepts/build-deploy#maintenance-window) configured, Upsun Cloud applies patches only during that window. Upsun Cloud may still apply urgent or critical fixes outside of the maintenance window.

* <span>1</span>

## Deprecated versions

The following versions are still available in your projects,
but they're at their end of life and are no longer receiving security updates from upstream.

*No deprecated versions.*

To ensure your project remains stable in the future, switch to a [supported version](#supported-versions).

## Retired versions

The following versions have been retired and are no longer available.
If your project uses a retired version, you must update to a [supported version](#supported-versions).

*No retired versions.*

## Dependencies

The recommended way to handle Rust dependencies on Upsun Cloud is using Cargo.
Commit a `Cargo.toml` and a `Cargo.lock` file in your repository
so the system automatically downloads dependencies using Cargo.

## Building and running your app

Assuming your `Cargo.toml` and `Cargo.lock` files are present in your repository,
you can build your app using the `cargo build` command to produce a working executable.

You can then start it from the `web.commands.start` directive.
Note that the start command *must* run in the foreground.
If the program terminates for any reason it is automatically restarted.

The following basic [app configuration](/docs/configure-apps) is sufficient to run most Rust apps.
See the [complete example](#complete-example) below for more details.

```yaml .upsun/config.yaml theme={null}
applications:
  # The app's name, which must be unique within the project.
  myapp:

    # The language and version for your app.
    type: 'rust:1'

    hooks:
      build:
        cargo build

    web:
      commands:
        # Customize the start command with your own target.
        start: './target/debug/hello'

      locations:
        /:
          # Route all requests to the Rust app, unconditionally.
          allow: false
          passthru: true
```

Note that there is still an Nginx proxy server sitting in front of your application. If desired, certain paths may be served directly by Nginx without hitting your application (for static files, primarily) or you may route all requests to the Rust app unconditionally, as in the example above.

## Built-in variables

Upsun Cloud exposes relationships and other configuration as [environment variables](/docs/development/variables).

To get the `PORT` environment variable (the port on which your app is supposed to listen),
use the following snippet:

```rust theme={null}
let port : String = env::var("PORT").unwrap_or(String::from("8888"));
```

Note that some of the environment variables are in JSON format and are base64 encoded.
For example, to decode the `PLATFORM_RELATIONSHIPS` environment variable,
use the following snippet:

```rust theme={null}
use base64::{Engine as _, engine::{general_purpose}};
use serde_json::Value;

let bytes = general_purpose::STANDARD.decode(env::var("PLATFORM_RELATIONSHIPS").unwrap_or(String::new())).unwrap();
let psh_config: Value = serde_json::from_slice(&bytes).unwrap();
println!("{}", psh_config["database"]);
```

## Complete example

Here is a basic hello world app to illustrate how you can use Rust with Upsun Cloud.
It builds from a `hello.rs` file to serve a static `index.html`.
Follow these steps:

1. [Install Rust and Cargo](https://www.rust-lang.org/tools/install).

2. Create a repository for your app and add the following `Cargo.toml` file:

   ```toml theme={null}
   [package]
   name = "hello_world"
   version = "0.1.0"
   edition = "2021"

   [[bin]]
   name = "hello"
   path = "hello.rs"

   [dependencies]
   time = "0.1.12"
   regex = "0.1.41"
   base64 = "0.21.0"
   serde = { version = "1.0", features = ["derive"] }

   serde_json = "1.0"
   ```

3. Add the following [app configuration](/docs/configure-apps):

   ```yaml .upsun/config.yaml theme={null}
   applications:
     # The app's name, which must be unique within the project.
     myapp:

       # The language and version for your app.
       type: 'rust:1'

       hooks:
         build:
           cargo build

       web:
         commands:
           # Customize the start command with your own target.
           start: './target/debug/hello'

       locations:
         /:
           # Route all requests to the Rust app, unconditionally.
           allow: false
           passthru: true
   ```

4. To generate a `Cargo.lock` file,
   run the following command:

   ```bash theme={null}
   cargo generate-lockfile
   ```

5. Add the following `hello.rs` file:

   ```rust theme={null}
   /* Simple HTTP Server */
   /* Author : Ramesh Vyas */
   use std::io::prelude::*;
   use std::net::TcpListener;
   use std::net::TcpStream;
   use std::fs;
   use std::env;

   fn main() {

       /* Creating a Local TcpListener at Port 8888 */
       const HOST : &str ="127.0.0.1";
       let port : String = env::var("PORT").unwrap_or(String::from("8888"));

       /* Concating Host address and Port to Create Final Endpoint */
       let end_point : String = HOST.to_owned() + ":" +  &port;

       /*Creating TCP Listener at our end point */
       let listener = TcpListener::bind(end_point).unwrap();

       println!("Web server is listening at port {}",port);

       /* Connecting to any incoming connections */
       for stream in listener.incoming() {
           let _stream = stream.unwrap();
           // Call Function to process any incomming connections
           handle_connection(_stream);
       }

   }

   fn handle_connection(mut stream: TcpStream) {
       let mut buffer = [0; 1024];
       stream.read(&mut buffer).unwrap();

       let get = b"GET / HTTP/1.1\r\n";

       if buffer.starts_with(get) {
           let contents = fs::read_to_string("index.html").unwrap();

           let response = format!(
               "HTTP/1.1 200 OK\r\nContent-Length: {}\r\n\r\n{}",
               contents.len(),
               contents
           );

           stream.write(response.as_bytes()).unwrap();
           stream.flush().unwrap();
       } else {
           // some other request
       }
   }
   ```


# Resource configuration
Source: https://developer.upsun.com/docs/manage-resources/adjust-resources

Configure CPU, RAM, and disk storage on a per-environment basis so your apps and services can run smoothly.

When you first deploy your project, or add a new app or service to it,
Upsun Cloud allocates [default resources](/docs/manage-resources/resource-init#default-resources) to each of your containers.
If you don't want to use those default resources, define a different [resource initialization strategy](/docs/manage-resources/resource-init#specify-a-resource-initialization-strategy).

After the initial deployment, or if you opt for the `Manual` [resource initialization strategy](/docs/manage-resources/resource-init#specify-a-resource-initialization-strategy),
you can adjust container resources manually.
To do so, follow the instructions on this page.

Upsun Cloud allows you to configure resources (CPU, RAM, and disk) per environment for each app and service.
You can also add instances for each app depending on your needs.

For example, you can scale vertically and allocate more resources to your production and staging environments
than to your development environments.
This flexibility allows you to optimize performance and costs.

You can also scale horizontally if your apps are struggling with high load, or if you're expecting a traffic spike,
by adding more instances for your apps and workers.

<Note>
  For information on costs related to resource usage, see the [Upsun pricing page](https://upsun.com/pricing/).
  You can [monitor these costs](/docs/administration/billing/bp-monitor-billing) in the Console.
</Note>

## Vertical scaling

To define how much CPU, RAM, and disk storage you want to allocate to each individual container,
follow these steps:

<Tabs>
  <Tab title="Using the CLI">
    To set resources for each of your apps and services,
    you can use the Upsun Cloud CLI interactive prompts, or run commands manually.

    * **Interactive prompts:**

    Run the `upsun resources:set` command, and follow the prompts to set resources for each app and service.

    <Note>
      For further guidance on how to set resources using the CLI, run the `upsun resources:set --help` command.
      Note that if the deployment fails after you've run `upsun resources:set`,
      you may need to set the resources again.
    </Note>

    After you've set resources, your environment is redeployed,
    which causes a short downtime.

    * **Manual commands:**

    Run the `resources:set` command using the following CLI options:

    | CLI option | Description |
    | - | - |
    | `size` | Allows you to define how much CPU you want to allocate to each app or service.<br />The amount of CPU then determines how much RAM is also allocated, based on the [container profile](#advanced-container-profiles). |
    | `disk` | Allows you to define how much disk/storage you want to allocate to each app or service. Disk space and inode limits scale together. |

    *Example 1:*

    The following command allocates `0.1` CPU to the `frontend` app, `0.25` CPU to the `backend` app, and `1` CPU to the `database` service.
    The amount of RAM these settings translate into depends on each [container profile](#advanced-container-profiles).

    ```bash Terminal theme={null}
    upsun resources:set --size frontend:0.1,backend:0.25,database:1
    ```

    *Example 2:*

    The following command allocates `640 MB` of disk to the `backend` app, and `2048 MB` to the `database` service:

    ```bash Terminal theme={null}
    upsun resources:set --disk backend:640,database:2048
    ```

    *Example 3:*

    You can also use wildcards. For example, if you have two apps named `frontend` and `backend`,
    you could allocate the same CPU and RAM combination to both by using the following command:

    ```bash Terminal theme={null}
    upsun resources:set --size '*end:0.1'
    ```
  </Tab>

  <Tab title="Using the Console">
    1. Open your project.
    2. Click the **Configure resources** button in the project card or the **App & Services** panel:
       <img alt="Project card" />
    3. For each app and service, select a CPU & RAM combination, and enter the amount of disk/storage you want to allocate.
       <img alt="Configure your resources on the current environment window" />
       <Note>
         The values from the **CPU & RAM** menu depend on the [container profile](#advanced-container-profiles) of each instance.<br />
         If you deploy several instances of your app, the selected CPU & RAM combination isn't divided between those instances.
         Each instance benefits from the full, selected CPU & RAM.
       </Note>
    4. Click **Save**.<br />
       You environment is redeployed, which causes a short downtime.
  </Tab>
</Tabs>

## Horizontal scaling

For apps and workers, you can also define how many instances you want to deploy.
To do so, follow these steps:

<Note>
  When you have several instances of an app, the Upsun Cloud router randomly distributes requests to available instances.
</Note>

<Tabs>
  <Tab title="Using the CLI">
    To define how many instances of an app or worker you want to deploy,
    you can use the Upsun Cloud CLI interactive prompts,
    or run commands manually.

    * **Interactive prompts:**

      Run the `upsun resources:set` command, and follow the prompts to set resources for each app and service.

      <Note>
        For further guidance on how to set resources using the CLI, run the `upsun resources:set --help` command.

        Note that if the deployment fails after you've run `upsun resources:set`,
        you may need to set the resources again.
      </Note>

    * **Manual commands:**

      To scale an app or worker, run the following command:

      ```bash Terminal theme={null}
      upsun resources:set --count <APP_NAME>:<NUMBER_OF_INSTANCES>
      ```

      For example, to scale your `myapp` app to 3 instances, run the following command:

      ```bash Terminal theme={null}
      upsun resources:set --count myapp:3
      ```

      You can also set the same instance count for all your apps using a wildcard.
      To do so, run the following command:

      ```bash Terminal theme={null}
      upsun resources:set --count '*:<NUMBER_OF_INSTANCES>'
      ```

      For example, to scale all your apps to 3 instances, run the following command:

      ```bash Terminal theme={null}
      upsun resources:set --count '*:3'
      ```

      <Note>
        For further guidance on how to set resources using the CLI, run the `upsun resources:set --help` command.

        After you've set the number of instances for your apps and workers, your environment is redeployed.
        If you've made no other changes, this redeployment causes no downtime.

        If the redeployment fails after you've run `upsun resources:set`,
        you may need to set the resources again.
      </Note>
  </Tab>

  <Tab title="Using the Console">
    1. Open your project.
    2. Click the **Configure resources** button in the project card or the **App & Services** panel:
       <img alt="Project card" />
    3. For each of your apps and workers, select the number of instances you want to deploy.
       <img alt="Configure your resources on the current environment window" />
       <Note>
         If you deploy several instances of your app, the [selected CPU & RAM combination](#vertical-scaling) isn't divided between those instances.
         Each instance benefits from the full, selected CPU & RAM.
       </Note>
    4. Click **Save**.<br />
       Your environment is redeployed.
       If you've only made changes to the number of instances for your apps and workers,
       this redeployment causes no downtime.
  </Tab>
</Tabs>

<Info>
  <h4>Autoscaling</h4>
  Upsun Cloud provides [**native autoscaling** support](/docs/manage-resources/autoscaling). You can configure thresholds for metrics such as CPU, RAM, and request latency. Resources will automatically adjust horizontally to meet demand.
</Info>

## View application instance details

Upsun Cloud maintains a real-time indexed list of an application's instances and their IP addresses in the project's `/run/peers.json` file. You might view this read-only file to gain insight into how your application instances are distributed. Upsun Cloud maintains this file whether you scale instances manually or have autoscaling enabled.

Distributed applications (for example, those running on Elixir and Erlang) and applications that can scale horizontally must be aware of all its instances in order to coordinate activities such as setting up clusters and handling application failures.

The number of instances in this file at any time matches the number of application instances shown on the Configure Resources page of the Console.

To view the contents of the file, run this command from the root of your project directory:

```sh theme={null}
cat /run/peers.json | jq
```

The output is similar to this:

```json theme={null}
{
  "hello_distributed.1": "123.456.789.10",
  "hello_distributed.3": "123.456.789.20",
  "hello_distributed.2": "123.456.789.30",
  "hello_distributed.0": "123.456.789.40"
}
```

## Advanced: Container profiles

### Shared CPU container sizes

By default, Upsun Cloud allocates a container profile to each app and service depending on the range of resources it's expected to need.

Each container profile gives you access to a specific list of CPU and RAM combinations.
Using the Upsun Cloud CLI or Console, you can then pick a CPU and RAM combination for each of your apps and services.

There are four container profiles available: `HIGH_CPU`, `BALANCED`, `HIGH_MEMORY`, and `HIGHER_MEMORY`.
The following table displays the different CPU and RAM combinations each container profile provides:

| CPU | `HIGH_CPU` | `BALANCED` | `HIGH_MEMORY` | `HIGHER_MEMORY` |
| - | - | - | - | - |
| 0.1 | 64 MB | 352 MB | 448 MB | 864 MB |
| 0.25 | 128 MB | 640 MB | 832 MB | 1472 MB |
| 0.5 | 224 MB | 1088 MB | 1408 MB | 2368 MB |
| 1 | 384 MB | 1920 MB | 2432 MB | 3840 MB |
| 2 | 704 MB | 2800 MB | 4032 MB | 6336 MB |
| 4 | 1216 MB | 4800 MB | 6720 MB | 10496 MB |
| 6 | 1728 MB | 6080 MB | 9024 MB | 14080 MB |
| 8 | 2240 MB | 7296 MB | 11200 MB | 17408 MB |

You can check which container profile is set for an app or service in your project from the Console.
To do so, navigate to your environment and select the app or service in the tree on the left-hand side:

<img alt="Apps and services tree" />

For information on resource-related costs, see the [Upsun pricing page](https://upsun.com/pricing/).

### Guaranteed CPU container sizes

When selecting a container profile for [Guaranteed CPU](/docs/manage-resources/guaranteed-resources), use the table below to identify available CPU and memory combinations. These predefined sizes help you match resource profiles to your application’s workload requirements.

| CPU | HIGH\_CPU | BALANCED | HIGH\_MEMORY | HIGHER\_MEMORY |
| - | - | - | - | - |
| 2 | 4 GB | 8 GB | 16 GB | not supported |
| 4 | 8 GB | 16 GB | 32 GB | not supported |
| 8 | 16 GB | 32 GB | 64 GB | not supported |
| 16 | 32 GB | 64 GB | 128 GB | not supported |
| 32 | 64 GB | 128 GB | 256 GB | not supported |
| 48 | 96 GB | 192 GB | 384 GB | not supported |
| 64 | 128 GB | 256 GB | 512 GB | not supported |

<Note>
  Guaranteed CPU is not currently available on [OVHcloud regions](/docs/development/regions) and some CPU sizes may not be available in all regions.

  For more information about pricing, visit the Upsun [pricing page](https://upsun.com/pricing/).
</Note>

### Default container profiles

The following table shows the default container profiles Upsun Cloud applies when first deploying your project.

| Container | Default profile |
| - | - |
| [C#/.Net Core](/docs/languages/dotnet) | HIGH\_CPU |
| [ClickHouse](/docs/add-services/clickhouse) | HIGH\_MEMORY |
| [Elasticsearch](/docs/add-services/elasticsearch) | HIGH\_MEMORY |
| [Elixir](/docs/languages/elixir) | HIGH\_CPU |
| [Go](/docs/languages/go) | HIGH\_CPU |
| [Gotenberg](/docs/add-services/gotenberg) | HIGH\_MEMORY |
| [Headless Chrome](/docs/add-services/headless-chrome) | HIGH\_CPU |
| [InfluxDB](/docs/add-services/influxdb) | HIGH\_MEMORY |
| [Java](/docs/languages/java) | HIGH\_MEMORY |
| [JavaScript/Node.js](/docs/languages/nodejs) | HIGH\_CPU |
| [Kafka](/docs/add-services/kafka) | HIGH\_MEMORY |
| [MariaDB/MySQL](/docs/add-services/mysql) | HIGH\_MEMORY |
| [Memcached](/docs/add-services/memcached) | BALANCED |
| [MongoDB](/docs/add-services/mongodb) | HIGH\_MEMORY |
| [Network Storage](/docs/add-services/network-storage) | HIGH\_MEMORY |
| [OpenSearch](/docs/add-services/opensearch) | HIGH\_MEMORY |
| [Oracle MySQL](/docs/add-services/mysql) | HIGH\_MEMORY |
| [PHP](/docs/languages/php) | HIGH\_CPU |
| [PostgreSQL](/docs/add-services/postgresql) | HIGH\_MEMORY |
| [Python](/docs/languages/python) | HIGH\_CPU |
| [RabbitMQ](/docs/add-services/rabbitmq) | HIGH\_MEMORY |
| [Redis](/docs/add-services/redis) | BALANCED |
| [Ruby](/docs/languages/ruby) | HIGH\_CPU |
| [Rust](/docs/languages/rust) | HIGH\_CPU |
| [Solr](/docs/add-services/solr) | HIGH\_MEMORY |
| [Valkey](/docs/add-services/valkey) | BALANCED |
| [Varnish](/docs/add-services/varnish) | HIGH\_MEMORY |
| [Vault KMS](/docs/add-services/vault) | HIGH\_MEMORY |

### Adjust a container profile

In most cases, it's best not to adjust container profiles.
As a best practice, Upsun recommends adjusting the profile of a container **only if the CPU/RAM ratio doesn’t match how the container scales**,
taking into account both production and preview (staging and development) environments.

To adjust a container profile, amend the value of the `container_profile` key in your configuration:


# Autoscaling
Source: https://developer.upsun.com/docs/manage-resources/autoscaling

Learn how autoscaling adjusts application, worker, and service instances based on CPU and memory usage to keep your workloads stable and cost-efficient under varying demand.

Autoscaling automatically adjusts how many instances of your applications, workers, and services are running, increasing capacity when demand rises, and reducing it when deamnd is lower. It helps your workloads stay responsive under heavy load while keeping your infrastructure costs efficient.

## What is autoscaling?

Autoscaling works through [horizontal scaling](/docs/manage-resources/adjust-resources#horizontal-scaling), by adding or removing whole instances of your applications, workers, and database read replicas depending on resource usage. If CPU or [memory](#memory-based-triggers) utilization stays above a certain threshold for a set time, Upsun Cloud automatically adds more instances. If it stays low, Upsun Cloud removes unneeded ones. You control these thresholds and limits, so scaling always happens safely and predictably.

* **Scope:** Available for applications, workers, and selected services ([MariaDB](/docs/add-services/mysql/mysql-readonly-replication) and [PostgreSQL](/docs/add-services/postgresql/postgresql-readonly-replication) read-only replicas)
* **Product tiers:** Available for all Upsun Cloud environments
* **Environments:** Configurable per environment - across development, staging, and production

<Info>
  <h4>Know your app first</h4>
  Autoscaling is quick to set up: you can [enable it in a few clicks](#enable-autoscaling) from your environment's **Configure resources** tab. However, it's important to understand your app's typical performance before turning it on.

  Tools like [Upsun Blackfire](https://www.blackfire.io/) can help you identify where your app consumes CPU or memory, so you can set realistic thresholds that reflect your traffic patterns. Upsun Blackfire can also help you spot whether autoscaling is likely to benefit your app or if a fixed setup with tuned [vertical resources](/docs/manage-resources/adjust-resources#vertical-scaling) like CPU/RAM would serve you better.
</Info>

## When to use autoscaling

Autoscaling makes the most sense for workloads with variable or unpredictable traffic. It's especially valuable when:

* You run time-sensitive or customer-facing applications or APIs where latency matters.
* Your workloads experience seasonal or campaign-driven spikes.
* You want to avoid paying for idle capacity during quieter periods.

### Example: When autoscaling works effectively

A retail application and its database see traffic jump fivefold every Friday evening and during holiday campaigns. By enabling autoscaling, the environment automatically adds instances when CPU usage rises and scales back overnight, ensuring smooth checkouts without wasted cost.

### Example: When autoscaling might not be needed

An internal dashboard with predictable, low usage may not benefit from autoscaling. In this case, a fixed number of instances and tuned vertical resources (CPU/RAM) can be more cost-effective and stable.

<Info>
  <h4>Scale databases and resources</h4>
  To vertically scale CPU, RAM, or disk, or horizontally scale applications and workers (manually), see:

  * [Resource configuration](/docs/manage-resources/adjust-resources)
  * [Resource initialization](/docs/manage-resources/resource-init)
  * [Horizontal scaling (manual)](/docs/manage-resources/adjust-resources#horizontal-scaling)
  * [Vertical scaling](/docs/manage-resources/adjust-resources#vertical-scaling)
</Info>

## Autoscaling availability

The tables below outline where autoscaling and manual scaling are supported, so you can plan your deployments with the right balance of flexibility and control.

### Component support

| Component | Horizontal autoscaling | Manual scaling (Vertical) |
| - | - | - |
| Applications ([PHP](/docs/languages/php), [Node.js](/docs/languages/nodejs), etc.) | Available | Available |
| Services | Available for [services that support autoscaling](#services-that-support-autoscaling) | Available |
| Queues ([workers](/docs/configure-apps/workers), background jobs) | Available (workers only) | Available |

#### Services that support autoscaling

<AutoscalingSupportedServices />

### Product tier support

| Product tier | Horizontal autoscaling | Manual scaling (Vertical) |
| - | - | - |
| Upsun Cloud | Available | Available |
| Upsun Fixed | Unavailable | Available |

### Environment support

| Environment | Horizontal Autoscaling | Manual scaling (Vertical) |
| - | - | - |
| Development | Available | Available |
| Staging | Available | Available |
| Production | Available | Available |

### Scaling trigger support

| Trigger | Console |
| - | - |
| Average CPU (min/max) | Available |
| Average Memory (min/max) | Available |

## How autoscaling works

### Thresholds

Autoscaling monitors the average CPU and [memory usage](#memory-based-triggers) of your running app and worker instances, as well as database read replicas ([MariaDB](/docs/add-services/mysql/mysql-readonly-replication), [PostgreSQL](/docs/add-services/postgresql/postgresql-readonly-replication)).\
You define thresholds that determine when new instances are launched or removed.

There are two different thresholds that your CPU and memory utilization operate within: A scale-up threshold and a scale-down threshold.

* **Scale-up threshold**: If your chosen trigger (e.g. CPU usage) stays **above** this level for the time period you've set (the evaluation period), autoscaling will launch additional instances to share the load.

* **Scale-down threshold**: If your chosen trigger stays **below** this level for the time period you've set, autoscaling will remove unneeded instances to save resources and costs.

To prevent unnecessary back-and-forth, autoscaling also uses a cooldown window: a short waiting period before another scaling action can be triggered. This can also be configured or kept to the [default](#default-settings) waiting period before any additional scaling starts.

<Warning>
  <h4>Combined triggers</h4>
  If both CPU and memory triggers are enabled, either one can initiate scaling. A global cooldown applies after each scaling event, but in rare cases, combined triggers may interact unexpectedly. For example, CPU scaling up followed by memory scaling down. Adjust thresholds and cooldowns carefully to avoid oscillation.
</Warning>

### Default settings

Autoscaling continuously monitors the configured **trigger** across your app's running instances. We will use the **average CPU utilization** trigger as the primary example for the default settings and examples below.

* **Scale-up threshold:** 80% CPU for 5 minutes
* **Scale-down threshold:** 20% CPU for 5 minutes
* **Cooldown window:** 5 minutes between scaling actions
* **Instance limits:** 1 to 8 per environment (region-dependent)

<Info title="Instance limits and counts">
  - **Default instance limits are typically 1 to 8 instances per environment**, but the exact values depend on the region. Some regions may have higher or lower defaults. The scaling settings in your project always reflect the limits for the region where it runs.
  - **When autoscaling is enabled, [manual instance count](/docs/manage-resources/adjust-resources#horizontal-scaling) changes to apps are disabled.** [Vertical resources](/docs/manage-resources/adjust-resources#vertical-scaling) (CPU/RAM/disk per instance) remain configurable.
  - **To understand how an application's instances are distributed**, you can view the instance details in the project's `/run/peers.json` file. To learn more, see [View application instance details](/docs/manage-resources/adjust-resources#view-application-instance-details) in the "Resource configuration" topic.
</Info>

#### Default behaviour (CPU example)

* If CPU stays at **80% or higher for 5 minutes**, autoscaling adds an instance.
* If CPU stays at **20% or lower for 5 minutes**, autoscaling removes an instance.
* After a scaling action, autoscaling waits **5 minutes** before making another change.

This cycle ensures your app automatically scales up during high demand and scales down when demand drops, helping balance performance with cost efficiency.

## Resource-based autoscaling

Autoscaling primarily relies on CPU utilization as its trigger, however you can also configure memory-based autoscaling, which works in a similar way, but with a few important differences to understand.

### CPU-based triggers

CPU-based autoscaling reacts to sustained changes in average CPU utilization.

* Scale-up threshold: When average CPU usage stays above your defined limit for the evaluation period, instances are added to distribute the load.
* Scale-down threshold: When CPU usage remains below your lower limit for the evaluation period, instances are removed to save resources.
* Cooldown window: A delay (default: 5 minutes) before another scaling action can occur.

### Memory-based triggers

Memory-based autoscaling follows the same principle as CPU triggers but measures average memory utilization instead. When your app consistently uses more memory than your upper threshold, Upsun Cloud adds instances; when memory usage remains low, it removes them.

This option is useful for workloads where caching or in-memory data handling determine performance - for example, large data processing apps or services with persistent caching layers.

#### Example

| Condition | Scaling action |
| - | - |
| Memory above 80% for 5 minutes | Scale up: Add one instance |
| Memory below 30% for 5 minutes | Scale down: Remove one instance |

<Warning>
  <h4>Understand your app's memory profile</h4>
  High memory usage doesn't always mean your app needs more instances. Linux systems use available memory for caching and buffering, so 90–100% usage can be normal even under stable conditions. Before using memory-based autoscaling, profile your application's typical memory behavior to avoid unnecessary scaling and extra cost.

  Tools such as [Upsun Blackfire](https://www.blackfire.io/) or system-level metrics in your [Application metrics dashboard](/docs/observability/application-metrics) can help you understand what "normal" looks like for your app.
</Warning>

#### Configure memory triggers

1. Open your project in the Console.
2. Select your target environment.
3. Choose **Configure resources**.
4. Under **Autoscaling**, select **Enable** (if not already enabled).
5. Choose **Memory usage (min/max)** as your scaling trigger.
6. Set scale-up and scale-down thresholds, evaluation period, and cooldown window.
7. Save changes — your app will now automatically scale based on memory utilization.

## Guardrails and evaluation

Autoscaling gives you control over the minimum and maximum number of instances your app/worker can run. These guardrails ensure your app/worker never scales up or down too far. Set boundaries to keep scaling safe, predictable, and cost-efficient:

For example, you might configure:

* **Minimum instances** — Ensures a minimum number of instances of the configured application are always running (e.g. `2`)
* **Maximum instances** — Prevents runaway scaling (e.g. `8`)
* **Evaluation period** — Time CPU must stay above or below a threshold before action (1–60 minutes)
* **Cooldown window** — Wait time before any subsequent scaling action (default: 5 minutes)

<Info>
  <h4>Manual instance scaling</h4>
  When autoscaling is enabled, manual instance scaling is disabled. Autoscaling manages instance counts within the min/max guardrails you define.
  To understand how an application's instances are distributed, you can view the instance details in the project's `/run/peers.json` file. To learn more, see [View application instance details](/docs/manage-resources/adjust-resources#view-application-instance-details) in the "Resource configuration" topic.
</Info>

## Enable Autoscaling

To enable autoscaling, follow the steps below:

1. Open your project in the Console
2. Select the environment where you want to enable autoscaling
3. Choose **Configure resources**

<img alt="Navigate to Configure resources in Console" />

4. Under the autoscaling column select **Enable**
5. Configure thresholds, evaluation period, cooldown, and instances as needed

<img alt="Configure autoscaling in Console" />

## Alerts and metrics

When autoscaling is enabled, the system continuously monitors metrics such as CPU usage, instance count, and request latency. If a defined threshold is crossed, an alert is triggered and the platform automatically responds by adjusting resources.

Scaling activity is visible in several places:

* **Metrics dashboards** show when scaling has occurred
* Alerts and scaling actions are also visible in the Console:
  * **Alerts** appear with a bell icon (for example - *Scaling: CPU for application below 70% for 5 minutes*)
  * **Scaling actions** appear with a resources icon (for example, *Upscale: 1 instance added to application*)
* Alerts and scaling actions are also listed in the CLI as `environment.alert` and `environment.resources.update`
* To review detailed scaling events, open the **Resources** dashboard by navigating to **\{Select project} > \{Select environment} > Resources**

### Configure alerts

You can also [configure notifications for alerts](/docs/administration/billing/bp-monitor-billing#set-a-billing-alert).

For example, by setting up an activity script on `environment.alert`, you can automatically send yourself an email, a Slack message, or another type of custom notification.

<Info>
  <h4>Metric resources</h4>
  If you're looking to keep track of your infrastructure and application metrics see:

  * [Infrastructure metrics](/docs/observability/metrics)
  * [Application metrics](/docs/observability/application-metrics)
</Info>

## Billing and cost impact

Autoscaling projects are billed for the resources that they consume. Instances added through autoscaling are billed the same as if you were to manually configure those resources.

Added instances are deployed automatically without downtime.

To control costs, avoid overly aggressive settings (e.g. very short evaluation periods).

<Info>
  <h4>Metric resources</h4>
  If you're looking to keep track of your billing, refer to these topics:

  * [Monitor billing](/docs/administration/billing/bp-monitor-billing)
  * [Pricing overview](https://www.upsun.com/pricing/)
</Info>

## Best practices for autoscaling

Autoscaling gives you flexibility and resilience, but to get the best results it's important to configure your app and thresholds thoughtfully. Below are some best practices to help you balance performance, stability, and cost.

### Cost and stability

* **Set thresholds wisely**: Configure realistic scale-up and scale-down thresholds to avoid unnecessary deployments.
* **Smooth spikes**: Use longer evaluation periods (10–15 minutes) if your app traffic spikes often, to prevent rapid up-and-down scaling.
* **Control instance counts**: Define minimum and maximum instances to manage costs while keeping required availability.
* **Monitor costs**: Track billing and usage after enabling autoscaling, then adjust thresholds as needed.

### Application design

* **External services**: Use external [services](/docs/add-services/) such as databases and caches instead of embedding them within the autoscaled applications. Note that database read replicas like [MariaDB](/docs/add-services/mysql/mysql-readonly-replication) and [PostgreSQL](/docs/add-services/postgresql/postgresql-readonly-replication) **can be** autoscaled.
* **Keep containers portable**: Follow Upsun Cloud recommendations for [caching](/docs/routes/cache) and mounts for [composable images](/docs/configure-apps/image-properties/mounts) and [single-runtime images](/docs/configure-apps/image-properties/mounts).

### Cron jobs and long-running tasks

* **CPU spikes from jobs**: Cron jobs can increase CPU usage and may trigger scale-ups so factor this into your threshold settings.
* **Job continuity**: Cron jobs remain bound to their starting container and are **not** interrupted by scaling, so plan instances accordingly.

<Tip>
  <h4>Supported services and actions</h4>

  Scaling down to zero instances is **not supported**. Use minimum instance counts to define your baseline availability.
</Tip>

## Related documentation

##### Resources and scaling

* [Resource configuration](/docs/manage-resources/adjust-resources)
* [Resource initialization](/docs/manage-resources/resource-init)
* [Horizontal scaling](/docs/manage-resources/adjust-resources#horizontal-scaling)

##### Metrics

* [Infrastructure metrics](/docs/observability/metrics)
* [Application metrics](/docs/observability/application-metrics)

##### Image reference

* [Composable image](/docs/configure-apps/app-reference/composable-image)
* [Single-runtime image](/docs/configure-apps/app-reference/single-runtime-image)

##### Billing and payment

* [Monitor billing](/docs/administration/billing/bp-monitor-billing)
* [Pricing overview](https://www.upsun.com/pricing/)


# Project build resources
Source: https://developer.upsun.com/docs/manage-resources/build-resources

Configure project build resources on Upsun Cloud.

When you push changes through Git, your applications are first built, then deployed.

During the build process, Upsun Cloud creates a build image for each of your application, as a dedicated build container, and runs your build hooks inside that build container.
The duration of the build process is directly linked to the amount of resources (CPU and RAM) allocated to that build container.

Every Upsun Cloud project includes a fixed amount of build resources per month:

* 2.5 hours of build CPU
* 5 hours of build memory

You can adjust the amount of build resources that a project can use.

<Tabs>
  <Tab title="Using the Console">
    1. Navigate to your project.
    2. Access the **project settings**.
    3. Expand the Project Setting accordion and click **Resources**.
    4. Enter the amount of CPU and RAM that your build containers can use.
    5. Click **Save**.
  </Tab>

  <Tab title="Using the CLI">
    1. Run the following command:

       ```bash theme={null}
       upsun resources:build:set
       ```
    2. Enter the amount of CPU.
    3. Enter the amount of RAM.
  </Tab>
</Tabs>

Additional build resources (CPU and RAM) are billed by the hour.
For more information on the costs incurred, see the [Upsun pricing page](https://upsun.com/pricing/).

<Note>
  Make sure that your build process supports using extra build resources.
  Otherwise, the duration of your builds will remain the same despite adding more resources.
</Note>


# Configure resources
Source: https://developer.upsun.com/docs/manage-resources/configure

Learn how to initialize, adjust, and manage build resources for your project.

<CardGroup>
  <Card title="Resource initialization" icon="play" href="/docs/manage-resources/resource-init">
    Learn how resources are allocated by default upon first deployment.
  </Card>

  <Card title="Resource configuration" icon="sliders-horizontal" href="/docs/manage-resources/adjust-resources">
    Configure CPU, RAM, and disk storage on a per-environment basis.
  </Card>

  <Card title="Build resources" icon="hammer" href="/docs/manage-resources/build-resources">
    Configure project build resources on Upsun Cloud.
  </Card>
</CardGroup>


# Guaranteed resources
Source: https://developer.upsun.com/docs/manage-resources/guaranteed-resources

Learn how Guaranteed CPU on Upsun Cloud provide dedicated CPU and memory allocations for consistent, high-performance workloads.

<Info>
  <h4>Need this feature enabled?</h4>
  If this feature is not enabled for your project and you need it, [open a support ticket](/docs/core-concepts/get-support) to request activation.
</Info>

For applications or services that need to scale to large resources and have performance guarantees, Upsun Cloud offers Guaranteed resources (Guaranteed CPU).

Guaranteed CPU ensure that your app or service receives dedicated access to the specified amount of CPU and RAM. These resources are reserved exclusively for your container.

This kind of allocation provides performance close to dedicated infrastructure, ideal for:

* Backend services
* Real-time APIs
* Load testing
* High-traffic production application containers
* Resource-intensive services (e.g. database, search engine)
* Any container requiring large resource allocations with consistent and predictable performance

<Warning>
  <h4>Region availability</h4>
  Guaranteed CPU is **not supported on OVHcloud regions**, and some sizes **may not be available for [all regions](/docs/development/regions).**
</Warning>

## Enable Guaranteed CPU

1. Open your project.
2. Click the Configure resources button from the Allocated resources block.
3. For each app/service:
   * Select **Guaranteed** or **Shared** as the resource type.
   * Choose the desired CPU and RAM combination.
   * Enter the amount of Disk/Storage to allocate.
4. Click Save. Saving will rebuild your environment, which may cause temporary downtime.

<Note>
  You cannot enable Guaranteed CPU if your [container profile is set to `HIGHER_MEMORY`](/docs/manage-resources/adjust-resources#advanced-container-profiles).
</Note>

## Pause environments with Guaranteed CPU

When any app or service in an environment uses Guaranteed CPU, that environment cannot be paused automatically or manually.

This is because, with Guaranteed CPU, you're billed for the reserved CPU and memory, so allowing pause functionality would lead to potential overuse of reserved compute and incorrect billing.

### To pause the environment again:

1. Switch all containers using Guaranteed CPU back to shared mode.
2. Once no containers are using Guaranteed CPU, the environment can be paused as usual.

<Note>
  You can upscale to Guaranteed CPU even if the environment is currently paused. Doing so will automatically resume the environment and apply the changes.
</Note>

## Guaranteed CPU container sizes

The following table lists the available CPU and memory configurations for [containers](/docs/manage-resources/adjust-resources#advanced-container-profiles) using Guaranteed CPU. These container profiles (`HIGH_CPU`, `BALANCED`, `HIGH_MEMORY`, and `HIGHER_MEMORY`) ensure consistent performance by allocating dedicated compute resources to your services.

| CPU | HIGH\_CPU | BALANCED | HIGH\_MEMORY | HIGHER\_MEMORY |
| - | - | - | - | - |
| 2 | 4 GB | 8 GB | 16 GB | not supported |
| 4 | 8 GB | 16 GB | 32 GB | not supported |
| 8 | 16 GB | 32 GB | 64 GB | not supported |
| 16 | 32 GB | 64 GB | 128 GB | not supported |
| 32 | 64 GB | 128 GB | 256 GB | not supported |
| 48 | 96 GB | 192 GB | 384 GB | not supported |
| 64 | 128 GB | 256 GB | 512 GB | not supported |

<Note>
  Guaranteed CPU is not currently available on [OVHcloud regions](/docs/development/regions) and some CPU sizes may not be available in all regions.

  For more information about pricing, visit the Upsun [pricing page](https://upsun.com/pricing/).
</Note>


# How resources work on Upsun Cloud
Source: https://developer.upsun.com/docs/manage-resources/how-resources-work

Understand how resources work on Upsun Cloud. Learn the differences between shared and guaranteed CPU, how RAM is allocated, and how to configure scalable resources for your apps.

On **Upsun Cloud**, you have granular control over your application's resources. Instead of choosing from pre-defined plans, you can configure resources (CPU, RAM, and disk) per environment for each of your apps and services. You can also add instances for each of your apps depending on your needs.

Understanding how Upsun Cloud allocates these resources is key to building stable and cost-effective architecture for your project.

For information on costs related to resource usage, see the [Upsun pricing page](https://upsun.com/pricing/).

## CPUs vs. vCPUs

Throughout our product and documentation, when we refer to **CPU**, we are describing **vCPUs (virtual CPUs)**. A vCPU is a virtual representation of a physical CPU core. This is the standard for cloud computing, as it allows a physical server's resources to be securely divided among multiple applications.

vCPU performance can sometimes vary depending on factors such as:

* Cloud provider and [region](/docs/development/regions)
* System load from other containers on a shared host (in shared mode)

## CPU: Shared vs. Guaranteed

CPU resources can be allocated in two distinct ways. This choice allows you to precisely balance cost with performance needs for each individual container in your project.

### Shared CPU (Default)

By default, projects on Upsun Cloud run on a **shared infrastructure**.

Our shared infrastructure is designed to provide CPU performance that typically aligns with the resources you've purchased. However, because this environment is shared among multiple tenants, performance can occasionally vary for [many reasons](/docs/manage-resources/resource-init#default-resources) - for example, other workloads on the same physical host temporarily consuming more system resources.

In most cases, this variability is short-lived and performance returns to normal levels without intervention. We continuously monitor performance at the regional level to detect and mitigate systemic issues, by constantly balancing containers to hosts that are less busy.

However, if you experience prolonged or recurring performance issues that may be caused by noisy neighbors, please open a support ticket so our team can investigate directly.

If you require fully consistent and isolated performance, we recommend using our [Guaranteed Resources](/docs/manage-resources/guaranteed-resources) offering, which provides [dedicated CPU allocations](#guaranteed-cpu) and eliminates variability from shared usage.

<Info>
  Projects are always kept **strictly isolated** from each other. This behaviour applies to both [Upsun Fixed and Upsun Cloud](/docs/administration/organizations#upsun-fixed-and-upsun-cloud-organizations) projects.
</Info>

**Best for:**

* Containers in development/staging environments
* Production containers with low-to-moderate traffic

**Consideration:**

* Performance can be variable due to the "noisy neighbour" effect inherent in shared infrastructure.

### Guaranteed CPU

With [Guaranteed CPU](/docs/manage-resources/guaranteed-resources), your container is placed on a dedicated host, and the host's CPU resources are reserved exclusively for your container's use. This provides the highest level of CPU performance and predictability by eliminating any "noisy neighbour" effect.

**Best for:**

* High-traffic production application containers
* Resource-intensive services (e.g. database, search engine)
* Any container requiring large resource allocations with consistent and predictable performance

**Consideration:**

* This option has a higher cost due to its dedicated nature.
* A small portion of host CPU and RAM is used by Upsun Cloud’s system services. The available capacity will be slightly lower than the full allocation selected.

## Memory (RAM)

The memory (RAM) you configure for a container is **always guaranteed**.

This means the full amount of RAM you define is exclusively available to that container and is never shared. This guarantees predictable memory performance and prevents issues caused by other applications on the same host, regardless of your chosen CPU type.


# Manage resources
Source: https://developer.upsun.com/docs/manage-resources/index

Configure resources per environment for each of your apps and services.

<CardGroup>
  <Card title="How resources work" icon="info" href="/docs/manage-resources/how-resources-work">
    Understand CPU, RAM, and disk allocation on Upsun Cloud.
  </Card>

  <Card title="Configure resources" icon="sliders-horizontal" href="/docs/manage-resources/configure">
    Initialize, adjust, and manage build resources for your project.
  </Card>

  <Card title="Scaling" icon="scaling" href="/docs/manage-resources/scaling">
    Scale your applications automatically or with guaranteed resource allocations.
  </Card>

  <Card title="Object storage" icon="layers" href="/docs/manage-resources/object-storage">
    Add an S3-compatible object-storage to your project and configure it.
  </Card>
</CardGroup>


# Object storage
Source: https://developer.upsun.com/docs/manage-resources/object-storage

Add an S3-compatible object storage bucket to your Upsun Cloud project, configure its size, and connect your app through the S3 API.

<Note>
  Object storage is not available on projects that are part of an Upsun Cloud [trial](/docs/glossary#trial).
</Note>

Object storage is an S3-compatible bucket attached to your application, provisioned and connected automatically once you set a size on the app's resources.

Object storage is integrated with the rest of the Upsun Cloud platform:

* When you [back up an environment](/docs/environments/backup), the bucket's contents are included.
* When you [branch an environment](/docs/environments), the bucket and its allocated size are cloned along with the environment's other data.

## When to use object storage

Use object storage when your app needs to store large or growing volumes of unstructured data (uploads, media, backups, generated artifacts) and you want to reach it through the S3 API.

For small amounts of file data that a single instance reads and writes through the filesystem, a persistent [mount](/docs/configure-apps/image-properties/mounts) is usually a better fit.

## Set the object-storage size

<Tabs>
  <Tab title="CLI">
    **Set**

    ```bash Terminal theme={null}
    upsun resources:set --object-storage myapp:524288
    ```

    The same `resources:set --object-storage <APP_NAME>:<SIZE_IN_MB>` command (size in MB) enables object storage if the app doesn't have any yet, or resizes it if it does. Any value must be a multiple of the [step size](#object-storage-sizing-rules); this example uses the minimum allocation, 512 GB.

    ***

    **View**

    ```bash Terminal theme={null}
    upsun resources:get
    ```

    When an app has object storage, the output includes an **Object storage (MB)** column.

    ***

    **Remove**

    <Warning>
      Setting the storage size to `0`, or removing the app, deletes the bucket and all of its contents on the next deployment. There's no soft-delete or retention period. Back up any data you need before removing.
    </Warning>

    Set the bucket size to `0`:

    ```bash Terminal theme={null}
    upsun resources:set --object-storage myapp:0
    ```
  </Tab>

  <Tab title="Console">
    1. Navigate to the project, and in the **Allocated resources** pane, click **Configure resources**.
    2. On the **Configure resources** page:
       * To enable object storage, toggle **Enable object storage** on.
       * To resize object storage, confirm that it's enabled, and in the app's row, select a [size](#object-storage-sizing-rules) from the **Object storage** menu.
       * To remove object storage, toggle **Enable object storage** off.

         <Warning>
           Removing object storage **permanently deletes** the bucket and all of its contents on the next deployment (which occurs when you click **Save**). There's no soft-delete or retention period. Back up any data you need before disabling object storage.
         </Warning>
    3. Save your changes.
  </Tab>
</Tabs>

### Object storage sizing rules

Object storage is allocated in fixed steps, within a minimum and a maximum. The size you request must be a multiple of the step and fall within these bounds:

| Rule | Value |
| - | - |
| Step | 524288 MB (512 GB) |
| Minimum | 524288 MB (512 GB) |
| Maximum | 10485760 MB (10 TB) |

### Storage pricing

Object storage requires a minimum allocation of 512 GB and is billed on allocated capacity (the storage size that you specify, not the amount of data actually stored), prorated hourly.

Backup storage is billed separately as its own line item, also based on allocated capacity.

For pricing information, see the Upsun [pricing page](https://upsun.com/pricing/).

## Relationship reference

Enabling object storage adds a relationship named `object-storage` to your app. This relationship name is reserved. If your configuration already declares a relationship called `object-storage`, the deployment fails and you must rename the relationship to proceed.

The relationship provides the connection details for an S3-compatible endpoint. Upsun Cloud automatically generates [service environment variables](/docs/development/variables#service-environment-variables) for it within your application container, in the `$<RELATIONSHIP-NAME>_<SERVICE-PROPERTY>` format.

The prefix follows the relationship name, so a container that reaches the bucket through a relationship named `bucket`, as in [Share a bucket across containers](#share-a-bucket-across-containers), gets `BUCKET_ACCESS_KEY` rather than `OBJECT_STORAGE_ACCESS_KEY`.

Here is example information available through the service environment variables themselves, or through the [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables).

<Tabs>
  <Tab title="Service environment variables">
    You can obtain the complete list of available service environment variables in your app container by running `upsun ssh env`.

    Note that the information about the relationship can change when an app is redeployed or restarted. So your apps should only rely on the service environment variables directly rather than hard coding any values.
  </Tab>

  <Tab title="`PLATFORM_RELATIONSHIPS` environment variable">
    For some advanced use cases, you can use the [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables).
    The structure of the `PLATFORM_RELATIONSHIPS` environment variable can be obtained by running `upsun relationships` in your terminal:

    Here is an example of how to gather that information in a [`.environment` file](/docs/development/variables/set-variables#when-to-use-env-files):

    ```bash .environment theme={null}
    # Decode the built-in credentials object variable.
    export RELATIONSHIPS_JSON="$(echo "$PLATFORM_RELATIONSHIPS" | base64 --decode)"

    # Set environment variables for individual credentials.
    export AWS_ACCESS_KEY_ID="$(echo "$RELATIONSHIPS_JSON" | jq -r '.["object-storage"][0].access_key')"
    export AWS_SECRET_ACCESS_KEY="$(echo "$RELATIONSHIPS_JSON" | jq -r '.["object-storage"][0].secret_key')"
    export AWS_DEFAULT_REGION="$(echo "$RELATIONSHIPS_JSON" | jq -r '.["object-storage"][0].region')"

    # Some SDKs read AWS_REGION instead of AWS_DEFAULT_REGION.
    export AWS_REGION="$AWS_DEFAULT_REGION"

    # Read the bucket name rather than assuming it.
    export S3_BUCKET="$(echo "$RELATIONSHIPS_JSON" | jq -r '.["object-storage"][0].buckets | keys[0]')"
    ```

    The `object-storage` key has to match the relationship name. A container that reaches the bucket through a relationship named `bucket` uses `.["bucket"][0]` instead. A key that matches no relationship exports the literal string `null` rather than failing, so requests are signed with invalid credentials.
  </Tab>
</Tabs>

## Connect from your app

The endpoint URL is `http://<HOST>:<PORT>`, built from the `host` and `port` values in the [relationship](#relationship-reference). The endpoint is reachable over your project's internal network only and isn't exposed publicly.

A single bucket is created per app, named after the app, and the relationship lists it in `buckets`, an object keyed by bucket name. So an app named `myapp` reaches its bucket at `http://<HOST>:<PORT>/myapp/<KEY>`. Take the name from the `buckets` keys rather than assuming it, so the same code keeps working in a container that reaches another app's bucket through a [shared relationship](#share-a-bucket-across-containers).

When configuring your S3 client, note two requirements:

* **Use path-style addressing.** The bucket name goes in the URL path (`http://<HOST>:<PORT>/myapp/object.txt`), not the hostname. Disable virtual-hosted-style addressing.
* **Use the credentials from the relationship.** The endpoint authenticates every request, so configure your client with the `access_key`, `secret_key`, and `region` values from the [relationship](#relationship-reference). Empty or arbitrary credentials are rejected.

### Example (Python, boto3)

```python theme={null}
import base64
import json
import os

import boto3

relationships = json.loads(base64.b64decode(os.environ["PLATFORM_RELATIONSHIPS"]))
endpoint = relationships["object-storage"][0]

s3 = boto3.client(
    "s3",
    endpoint_url=f"http://{endpoint['host']}:{endpoint['port']}",
    aws_access_key_id=endpoint["access_key"],
    aws_secret_access_key=endpoint["secret_key"],
    region_name=endpoint["region"],
    config=boto3.session.Config(s3={"addressing_style": "path"}),
)

bucket = list(endpoint["buckets"].keys())[0]

s3.put_object(Bucket=bucket, Key="hello.txt", Body=b"Hello, World!")
```

## Share a bucket across containers

Other containers can use an app's bucket through a relationship:

* A **worker** that doesn't declare its own `relationships` block inherits the parent app's relationships, including `object-storage`, with no extra configuration.
* A **worker** with its own `relationships` block, another application, or a task can reach an application's bucket by targeting that app's `object-storage` endpoint:

```yaml .upsun/config.yaml theme={null}
applications:
  myapp:
    # ...
    workers:
      queue:
        relationships:
          bucket: 'myapp:object-storage'
```

The relationship name on the left (`bucket` here) is yours to choose. Targeting an app that doesn't have object storage configured fails the deployment.

## Limitations

* Each app gets a single bucket, named after the app. Multiple buckets per app aren't supported.
* A bucket belongs to one app. Other containers can share it through a relationship, but buckets can't be reassigned between apps.
* The endpoint is internal to the project and isn't exposed publicly.
* The following S3 features aren't implemented: bucket versioning, object locking, server-side encryption (SSE), access control lists (ACLs), bucket policies, and lifecycle policies. Requests for them return a "not implemented" error.
* Concurrent writes to the same object are last-write-wins with no object locking.

## Inspect the bucket from an SSH session

You can explore your bucket directly from a running container using the AWS CLI.

### Run S3 commands

The endpoint authenticates every request, so pass the credentials from the relationship. Inside the container they're available as [service environment variables](#relationship-reference), along with the host and port.

Pointed at a custom endpoint with `--endpoint-url`, the AWS CLI uses [path-style addressing](#connect-from-your-app) on its own, so no extra configuration is needed.

```bash Terminal theme={null}
AWS_ACCESS_KEY_ID="$OBJECT_STORAGE_ACCESS_KEY" \
AWS_SECRET_ACCESS_KEY="$OBJECT_STORAGE_SECRET_KEY" \
AWS_DEFAULT_REGION="$OBJECT_STORAGE_REGION" \
aws s3 --endpoint-url "http://$OBJECT_STORAGE_HOST:$OBJECT_STORAGE_PORT" ls s3://<APP_NAME>/
```

Other standard S3 commands work the same way, with the same credentials and `--endpoint-url` flag:

| Goal | Command |
| - | - |
| List objects | `ls s3://<APP_NAME>/` |
| Download a file | `cp s3://<APP_NAME>/path/to/file ./local-file` |
| Upload a file | `cp ./local-file s3://<APP_NAME>/path/to/file` |
| Sync a directory | `sync ./local-dir s3://<APP_NAME>/prefix/` |
| Delete an object | `rm s3://<APP_NAME>/path/to/file` |


# Resource initialization
Source: https://developer.upsun.com/docs/manage-resources/resource-init

Learn how resources are allocated by default upon first deployment, and how you can define a resource initialization strategy that better fits your needs.

Resources (CPU, RAM, disk) are allocated per container. Each app and service in your project runs as a separate container within an environment.

<Warning>
  This page describes resource initialization on Upsun projects. On Upsun Fixed projects, resources are automatically distributed across your containers, and you cannot configure per-container resources manually. For details, see [container sizes](https://docs.upsun.com/anchors/fixed/app/reference/sizes/) in the Upsun Fixed documentation.
</Warning>

By default, when you first deploy your project or add a new container to it,
Upsun Cloud uses the `parent` [resource initialization strategy](#specify-a-resource-initialization-strategy),
which copies resource allocations from the parent environment.
If no parent environment exists, Upsun Cloud falls back to [preset resource amounts](#default-resources) instead.

You can also specify a different strategy when [branching](#environment-branch), [merging](#environment-merge),
[activating](#environment-activation), or [restoring a backup](#backup-restoration).

The strategy applied by default depends on how the environment is created:

* For standard branching and activation, the default strategy depends on the environment type.
* For environments created through a source integration, the strategy configured on the integration applies instead.

## Default resources

Upsun Cloud allocates the following default resources to every container when deployed for the first time:

| Resource type | Default amount |
| - | - |
| CPU | 0.5 |
| RAM | Depends on the [container profile](/docs/manage-resources/adjust-resources#shared-cpu-container-sizes) assigned to each [container type](https://developer.upsun.com/docs/manage-resources/adjust-resources#default-container-profiles) (for example, PHP uses `HIGH_CPU`). |
| Disk size\* | 512 MB |

\* Only applicable if the app or service requires a disk (for example, databases such as MariaDB or PostgreSQL).

To allocate different resources, specify a [resource initialization strategy](#specify-a-resource-initialization-strategy), or [adjust resources](/docs/manage-resources/adjust-resources) after deployment.

<Warning>
  Changing resource allocation directly affects your costs. Review the [Upsun pricing page](https://upsun.com/pricing/) before increasing resources. You can [monitor your current costs](/docs/administration/billing/bp-monitor-billing) in the Console.
</Warning>

## Specify a resource initialization strategy

Upsun Cloud provides the following resource initialization strategies:

| Strategy | Description |
| - | - |
| `default` | Uses the parent environment's resource allocation for new containers. If no parent environment exists, allocates [default resources](#default-resources) instead. |
| `manual` | Skips automatic allocation. The first deployment fails until you configure resources manually through [the Console](https://console.upsun.com/) or `resources:set` in the CLI.<br /><br /> This strategy lets you set the exact resources you want with a single deployment. Other strategies may require fine-tuning after the first deployment, which generates a second deployment. During that window, your environment runs briefly with unnecessary resources, and both deployments cause downtime. |
| `minimum` | Uses the Upsun Cloud [minimum resources](#minimum-resources) for new containers. |
| `parent` | Uses the parent environment's resource allocation for new containers. If no parent environment exists, or if the container does not exist on the parent environment, falls back to allocating [default resources](#default-resources). |
| `child` | Uses the child environment's resource allocation for new containers. Used only when merging a child environment into its parent. |
| `backup` | When restoring a backup, initializes new containers using the same resource allocation as when the backup was taken. |

<Accordion title="Minimum resource amounts per container type">
  The following table shows the resources Upsun Cloud allocates to your containers when you opt for the `minimum` [resource initialization strategy](#specify-a-resource-initialization-strategy).

  | Container | CPU | RAM | Disk\* |
  | - | - | - | - |
  | .NET core | 0.1 | 64 MB | 0 MB |
  | Chrome Headless | 0.1 | 64 MB | None |
  | Elasticsearch | 0.1 | 448 MB | 256 MB |
  | Elasticsearch Premium | 0.1 | 448 MB | 256 MB |
  | Elixir | 0.1 | 64 MB | 0 MB |
  | Go | 0.1 | 64 MB | 0 MB |
  | InfluxDB | 0.1 | 448 MB | 256 MB |
  | Java | 0.1 | 448 MB | 0 MB |
  | Kafka | 0.1 | 448 MB | 512 MB |
  | MariaDB | 0.1 | 448 MB | 256 MB |
  | Memcached | 0.1 | 352 MB | None |
  | MongoDB | 0.1 | 448 MB | 256 MB |
  | MongoDB Premium | 0.1 | 448 MB | 256 MB |
  | Network Storage | 0.1 | 448 MB | 256 MB |
  | Node.js | 0.1 | 64 MB | 0 MB |
  | OpenSearch | 0.1 | 448 MB | 256 MB |
  | Oracle MySQL | 0.1 | 448 MB | 256 MB |
  | PHP | 0.1 | 64 MB | 0 MB |
  | PostgreSQL | 0.1 | 448 MB | 256 MB |
  | Python | 0.1 | 64 MB | 0 MB |
  | RabbitMQ | 0.1 | 448 MB | 256 MB |
  | Redis ephemeral | 0.1 | 352 MB | None |
  | Redis persistent | 0.1 | 352 MB | 256 MB |
  | Ruby | 0.1 | 64 MB | 0 MB |
  | Rust | 0.1 | 64 MB | 0 MB |
  | Solr | 0.1 | 448 MB | 256 MB |
  | Varnish | 0.1 | 448 MB | None |
  | Vault KMS | 0.1 | 448 MB | 256 MB |

  \* The disk size is set to `None` when the container never uses disk, and to `0 MB` when the container doesn't require disk but *can* use it.
</Accordion>

You can specify a resource initialization strategy when performing the following actions:

| Action | Available strategies | Default |
| - | - | - |
| [First deployment](#first-deployment) | `parent`, `default`, `minimum`, `manual` | `parent` |
| [Environment branch](#environment-branch) | `parent`, `default`, `minimum` | `default` (staging) / `minimum` (development), unless a source integration uses its configured strategy |
| [Environment merge](#environment-merge) | `child`, `default`, `minimum`, `manual` | `child` |
| [Environment activation](#environment-activation) | `parent`, `default`, `minimum` | `default` (staging) / `minimum` (development) |
| [Backup restoration](#backup-restoration) | `backup`, `parent`, `default`, `minimum` | `backup` |

### First deployment

<Info>
  <h4>Resource initialization strategies</h4>
  Available: `parent`, `default`, `minimum`, `manual` <br />
  Default: `parent`
</Info>

You can define [which resource initialization strategy](#specify-a-resource-initialization-strategy) Upsun Cloud uses to allocate resources
when you first deploy your project or add a new container.

<Tabs>
  <Tab title="Without a source integration">
    If you're not using a [source integration](/docs/integrations),
    you can use a [Git push option](/docs/environments#push-options) to specify a resource initialization strategy.
    To do so, run the following command:

    ```bash Terminal theme={null}
    upsun push --resources-init=<INITIALIZATION_STRATEGY>
    ```

    For example, to use the `minimum` strategy for your deployment, run the following command:

    ```bash Terminal theme={null}
    upsun push --resources-init=minimum
    ```

    <Note>
      Alternatively, you can use the official Git syntax for [push options](/docs/environments#push-options):

      ```bash Terminal theme={null}
      git push upsun -o resources.init=minimum
      ```
    </Note>

    You can specify a different resource initialization strategy for each deployment.
  </Tab>

  <Tab title="With a source integration">
    If you're using a [source integration](/docs/integrations), you can specify a resource initialization strategy for that integration.

    <Note>
      After a resource initialization strategy is specified for a source integration, it applies to environments created through that integration until you change it.

      This behavior can differ from the environment-type defaults described for standard branching, which may result in larger resources being allocated than expected.
    </Note>

    #### When creating a new source integration

    To specify a resource initialization strategy when [creating your source integration](/docs/integrations/source),
    include the `--resources-init` flag in your source integration options.<br />
    For example, if you [set up a GitHub integration](/docs/integrations/source/github), use the following options:

    ```bash Terminal theme={null}
    upsun integration:add \
      --project <PROJECT_ID> \
      --type github \
      --repository <OWNER/REPOSITORY> \
      --token <GITHUB_ACCESS_TOKEN> \
      --base-url <GITHUB_URL> \
      --resources-init <INITIALIZATION_STRATEGY>
    ```

    #### Update an existing source integration

    To specify a resource initialization strategy for an existing source integration,
    run the following command:

    ```bash Terminal theme={null}
    upsun integration:update --resources-init=<INITIALIZATION_STRATEGY>
    ```

    For example, to use the `minimum` strategy for environments created through the integration, run the following command:

    ```bash Terminal theme={null}
    upsun integration:update --resources-init=minimum
    ```
  </Tab>
</Tabs>

### Environment branch

<Info>
  <h4>Resource initialization strategies</h4>
  Available: `parent`, `default`, `minimum` <br />
  Default: `default` (staging) / `minimum` (development)

  When using a [source integration](/docs/integrations/source), defaults are per environment type:

  * `default` for production and staging environments
  * `minimum` for development environments

  `parent` is not available for production environments in source integrations.
</Info>

| Environment type | Default strategy | Resources allocated |
| - | - | - |
| Staging | `default` | [default resource amounts](#default-resources) |
| Development | `minimum` | [minimum resources](#minimum-resources) |

<Note>
  To override these defaults, use the CLI (development environments only) or the API (all environment types). See the **With a source integration** tab below.
</Note>

Use the methods below to specify a different [resource initialization strategy](#specify-a-resource-initialization-strategy).

<Note>
  Regardless of strategy or integration, Upsun Cloud applies the parent's disk size to the child environment if the child's disk size is smaller. This ensures the branch can be created.
</Note>

<Tabs>
  <Tab title="Without a source integration">
    Run the following command:

    ```bash Terminal theme={null}
    upsun environment:branch --resources-init=<INITIALIZATION_STRATEGY>
    ```

    For example, to inherit resources from the parent environment, run the following command:

    ```bash Terminal theme={null}
    upsun environment:branch --resources-init=parent
    ```
  </Tab>

  <Tab title="In the Console (without source integration)">
    1. Navigate to the environment you want to branch from.
    2. Click <BranchIcon /> **Branch**.
    3. Enter a name and a type for the new environment.
    4. Select an initialization strategy from the proposed list.
    5. Click **Branch**.
  </Tab>

  <Tab title="With a source integration">
    When you push a new branch to your repository, your [source integration](/docs/integrations/source) creates an environment using the resource initialization strategy configured on the integration.

    To override these defaults:

    #### Using the CLI (development environments only)

    Run the following command to update your integration's resource initialization strategy:

    ```bash Terminal theme={null}
    upsun integration:update --resources-init=<INITIALIZATION_STRATEGY>
    ```

    For example, to use the `parent` strategy:

    ```bash Terminal theme={null}
    upsun integration:update --resources-init=parent
    ```

    <Note>
      When using the CLI, the value applies to **development** environments only. Production and staging environments always use the `default` strategy.
    </Note>

    #### Using the API (full per-type control)

    To set the resource initialization strategy independently for each environment type, use the API:

    ```bash Terminal theme={null}
    curl -X PATCH https://api.upsun.com/projects/<PROJECT_ID>/integrations/<INTEGRATION_ID> \
      -H "Authorization: Bearer <API_TOKEN>" \
      -H "Content-Type: application/json" \
      -d '{
        "environment_init_resources": {
          "production": "<STRATEGY>",
          "staging": "<STRATEGY>",
          "development": "<STRATEGY>"
        }
      }'
    ```

    Valid strategies: `minimum`, `default`, `manual`, `parent` (however, `parent` is not available for production environments).

    See [available resource initialization strategies](#specify-a-resource-initialization-strategy) for details.
  </Tab>
</Tabs>

### Environment merge

<Info>
  <h4>Resource initialization strategies</h4>
  Available: `child`, `default`, `minimum`, `manual` <br />
  Default: `child`
</Info>

When you [merge](/docs/glossary#merge) a child environment into its parent, any apps and services that exist on the child but not on the parent are created on the parent environment.

These new apps and services are granted resources according to the selected strategy. However, you can specify a different resource initialization strategy.

<Note>
  Apps and services already running on the parent environment keep their existing resources.
</Note>

<Tabs>
  <Tab title="Using the CLI">
    Run the following command:

    ```bash Terminal theme={null}
    upsun environment:merge --resources-init=<INITIALIZATION_STRATEGY>
    ```

    For example, to use the `manual` resource initialization strategy, run the following command:

    ```bash Terminal theme={null}
    upsun environment:merge --resources-init=manual
    ```
  </Tab>

  <Tab title="In the Console">
    1. Navigate to the environment you want to merge into its parent.
    2. Click <MergeIcon /> **Merge**.
    3. Select an initialization strategy from the proposed list.
       <Note>
         The list of strategies is only displayed if a new app or service is included in the merge.
       </Note>
    4. Click **Merge**.
  </Tab>
</Tabs>

### Environment activation

<Info>
  <h4>Resource initialization strategies</h4>
  Available: `parent`, `default`, `minimum` <br />
  Default: `default` if the new environment is of type `staging`, `minimum` if the new environment is of type `development`
</Info>

When you activate a new environment, the resource initialization strategy applied depends on the environment type:

| Environment type | Default strategy | Resources allocated |
| - | - | - |
| Staging | `default` | [default resource amounts](#default-resources) |
| Development | `minimum` | [minimum resources](#minimum-resources) |

To specify a different strategy, run the following command:

```bash Terminal theme={null}
upsun environment:activate --resources-init=<INITIALIZATION_STRATEGY>
```

For example, to use the `parent` resource initialization strategy, run the following command:

```bash Terminal theme={null}
upsun environment:activate --resources-init=parent
```

<Note>
  [Setting resources](/docs/manage-resources/adjust-resources) on an inactive environment using the Console or the CLI automatically activates it.
</Note>

### Backup restoration

<Info>
  <h4>Resource initialization strategies</h4>
  Available: `backup`, `parent`, `default`, `minimum` <br />
  Default: `backup`
</Info>

<Tabs>
  <Tab title="Using the CLI">
    When you [restore a backup](/docs/environments/restore) using the CLI,
    you can restore it to your current environment or a different environment.

    #### Restore to your current environment

    By default, when you [restore a backup](/docs/environments/restore) using the CLI, it is restored to your current environment.
    The resources of every container running on the environment revert to the state they were in when the backup was taken.

    <Note>
      To skip restoring resources, use the `--no-resources` option.
    </Note>

    If you deleted containers after backing up but before restoring, they are recreated using the `backup` strategy and granted the same resources as when the backup was taken.

    <Note>
      To skip restoring deleted containers, use the `--no-code` option.
    </Note>

    When you restore previously deleted containers,
    you can specify a different resource initialization strategy for them.

    #### Restore to a different environment

    The `backup` strategy applies by default.
    All apps and services are initialized as new containers on the environment,
    and granted the same resources as in the backup.
    You can specify a different resource initialization strategy for all containers.

    #### Specify a resource initialization strategy

    Run the following command:

    ```bash Terminal theme={null}
    upsun backup:restore --resources-init=<INITIALIZATION_STRATEGY>
    ```

    For example, to use the `minimum` resource initialization strategy, run the following command:

    ```bash Terminal theme={null}
    upsun backup:restore --resources-init=minimum
    ```
  </Tab>

  <Tab title="In the Console">
    When you [restore a backup](/docs/environments/restore) using the Console, it is restored to your current environment.
    The resources of every container running on the environment revert to the state they were in when the backup was taken.

    <Note>
      To skip restoring resources, use the `--no-resources` option.
    </Note>

    If you deleted containers after backing up but before restoring, they are recreated using the `backup` strategy and granted the same resources as when the backup was taken.

    <Note>
      To skip restoring deleted containers, restore the backup using the CLI and use the `--no-code` option.
    </Note>
  </Tab>
</Tabs>

## Environment sync

[Syncing an environment](/docs/glossary#sync) means propagating changes from a parent environment into a child environment (the opposite direction of an [environment merge](#environment-merge)).
You can sync:

* Only the code
* Only the data (databases, files)
* Only the resources (CPU and RAM, instances, and disk space)
* Any combination of the three (code and data, code and resources, data and resources, or all three)

<Note>
  If the child's disk is smaller than the parent's, Upsun Cloud automatically applies the parent's disk size before syncing.
  This ensures the sync can succeed.
</Note>

<Tabs>
  <Tab title="Using the CLI">
    Run the following commands depending on your needs:

    * Sync only resources:

      ```bash Terminal theme={null}
      upsun sync resources
      ```

    * Sync only code:

      ```bash Terminal theme={null}
      upsun sync code
      ```

    * Sync only data:

      ```bash Terminal theme={null}
      upsun sync data
      ```

    * Sync everything:

      ```bash Terminal theme={null}
      upsun sync code data resources
      ```

      You can adjust the command depending on the exact combination of elements you want to sync.
  </Tab>

  <Tab title="In the Console">
    1. Navigate to your Production environment.
    2. Click <SyncIcon /> **Sync**.
    3. Select the sync options you want from the proposed list.
    4. Select **Sync resources from Production into Staging**.
    5. Click **Sync**.
  </Tab>
</Tabs>


# Scaling
Source: https://developer.upsun.com/docs/manage-resources/scaling

Scale your applications automatically or with guaranteed resource allocations.

<CardGroup>
  <Card title="Autoscaling" icon="scaling" href="/docs/manage-resources/autoscaling">
    Learn how autoscaling adjusts app instances based on CPU and memory usage.
  </Card>

  <Card title="Guaranteed resources" icon="shield-check" href="/docs/manage-resources/guaranteed-resources">
    Learn how guaranteed CPU provides dedicated CPU and memory allocations.
  </Card>
</CardGroup>


# Upsun Blackfire for PHP and Python
Source: https://developer.upsun.com/docs/observability/application-metrics/blackfire

Upsun Blackfire is bundled with your PHP and Python Upsun Cloud projects.

Full access to [Upsun Blackfire](https://www.blackfire.io/) is bundled with all your PHP and
Python Upsun Cloud projects.

Upsun Blackfire is the **official Upsun Cloud observability service** that helps you
improve the performance of your apps at each stage of their lifecycle.
With Upsun Blackfire's unique Application Performance Monitoring (APM), Profiling,
Alerting, and Testing features, you can achieve the following goals:

* Avoid performance bottlenecks by proactively identifying issues in your code
* Promptly solve identified issues by taking advantage of actionable recommendations
* Create performance budgets for critical parts of your app and get alerted of any
  problem before a change hits your production

<iframe title="YouTube video" />

Upsun Blackfire is installed natively on Upsun Cloud and [works integrally with the Upsun Cloud workflow](https://www.youtube.com/watch?v=Bq-LFjgD6L0).
This results in an effortless setup process and smooth user experience.

## Get started with Upsun Blackfire

You can only access your Upsun Blackfire environments after you've been granted access to the related Upsun Cloud project.
Therefore, to access your Upsun Blackfire environments, make sure you log in using your Upsun account.

To access an Upsun Blackfire environment, each project user needs an Upsun Blackfire account.
When a project user doesn't already have an Upsun Blackfire account,
a new one is automatically created using the user's Upsun Cloud credentials.

<Note>
  If you're using a [Content Delivery Network (CDN)](/docs/domains/cdn),
  make sure you [configure it](https://blackfire.io/docs/integrations/proxies/index)
  to let Upsun Blackfire profile the code running on your servers.
</Note>

### Automated integration

The Upsun Blackfire automated integration is enabled on your environments by default.

When you create a new environment,
it automatically triggers the creation of an Upsun Blackfire environment with the same settings.
On this Upsun Blackfire environment, you have access to [all the features provided by Upsun Blackfire](https://www.blackfire.io/features/).
This includes monitoring, profiling, alerting, and build-related features.

Note that Upsun Blackfire monitoring is enabled by default on your production environment.
On other environment types, you need to [enable it](#upsun-blackfire-monitoring).
User access settings are replicated from the Upsun Cloud Console to Upsun Blackfire -- this includes all [access levels](https://blackfire.io/docs/up-and-running/access-management).

You might have Upsun Blackfire variables already set on your project.
In this case, the existing variables override the settings of the automated integration.

<Note>
  To trigger the synchronization of changes to users and their access levels,
  you need to redeploy the environment.
</Note>

### Upsun Blackfire monitoring

Upsun Blackfire monitoring is enabled by default on your production environment.
To enable Upsun Blackfire monitoring on your development or staging environments, follow these steps:

1. Go to your [organizations list](https://blackfire.io/my/organizations)
   and select the organization where you want to enable Upsun Blackfire monitoring.

2. Click **Organization Monitoring Usage**.

   <img alt="A screenshot of where to find Organization Monitoring Usage" />

3. In the **Monitoring Activation** section,
   enable monitoring on the environments of your choice.

   <img alt="A screenshot of what's seen in Monitoring Activation" />

For more information on Upsun Blackfire monitoring features,
see the [Upsun Blackfire documentation](https://blackfire.io/docs/monitoring-cookbooks/index).

## Upsun Blackfire Profiling

While your code is running, the Upsun Blackfire profiler collects deep performance metrics
and provides full details and context of your code's behavior.
This helps you find the root cause of performance bottlenecks.

Upsun Blackfire lets you profile your application anywhere it's deployed,
including on your local development machines.
Using a browser extension or CLI command,
you can profile HTTP requests, CLI scripts, Consumers, and Daemons.

While HTTP requests can be profiled out-of-the-box, CLI profiling requires a
[specific configuration](https://blackfire.io/docs/integrations/paas/upsun#cli-profiling).

For more information on Upsun Blackfire profiling features,
see the [Upsun Blackfire documentation](https://blackfire.io/docs/profiling-cookbooks/index).

Upsun Blackfire profiles are also one of the observability signals correlated by the [Upsun Cloud performance agent](/docs/get-started/ai/upsun-cloud-performance-agent), which analyzes up to 7 days of profiling and traffic data alongside your application source code to generate a performance analysis report with recommendations.

## Test the performance of each new deployment

Upsun Blackfire's native integration with Upsun Cloud enables you to test your app's performance
every time you deploy a branch in production, staging, or development.
Follow these steps:

1. Set up the [Upsun Blackfire Builds integration](https://blackfire.io/docs/integrations/paas/upsun#builds).

2. Optional: set up an [integration with your Git provider](https://blackfire.io/docs/integrations/git/index)
   and get commit status updates from build reports.

3. Recommended: test business-critical use cases, with Upsun Blackfire [synthetic monitoring](https://blackfire.io/docs/builds-cookbooks/scenarios).

## Troubleshooting

### Bypass your reverse proxy, load balancer or CDN

To use [Upsun Blackfire profiling](#upsun-blackfire-profiling), you need to bypass any reverse
proxy, load balancer or [CDN](/docs/domains/cdn) that sits in front of your app.

See [how to configure a bypass](https://blackfire.io/docs/reference-guide/reverse-proxies#documentation).

### Configure your HTTP cache

To take advantage of Upsun Blackfire features while using the HTTP cache with cookies,
allow the `__blackfire` cookie to go through the cache.

To do so, add [a configuration](/docs/routes/cache#allowing-only-specific-cookies)
similar to the following:

```yaml .upsun/config.yaml theme={null}
routes:
  "https://{default}/":
    cache:
      enabled: true
      cookies: ["/SESS.*/", "__blackfire"]
```

## Get support

If you're experiencing issues with Upsun Blackfire and [troubleshooting](#troubleshooting)
information doesn't help, follow these steps:

1. Retrieve [startup errors](#1-retrieve-startup-errors).
2. Retrieve your [Upsun Blackfire logs](#2-retrieve-your-upsun-blackfire-logs).
3. Send this data to [Upsun Blackfire Support](https://support.blackfire.upsun.com/hc/en-us).

### 1. Retrieve startup errors

To retrieve startup errors, run the following command:

```bash theme={null}
upsun ssh -- php -d display_startup_errors=on --ri blackfire
```

### 2. Retrieve your Upsun Blackfire logs

To retrieve your Upsun Blackfire logs, follow these steps:

1. On the environment where you're facing issues, create the following [variable](/docs/development/variables/set-variables):

   ```bash theme={null}
   upsun variable:create php:blackfire.log_file --value /tmp/blackfire.log
   ```

2. To set the verbosity of the logs to level 4 (debug level), create the following variable:

   ```bash theme={null}
   upsun variable:create php:blackfire.log_level --value 4
   ```

3. Start a profile or build.

4. To display the logs, run the following command:

   ```bash theme={null}
   upsun ssh -- cat /tmp/blackfire.log > blackfire.log
   ```

After you've retrieved the logs, you can disable them.
To do so, run the following commands:

```bash theme={null}
upsun variable:delete php:blackfire.log_file
upsun variable:delete php:blackfire.log_level
```


# Continuous Profiling dashboard
Source: https://developer.upsun.com/docs/observability/application-metrics/cont-prof

Understanding the Continuous Profiling dashboard

<ContinuousProfilingSellableBody />

Continuous profiling is a multi-dimensional performance optimization technique
where web applications are monitored and profiled in real-time. Lightweight and
scalable, it's tailored for holistic application oversight.

Continuous profiling collects performance data continuously, enabling developers to
gain deep insights into their application's behavior, identify bottlenecks, and
optimize code for better performance and resource utilization. This proactive
approach allows for quicker identification and resolution of performance issues,
ensuring the smooth running of software in live environments.

## Continuous profiling on Upsun Cloud

Upsun Cloud Continuous Profiling is powered by [Upsun Blackfire](/docs/observability/application-metrics/blackfire).

Continuous profiling data is also one of the observability signals correlated by the [Upsun Cloud performance agent](/docs/get-started/ai/upsun-cloud-performance-agent), which analyzes up to 7 days of profiling and traffic data alongside your application source code to generate a performance analysis report with recommendations.

To access Continuous Profiling in the Console:

1. Open your project in the Console.
2. Select **Apps and Services**.
3. Select your **app**.
4. Click **Profiling**.

The Continuous Profiling dashboard lets you visualize the profiling data of a specific application.
It is composed of several views: flame graph, table view, and a split view combining the flame graph and table views.

Each view helps make sense of the profiling data for the selected dimension and time frame. The available dimensions vary with the runtime profiled.

## Color-coded node dimensions

Upsun Cloud continuous profiling dashboard employs a color-coded system to represent each dimension, ensuring consistency across different runtimes.

The intensity of a node's background color is directly proportional to the resources it consumes. As resource consumption increases, so does the vibrancy of the background color. This visual representation pinpoints application areas that may require optimization.

<img alt="Routes" />

The contrast between the dimension color and the grayscale of regular nodes has been designed to ensure accessibility for all users and allow colorblind users to benefit from this feature.

## Flame graph

The flame graph is a hierarchical visualization of the contribution of the different function calls to the selected dimensions.

Flame graphs are effective in identifying performance issues and understanding the behavior of software during execution.

<img alt="Routes" />

Rectangles in a flame graph are called frames. Each frame represents a function, arranged vertically (y-axis) to show the sequence of method calls.

The width of a frame relates to its resource usage. It helps pinpoint the most resource-intensive function calls. Their colors are not performance-related. They are meant to differentiate between functions.

Horizontally (x-axis), methods are sorted by name, not the order in which they run.

Hovering a frame displays in-depth information on it.

<img alt="Routes" />

Clicking on a frame narrows down the flame graph to the callers and callee nodes of that frame.

<img alt="Routes" />

## Table view

The table view displays a list of all the frames sorted by their resource consumption, for the selected dimension and time frame. By default, the table is sorted by `exclusive` resource consumption, which is the total value of the frame, minus the combined total values of its direct children.

<img alt="Routes" />


# Comparing Continuous Profiling Timeframes
Source: https://developer.upsun.com/docs/observability/application-metrics/cont-prof-comparison

Comparing continuous profiling timeframes

<ContinuousProfilingSellableBody />

Upsun Cloud Continuous Profiler dashboard allows comparing two timeframes to better
understand application dynamics in various contexts.

You could compare two versions of the application, before and after a deployment,
or rush hours with quiet times for instance.

## Enabling comparison mode

A toggle on the top right corner of the continuous profiling dashboard enables
the comparison mode.

<img alt="Routes" />

With comparisons enabled, you can select two timeframes referred to as `A` and
`B`. Those times can overlap.

## Understanding continuous profiling visual comparison

The flamegraph provides a visual representation of how timeframe `B` compares
to `A` for the selected dimension using shades of colors. The stronger the
color, the higher resource variation.

<img alt="Routes" />

Shades of green indicates timeframe `B` is consuming less resources than `A`
for the selected dimension. Shades of red indicate the opposite.

A scale and contextual information are displayed when hovering a span. This ensures
accessibility for all users and allow colorblind users to benefit from this feature.

<img alt="Routes" />

<PerformanceAgentMention />


# Monitor Cron job executions
Source: https://developer.upsun.com/docs/observability/application-metrics/cron-metrics

Learn how to visualize and interpret your Cron job runs directly in the Console.

You can view your [Cron job](/docs/configure-apps/image-properties/crons) executions directly from your project’s Services > Apps or Services > Workers pages. This visualization helps you quickly understand how scheduled jobs are performing and spot unusual patterns without manually checking logs.

Each execution is represented visually, letting you monitor performance trends and failures at a glance.

This makes it easier to:

* Verify that scheduled jobs are running on time.
* Identify failed or unusually long-running jobs.
* Drill into logs only when something looks wrong.

## How to view Cron job executions

1. Open your project in the Console.
2. Select your chosen Environment.
3. Navigate to:
   * Services --> Apps & Services --> Apps --> app
   * Services --> Apps & Services --> Apps --> Workers (for background jobs).
4. Click the **Crons** tab to view your scheduled jobs.

Each Cron job displays a visual history of its executions over time.

## Understanding the visualization

Each execution appears as a vertical bar in the visualization:

| Visual element | Meaning | Example |
| - | - | - |
| **Color** | Indicates success or failure. | Green = success, Red = failure |
| **Height** | Proportional to the job’s execution time. | Taller bars indicate longer runtimes |
| **Click a bar** | Opens detailed logs for that specific run. | Review stdout/stderr for debugging |

This combination of color and height helps in spotting outliers, for example:

* A sudden tall red bar indicates a failed job that took longer than usual.
* Consistently tall green bars suggest a job that may need optimization.

Each vertical bar corresponds to a single execution. Hover over any bar to view basic details such as:

* Execution date and time
* Duration
* Status (success/failure)

Click a bar to open the detailed execution log, where you can inspect errors or performance information.

## Troubleshooting and best practices

* **Monitor for patterns**: Look for recurring red (failed) bars or progressively longer runtimes.
* **Drill into logs**: Clicking a bar takes you directly to logs for that specific execution.
* **Correlate with metrics**: Combine this view with [application metrics](/docs/observability/application-metrics) to identify performance bottlenecks.
* **Adjust Cron timing**: If jobs overlap or run too frequently, adjust their schedule in your [`crons` configuration](/docs/configure-apps/image-properties/crons).

<Info>
  <h4>Investigate consistently high durations</h4>
  If you notice that your Cron job runtimes are consistently increasing, this may indicate:

  * Growing data volumes,
  * Inefficient queries
  * Resource limits being reached.

  Use profiling tools like [Upsun Blackfire](/docs/observability/application-metrics/blackfire) to identify and resolve performance issues.
</Info>

## When to check Cron execution history

| Use case | Why it’s useful |
| - | - |
| **Autoscaling investigations** | Understand whether jobs are driving unexpected CPU or memory spikes. |
| **Deployment monitoring** | Verify that scheduled jobs resume normally after deployments. |
| **Job failure analysis** | Quickly locate the time and context of a failed execution. |
| **Performance tuning** | Spot trends in runtime duration and optimize resource usage. |

## Related content

* [Define and schedule Cron jobs](/docs/configure-apps/image-properties/crons)
* [Application metrics](/docs/observability/application-metrics)
* [Consume logs](/docs/observability/logs)
* [Upsun Blackfire for PHP and Python](/docs/observability/application-metrics/blackfire)


# Continuous profiling for Go
Source: https://developer.upsun.com/docs/observability/application-metrics/go

Configure and use the Go continuous profiler.

<ContinuousProfilingSellableBody />

## Continuous profiling on Upsun Cloud

Upsun Cloud [Continuous Profiler](/docs/observability/application-metrics/cont-prof) is powered by [Upsun Blackfire](/docs/observability/application-metrics/blackfire).
It is available in the Console under **Apps and Services → your app → Profiling**.

The GO continuous profiling is currently made across 6 dimensions:

* **Allocations**: Number of objects allocated
* **Allocated Memory**: Number of bytes allocated
* **CPU**: Time spent running on the CPU
* **Goroutines**: Number of goroutines (both on-CPU and off-CPU)
* **Heap Live Objects**: Number of objects allocated that are not yet garbage collected
* **Heap Live Size**: Number of bytes allocated that are not yet garbage collected

The default sampling frequency is 100 Hz. This means the Go continuous profiler is
collecting information 100 times per second.

## Prerequisites

Upsun Cloud Continuous Profiler requires [`Go >=1.18`](/docs/languages/go).

## Installation

Get the [Upsun Blackfire Continuous Profiler Go library](https://github.com/blackfireio/go-continuous-profiling):

```bash theme={null}
go get github.com/blackfireio/go-continuous-profiling
```

## Go continuous profiler API

The Go continuous profiler API has two functions:

```go theme={null}
func Start(opts ...Option) error {}
func Stop() {}
```

### `func Start(opts ...Option) error`

`Start` starts the continuous profiler probe. It collects profiling information and uploads
it to the Upsun Blackfire Agent periodically.

```go theme={null}
profiler.Start(
       profiler.WithCPUDuration(3 * time.Second),
       profiler.WithCPUProfileRate(1000),
       profiler.WithProfileTypes(profiler.CPUProfile, profiler.HeapProfile, profiler.GoroutineProfile),
       profiler.WithLabels({
            "key1": "value1",
            "key2": "value2",
       }),
       profiler.WithUploadTimeout(5 * time.Second),
)
defer profiler.Stop()
```

The `Start` function accepts the following options:

* `WithCPUDuration`: specifies the length at which to collect CPU profiles.
  The default is 45 seconds. Can also be set via the environment variable `BLACKFIRE_CONPROF_CPU_DURATION`.

* `WithCPUProfileRate`: sets the CPU profiling rate in Hz (number of samples per second).
  The default is defined by the Go runtime as 100 Hz. Can also be set via the environment
  variable `BLACKFIRE_CONPROF_CPU_PROFILERATE`.

* `WithProfileTypes`: sets the profiler types. Multiple profile types can be set (`profiler.CPUProfile`, `profiler.HeapProfile`, `profiler.GoroutineProfile`).
  The default is `Profiler.CPUProfile`.

* `WithLabels`: sets custom labels specific to the profile payload that is sent.

* `WithUploadTimeout`: sets the upload timeout of the message that is sent to the Upsun Blackfire Agent.
  The default is 10 seconds. Can also be set via the environment variable `BLACKFIRE_CONPROF_UPLOAD_TIMEOUT`.

<Info>
  <h4>Note:</h4>
  If the same parameter is set by both an environment variable and a `Start` call, the explicit
  parameter in the `Start` call takes precedence.
</Info>

There is also some additional configuration that can be done using environment variables:

* `BLACKFIRE_LOG_FILE`: Sets the log file. The default is logging to `stderr`.

* `BLACKFIRE_LOG_LEVEL`: Sets the log level. The default is logging only errors.

### `func Stop()`

Stops the continuous profiling probe.

## An example application

1. Get the Upsun Blackfire Continuous Profiler Go library

```bash theme={null}
go get github.com/blackfireio/go-continuous-profiling
```

2. Save the following code as `main.go` and run as follows:

```bash theme={null}
go run main.go
```

```go theme={null}
package main

import (
	"crypto/md5"
	"encoding/hex"
	"io"
	"time"

	profiler "github.com/blackfireio/go-continuous-profiling"
)

func doSomethingCpuIntensive() {
	md5Hash := func(s string) string {
		h := md5.New()
		io.WriteString(h, s)
		return hex.EncodeToString(h.Sum(nil))
	}
	for i := 0; i < 1_000_000; i++ {
		md5Hash("UpsunIsCoolAndSoAreYou")
	}
}

func main() {
	err := profiler.Start(
		profiler.WithAppName("my-app"),
	)
	if err != nil {
		panic("Error while starting Profiler")
	}
	defer profiler.Stop()

	for i := 0; i < 15; i++ {
		doSomethingCpuIntensive()

		time.Sleep(1 * time.Second)
	}
}
```


# Application metrics
Source: https://developer.upsun.com/docs/observability/application-metrics/index

See how to better understand your applications' real behavior with live and detailed insights.

<CardGroup>
  <Card title="Monitor Cron job executions" icon="clock" href="/docs/observability/application-metrics/cron-metrics">
    Visualize and interpret your Cron job runs directly in the Console.
  </Card>

  <Card title="Understanding application observability" icon="eye" href="/docs/observability/application-metrics/understanding">
    Understand the differences between deterministic and probabilistic observability.
  </Card>

  <Card title="Upsun Blackfire for PHP and Python" icon="gauge" href="/docs/observability/application-metrics/blackfire">
    Full access to Upsun Blackfire is bundled with your PHP and Python projects.
  </Card>

  <Card title="Continuous profiling" icon="chart-area" href="/docs/observability/application-metrics/cont-prof">
    Understand your application's performance with continuous profiling.
  </Card>
</CardGroup>


# Continuous profiling for Java
Source: https://developer.upsun.com/docs/observability/application-metrics/java

Configure and use the Java continuous profiler.

Upsun Cloud [Continuous Profiler](/docs/observability/application-metrics/cont-prof) is powered by [Upsun Blackfire](/docs/observability/application-metrics/blackfire).
It is available directly from the [Console](/docs/administration/web), under **Apps and Services → your app → Profiling**.

The Java continuous profiling is currently made across 3 dimensions:

* **CPU Time**:  Time spent running on the CPU
* **Allocations**: Time spent running on the CPU
* **Allocated Memory**: Number of bytes allocated

The default sampling frequency is 100 Hz. This means the Java continuous profiler is
collecting information 100 times per second.

## Prerequisites

Upsun Cloud Continuous Profiler requires [`Java >= 21`](/docs/languages/java).

## Configuration

The Java continuous profiler is enabled by default without configuration.


# Continuous profiling for Node.js
Source: https://developer.upsun.com/docs/observability/application-metrics/nodejs

Configure and use the NodeJS continuous profiler.

<ContinuousProfilingSellableBody />

## Continuous profiling on Upsun Cloud

Upsun Cloud Continuous Profiling is powered by [Upsun Blackfire](/docs/observability/application-metrics/blackfire).
It is available directly in the Console, under **Apps and Services → your app → Profiling**.

The Node.js continuous profiling is currently made across 3 dimensions:

* **CPU Time**:  Time spent running on the CPU
* **Wall-time**: Elapsed time per function call
* **Heap**: Memory allocation and reserved space over time

The default sampling frequency is 100 Hz. This means the Node.js continuous profiler is
collecting information 100 times per second.

## Prerequisites

Upsun Cloud Continuous Profiler requires [`Node.js >= 18.0.0`](/docs/languages/nodejs).

## Installation

Get the [Upsun Blackfire Continuous Profiler NodeJS library](https://github.com/blackfireio/node-continuous-profiling/):

```shell theme={null}
npm install @blackfireio/node-tracing
```

```js theme={null}
const Blackfire = require('@blackfireio/node-tracing');
```

## NodeJS continuous profiler API

The NodeJS continuous profiler API has two functions:

```js theme={null}
function start(config) {}
function stop() {}
```

### `function start(config) {}`

The `start` function starts the continuous profiler probe.
It collects profiling information in the background and periodically uploads it to the Upsun Blackfire Agent until the `stop` function is called.

```js theme={null}
const Blackfire = require('@blackfireio/node-tracing');
Blackfire.start({
   appName: 'my-app'
});
// your application...
// If needed, you can stop profiling before cpuDuration
// Blackfire.stop();
```

The `start` function accepts an object as a parameter with the following keys:

* `appName`: name of the application

* `durationMillis`: time in milliseconds for which to collect profile (default: 45\_000)

* `cpuProfileRate`: average sampling frequency in Hz. (default: 100)

* `labels`: Labels to add to the profile. (default: )

* `uploadTimeoutMillis`: Timeout in milliseconds for the upload request (default: 10000)

### `function stop() {}`

Stops the continuous profiling probe.

## An example application

1. Get the Continuous Profiler NodeJS library

```shell theme={null}
npm install express @blackfireio/node-tracing
```

2. Create `index.js` with the following code

```js theme={null}
const Blackfire = require('@blackfireio/node-tracing');
const express = require('express')
const crypto = require("crypto");
const app = express()
const port = 3000

app.get('/', (req, res) => {
   const salt = crypto.randomBytes(128).toString("base64");
   const hash = crypto.pbkdf2Sync("this is my password", salt, 10000, 512, "sha512");

   res.send('Hello World!');
})


app.listen(port, () => {
   console.log(`Example app listening on port ${port}`)
   Blackfire.start({appName: 'blackfire-example'});
})
```

3. Run the Node.js server

```bash theme={null}
node index.js
```


# Continuous profiling for PHP
Source: https://developer.upsun.com/docs/observability/application-metrics/php

Configure and use the PHP continuous profiler.

<ContinuousProfilingSellableBody />

Upsun Cloud [Continuous Profiler](/docs/observability/application-metrics/cont-prof) is powered by [Upsun Blackfire](/docs/observability/application-metrics/blackfire).
It is available directly in the [Console](/docs/administration/web), under **Apps and Services → your app → Profiling**.

The PHP continuous profiling is currently made across 4 dimensions:

* **CPU Time**:  Time spent running on the CPU
* **Wall-time**: Elapsed time per function call
* **Allocated Memory**: Number of bytes allocated in memory
* **Allocations**: Time spent running on the CPU

The default sampling frequency is 100 Hz. This means the PHP continuous profiler is
collecting information 100 times per second.

## Prerequisites

Upsun Cloud Continuous Profiler requires [`PHP >=8.2`](/docs/languages/php).

## Installation

The Upsun Blackfire Continuous Profiler PHP library is included by default in all
PHP images matching its requirements. There is no installation required.

## Configuration

The PHP continuous profiler is enabled by default without configuration.

Optionally, you can override the following environment variables:

* `DD_PROFILING_ENABLED=true`: forces the PHP continuous profiler activation/deactivation
* `DD_PROFILING_LOG_LEVEL=off`: controls the PHP continuous profiler log level


# Continuous profiling for Python
Source: https://developer.upsun.com/docs/observability/application-metrics/python

Configure and use the Python continuous profiler.

<ContinuousProfilingSellableBody />

Upsun Cloud [Continuous Profiler](/docs/observability/application-metrics/cont-prof) is powered by [Upsun Blackfire](/docs/observability/application-metrics/blackfire).
It is available directly in the [Console](/docs/administration/web), under **Apps and Services → your app → Profiling**.

The PHP continuous profiling is currently made across 4 dimensions:

* **CPU Time**:  Time spent running on the CPU
* **Wall-time**: Elapsed time per function call
* **Heap Live Size**: Number of bytes allocated that are not yet garbage collected
* **Allocated Memory**: Number of bytes allocated in memory
* **Allocations**: Time spent running on the CPU

The default sampling frequency is 100 Hz. This means the Python continuous profiler is
collecting information 100 times per second.

## Prerequisites

Upsun Cloud Continuous Profiler requires [`Python >=3.7.0`](/docs/languages/python).

## Installation

The [Upsun Blackfire Continuous Profiler Python library](https://github.com/blackfireio/python-continuous-profiling) is included by default in all
Python images matching its requirements. There is no installation required.

## Python continuous profiler API

The Python profiler API (`profiler`) can be initiated with the following options:

* `application_name`: the application name.
* `period`: specifies the length at which to collect CPU profiles. The default is 45 seconds.
* `upload_timeout`: observability data upload timeout. The default is 10 seconds.
* `labels`: a dict containing the custom labels specific to the profile payload that is sent.

The Python continuous profiler API has two functions:

```python theme={null}
def start():
def stop():
```

| Function | Description |
| - | - |
| `def start():` | The `start` function starts the continuous profiler probe. <br />It collects profiling information in the background and periodically uploads it to the Upsun Blackfire Agent until the `stop` function is called. |
| `def stop():` | Stops the continuous profiling probe. |

## Example

Here is an example of how you can initiate the Python `profiler` on a basic app:

1. Create `example.py` with the following code:

   ```python theme={null}
   def foo():
     import time
     time.sleep(1.0)

   profiler = Profiler(application_name="my-python-app", labels={'my-extra-label': 'data'})
   profiler.start()
   foo()
   profiler.stop()
   ```

2. Run the app:

   ```bash theme={null}
   python example.py
   ```


# Continuous profiling for Ruby
Source: https://developer.upsun.com/docs/observability/application-metrics/ruby

Configure and use the Ruby continuous profiler.

Upsun Cloud [Continuous Profiler](/docs/observability/application-metrics/cont-prof) is powered by [Upsun Blackfire](/docs/observability/application-metrics/blackfire).
It is available directly from the [Console](/docs/administration/web), under **Apps and Services → your app → Profiling**.

The Ruby continuous profiling is currently made across 3 dimensions:

* **CPU Time**:  Time spent running on the CPU
* **Wall-time**: elapsed time per function call
* **Allocations**: Time spent running on the CPU

The default sampling frequency is 100 Hz. This means the Ruby continuous profiler is
collecting information 100 times per second.

## Prerequisites

Upsun Cloud Continuous Profiler requires [`Ruby >= 3.0`](/docs/languages/ruby).

## Installation

1. Add the `datadog` gem to your `Gemfile` or `gems.rb` file:

```bash theme={null}
gem 'datadog', '~> 2.0'
```

2. Install the gems running the `bundle install` command.

3. Add the `ddprofrb exec` command to your Ruby application start command:

```bash theme={null}
bundle exec ddprofrb exec ruby myrubyapp.rb
```

Rails example:

```bash theme={null}
bundle exec ddprofrb exec bin/rails s
```

Alternatively, start the profiler by adding the following code in your application's entry point if you can't start it using `ddprofrb exec`:

```bash theme={null}
require 'datadog/profiling/preload'
```


# Continuous profiling for Rust
Source: https://developer.upsun.com/docs/observability/application-metrics/rust

Configure and use the Rust continuous profiler.

Upsun Cloud [Continuous Profiler](/docs/observability/application-metrics/cont-prof) is powered by [Upsun Blackfire](/docs/observability/application-metrics/blackfire).
It is available directly from the [Console](/docs/administration/web), under **Apps and Services → your app → Profiling**.

The Rust continuous profiling is currently made across 3 dimensions:

* **CPU Time**:  Time spent running on the CPU
* **Allocated Memory**: Number of bytes allocated in memory
* **Allocations**: Time spent running on the CPU

The default sampling frequency is 100 Hz. This means the Rust continuous profiler is
collecting information 100 times per second. The allocated memory sampling frequency is 524288 Hz.

## Installation

The Upsun Blackfire Continuous Profiler Rust library is included by default in all
Rust images. There is no installation required nor minimal Rust version needed.

## Configuration

The Rust continuous profiler is enabled by default without configuration.

It is recommended to build your Rust application in [debug mode](https://doc.rust-lang.org/book/ch14-01-release-profiles.html) to benefit from comprehensive stacktrace and information that could be obfuscated and collapsed otherwise.

```shell theme={null}
$ cargo build
```


# Understanding application observability
Source: https://developer.upsun.com/docs/observability/application-metrics/understanding

Understanding the differences between deterministic and probabilistic observability

Multiple application observability features are available for your Upsun Cloud projects.

A full access to [Upsun Blackfire](https://www.blackfire.io/) is bundled with all your PHP and Python projects.
The continuous profiling of your NodeJS, Go, Ruby and Rust applications is available directly from the Console under **Apps and Services → your app → Profiling**.

## Upsun Blackfire: Deterministic observability for PHP and Python

Upsun Blackfire has a **deterministic** approach for PHP and Python, meaning it collects an extensive range of metrics for every instrumented request or script.

The quantity of data and metrics collected differ for every layer of data Upsun Blackfire collects. The way scripts or requests are chosen to be instrumented also depends on the data layer.

[Profiles](https://blackfire.io/docs/profiling-cookbooks/index) are manually triggered by an Upsun Blackfire user, or automatically triggered by [Upsun Blackfire builds](https://blackfire.io/docs/builds-cookbooks/index), the synthetic monitoring feature that evaluates the performance of critical user journeys.

Meanwhile, monitoring traces and extended traces are based on the sample rate, which is the percentage of requests that are monitored.  In that matter, [Upsun Blackfire monitoring](https://blackfire.io/docs/monitoring-cookbooks/index) offers a mix of two approaches:

* a probabilistic one on how requests are selected to be instrumented
* a deterministic one on how they are monitored, with the instrumentation starting at the very beginning of the request and ending with it

A [blog post](https://blog.blackfire.io/understanding-monitoring-traces-extended-traces-and-profiles.html) provides all the details on the differences and complementarity between Upsun Blackfire's monitoring traces, extended traces, and profiles.

## Continuous Profiling: Probabilistic observability

Probabilistic profiling involves capturing data intermittently. It collects information at defined intervals, logging functions or services activated by any ongoing request or script. This approach provides a more comprehensive view of your application’s performance over time, but certain event nuances may be overlooked due to the frequency of sampling.

Comparing deterministic to probabilistic profiling is akin to contrasting medical imaging devices. Asserting that an fMRI is unequivocally better than a PET scan or ultrasound is a misplaced judgment; each tool has its specific diagnostic purpose.

You might not know all the details about a specific script. But you will have a good overview of everything happening at a specific time. Information on shorter spans starting and ending between two consecutive ticks won’t be collected.

## Pros and cons

Both approaches have their strengths and weaknesses. One is not better than the other. It all depends on the instrumented languages and your understanding of the data.

* Deterministic profiling: Its strength lies in precision and facilitating meticulous script analysis. But it’s resource-intensive, leading to considerable overhead and potential data overload, making analysis potentially tedious.
* Probabilistic profiling: Lightweight and scalable, tailored for holistic application oversight. However, its periodic snapshots might miss rapid function calls, yielding a not-so-perfect application map.

Deterministic and probabilistic profiling each hold value within the development process. The former delivers a thorough and detailed view, while the latter offers a wider, more adaptable perspective. Developers may choose one or even combine both approaches based on the project’s specifics and the issues faced.


# Increase observability
Source: https://developer.upsun.com/docs/observability/index

See how to increase observability for your Upsun Cloud projects.

Observability refers to the capability to evaluate the current state of an application and its architecture by analyzing metrics, traces and logs.

Observability is key to the success of your Upsun Cloud projects by empowering you with:

* **Optimized performance**: monitor how your applications perform in real-time and identify bottlenecks or inefficiencies

* **Resource efficiency**: Better understand your application's resource utilization and make informed decisions to correctly scale them.

* **Rapid troubleshooting**: swiftly pinpoint issues in your projects by identifying their root causes.

* **Synthetic monitoring**: Automatically runs performance tests on all your branch and proactively identify and fix any performance regression.

* **AI-driven analysis**: Run the [Upsun Cloud performance agent](/docs/get-started/ai/upsun-cloud-performance-agent) on demand to turn your observability data into a ranked report of bottlenecks with recommended code changes.


# Access your logs
Source: https://developer.upsun.com/docs/observability/logs/access-logs

Increase your knowledge of how your apps are performing by accessing their container and activity logs.

## Activity logs

Changes to your environments, such as deployments, cron jobs, and code or variable updates,
are each logged as activities.
You can access the logs either in the Console or using the [CLI](/cli):

<Tabs>
  <Tab title="In the Console">
    1. Open the project you are interested in.
    2. From the **Environment** menu, select an environment.
    3. Click a recent activity from the activity feed or click **All** to see the complete history.

       <img alt="An activity feed within an environment" />
  </Tab>

  <Tab title="Using the CLI">
    1. Get a list of activities by running

       ```bash theme={null}
       upsun activity:list -e <ENVIRONMENT_NAME>
       ```

       Pass the `--start` flag to get activities from a specific date in the past.

    2. To see details about the activity's state and timing, run

       ```bash theme={null}
       upsun activity:get <ACTIVITY_ID>
       ```

       Where `<ACTIVITY_ID>` comes from the list in step 1.

    3. Get a log of any given activity by running

       ```bash theme={null}
       upsun activity:log <ACTIVITY_ID>
       ```
  </Tab>
</Tabs>

If a running activity is stuck, you can [cancel the activity](/docs/environments/cancel-activity).

A scheduled [maintenance window](/docs/core-concepts/build-deploy#maintenance-window) run also appears here as a pending activity, about 5 days before it runs.

### Sharing activity logs

When trying to identify and resolve failures, it can often help to have another person's perspective.
Troubleshoot collaboratively by sharing the logs of specific activities.

To share a log, open the log and click <ShareIcon /> **Copy URL**.

Share specific lines in the log on clicking the line number.
To select multiple lines, hold <kbd>Shift</kbd>.
After selecting multiple lines,
hovering on the next unselected line gives you the amount of time that passed between the selected lines.

<img alt="An activity log with multiple lines selected showing the duration of part of the activity" />

## Container logs

Events that occur within an app container are logged within that container.
The logs can be written to, but you should do so only with standard logging mechanisms.
If your app has its own logging mechanism, use it to write to a dedicated logs [mount](/docs/configure-apps/image-properties/mounts).

To access the logs of various types of events:

<Tabs>
  <Tab title="Using the CLI">
    Use the `upsun log` command and specify the type of log you want.
    For example, to get the access log, run:

    ```bash theme={null}
    upsun log -e <ENVIRONMENT_NAME> access
    ```

    To get other logs, just replace `access` with the [type of log](#types-of-container-logs).
    To view more lines, use the `--lines` flag.
  </Tab>

  <Tab title="Using SSH directly">
    1. Access the container by running

       ```bash theme={null}
       upsun ssh -e <ENVIRONMENT_NAME>
       ```

    2. Change to the right directory by running `cd /var/log`.
       If you're on a Dedicated Gen 2 cluster, run

       ```bash theme={null}
       cd /var/log/upsun/<APP_NAME>/
       ```

    3. Read the desired log, such as by running `tail access.log`.
  </Tab>
</Tabs>

All log files are trimmed to 100 MB automatically.
If you need larger logs, set up a [cron job](/docs/configure-apps/image-properties/crons) to upload them to third-party storage.
See an example of [uploading logs to Amazon S3](https://gitlab.com/contextualcode/platformsh-store-logs-at-s3) from Contextual Code.

### Types of container logs

| Type | Always present | Description |
| - | - | - |
| `access` | Yes | The raw access log for the nginx instance running on the container. It doesn't include requests that are redirected or cached by the [router](/docs/routes). |
| `app` | Yes | All log messages generated by the app including language errors and exceptions. |
| `cron` | No | The output of cron jobs. Only exists after a cron job has run. |
| `deploy` | No | The output of the [`deploy` hook](/docs/configure-apps/hooks/hooks-comparison#deploy-hook). Only exists after a `deploy` hook has run. |
| `dns` | Yes | All DNS queries made by processes in the container (such as the app and cron jobs). |
| `error` | Yes | nginx-level errors that occur once nginx has fully started such as HTTP errors for missing directories and excluded file types. |
| `nginx/error` | No | All nginx startup log messages. Only useful when debugging possible nginx configuration errors. Not currently available using the `upsun log` command. |
| `php.access` | No | A record of all requests to the PHP service. See [PHP access record format](#php-access-record-format). |
| `post-deploy` | No | The output of the [`post_deploy` hook](/docs/configure-apps/hooks/hooks-comparison#post-deploy-hook). Only exists after a `post_deploy` hook has run. |
| `syslog` | Yes | General system-wide logs. |

#### PHP access record format

The formatting of `php.access.log` is determined by the PHP settings.
To determine the format, run the following:

```bash theme={null}
upsun ssh cat -n /etc/php/<PHP_VERSION>-zts/fpm/php-fpm.conf | grep "access.format"
```

You get a response such as the following:

```bash theme={null}
Connection to ssh.eu.platform.sh closed.
access.format = "%{%FT%TZ}t %m %s %{mili}d ms %{kilo}M kB %C%% %{REQUEST_URI}e"
```

See what [each value in this string means](https://www.php.net/manual/en/install.fpm.configuration.php#access-format).

## Timezones

UTC is the default timezone for all logs.


# Forward Upsun Cloud and Upsun Blackfire logs
Source: https://developer.upsun.com/docs/observability/logs/forward-logs

Send your Upsun Cloud and Upsun Blackfire logs to a third-party service for further analysis.

You might use a service to analyze logs from various parts of your fleet.
You might want to consolidate all your logs in one place that everyone has access to
without needing to grant them access to each project individually.

In such cases, forward your logs from Upsun Cloud and Upsun Blackfire to a third-party service.
You can use a [service with an integration](#use-a-log-forwarding-integration)
or any service that supports a [syslog endpoint](#forward-to-a-syslog-endpoint) or [HTTP endpoint](#forward-to-an-http-endpoint).

Log forwarding is available for Grid projects.
For Dedicated Gen 2 projects, see how to [log remotely with `rsyslog`](https://docs.platform.sh/dedicated-gen-2/architecture/options.html#remote-logging).
To enable log forwarding in a project, you need to be a [project admin](/docs/administration/users).
For pricing information for real-time logs forwarding, refer to the **Observability and performance monitoring** section of the [Upsun pricing page](https://upsun.com/pricing/).

### Which logs are forwarded?

When log forwarding is enabled, Upsun Cloud forwards logs sent to journald.

By default, Upsun Cloud sends the following logs to journald:

* `stdout` and `stderr` logs from your application<br />
  Note: You can configure your application to use syslog to send these (or additional) messages to journald.
* MariaDB/MySQL slow query logs
* Redis logs (all except command-level operations and low-level internals)

Logs in files are not forwarded to journald.

## Use a log forwarding integration

Certain services have a specific integration for forwarding logs.
If your third-party service isn't supported, you can forward to a [syslog endpoint](#forward-to-a-syslog-endpoint).

### Integrated third-party services

Upsun Cloud supports forwarding logs not only to custom remote syslog endpoints but also directly to a set of
popular third‑party log management and observability services. These integrations allow you to centralize logs from
applications, services, and infrastructure into your existing monitoring stack:

* **[Sumo Logic](https://www.sumologic.com/)** – Cloud-based log management and analytics.
* **[New Relic](https://newrelic.com/)** – Unified observability platform with logs and metrics.
* **[Splunk](https://www.splunk.com/)** – Searchable log platform for monitoring and operational intelligence.
* **[Datadog](https://www.datadoghq.com/)** – Observability suite with log collection and processing.
* **[Loggly](https://www.loggly.com/)** – Cloud-native log monitoring, aggregation, and alerting.
* **[LogDNA (Mezmo)](https://www.mezmo.com/)** – Centralized log management and analysis in real time.
* **[Papertrail](https://www.papertrail.com/)** – Real-time log aggregation via syslog.
* **[Logz.io](https://logz.io/)** – ELK-based log analytics and monitoring.

### Enable a log forwarding integration

#### Using the CLI

To enable log forwarding for a specific project using the [Upsun Cloud CLI](/cli),
follow the steps for your selected service.

<Tabs>
  <Tab title="New Relic">
    1. Get an API key from New Relic.
       You need a [license key](https://docs.newrelic.com/docs/apis/intro-apis/new-relic-api-keys/#license-key).
       Your New Relic organization likely has one, but you can create one by following the New Relic docs.
    2. Choose an API endpoint.
       You can use the U.S. endpoint `https://log-api.newrelic.com/log/v1`
       or the EU endpoint `https://log-api.eu.newrelic.com/log/v1`.
    3. Create the integration with the following command:

       ```bash theme={null}
       upsun integration:add --type newrelic --url <API_ENDPOINT> --license-key <LICENSE_KEY>
       ```

    View your logs in the **Logs** dashboard.
  </Tab>

  <Tab title="Splunk">
    1. In Splunk, get an Event Collector token on [Splunk Platform](https://docs.splunk.com/Documentation/Splunk/latest/Data/UsetheHTTPEventCollector#Create_an_Event_Collector_token_on_Splunk_Cloud_Platform)
       or [Splunk Enterprise](https://docs.splunk.com/Documentation/Splunk/latest/Data/UsetheHTTPEventCollector#Create_an_Event_Collector_token_on_Splunk_Enterprise).
    2. Determine your host, which is the Splunk instance that's collecting data.
    3. Choose an index name.
    4. Create the integration with the following command:

       ```bash theme={null}
       upsun integration:add --type splunk --url https://http-inputs.<HOST>.splunkcloud.com/services/collector/event --index <INDEX> --token <TOKEN>
       ```

    View your logs in the **Apps->Search & Reporting** dashboard.
    Filter by the index name to find the relevant events.
  </Tab>

  <Tab title="Sumo Logic">
    1. In Sumo Logic, [configure an HTTP source](https://www.sumologic.com/help/docs/send-data/hosted-collectors/http-source/logs-metrics/#configure-an-httplogs-and-metrics-source).
       Make sure to copy the Source Category and collector URL.
    2. Create the integration with the following command:

       ```bash theme={null}
       upsun integration:add --type sumologic --url <COLLECTOR_URL> --category <SOURCE_CATEGORY>
       ```

    View your logs in the **Log Search** tab.
  </Tab>
</Tabs>

To start forwarding logs, [trigger a redeploy](/docs/troubleshooting/general#force-a-redeploy).

#### In the Console

To enable log forwarding for a specific project from the Console,
follow these steps:

1. Navigate to your project.
2. Click <SettingsIcon /> **Settings**.
3. Click **Integrations**.
4. Click **Add Integration**.
5. Select the integration you want to enable.
6. In the **Configure your integration** window,
   specify your configuration options.
7. Click **Add Integration**.
   The new integration overview is displayed,
   and you can view your logs in the **Activity** section.

## Forward to a syslog endpoint

Syslog is a standard protocol for transferring log messages.
Many third-party services offer endpoints for ingesting syslog events.
You can forward your Upsun Cloud and Upsun Blackfire logs to any of those endpoints.

<Tabs>
  <Tab title="Using the CLI">
    To enable log forwarding to a syslog endpoint,
    run a command similar to the following:

    ```bash theme={null}
    upsun integration:add --type syslog --syslog-host <INGESTION_HOST> --syslog-port <INGESTION_HOST_PORT>
    ```

    `type`, `syslog-host`, and `syslog-port` are the only properties required for all endpoints.
    The following table shows the other available properties:

    | Property | Type | Default | Description |
    | - | - | - | - |
    | `auth-token` | `string` | | The token to authenticate with the given service. |
    | `auth-mode` | `string` | `prefix` | The mode for authentication with the given service. Can be `prefix` or `structured_data`. Defaults to `prefix`. |
    | `facility` | `string` | `1` (user) | A [syslog facility code](https://en.wikipedia.org/wiki/Syslog#Facility) to attach with each log to identify the source. Can be a number from 0 to 23. |
    | `message-format` | `string` | `rfc5424` | The standard to use for the message format. Can be `rfc5424` or `rfc3164`. |
    | `protocol` | `string` | `tls` | The network protocol to use in the connection. Can be one of `tls`, `tcp`, or `udp`. Defaults to `tls`. |
    | `verify-tls` | `boolean` | `true` | Whether to verify Transport Layer Security (TLS) certification when using the TLS protocol. |

    To include a property, add it as a flag, for example `--protocol tcp`.
    This should let you connect to any service that has syslog endpoints.

    To start forwarding logs, once you've added the service [trigger a redeploy](/docs/troubleshooting/general#force-a-redeploy).
  </Tab>

  <Tab title="In the Console">
    To enable log forwarding to a syslog endpoint for a specific project using the [Upsun Cloud CLI](/cli),
    follow these steps:

    1. Navigate to your project.
    2. Click <SettingsIcon /> **Settings**.
    3. Click **Integrations**.
    4. Click **Add Integration**.
    5. Select the syslog integration.
    6. In the **Configure your integration** window,
       specify your configuration options.
    7. Click **Add Integration**.
       The new integration overview is displayed,
       and you can view your logs in the **Activity** section.
  </Tab>
</Tabs>

## Forward to an HTTP endpoint

Some third-party services, such as [Elasticsearch](/docs/add-services/elasticsearch) and [OpenSearch](/docs/add-services/opensearch),
support ingesting log messages through an HTTP endpoint.
You can use HTTP forwarding to forward Upsun Cloud and Upsun Blackfire logs to such third-party services.

HTTP forwarding makes a `POST` HTTP request with an `application/json` body while forwarding the log messages to the endpoint.

As an example, to forward logs to Elasticsearch using HTTP log forwarding, run the following command:

```
upsun integration:add --type httplog --url "https://<ELASTICSEARCH_URL>/<INDEX_NAME>/_doc" --header "Authorization: Basic <basic_auth_token>" --header "Content-Type: application/json"
```

`type` and `url` are the only properties required for all endpoints.
Optionally, you can use the `headers` property to pass additional headers in the HTTP requests.

Note that if your endpoint URL includes a `PORT`, that can also be included in the `--url` flag:

```
upsun integration:add --type httplog --url "https://<ELASTICSEARCH_URL>:<PORT>/<INDEX_NAME>/_doc" --header "Authorization: Basic <basic_auth_token>" --header "Content-Type: application/json"
```

Once you've [added the service](/docs/add-services),
to start forwarding logs [trigger a redeploy](/docs/troubleshooting/general#force-a-redeploy).

## Log levels

Your app may output logs with distinct severity levels.
But as Upsun Cloud only reads logs from `stdout`,
this distinction is lost and everything gets logged at `INFO` level.

To preserve the original log level, use a language-specific syslog module/package for logging.

The following example code snippets show how logs can be written to Syslog:

<Tabs>
  <Tab title="PHP">
    ```php theme={null}
    openlog("", LOG_PID, LOG_LOCAL0);
    syslog(LOG_INFO, "Operation started");
    syslog(LOG_ERR, "Operation failed");
    closelog();
    ```
  </Tab>

  <Tab title="Python">
    Using the logging module:

    ```python theme={null}
    import logging
    import logging.handlers

    logger = logging.getLogger(__name__)
    logger.setLevel(logging.DEBUG)
    handler = logging.handlers.SysLogHandler(address="/dev/log")
    logger.addHandler(handler)

    logger.info("Operation started")
    logger.error("Operation failed")
    ```

    Using the Syslog module:

    ```python theme={null}
    import syslog

    syslog.openlog(logoption=syslog.LOG_PID, facility=syslog.LOG_LOCAL0)
    syslog.syslog(syslog.LOG_INFO, "Operation started")
    syslog.syslog(syslog.LOG_ERR, "Operation failed")
    syslog.closelog()
    ```
  </Tab>

  <Tab title="Go">
    Using the log package:

    ```go theme={null}
    package main

    import (
    	"log"
    	"log/syslog"
    )

    func main() {
    	logger, err := syslog.NewLogger(syslog.LOG_LOCAL0|syslog.LOG_INFO, log.LstdFlags)
    	if err != nil {
    		panic(err)
    	}

    	logger.Println("Operation started...")
    	logger.Fatalln("Operation failed")
    }

    ```

    Using the Syslog package:

    ```go theme={null}
    package main

    import (
    	"fmt"
    	"log"
    	"log/syslog"
    )

    func main() {
    	syslogWriter, err := syslog.Dial("", "", syslog.LOG_LOCAL0|syslog.LOG_INFO, "")
    	if err != nil {
    		log.Fatal(err)
    	}
    	defer syslogWriter.Close()

    	fmt.Fprintf(syslogWriter, "Operation has started")
    	syslogWriter.Err("Operation failed")
    }
    ```
  </Tab>
</Tabs>


# Consume logs
Source: https://developer.upsun.com/docs/observability/logs/index

See how to access or forward logs to get increased insights into your apps and services.

<CardGroup>
  <Card title="Access your logs" icon="terminal" href="/docs/observability/logs/access-logs">
    Access container and activity logs to understand how your apps are performing.
  </Card>

  <Card title="Forward logs" icon="send" href="/docs/observability/logs/forward-logs">
    Send your Upsun Cloud and Upsun Blackfire logs to a third-party service for further analysis.
  </Card>
</CardGroup>


# HTTP metrics
Source: https://developer.upsun.com/docs/observability/metrics/http-metrics

Understand HTTP metrics

The HTTP metrics dashboard provides Upsun Cloud users with network-related metrics.
Those insights are designed to help them better understand the state of their
applications.

Those metrics can be accessed by clicking the **HTTP metrics** tab on the
environment page within the Console.

The HTTP metrics dashboard can help you:

* Verify if there were any recent spikes in error responses
* Check bandwidth consumption to determine if there were any service interruptions
* Identify specific URLs causing site-wide issues
* Prioritize performance optimization (see [application metrics](/docs/observability/application-metrics))

<PerformanceAgentMention />

## HTTP requests status graph

The **HTTP requests** graph provides an aggregated view of the health of HTTP
requests made to the application. It reflects the status responses
(e.g. 1XX, 2XX, 3XX, 4XX, 5XX) of HTTP requests across a defined time frame.

This graph helps identify surge of error responses or periods of elevated
request activity.

## Bandwidth usage graph

The **Bandwidth** graph displays the data transfer volume. It represents
incoming (data the app receives) and outgoing (data the app sends) bandwidth
usage over time.

This graph helps identify bandwidth bottlenecks, optimize resource allocation,
and track bandwidth usage.

## Top 10 most impactful URLs

The **Top 10 URL Impact** graph and list pinpoint high-traffic or resource-intensive
URLs for targeted optimization or investigation. It showcases the evolution over
time of the top-10 most impactful URLs during a given time frame.

This graph helps identify potential trouble spots, understand user behavior, and
prioritize areas for optimization.

<Note>
  For security and privacy reasons, all URLs undergo the following sanitization measures:

  * All query parameters (`?param=value`) are sanitized to prevent leakage of sensitive information.
  * URLs exceeding 2048 characters are truncated to adhere to security best practices.
  * Specific sensitive URL paths are proactively scrubbed and anonymized.
</Note>


# Infrastructure metrics
Source: https://developer.upsun.com/docs/observability/metrics/index

See all of the live infrastructure metrics available to give you an overview of resource usage.

Upsun Cloud projects are accompanied by live infrastructure metrics that provide an overview of resource usage for environments.

Within the Console, metrics can be found for an environment under **Resources**.

The information under **Resources** shows usage metrics for:

Upsun Cloud environments: your service, app, and worker containers.
These metrics are available for all of your environments.

## Default thresholds

All of the graphs show color-coded lines for the following thresholds:

* Usage up to *100%* results.
* Usage that crosses *80%* results.
* Usage that crosses *90%* results.
* Usage that crosses *50%* results.

### Recommendations

The default thresholds aim to give you an idea of when your hosts or containers are close to running out of resources. The impact differs based on your specific apps and service.

If the resources are hovering close to the 100% threshold, you might want to consider:

* [Optimizing your code](/docs/observability/application-metrics) (if possible)
* [Changing your app size or service size](/docs/manage-resources)

<PerformanceAgentMention />

## Time intervals

Measurements are taken for each metric every 1 minute. You can select a time frame over which to see these measurements for the entire **Resources** view. In the primary three views, averages are shown over larger intervals.

| View | Time between measurements | Example |
| :- | :- | :- |
| The last 15 minutes (*15m*) | 1 minute | 10:00, 10:01, 10:02 |
| The last hour (*1hr*) | 1 minute | 10:00, 10:01, 10:02 |
| The last 8 hours (*8hr*) | 10 minutes | 10:00, 10:10, 10:20, 11:00 |

To zoom in on smaller intervals, select specific ranges in a graph.

The interval between measurements then changes based on the range you choose.

| View | Time between measurements |
| :- | :- |
| \< 2 hours | 1 minute |
| 2 to 5 hours | 5 minutes |
| 5+ hours | 20 minutes |

### Longer time intervals

You can access historical data for up to 30 days. These data should help you understand trends over time and whether a given measurement is normal, something that occurs occasionally, or a true anomaly.

To see data over a given time frame, use the date picker to select the range to display.

## Deployments

Sometimes deployment activities (pushes, merges, syncs) can influence the underlying infrastructure.
You don't want to confuse a spike caused by a successful deploy with an issue that needs your attention.

To see how deployment activity influences the infrastructure, turn on **Deployments** on your metrics.

Each deployment activity appears as a line on each graph corresponding to the time the activity finished.

* To see information about the deployment activity, hover over the line.
* To see the build log for a specific deployment activity, click the line.


# Understand  metrics
Source: https://developer.upsun.com/docs/observability/metrics/understand-metrics

Understand how to read metrics for Upsun Cloud environments.

Upsun Cloud environments consist of:

* App containers: one or more [app containers](/docs/configure-apps)
* Service containers: zero or more [service containers](/docs/add-services)
* Worker containers: zero or more [worker instances](/docs/configure-apps/image-properties/workers).

Infrastructure metrics report CPU, RAM, and disk space for app, service, and worker containers.
These metrics are available for all of your environments.

App containers are shown first, with the app name and an image corresponding to the app type.
Service containers follow next with the same pattern, and worker containers are shown last.

You can collapse the graphs by clicking the 3-dot menu on the right-hand side, then **Hide resources**.
The graphs switch to an overview of the average resource utilization for the selected container.

<img alt="How service container metrics look when minimized" />

The same menu provides a convenient **Configure resource** CTA, allowing you to swiftly
adjust resources allocation for that container based on the observability metrics.

<PerformanceAgentMention />

## Example of how to read metrics

This example should give you an idea of how the metrics appear.
Environment metrics show resource usage for each app, service, and worker container.

This reference project has a single app, two services (MySQL and Redis), and two workers.
The appropriate resources have been [manually allocated](/docs/manage-resources) for each container.
The graphs show the current average usage in relation to the resources allocated to each container.

By default, the graphs include all instances and an average over the instances.
To select metrics for specific instances, click **Filter**.

<img alt="Clicking Filter reveals a list of instances you can filter" />

### App container

Metrics graphs for the app container show CPU, RAM, and disk allocation and usage.
The persistent disk has been configured in the [project resources](/docs/manage-resources).

<img alt="All of the metrics for the app container" />

### Service containers

Metrics graphs for the service containers show CPU, RAM, and disk allocation and usage.

#### MySQL

Metrics graphs for the MySQL service container show CPU, RAM, and disk allocation and usage.
The persistent disk has been configured in the [project resources](/docs/manage-resources).

<img alt="All of the metrics for the MySQL container" />

#### Redis

Metrics graphs for the Redis service container show CPU, RAM, disk allocation and usage.
No persistent disk has been configured for Redis.

<img alt="All of the metrics for the Redis container" />

### Worker containers

Metrics graphs for the App-Horizon worker container show CPU, RAM, and disk allocation and usage.
The persistent disk has been configured in the [project resources](/docs/manage-resources).

<img alt="All of the metrics for the App-Horizon worker container" />

Metrics graphs for the App-Schedule worker container show CPU, RAM, and disk allocation and usage.

The persistent disk has been configured in the [project resources](/docs/manage-resources).

<img alt="All of the metrics for the App-Horizon worker container" />


# Change the project timezone
Source: https://developer.upsun.com/docs/projects/change-project-timezone

See how to change the timezone for a project and what it affects.

The project timezone affects [automated backups](/docs/environments/backup) and the day and time you choose for your [maintenance window](/docs/core-concepts/build-deploy#maintenance-window).

The project timezone doesn't affect:

* [App runtime](/docs/configure-apps/timezone).
* [Cron jobs](/docs/configure-apps/image-properties/crons).
* [System logs](/docs/observability/logs). UTC is the default timezone for all logs.

To change the timezone for a project, follow these steps:

1. Open the project where you want to change the timezone.
2. Click <SettingsIcon /> **Settings**.
3. Select the timezone from the list.
4. Click **Save**.


# Delete a project
Source: https://developer.upsun.com/docs/projects/delete-project

See how to delete projects you no longer need.

To delete a project, you must be an organization owner or have the [manage plans permission](/docs/administration/users#organization-permissions).

<Note>
  If your project has custom domains attached, you must remove the default domain  before you can delete the project.
  To do so, run `upsun domain:delete <YOUR_DOMAIN>` or go to your project's **Settings** > **Domains** in the Console.
</Note>

To delete an Upsun Cloud project, including all data, code, and active environments:

<Tabs>
  <Tab title="In the Console">
    1. On the tile of the project you want to delete, click **<MoreIcon /> More**.
    2. Click **Project settings**.
    3. Click **Delete project**.
    4. To confirm your choice, enter the project's name.
    5. Click **Yes, Delete Project**.
  </Tab>

  <Tab title="Using the CLI">
    1. Run the following command:

       ```bash theme={null}
       upsun project:delete --project <PROJECT_ID>
       ```

    2. Read the consequences to deletion and enter `y`.

    3. Enter the project title to confirm.
  </Tab>
</Tabs>

You are billed only for the portion of a month when the project was active.

When you remove all your projects from your user account,
you stop being charged.


# Manage projects
Source: https://developer.upsun.com/docs/projects/index

Learn about projects on Upsun Cloud and how to configure them.

See how to manage projects within Upsun Cloud.
To create a project, see how to [get started](/docs/get-started).

<CardGroup>
  <Card title="Project settings" icon="settings" href="/docs/projects/settings">
    Change your project's region, timezone, or delete a project.
  </Card>

  <Card title="Custom domains" icon="globe" href="/docs/domains">
    Set up custom domains, DNS, TLS, and CDN for your project.
  </Card>

  <Card title="Administration" icon="users" href="/docs/administration/web">
    Manage your Console, organizations, teams, users, billing, and security.
  </Card>

  <Card title="Security & compliance" icon="shield" href="/docs/security">
    WAF, data retention, and project isolation.
  </Card>
</CardGroup>


# Change a project's region
Source: https://developer.upsun.com/docs/projects/region-migration

See how to change the region your project is in and why you might want to do so.

To host your project data, Upsun Cloud offers several [regions](/docs/development/regions).
You specify a region when you create a project.

You can also change the project's region after it's created.

## Why migrate between regions

* Different data centers are located in different geographic areas.
  You may want your site close to your users for improved performance.
* You may want to move to a region with a lower [environmental impact](/docs/development/regions#environmental-impact).

## 1. Plan the migration

Before starting the migration process, you need to plan for it:

* Plan a time frame in which to handle the migration.
  Your code shouldn't change during this time to ensure all changes are copied to the new project.
  Prepare for a brief site outage when you migrate, just as with a relaunch of a site.
* Set your DNS Time-to-Live as low as possible.
  This ensures the switch to the new site propagates as quickly as possible.

## 2. Create a new project

In the target region, [create a new project from scratch](https://console.upsun.com/org/create-project/info).

If you plan to test for long, start with the least amount of resources on the project and then upsize it before switching the DNS.

## 3. Add code and environments

<Tabs>
  <Tab title="Without a source integration">
    1. Clone your existing project with Git.

    2. In the new clone, add a remote for the project:

       ```bash theme={null}
       upsun project:set-remote
       ```

       Select your newly created blank project.

    3. Push the code for your production branch:

       ```bash theme={null}
       upsun push --target <PRODUCTION_BRANCH_NAME>
       ```

    4. (Optional) Checkout other branches and then push their code:

       ```bash theme={null}
       upsun push --activate --target <BRANCH_NAME> --parent <PRODUCTION_BRANCH_NAME>
       ```
  </Tab>

  <Tab title="With a source integration">
    For a [source integration](/docs/integrations/source) with GitHub, BitBucket, or GitLab,
    add the integration to your new project.
    Your new project then mirrors the configured repository automatically.
  </Tab>
</Tabs>

## 4. Copy files

If you have files in a mount, first download them:

```bash theme={null}
upsun mount:download
```

Then upload them to your new project:

```bash theme={null}
upsun mount:upload
```

See more options on [how to export files](/docs/core-concepts/common-tasks/exporting)
and [how to import files](/tutorials/migration/from-fixed#6-import-data).

## 5. Copy data from services

For services with generated data such as Solr and Redis, you don't need to copy data directly.
Just rebuild the data in the new project.

To download data from persistent services such as databases,
see how to export and then import data for each service:

* [InfluxDB](/docs/add-services/influxdb#export-data)
* [MongoDB](/docs/add-services/mongodb#exporting-data)
* [MariaDB/MySQL](/docs/add-services/mysql#exporting-data)
* [PostgreSQL](/docs/add-services/postgresql#exporting-data)

## 6. Migrate variables and project settings

Make sure anything else connected to your old project is moved to your new project:

* If you have project or environment variables defined on your old project, add them to your new project.
  Get a list of all variables set outside of code by running `upsun variables`.
* Add any users to your new project that you want to continue to have access.
* Add any existing [integrations](/docs/integrations).

## 7. Test the site

Verify that the new site is working as desired before continuing.
You can leave the two projects running for as long as you need.
After you have finished all your testing, sync all your data (code, files, database) for the last time.

## 8. Switch to the new site

Now that you know the new project works, switch public traffic to that site:

1. Make sure your new project has the [necessary resources](/docs/manage-resources/adjust-resources).
2. If possible, put your site into read-only mode or maintenance mode.
3. Add your domain names to your new project and remove them from the old project.
4. (Optional) Add any custom SSL certificates you have.
5. Update your DNS provider's records to point to the new site. See more on [setting custom domains](/docs/domains/steps).

It may take some time for the DNS change and SSL change to propagate.
Until it does, some browsers may not see the new site or may get an SSL mismatch error.
In most cases that resolves itself in 1--3 hours.

## 9. Remove the old project

Once the new project is running and the DNS has fully propagated, delete the old project.

## Alternative process

We have open-sourced [the Upsun Cloud cloning tool](https://github.com/upsun/clonsun), which allows you to clone a project from one region to another. This cloning tool helps you migrate most of your project assets from one region to another with some remaining manual steps like moving your domain names from one region to the other (or at the CDN level) and update your DNS records.

We also have [the Upsun Cloud converting tool](https://github.com/upsun/convsun), which allows you to change existing configuration files to another format. It converts details from files like `services.yaml` and `routes.yaml`, and generates a new `config.yaml` file. This streamlines the conversion process by significantly reducing the manual effort required to adapt your app’s infrastructure setup.

<Info>
  To learn more about the converter tool and how it works, read the [converting projects](/tutorials/migration/from-fixed) page.
</Info>

Although not directly supported by Upsun Cloud,
an agency named [Contextual Code](https://www.contextualcode.com/) has built a bash migration script.
This script automates most common configurations.
If your site is a typical single app with a single SQL database,
the script should take care of most of the process for you.

See more at the [Upsun Cloud Project Migration repository](https://gitlab.com/contextualcode/platformsh-migration).


# Project settings
Source: https://developer.upsun.com/docs/projects/settings

Manage your project's region, timezone, and lifecycle.

<CardGroup>
  <Card title="Change a project's region" icon="map" href="/docs/projects/region-migration">
    See how to change the region your project is in and why you might want to do so.
  </Card>

  <Card title="Change the project timezone" icon="clock" href="/docs/projects/change-project-timezone">
    See how to change the timezone for a project and what it affects.
  </Card>

  <Card title="Delete a project" icon="trash" href="/docs/projects/delete-project">
    See how to delete projects you no longer need.
  </Card>

  <Card title="Set a maintenance window" icon="clock" href="/docs/core-concepts/build-deploy#maintenance-window">
    See how to schedule when platform updates are applied to your project.
  </Card>
</CardGroup>


# Data Register
Source: https://developer.upsun.com/docs/registry/index

A comprehensive register of data categories across the Upsun Cloud platform, including export methods and Data Act classifications.

This page provides a comprehensive overview of all data categories managed across the Upsun Cloud platform,
including their classification under the EU Data Act, export availability, and relevant documentation.

<Note>
  This register is maintained to support compliance with the **EU Data Act** and to help you understand
  what data is stored, how it's classified, and how to export it.
</Note>

## Control Plane

Data managed through the Upsun Cloud management layer, including organization, project, and environment metadata.

<AccordionGroup>
  <Accordion title="Organization & Identity Metadata">
    | Property | Details |
    | - | - |
    | **Data Category** | Organization & Identity Metadata |
    | **Examples** | Organizations, members, teams, roles, user associations |
    | **Data Act Classification** | Digital Asset |
    | **Exportable Today** | Yes |
    | **Export Method** | Management API / CLI (API-backed) |
    | **Documentation** | [Management API](https://api.upsun.com/docs/) |
  </Accordion>

  <Accordion title="Project Metadata">
    | Property | Details |
    | - | - |
    | **Data Category** | Project Metadata |
    | **Examples** | Project IDs, titles, regions, plan/subscription metadata |
    | **Data Act Classification** | Digital Asset |
    | **Exportable Today** | Yes |
    | **Export Method** | Management API / CLI |
    | **Documentation** | [Management API](https://api.upsun.com/docs/) |
  </Accordion>

  <Accordion title="Environment Metadata">
    | Property | Details |
    | - | - |
    | **Data Category** | Environment Metadata |
    | **Examples** | Environment IDs, names, parent relationships, status |
    | **Data Act Classification** | Digital Asset |
    | **Exportable Today** | Yes |
    | **Export Method** | Management API / CLI |
    | **Documentation** | [Management API](https://api.upsun.com/docs/) |
  </Accordion>

  <Accordion title="Deployment Configuration Metadata">
    | Property | Details |
    | - | - |
    | **Data Category** | Deployment Configuration Metadata |
    | **Examples** | Routes, services definitions, variables in deployment payloads |
    | **Data Act Classification** | Digital Asset |
    | **Exportable Today** | Partial |
    | **Export Method** | API / CLI / Git config export |
    | **Documentation** | [Management API](https://api.upsun.com/docs/) |
  </Accordion>
</AccordionGroup>

## Workload Plane

Data stored and managed within your application environments, including source code, databases, file storage, and service data.

### Application Data

<AccordionGroup>
  <Accordion title="Source Code Repository">
    | Property | Details |
    | - | - |
    | **Data Category** | Source Code Repository |
    | **Examples** | Git history, branches, tags |
    | **Data Act Classification** | Exportable Data |
    | **Exportable Today** | Yes |
    | **Export Method** | Git clone / fetch |
    | **Documentation** | [Download your app's code](/docs/core-concepts/common-tasks/exporting#1-download-your-app’s-code) |
  </Accordion>

  <Accordion title="Persistent File Mounts">
    | Property | Details |
    | - | - |
    | **Data Category** | Persistent File Mounts |
    | **Examples** | User uploads, generated assets, stored files |
    | **Data Act Classification** | Exportable Data |
    | **Exportable Today** | Yes |
    | **Export Method** | CLI / SSH file transfer |
    | **Documentation** | [Download your files](/docs/core-concepts/common-tasks/exporting#2-download-your-files) |
  </Accordion>

  <Accordion title="Environment Variables">
    | Property | Details |
    | - | - |
    | **Data Category** | Environment Variables |
    | **Examples** | User-defined variables, PLATFORM\_VARIABLES payload |
    | **Data Act Classification** | Digital Asset |
    | **Exportable Today** | Yes |
    | **Export Method** | CLI / SSH export (decode variables) |
    | **Documentation** | [Get environment variables](/docs/core-concepts/common-tasks/exporting#4-get-environment-variables) |
  </Accordion>
</AccordionGroup>

### Databases

<AccordionGroup>
  <Accordion title="MariaDB/MySQL">
    | Property | Details |
    | - | - |
    | **Data Category** | Database Data |
    | **Examples** | Schemas, tables, records |
    | **Data Act Classification** | Exportable Data |
    | **Exportable Today** | Yes |
    | **Export Method** | `upsun db:dump` |
    | **Documentation** | [MariaDB/MySQL](/docs/add-services/mysql#exporting-data) \| [Exporting data](/docs/core-concepts/common-tasks/exporting#relational-databases) |
  </Accordion>

  <Accordion title="PostgreSQL">
    | Property | Details |
    | - | - |
    | **Data Category** | Database Data |
    | **Examples** | Schemas, tables, records |
    | **Data Act Classification** | Exportable Data |
    | **Exportable Today** | Yes |
    | **Export Method** | `upsun db:dump` / `pg_dump` via tunnel |
    | **Documentation** | [PostgreSQL](/docs/add-services/postgresql#exporting-data) \| [Exporting data](/docs/core-concepts/common-tasks/exporting#relational-databases) |
  </Accordion>

  <Accordion title="MongoDB">
    | Property | Details |
    | - | - |
    | **Data Category** | Database Data |
    | **Examples** | Collections, documents |
    | **Data Act Classification** | Exportable Data |
    | **Exportable Today** | Yes |
    | **Export Method** | `upsun tunnel:open` + `mongodump` |
    | **Documentation** | [MongoDB](/docs/add-services/mongodb#exporting-data) \| [Exporting data](/docs/core-concepts/common-tasks/exporting#document-and-time-series-databases) |
  </Accordion>

  <Accordion title="InfluxDB">
    | Property | Details |
    | - | - |
    | **Data Category** | Time-series Data |
    | **Examples** | Buckets, measurements |
    | **Data Act Classification** | Exportable Data |
    | **Exportable Today** | Yes |
    | **Export Method** | `upsun tunnel:single` + `influx backup` |
    | **Documentation** | [InfluxDB](/docs/add-services/influxdb#export-data) \| [Exporting data](/docs/core-concepts/common-tasks/exporting#document-and-time-series-databases) |
  </Accordion>

  <Accordion title="ClickHouse">
    | Property | Details |
    | - | - |
    | **Data Category** | Analytical Database Data |
    | **Examples** | Tables, datasets |
    | **Data Act Classification** | Exportable Data |
    | **Exportable Today** | Yes |
    | **Export Method** | Service-native tooling over tunnel |
    | **Documentation** | [ClickHouse](/docs/add-services/clickhouse#exporting-data) \| [Exporting data](/docs/core-concepts/common-tasks/exporting#document-and-time-series-databases) |
  </Accordion>
</AccordionGroup>

### Search Engines

<AccordionGroup>
  <Accordion title="OpenSearch">
    | Property | Details |
    | - | - |
    | **Data Category** | Search Index Data |
    | **Examples** | Indexes, mappings |
    | **Data Act Classification** | Exportable Data |
    | **Exportable Today** | Yes |
    | **Export Method** | Service snapshot APIs |
    | **Documentation** | [OpenSearch](/docs/add-services/opensearch#exporting-data) \| [Exporting data](/docs/core-concepts/common-tasks/exporting#search-engines) |
  </Accordion>

  <Accordion title="Elasticsearch">
    | Property | Details |
    | - | - |
    | **Data Category** | Search Index Data |
    | **Examples** | Indexes, mappings |
    | **Data Act Classification** | Exportable Data |
    | **Exportable Today** | Yes |
    | **Export Method** | Snapshot APIs |
    | **Documentation** | [Elasticsearch](/docs/add-services/elasticsearch#exporting-data) \| [Exporting data](/docs/core-concepts/common-tasks/exporting#search-engines) |
  </Accordion>

  <Accordion title="Solr">
    | Property | Details |
    | - | - |
    | **Data Category** | Search Index Data |
    | **Examples** | Indexes, configsets |
    | **Data Act Classification** | Exportable Data (often rebuildable) |
    | **Exportable Today** | No (rebuildable) |
    | **Export Method** | Rebuild from primary data store |
    | **Documentation** | [Solr](/docs/add-services/solr) |

    <Info>Solr indexes are generally rebuildable from the primary data store. Export is not typically necessary.</Info>
  </Accordion>
</AccordionGroup>

### Caching & Data Stores

<AccordionGroup>
  <Accordion title="Redis">
    | Property | Details |
    | - | - |
    | **Data Category** | Cache Data |
    | **Examples** | Key-value cache entries |
    | **Data Act Classification** | Exportable Data (if persistent) |
    | **Exportable Today** | Yes (persistent) |
    | **Export Method** | RDB/AOF backup |
    | **Documentation** | [Redis](/docs/add-services/redis#exporting-data-persistent) \| [Exporting data](/docs/core-concepts/common-tasks/exporting#key-value-stores-persistent) |

    <Info>Ephemeral Redis stores data only in memory and does not need to be exported. Persistent Redis data can be exported.</Info>
  </Accordion>

  <Accordion title="Valkey">
    | Property | Details |
    | - | - |
    | **Data Category** | Cache/Data Store |
    | **Examples** | Key-value data |
    | **Data Act Classification** | Exportable Data (if persistent) |
    | **Exportable Today** | Yes (persistent) |
    | **Export Method** | Service-native backup |
    | **Documentation** | [Valkey](/docs/add-services/valkey#exporting-data-persistent) \| [Exporting data](/docs/core-concepts/common-tasks/exporting#key-value-stores-persistent) |

    <Info>Ephemeral Valkey stores data only in memory and does not need to be exported. Persistent Valkey data can be exported.</Info>
  </Accordion>

  <Accordion title="Memcached">
    | Property | Details |
    | - | - |
    | **Data Category** | Cache |
    | **Examples** | Ephemeral cache entries |
    | **Data Act Classification** | Exportable Data (not durable-of-record) |
    | **Exportable Today** | No |
    | **Export Method** | Not applicable (ephemeral) |
    | **Documentation** | [Memcached](/docs/add-services/memcached) |

    <Info>Memcached is ephemeral by nature. No export is required.</Info>
  </Accordion>

  <Accordion title="Varnish">
    | Property | Details |
    | - | - |
    | **Data Category** | HTTP Cache |
    | **Examples** | Cached HTTP responses |
    | **Data Act Classification** | Exportable Data (not durable-of-record) |
    | **Exportable Today** | No |
    | **Export Method** | Not applicable (cache) |
    | **Documentation** | [Varnish](/docs/add-services/varnish) |

    <Info>Varnish is a cache layer. No export is required.</Info>
  </Accordion>
</AccordionGroup>

### Message Queues & Event Streams

<AccordionGroup>
  <Accordion title="RabbitMQ">
    | Property | Details |
    | - | - |
    | **Data Category** | Message Queue Data |
    | **Examples** | Queues, exchanges, messages |
    | **Data Act Classification** | Exportable Data (context dependent) |
    | **Exportable Today** | Yes |
    | **Export Method** | Broker export tools |
    | **Documentation** | [RabbitMQ](/docs/add-services/rabbitmq#exporting-data) \| [Exporting data](/docs/core-concepts/common-tasks/exporting#message-brokers) |
  </Accordion>

  <Accordion title="Kafka">
    | Property | Details |
    | - | - |
    | **Data Category** | Event Streams |
    | **Examples** | Topics, partitions, messages |
    | **Data Act Classification** | Exportable Data (context dependent) |
    | **Exportable Today** | Yes |
    | **Export Method** | Consumer-based export |
    | **Documentation** | [Kafka](/docs/add-services/kafka#exporting-data) \| [Exporting data](/docs/core-concepts/common-tasks/exporting#message-brokers) |
  </Accordion>
</AccordionGroup>

### Vector Databases

<AccordionGroup>
  <Accordion title="Qdrant">
    | Property | Details |
    | - | - |
    | **Data Category** | Vector Database Data |
    | **Examples** | Vector collections, points, payloads |
    | **Data Act Classification** | Exportable Data |
    | **Exportable Today** | Yes |
    | **Export Method** | Qdrant Snapshot API |
    | **Documentation** | [Qdrant](/tutorials/self-hosted/qdrant#exporting-data) \| [Exporting data](/docs/core-concepts/common-tasks/exporting#vector-databases) |
  </Accordion>

  <Accordion title="Chroma">
    | Property | Details |
    | - | - |
    | **Data Category** | Vector Database Data |
    | **Examples** | Vector collections, embeddings, metadata |
    | **Data Act Classification** | Exportable Data |
    | **Exportable Today** | Yes |
    | **Export Method** | CLI / rsync (SQLite files) |
    | **Documentation** | [Chroma](/tutorials/self-hosted/chroma#exporting-data) \| [Exporting data](/docs/core-concepts/common-tasks/exporting#vector-databases) |
  </Accordion>
</AccordionGroup>

### Stateless Processing Services

<AccordionGroup>
  <Accordion title="Gotenberg">
    | Property | Details |
    | - | - |
    | **Data Category** | Stateless Processing |
    | **Examples** | Generated PDFs (stored elsewhere) |
    | **Data Act Classification** | Exportable Data (if stored) |
    | **Exportable Today** | Yes |
    | **Export Method** | [Export via file mounts](/docs/core-concepts/common-tasks/exporting#2-download-your-files) |
    | **Documentation** | [Gotenberg](/docs/add-services/gotenberg) |

    <Info>Gotenberg is stateless. Any generated output is stored in your file mounts.</Info>
  </Accordion>

  <Accordion title="Headless Chrome">
    | Property | Details |
    | - | - |
    | **Data Category** | Stateless Processing |
    | **Examples** | Generated artifacts (if stored) |
    | **Data Act Classification** | Exportable Data (if stored) |
    | **Exportable Today** | Yes |
    | **Export Method** | [Export via file mounts](/docs/core-concepts/common-tasks/exporting#2-download-your-files) |
    | **Documentation** | [Headless Chrome](/docs/add-services/headless-chrome) |

    <Info>Headless Chrome is stateless. Any generated output is stored in your file mounts.</Info>
  </Accordion>
</AccordionGroup>

## Security Services

<AccordionGroup>
  <Accordion title="Vault KMS">
    | Property | Details |
    | - | - |
    | **Data Category** | Keys & Policies |
    | **Examples** | Transit keys, policies, configuration |
    | **Data Act Classification** | Digital Asset |
    | **Exportable Today** | Partial |
    | **Export Method** | Vault API |
    | **Documentation** | [Vault](/docs/add-services/vault) |

    <Warning>Key export stance and procedures need clarification.</Warning>
  </Accordion>
</AccordionGroup>

## Non-Exportable Data

The following categories of data are internal to the Upsun Cloud platform and are **not exportable**.
These are not customer-specific and fall outside the scope of the EU Data Act's data portability requirements.

| Data Category | Examples | Reason |
| - | - | - |
| Provider Internal Telemetry | Infrastructure metrics, internal abuse signals | Provider internal operational data (trade secrets) |
| Internal Security Artifacts | Internal security monitoring, platform controls | Security-sensitive provider IP |
| Multi-tenant Derived Data | Aggregated analytics across customers | Not customer-specific data |


# Request features
Source: https://developer.upsun.com/docs/request-features/index

We're always open to new and fresh ideas that can help improve our product. Learn how to make a feature request and engage with the Upsun community.

## How to submit a feature request

If you'd like to submit a feature request, there are two ways for you to do so:

### If you already have an Upsun account

You can open a [support ticket](/docs/core-concepts/get-support) directly from [your Console](https://console.upsun.com/). Simply describe your needs and our team will take it from there.

### For non-account holders or those who prefer a chat

Join us on the [Community Forum](https://community.upsun.com/) where you can share your ideas and discuss them with our community and team members.

<Info>
  <h4>We love to hear from you!</h4>
  Your input helps us make our platform even better. Thank you for contributing.
</Info>


# HTTP cache
Source: https://developer.upsun.com/docs/routes/cache

Upsun Cloud supports HTTP caching at the server level. Caching is enabled by default, but is only applied to `GET` and `HEAD` requests.


The cache can be controlled using the `cache` key in your `.upsun/config.yaml` file.

If a request can be cached, Upsun Cloud builds a cache key from several request properties and stores the response associated with this key.
When a request comes with the same cache key, the cached response is reused.

When caching is on...

* you can configure cache behavior for different location blocks in your `.upsun/config.yaml`;
* the router respects whatever cache headers are sent by the application;
* cookies bypass the cache;
* responses with the `Cache-Control` header set to `Private`, `No-Cache`, or `No-Store` aren't cached.

You should *not* use the Upsun Cloud HTTP cache if you're using [Varnish](/docs/add-services/varnish) or an external CDN
such as [Fastly](/docs/domains/cdn/fastly) or [Cloudflare](/docs/domains/cdn/cloudflare).
Mixing cache services together most likely results in caches that are stale and can't be cleared.
For more details, see [best practices on HTTP caching](/docs/core-concepts/best-practices/http-caching).

## Basic usage

The HTTP cache is enabled by default, however you may wish to override this behavior.

To configure the HTTP cache, add a `cache` key to your route. You may like to start with the defaults:

```yaml .upsun/config.yaml theme={null}
routes:
  https://{default}/:
    type: upstream
    upstream: myapp:http
    cache:
      enabled: true
      default_ttl: 0
      cookies: ['*']
      headers: ['Accept', 'Accept-Language']
```

## Example

In this example, requests are cached based on the URI, the `Accept` header, `Accept-Language` header, and `X-Language-Locale` header.
Any response that lacks a `Cache-Control` header is cached for 60 seconds.
The presence of any cookie in the request disables caching of that response.

```yaml .upsun/config.yaml theme={null}
routes:
  https://{default}/:
    type: upstream
    upstream: myapp:http
    cache:
      enabled: true
      headers: ['Accept', 'Accept-Language', 'X-Language-Locale']
      cookies: ['*']
      default_ttl: 60
```

## How it works

### The cache key

If a request can be cached, Upsun Cloud builds a cache key from several request properties and stores the response associated with this key. When a request comes with the same cache key, the cached response is reused.

There are two parameters that let you control this key: `headers` and `cookies`.

The default value for these keys are the following:

```yaml .upsun/config.yaml theme={null}
routes:
  https://{default}/:
    # ...
    cache:
      enabled: true
      cookies: ['*']
      headers: ['Accept', 'Accept-Language']
```

### Duration

The cache duration is decided based on the `Cache-Control` response header value. If no `Cache-Control` header is in the response, then the value of `default_ttl` key is used.

### Conditional requests

Conditional requests using `If-Modified-Since` and `If-None-Match` are both supported. The web server doesn't honor the `Pragma` request header.

### Cache revalidation

When the cache is expired (indicated by `Last-Modified` header in the response) the web server sends a request to your application with `If-Modified-Since` header.

If the `If-None-Match` header is sent in the conditional request when `Etag` header is set in the cached response, your application can extend the validity of the cache by replying `HTTP 304 Not Modified`.

### Flushing

The HTTP cache doesn't support a complete cache flush, but you can invalidate the cache by setting `cache: false`. Alternatively, the cache clears on a rebuild, so triggering a rebuild (pushing a new commit) effectively causes a complete cache flush.

## Cache configuration properties

### `enabled`

Turns the cache on or off for a route.

<Note>
  <h4>none</h4>
  **Type:** Boolean

  **Required:** Yes

  **Values**

  * `true`: enable the cache for this route \[default, but only if the `cache` key isn't actually specified]
  * `false`: disable the cache for this route
</Note>

### `headers`

Adds specific header fields to the cache key, enabling caching of separate responses for those headers.

For example, if the `headers` key is the following, Upsun Cloud caches a different response for each value of the `Accept` HTTP request header only:

```yaml .upsun/config.yaml theme={null}
routes:
  https://{default}/:
    # ...
    cache:
        enabled: true
        headers: ["Accept"]
```

<Note>
  <h4>none</h4>
  **Type:** List

  **Values:**

  * `['Accept', 'Accept-Language']`: Cache on Accept & Accept-Language \[default]
</Note>

#### Header behaviors

The cache is only applied to `GET` and `HEAD` requests. Some headers trigger specific behaviors in the cache.

| Header field | Cache behavior |
| - | - |
| `Cache-Control` | Responses with the `Cache-Control` header set to `Private`, `No-Cache`, or `No-Store` aren't cached. All other values override `default_ttl`. |
| `Vary` | A list of header fields to be taken into account when constructing the cache key. Multiple header fields can be listed, separated by commas. The Cache key is the union of the values of the Header fields listed in Vary header, and whatever is listed in the `.upsun/config.yaml` file. |
| `Set-Cookie` | Not cached |
| `Accept-Encoding`, `Connection`, `Proxy-Authorization`, `TE`, `Upgrade` | Not allowed, and throws an error |
| `Cookie` | Not allowed, and throws an error. Use the `cookies` value, instead. |
| `Pragma` | Ignored |

A full list of HTTP headers is available on [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_header_fields).

### `cookies`

The `cookies` key allows you to define a list of cookies you want to include in the cache key, if any.

| Possible values | Description | Default |
| - | - | - |
| `['*']` | Any request with a cookie bypasses the cache.<br /><br /> Note that this is achieved by Upsun Cloud adding the `X-Platform-Cache: BYPASS` HTTP header in the router, and that the same behaviour applies if the `Set-Cookie` header is present. | Yes |
| `[]` | Ignore all cookies. | No |
| `['cookie_1','cookie_2']` | A list of allowed cookies to include in the cache key. All other cookies are ignored. | No |

#### Example with a single value

With the following configuration, the cache key depends on the value of the `foo` cookie in the request.
Other cookies are ignored.

```yaml .upsun/config.yaml theme={null}
routes:
  https://{default}/:
    # ...
    cache:
      enabled: true
      cookies: ["foo"]
```

#### Example with a regular expression

A cookie value can also be a regular expression.
An entry that begins and ends with a `/` is interpreted as a PCRE regular expression to match the cookie name.
For example:

```yaml .upsun/config.yaml theme={null}
routes:
  https://{default}/:
    # ...
    cache:
      enabled: true
      cookies: ['/^SS?ESS/']
```

This configuration causes all cookies beginning with `SESS` or `SSESS` to be part of the cache key, as a single value.
Other cookies are ignored for caching.

If your site uses a session cookie as well as third-party cookies, say from an analytics service,
this is the recommended approach.

### `default_ttl`

Defines the default time-to-live for the cache, in seconds, for non-static responses, when the response doesn't specify one.

The cache duration is decided based on the `Cache-Control` response header value. If no `Cache-Control` header is in the response, then the value of `default_ttl` is used. If the application code returns a `Cache-Control` header or if your `.upsun/config.yaml` file is configured to set a cache lifetime, then this value is ignored in favor of the application headers.

The `default_ttl` only applies to **non-static responses**, that is, those generated by your application.

To set a cache lifetime for static resources configure that in your [app configuration](/docs/configure-apps/image-properties/web#locations).
All static assets have a Cache-Control header with a max age defaulting to 0 (which is the default for `expires`).

<Note>
  <h4>none</h4>
  **Type:** integer

  **Values:**

  * `0`: Do not cache \[default]. This prevents caching, *unless* the response specifies a `Cache-Control` header value.
</Note>

## Debugging

Upsun Cloud adds an `X-Platform-Cache` header to each request which show whether your request is a cache `HIT`, `MISS` or `BYPASS`. This can be useful when trying to determine whether it's your application, the HTTP cache, or another proxy or CDN which isn't behaving as expected.

If in doubt, disable the cache using `cache: false`.

## Advanced caching strategies

### Cache per route

If you need fine-grained caching, you can set up caching rules for several routes separately:

```yaml .upsun/config.yaml theme={null}
routes:
  https://{default}/:
    type: upstream
    upstream: myapp:http
    cache:
      enabled: true

  https://{default}/foo/:
    type: upstream
    upstream: myapp:http
    cache:
      enabled: false

https://{default}/foo/bar/:
  type: upstream
  upstream: myapp:http
  cache:
    enabled: true
```

With this configuration, the following routes are cached:

* `https://{default}/`
* `https://{default}/foo/bar/`
* `https://{default}/foo/bar/baz/`

And the following routes are **not** cached:

* `https://{default}/foo/`
* `https://{default}/foo/baz/`

<Note>
  Regular expressions in routes are **not** supported.
</Note>

### Allowing only specific cookies

Some applications use cookies to invalidate cache responses, but expect other cookies to be ignored.
This is a case of allowing only a subset of cookies to invalidate the cache.

```yaml .upsun/config.yaml theme={null}
routes:
  https://{default}/:
    # ...
    cache:
      enabled: true
      cookies: ["MYCOOKIE"]
```

### Cache HTTP and HTTPS separately using the `Vary` header

Set the Vary header to `X-Forwarded-Proto` [custom request header](/docs/development/headers) to render content based on the request protocol (i.e. HTTP or HTTPS). By adding `Vary: X-Forwarded-Proto` to the response header, HTTP and HTTPS content would be cached separately.

### Cache zipped content separately

Use `Vary: Accept-Encoding` to serve different content depending on the encoding. Useful for ensuring that gzipped content isn't served to clients that can't read it.


# HTTPS
Source: https://developer.upsun.com/docs/routes/https

Learn how to enable HTTPS for your site and configure TLS connections.

Using HTTPS for your site helps ensure your users' information remains secure.
HTTPS provides enhanced security thanks to the following characteristics:

* With HTTPS, data is encrypted so user activity can't be tracked and user information can't be stolen.
* HTTPS prevents the corruption of files transferred from a web server to a website and vice-versa.
* HTTPS also authenticates websites, which helps build trust with your users.

To enable HTTPS on your site, you need [Transport Layer Security (TLS) certificates](#tls-certificates).

## TLS certificates

Upsun Cloud automatically provides TLS certificates for all sites and environments.
These certificates are issued at no charge by [Let's Encrypt](https://letsencrypt.org/) and cover most needs.
They're valid for 90 days and automatically renewed 28 days before expiration.

To use them, you only need to [specify HTTPS routes](/docs/routes/https#enable-https).
Note that [limitations](/docs/routes/https#lets-encrypt-limitations) apply.
If you encounter issues with the TLS certificates provided by Upsun Cloud,
check that [TLS encryption is up-and-running](/docs/domains/troubleshoot#verify-ssltls-encryption).

If you don't want to use the TLS certificates provided by Upsun Cloud,
configure your own [third-party TLS certificates](/docs/domains/steps/tls).

### Let's Encrypt limitations

When you use the Let's Encrypt [TLS certificates](#tls-certificates) provided by Upsun Cloud,
the following limitations apply.

Let's Encrypt allows a maximum of 100 hostnames per certificate.
You can have 1 Let's Encrypt certificate for each of your environments.
If you define both a `{default}` and a `www.{default}` route for each domain you use,
you can add up to 50 hostnames.
Going over this limitation results in a warning on deploy and no new TLS certificates are issued.

If you need more hostnames, you can obtain additional certificates
or a wildcard certificate from a [third-party issuer](/docs/domains/steps/tls).
Alternatively, consider splitting your project up into multiple Upsun Cloud projects.

Please note that when using multiple domains, the Common Name (CN) to which the certificate is issued to
is not guaranteed to be the same on each certificate renewal.

### Certificate renewals

When you use the [TLS certificates](#tls-certificates) provided by Upsun Cloud,
certificate renewals occur automatically.

These automatic renewals trigger a redeployment, and the following events occur, which can affect the duration of the redeployment:

* Any required security and system upgrades are applied to your containers.
* The `post_deploy` hook is invoked. **Make sure the scripts in your `post_deploy` hook are written to be idempotent** (safe to run multiple times) or have checks against duplication.

## Enable HTTPS

**Before adding routes to your Upsun Cloud project, you must configure your DNS records** so that each route's hostname resolves to the project's assigned target (for example, via CNAME or appropriate DNS records).
If DNS doesn't point to your project, certificate renewal will fail.

To enable HTTPS, add a routing configuration similar to the following:

```yaml .upsun/config.yaml theme={null}
routes:
  "https://{default}/":
    type: upstream
    upstream: "myapp:http"

  "https://www.{default}/":
    type: redirect
    to: "https://{default}/"
```

All traffic to your domain is then sent to your app.
The `www` subdomain redirects to the [default domain](/docs/routes#default).
This also includes redirecting requests from HTTP to HTTPS.

For more information, see how to [define routes](/docs/routes).

## Optional: Configure TLS connections

When you [specify HTTPS routes](#enable-https),
you can use the `tls` setting to further configure your TLS connections.

### Enforce TLS 1.3

Although you can still use TLS 1.2, TLS 1.3 is faster and more secure.
To instruct your web server to automatically reject TLS 1.2 connections,
enforce TLS 1.3 using the `min_version` setting:

```yaml .upsun/config.yaml theme={null}
routes:
  "https://{default}/":
    # ...
    tls:
      min_version: TLSv1.3
```

Note that TLS versions older than 1.2 are deprecated and are rejected by default.

### Enable HTTP Strict Transport Security (HSTS)

[HSTS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security) forces clients to always communicate with your site over HTTPS.
To enable HSTS, use `strict_transport_security` in a configuration similar to the following:

```yaml .upsun/config.yaml theme={null}
routes:
  "https://{default}/":
    # ...
    tls:
      strict_transport_security:
        enabled: true
        include_subdomains: true
        preload: true
```

The following table presents the possible properties for `strict_transport_security`:

| Name | Type | Default | Description |
| - | - | - | - |
| `enabled` | `boolean` | `null` | If set to `true`, HSTS is enabled for 1 year. If set to `false`, other properties are ignored. |
| `include_subdomains` | `boolean` | `false` | To specify whether HSTS applies to all subdomains. |
| `preload` | `boolean` | `false` | To add your website to the [HSTS preload list](https://hstspreload.org/). Thanks to this list, most browsers are informed that your site requires HSTS before an HSTS header response is even issued. |

Note that when you enable or disable HSTS, the entire domain is affected.
Make sure you only add the HSTS configuration to a single route.
Having different routes with conflicting HSTS configurations can cause issues.

### Enable mTLS

Standard TLS connections are useful to verify the identity of web servers and their certificates.
But you can also instruct your web server to verify the identity of clients and their certificates.
This allows you to restrict access to trusted users.

To do so, enable mTLS by adding the following configuration:

```yaml .upsun/config.yaml theme={null}
routes:
  "https://{default}/":
    # ...
    tls:
      client_authentication: "require"
```

By default, all valid TLS certificates issued by a legitimate certificate authority are accepted.
But you can instruct your web server to only accept TLS certificates issued by specific or even custom certificate authorities.

To do so, add a configuration similar to the following:

```yaml .upsun/config.yaml theme={null}
routes:
  "https://{default}/":
    # ...
    tls:
      client_authentication: "require"
      client_certificate_authorities:
        - !include
          type: string
          path: root-ca1.crt
        - !include
          type: string
          path: root-ca2.crt
```

In this case, the certificate files are resolved relative to the `.upsun/` directory.
Alternatively, you can specify the certificates inline in the file:

```yaml .upsun/config.yaml theme={null}
routes:
  "https://{default}/":
    # ...
    tls:
      client_authentication: "require"
      client_certificate_authorities:
        - |
          -----BEGIN CERTIFICATE-----
          ### Several lines of characters here ###
          -----END CERTIFICATE-----
        - |
          -----BEGIN CERTIFICATE-----
          ### Several lines of different characters here ###
          -----END CERTIFICATE-----
```

If you want to request a client certificate without *requiring* the client to send one, you can set this by using `request` as a value for `client_authentication`:

```yaml .upsun/config.yaml theme={null}
routes:
  "https://{default}/":
    # ...
    tls:
      client_authentication: "request"
    # ...
```

Requests on routes with mTLS configured that are passed through to your app will contain additional headers such as `X-Client-Verify` (with values like `Success` or `None` depending on whether a client certificate was presented and validated or not) and `X-Client-Cert` (with information about the client certificate that was used) that your application can use as required.


# Define routes
Source: https://developer.upsun.com/docs/routes/index

Set your project up so HTTP requests to your app are sent to the right locations.

A [*route*](/docs/glossary#route) defines how requests are handled *after* they reach Upsun Cloud. It tells the Upsun Cloud platform how to handle incoming web requests and to which application (or destination) to direct the requests.

You define routes in a [*router*](/docs/glossary#router), which is the `.routes` key in your project's `.upsun/config.yaml` file in your Git repository.

Routes define how your web applications are accessed, which is helpful when you have [multiple apps](/docs/configure-apps/multi-app) in one project or you want to redirect requests to specific destinations, such as `example.com` rather than `www.example.com`.

If you have a single route served by a single app, you do not need to configure routes:
your project includes a [default route](#default-route-definition).

**Before adding routes to your Upsun Cloud project, you must configure your DNS records** so that each route's hostname resolves to the project's assigned target (for example, via CNAME or appropriate DNS records).
If DNS doesn't point to your project, certificate renewal will fail.

## Examples

These examples show how to define routes.

### Default route definition

If you don't include a file defining routes, a single default route is deployed.
If you have one app to direct traffic to and its name is `myapp`,
this is equivalent to the following:

```yaml .upsun/config.yaml theme={null}
routes:
  "https://{default}/":
    type: upstream
    upstream: myapp:http
```

All traffic to your domain (say, `https://example.com`) is sent to your app.
This also includes redirecting requests from `http` to `https`.
It affects your [default domain](#default).

### Basic redirect definition

In a basic situation, you have one app to direct traffic to.
Say its name is `myapp`.
And say you want to redirect requests from `https://www.example.com` to `https://example.com`.

Define your routes like this:

```yaml .upsun/config.yaml theme={null}
routes:
  "https://{default}/":
    type: upstream
    upstream: "myapp:http"

  "https://www.{default}/":
    type: redirect
    to: "https://{default}/"
```

This affects your [default domain](#default).

You have one route that serves content (the one with the `upstream`)
and one that redirects to the first (the one with the `redirect`).

Redirects from `http` to `https` are generally included by default and don't need to be listed.

### Multi-app route definition

The specifics of configuring the Router container for multiple applications is explored in detail in the [Multiple apps](/docs/configure-apps/multi-app/routes) documentation.

### Sticky routing

Sticky routing ensures that all requests from a specific client are consistently routed to the same instance of your application. This can be critical for stateful applications that rely on local session data, preventing user context from being lost in a horizontally scaled environment. You can enable it in your [route configuration](#route-configuration-reference) to have the router attempt to send repeated requests from the same client to the same instance.

At Upsun Cloud, sticky routing is implemented using a hash of the client’s IP address. This ensures requests from the same IP are generally routed to the same container.

```yaml .upsun/config.yaml theme={null}
routes:
  "https://{default}/":
    type: upstream
    upstream: app:http
    sticky: true
```

This enables sticky routing at the router level.

<Note>
  <h4>Note</h4>
  Because the routing uses IP hashing, scaling your environment up or down can change the hash distribution, causing requests to be routed to different containers. For production workloads that require persistent sessions, use an external session store (for example, [Redis](/docs/add-services/redis)), or design your app to be stateless.
</Note>

## Trailing slashes

All defined routes have at least a slash in the path.
So you might define routes for 2 apps named `myapp` and `api` as follows:

```yaml .upsun/config.yaml theme={null}
routes:
  "https://{default}":
    type: upstream
    upstream: "myapp:http"

  "https://subdomain.example.com":
    type: upstream
    upstream: "api:http"
```

Both of these routes would be resolved with trailing slashes.
So if you check your [`PLATFORM_ROUTES` variable](/docs/development/variables/use-variables#use-provided-variables),
you see the following resolved routes (assuming `example.com` is your default domain):

```json theme={null}
{
  "https://example.com/": {
    "primary": true,
    "id": null,
    "attributes": {},
    "type": "upstream",
    "upstream": "myapp",
    "original_url": "https://{default}"
  },
  "https://subdomain.example.com/": {
    "primary": false,
    "id": null,
    "attributes": {},
    "type": "upstream",
    "upstream": "api",
    "original_url": "https://subdomain.example.com"
  }
}
```

## Route placeholders

Each route in your configuration file is defined in one of two ways:

* An absolute URL such as `https://example.com/blog`
* A URL with a placeholder such as `https://{default}/blog`

The available placeholders are `{default}` and `{all}`.
They stand in for the [custom domains](/docs/domains/steps) you've defined in your project.

These domains can be top-level domains (`example.com`) or subdomains (`app.example.com`).

### `{default}`

`{default}` represents your default custom domain.
If you have set your default domain to `example.com`,
`example.com` and `{default}` in your `.upsun/config.yaml` file have the same result for your Production environment.

You can use the `{default}` placeholder:

```yaml .upsun/config.yaml theme={null}
routes:
  "https://{default}/blog":
    type: upstream
    upstream: "myapp:http"
```

And you can use an absolute URL:

```yaml .upsun/config.yaml theme={null}
routes:
  "https://example.com/blog":
    type: upstream
    upstream: "myapp:http"
```

In both cases, the URLs for your Production environment are the same.

#### URLs in preview environments

URLs in [preview environments](/docs/glossary#preview-environment) (development and staging types) follow a different pattern depending on whether you use a placeholder or an absolute URL. For example, for an environment named `feature`:

| Route pattern | Resolves to |
| - | - |
| `https://{default}/blog` | `https://feature-t6dnbai-abcdef1234567.us-2.platformsh.site/blog` |
| `https://example.com/blog` | `https://example.com.feature-t6dnbai-abcdef1234567.us-2.platformsh.site/blog` |
| `https://www.{default}/` | `https://www.feature-t6dnbai-abcdef1234567.us-2.platformsh.site/` |

Only `{default}` is replaced with the generated per-environment domain — any literal text around it, such as `www.` or a custom domain, is preserved as-is in the result.

### `{all}`

You can also set up multiple domains for a single project.
To define rules for all of them, use `{all}` in your template.

Say you have both `example.com` and `example.net` as domains in a project.
You can then define the following routes:

```yaml .upsun/config.yaml theme={null}
routes:
  "https://{all}/":
    type: upstream
    upstream: "myapp:http"

  "https://www.{all}/":
    type: redirect
    to: "https://{all}/"
```

The first route means you're serving the same content at multiple domains:
your app runs at both `https://example.com` and `https://example.net`.

The second route means that `https://www.example.com` redirects to `https://example.com`
*and* `https://www.example.net` redirects to `https://example.net`.

If your project has no domains or only one, `{all}` behaves exactly like `{default}`.

If you have two routes sharing the same HTTP scheme, domain, and path
and the first route is using `{default}` and the second is using `{all}`,
the route using `{default}` takes precedence.
Say you have two apps named `app1` and `app2` and define two routes like this:

```yaml .upsun/config.yaml theme={null}
routes:
  "https://{default}/":
    type: upstream
    upstream: "app1:http"

  "https://{all}/":
    type: upstream
    upstream: "app2:http"
```

Requests to your default domain are served by `app1`.

## Wildcard routes

Upsun Cloud supports wildcard routes, so you can map multiple subdomains to the same application.
Both `redirect` and `upstream` routes support wildcard routes.
Prefix a route with an asterisk (`*`), for example `*.{default}`.
If you have configured `example.com` as your default domain,
HTTP requests to `www.example.com`, `blog.example.com`, and `us.example.com` are all routed to the same endpoint.

It also works on preview environments.
If you have a branch named `feature`, it's `{default}` domain looks something like:
`feature-def123-vmwklxcpbi6zq.us.upsun.com` (depending on the project's region).
So requests to `blog.feature-def123-vmwklxcpbi6zq.us.upsun.com` and `us.feature-def123-vmwklxcpbi6zq.eu.upsun.com`
are both routed to the same endpoint.

Let's Encrypt wildcard certificates aren't supported (they would need DNS validation).
So if you want to use a wildcard route and protect it with HTTPS,
you need to provide a [custom TLS certificate](/docs/domains/steps/tls).

## Route identifiers

When your project has deployed and routes are generated,
all placeholders (`{default}` and `{all}`) are replaced with appropriate domain names
and any additional routes (such as redirecting HTTP to HTTPS) are created.
This means the final generated routes differ by environment and so shouldn't be hard coded in your app.
These routes are available in the `PLATFORM_ROUTES` environment variable as a base64-encoded JSON object.
They are also available within an application container from the `/run/config.json` file so you can maintain a high number of routes more easily.

To locate routes in a standardized fashion in any environment,
you may specify an `id` for on each route.
This identifier is the same across all environments.

Say you have two apps, `app1` and `app2`, that you want to serve at two subdomains, `site1` and `site2`.

You can define your routes like this:

```yaml .upsun/config.yaml theme={null}
routes:
  "https://site1.{default}/":
    type: upstream
    upstream: 'app1:http'

  "https://site2.{default}/":
    type: upstream
    id: 'the-second'
    upstream: 'app2:http'
```

To see the generated routes on your environment named `feature`, run:

```bash theme={null}
upsun ssh --environment feature 'echo $PLATFORM_ROUTES | base64 --decode | jq .'
```

The result is something like this:

```json theme={null}
{
  "https://site1.feature-t6dnbai-abcdef1234567.us-2.platformsh.site/": {
    "primary": true,
    "id": null,
    "attributes": {},
    "type": "upstream",
    "upstream": "app1",
    "original_url": "https://site1.{default}/"
  },
  "https://site2.feature-t6dnbai-abcdef1234567.us-2.platformsh.site/": {
    "primary": null,
    "id": "the-second",
    "attributes": {},
    "type": "upstream",
    "upstream": "app2",
    "original_url": "https://site2.{default}/"
  },
  "http://site1.feature-t6dnbai-abcdef1234567.us-2.platformsh.site/": {
    "to": "https://site1.feature-t6dnbai-abcdef1234567.us-2.platformsh.site/",
    "original_url": "http://site1.{default}/",
    "type": "redirect",
    "primary": null,
    "id": null,
    "attributes": {}
  },
  "http://site2.feature-t6dnbai-abcdef1234567.us-2.platformsh.site/": {
    "to": "https://site2.feature-t6dnbai-abcdef1234567.us-2.platformsh.site/",
    "original_url": "http://site2.{default}/",
    "type": "redirect",
    "primary": null,
    "id": null,
    "attributes": {},
  }
}
```

The `site2` HTTPS route has an `id` specified as `the-second`, while the other routes have `null` for their `id`.
You can use this `id` to look up the domain of the route in every environment.

## Route attributes

You might want to add extra information to routes to identify them in your app.
Route `attributes` are arbitrary key-value pairs attached to a route.
This metadata has no impact on Upsun Cloud, but is available in the `PLATFORM_ROUTES` environment variable.

So you can define a route like this:

```yaml .upsun/config.yaml theme={null}
routes:
  "http://{default}/":
    type: upstream
    upstream: "myapp:http"
    attributes:
        "foo": "bar"
```

The attributes appear in the routes data like so:

```json theme={null}
"https://feature-t6dnbai-abcdef1234567.us-2.platformsh.site/": {
  "primary": true,
  "id": null,
  "attributes": {
    "foo": "bar"
  },
  "type": "upstream",
  "upstream": "myapp",
  "original_url": "https://{default}/"
}
```

## Route limits

The maximum size of the routes document is 128 KB, which should fit around 300 different routes.
If your `.upsun/config.yaml` file would result in too large of a route information value, it's rejected.

The full list of generated route information is often much larger than what's specified in the `.upsun/config.yaml` file.
For example, by default all HTTPS routes (and all uses of `{all}`) are duplicated to create HTTP redirect routes.
As a general rule, you should keep to your defined routes under 100.

If your `.upsun/config.yaml` file is rejected for being too big, do one of the following:

* Move redirect routes to the application.
* Collapse the route definitions into a [regular expression-based redirect](/docs/routes/redirects#partial-redirects).

Let's Encrypt allows a maximum of 100 hostnames per certificate.
You can have 1 Let's Encrypt certificate for each of your environments.
If you define both a `{default}` and a `www.{default}` route for each domain you use,
you can add up to 50 hostnames.
Going over this limitation results in a warning on deploy and no new TLS certificates are issued.

Non-default ports (other than `80` and `443`) aren't supported and can't be included in routes configuration.

## Route configuration reference

You can configure each route separately with the following properties:

| Name | Type | Required | Description |
| - | - | - | - |
| `type` | `string` | Yes | One of the following options:<ul><li>`upstream` means content is served at that route by an app and requires the `upstream` property to be set.</li><li>`redirect` means the route is redirected elsewhere in your project and requires the `to` property.</li><li>`proxy` means requests are redirected *outside* your project and requires the `to` property. See more about [proxy routes](/docs/routes/proxy).</li></ul> |
| `upstream` | `string` | If `type` is `upstream` | The `name` of the app to be served (as defined in your [app configuration](/docs/configure-apps)) followed by `:http`. Example: `app:http` |
| `sticky` | `boolean` | No | Enables [sticky routing](#sticky-routing) for the route. When `true`, the router attempts to send repeat requests from the same client to the same upstream container, based on a hash of the client’s IP address. |
| `to` | `string` | If `type` is `redirect` | The absolute URL or other route to which the given route should be redirected with an HTTP 301 status code. |
| `ssi` | `boolean` | No | Whether [server side includes](/docs/routes/ssi) are enabled. |
| `redirects` | Object | No | Defines redirects for partial routes. For definition and options, see the [redirect rules](/docs/routes/redirects). |
| `cache` | Object | No | Defines caching policies for the given route. Enabled by default. For details and options, see [route caching](/docs/routes/cache). |
| `id` | `string` | No | A unique identifier for the route. See [route identifiers](#route-identifiers). |
| `primary` | `boolean` | No | Whether the route is the primary route for the project. Can only be `true` for one route in the configuration file, but if you use the [`{all}` placeholder](#all), it can be `true` for multiple final routes. Defaults to the first defined `upstream` route. |
| `tls` | Object | No | TLS configuration. See [HTTPS](/docs/routes/https#optional-configure-tls-connections). |
| `attributes` | Object | No | Any key-value pairs you want to make available to your app. See [route attributes](#route-attributes). |

## CLI access

The [Upsun Cloud CLI](/cli) can show you the routes you have configured for an environment.
These are the routes as defined in the `.upsun/config.yaml` file with the [placeholders](#route-placeholders)
plus the default redirect from HTTP to HTTPS.
They aren't the final generated routes.

Run the following command:

```bash theme={null}
upsun environment:routes
```

You get output similar to:

```bash theme={null}
Routes on the project Example (abcdef123456), environment main (type: production):
+---------------------------+----------+---------------------------+
| Route                     | Type     | To                        |
+---------------------------+----------+---------------------------+
| https://www.{default}/    | upstream | myapp:http                  |
| https://www.{default}/api | upstream | api:http                  |
| http://www.{default}/     | redirect | https://www.{default}/    |
| http://www.{default}/api  | redirect | https://www.{default}/api |
+-----------------------+----------+-------------------------------+

To view a single route, run: upsun route:get <route>
```

Viewing a single route gives you more detailed info, such as its cache and SSI settings.

## WebSocket routes

To use the WebSocket protocol on a route, `cache` must be disabled because WebSocket is incompatible with buffering,
which is a requirement for the router caching.

1. Define a route that serves WebSocket:

```yaml .upsun/config.yaml theme={null}
routes:
  "https://{default}/ws":
    type: upstream
    upstream: "myapp:http"
    cache:
      enabled: false

  # Below HTTP config may not be necessary for every Websocket client.
  "https://{default}/ws":
    type: upstream
    upstream: "myapp:http"
    cache:
      enabled: false
```

2. [Disable request buffering](/docs/configure-apps/image-properties/web#locations) in your app configuration.

```yaml .upsun/config.yaml theme={null}
applications:
  myapp:
    web:
      commands:
        start: /app/.linuxbrew/bin/websocketd --port=$PORT ./wsmanager.sh
      upstream:
        socket_family: tcp
        protocol: http
      locations:
        '/':
          passthru: true
          request_buffering:
              enabled: false
```

## `.htaccess` files

Upsun Cloud uses Nginx servers, not Apache ones.
You [can't use `.htaccess` files with Nginx](https://www.nginx.com/resources/wiki/start/topics/examples/likeapache-htaccess/),
they are therefore ignored on Upsun Cloud.
You can accomplish the same redirect and rewrite goals with your [routes](/docs/routes)
and [web server locations](/docs/configure-apps/web).


# Proxy routes
Source: https://developer.upsun.com/docs/routes/proxy

Pass requests to a location outside your Upsun Cloud project using proxy routes.

<Warning>
  <h4>Warning</h4>
  Only use this feature to address edge cases where you need to proxy to another, outside project.<br />
  **Do not use this for internal routing.**<br />
  To expose your app to the outside world, see [how to define routes](/docs/routes).
</Warning>

Sometimes you want your app to pass requests on to a different Upsun Cloud project.
Basic redirects only work within the same project, so use proxy routes for routes elsewhere.

You can define an external proxy on your Upsun Cloud project by defining a route like the following:

```yaml .upsun/config.yaml theme={null}
routes:
  https://{default}/foo:
    type: proxy
    to: https://www.example.com
```

This route passes requests for `https://{default}/foo/index.html` to `https://www.example.com/foo/index.html`.

You can also define a proxy route to an URL composed of an IP address and a port:

```yaml .upsun/config.yaml theme={null}
routes:
  https://{default}/foo:
    type: proxy
    to: https://192.0.2.0:8000
```

## URL paths

In the basic example above, the route preserves the URL path, `/foo`, in the request.

If you want to proxy a route to `https://www.example.com` without the URL path `/foo`,
add a trailing slash `/` to the `to` definition.

```yaml .upsun/config.yaml theme={null}
routes:
  https://{default}/foo:
    type: proxy
    to: https://www.example.com/
```

The trailing slash makes the proxy route interpret the location as having a different path.
So requests for `https://{default}/foo/index.html` are forwarded to `https://www.example.com/index.html`.

To override the URL path entirely, define a route that contains its own path.
For example:

```yaml .upsun/config.yaml theme={null}
routes:
  https://{default}/foo:
    type: proxy
    to: https://www.example.com/bar
```

This route passes requests for `https://{default}/foo/index.html` to `https://www.example.com/bar/index.html`.

## Multiple apps with the same base URL

You can use proxy routes to map a single domain to multiple Upsun Cloud projects with their own subdomain/domain names.
You might have a need to access multiple projects, each hosting specific applications for different languages.
You want to serve them all at the same base URL with different paths
(`https://example.com/en`, `https://example.com/fr`, and so on).

Because domains can't be reused at Upsun Cloud, you can't just set the same domain for all projects.
Use proxy routes so a single project can access different projects using the same base URL.

In the following example, a single project specifies proxy routes to three apps with the same `default` base URL.
Each app handles a different language.

```yaml .upsun/config.yaml theme={null}
routes:
  https://{default}/en:
    type: proxy
    to: https://en.example.com/

  https://{default}/jp:
    type: proxy
    to: https://jp.example.com/

  https://{default}/pt:
    type: proxy
    to: https://pt.example.com/
```

The apps behind the proxy need to ensure links to assets are shown to the target domain.
For example, by changing `https://en.example.com/style.css` to `https://example.com/en/style.css`.

The following diagram shows the example project forwarding specific requests to the correct app.

```mermaid {no-copy="true"} theme={null}
sequenceDiagram
    participant User
    participant Project as Proxy project
    participant En as En project
    participant Jp as Jp project
    participant Pt as Pt project
    User->>+Project: example.com/en/index.html
    Project->>+En: en.example.com/index.html
    Note over En: Changes asset links
    En-->>-Project: index.html
    Project-->>-User: index.html
    User->>+Project: example.com/jp/index.html
    Project->>+Jp: jp.example.com/index.html
    Note over Jp: Changes asset links
    Jp-->>-Project: index.html
    Project-->>-User: index.html
    User->>+Project: example.com/pt/index.html
    Project->>+Pt: pt.example.com/index.html
    Note over Pt: Changes asset links
    Pt-->>-Project: index.html
    Project-->>-User: index.html
```

### Large projects

This architecture makes the router of a single project into the central element of your app.
This setup may make scaling more difficult as the router scales with the size of that project.
The router can become a bottleneck for all external sites and acts as a single point of failure.

For larger projects, you should handle multiple websites with the same base URL via a [CDN](/docs/domains/cdn).


# Redirects
Source: https://developer.upsun.com/docs/routes/redirects

Managing redirection rules is a common requirement for web applications, especially in cases where you do not want to lose incoming links that have changed or been removed over time.


You can manage redirection rules on your Upsun Cloud projects in two different ways, which we describe here. If neither of these options satisfy your redirection needs, you can still implement redirects directly from within your application, which if implemented with the appropriate caching headers would be almost as efficient as using the configuration options provided by Upsun Cloud.

<Info>
  <h4>Route limits</h4>
  Please note that the maximum size of the routes document is 128 KB, which should fit around 300 different routes. [Read more about route limits here.](/docs/routes#route-limits)
</Info>

## Whole-route redirects

Using whole-route redirects, you can define very basic routes in your [`.upsun/config.yaml`](/docs/routes) file whose sole purpose is to redirect. A typical use case for this type of route is adding or removing a `www.` prefix to your domain, as the following example shows:

```yaml .upsun/config.yaml theme={null}
routes:
  https://{default}/:
    type: redirect
    to: https://www.{default}/
```

The default HTTP status code for Whole-route redirects is `301`. See [Specify a HTTP status code](#specify-a-http-status-code) to change the status code that is used.

## Partial redirects

In the [`.upsun/config.yaml`](/docs/routes) file you can also add partial redirect rules to existing routes:

```yaml .upsun/config.yaml theme={null}
routes:
  https://{default}/:
    # ...
    redirects:
      expires: 1d
      paths:
        '/from':
          to: 'https://example.com/'
        '^/foo/(.*)/bar':
          to: 'https://example.com/$1'
          regexp: true
```

This format is richer and works with any type of route, including routes served directly by the application. The default HTTP status code for partial redirects is `302`. See [Specify a HTTP status code](#specify-a-http-status-code) to change the status code that is used.

Two keys are available under `redirects`:

| Key | Required | Description |
| - | - | - |
| `expires` | No | The duration the redirect is cached. Examples of valid values include `3600s`, `1d`, `2w`, `3m`.<br /> To disable caching for all your redirects, set `expires` to `0`. You can also [disable caching on a specific redirect](#disable-caching-on-your-redirects). |
| `paths` | Yes | The paths to be redirected |

Each rule under `paths` is defined by a key describing:

* The expression to match against the request path
* A value object describing both the destination to redirect to, with detail on how to handle the redirection

The value object is defined with the following keys:

| Key | Required | Default | Description |
| - | - | - | - |
| `to` | Yes | n/a | A relative URL - `'/destination'`, or absolute URL - `'https://example.com/'`. |
| `regexp` | No | `false` | Specifies whether the path key should be interpreted as a PCRE regular expression. If you use a capturing group, the replace field (`$1`) has to come after a slash (`/`). [More information](#redirects-using-regular-expressions). |
| `prefix` | No | `true`, but not supported if `regexp` is `true` | Specifies whether both the path and all its children or just the path itself should be redirected. [More information](#redirects-using-prefix-and-append_suffix). |
| `append_suffix` | No | `true`, but not supported if `regexp` is `true` or if `prefix` is `false` | Determines if the suffix is carried over with the redirect. [More information](#redirects-using-prefix-and-append_suffix). |
| `code` | No | n/a | HTTP status code. Valid status codes are `301`, `302`, `307`, and `308`. Defaults to `302` for [Partial redirects](#partial-redirects), and `301` for [Whole-route redirects](#whole-route-redirects). [More information](#specify-a-http-status-code). |
| `expires` | No | Defaults to the `expires` value defined directly under the `redirects` key, but can be fine-tuned. To [disable caching on a specific redirect](#disable-caching-on-your-redirects), set `expires` to `0`. | The duration the redirect is cached for. [More information](#manage-caching). |

To set up partial redirects, you can use regular expressions (`regexp`).<br />
Alternatively, and in many cases, you can use the `prefix` and/or `append_suffix` keys to achieve the same results.<br />
Here are some examples to illustrate this and help you choose a method for your partial redirects:

<Tabs>
  <Tab title="`regexp`">
    Consider this `regexp` redirect:

    ```yaml theme={null}
    '^/from(/.*|)$':
      regexp: true
      to: https://example.com/to$1
    ```

    It achieves the same result as this basic redirect:

    ```yaml theme={null}
    '/from':
      to: https://example.com/to
    ```
  </Tab>

  <Tab title="`prefix`">
    Consider this redirect using `prefix`:

    ```yaml theme={null}
    '/from':
      to: https//example.com/to
      prefix: false
    ```

    It achieves the same result as this `regexp` redirect:

    ```yaml theme={null}
    '^/from$':
      regexp: true
      to: https://example.com/to
    ```
  </Tab>

  <Tab title="`append_suffix`">
    Consider this redirect using `append_suffix`:

    ```yaml theme={null}
    '/from':
      to: https//example.com/to
      append_suffix: false
    ```

    It achieves the same result as this `regexp` redirect:

    ```yaml theme={null}
    '^/from(/.*|)$':
      regexp: true
      to: https://example.com/to
    ```
  </Tab>
</Tabs>

<Warning>
  <h4>Warning</h4>
  If you're using `regexp` in a redirect, you can't also use `prefix` and `append_suffix`.
  Likewise, if you're using `prefix` and `append_suffix`, you can't also use `regexp`.
</Warning>

### Redirects using regular expressions

You can use regular expressions to configure your redirects.

In the following example, a request to `https://example.com/foo/a/b/c/bar` redirects to `https://example.com/a/b/c`:

```yaml .upsun/config.yaml theme={null}
routes:
  https://{default}/:
    type: upstream
    # ...
    redirects:
      paths:
        '^/foo/(.*)/bar':
          to: 'https://example.com/$1'
          regexp: true
```

The following special arguments in the `to` statement are available when `regexp` is set to `true`:

* `$is_args` evaluates to `?` or empty string
* `$args` evaluates to the full query string if any
* `$arg_foo` evaluates to the value of the query parameter `foo`
* `$uri` evaluates to the full URI of the request.

### Redirects using `prefix` and `append_suffix`

Instead of using regular expressions to configure your redirects,
you might want to use the `prefix` and `append_suffix` keys.

<Warning>
  <h4>Warning</h4>
  If you're using `regexp` in a redirect, you can't also use `prefix` and `append_suffix`.
  Likewise, if you're using `prefix` and `append_suffix`, you can't also use `regexp`.
</Warning>

When set to `true`, which is their default value, `prefix` and `append_suffix` are equivalent.
For example:

```yaml .upsun/config.yaml theme={null}
routes:
  https://{default}/:
    type: upstream
    # ...
    redirects:
      paths:
        '/from':
          to: 'https://{default}/to'
          prefix: true
```

```yaml theme={null}
routes:
  https://{default}/:
    type: upstream
    # ...
    redirects:
      paths:
        '/from':
          to: 'https://{default}/to'
          append_suffix: true
```

```yaml theme={null}
routes:
  https://{default}/:
    type: upstream
    # ...
    redirects:
      paths:
        '/from':
          to: 'https://{default}/to'
          prefix: true
```

```yaml theme={null}
routes:
  https://{default}/:
    type: upstream
    # ...
    redirects:
      paths:
        '/from':
          to: 'https://{default}/to'
          append_suffix: true
```

With both configurations:

* `/from` redirects to `/to`
* `/from/some/path` redirects to `/to/some/path`

However, when set to `false`, `prefix` and `append_suffix` behave differently.
For example, with the following configuration:

```yaml theme={null}
routes:
  https://{default}/:
    type: upstream
    # ...
    redirects:
      paths:
        '/from':
          to: 'https://{default}/to'
          prefix: true
```

A request to `/from/` redirects to `/to/some/path`, but a request to `/from/some/path` does not.

And with the following configuration:

```yaml theme={null}
routes:
  https://{default}/:
    type: upstream
    # ...
    redirects:
      paths:
        '/from':
          to: 'https://{default}/to'
          append_suffix: false
```

A request to `/from/some/path` (and any path after `/from`) redirects to just `/to`.

### Specify a HTTP status code

To set a specific HTTP status code for your redirect, use the `code` key:

```yaml theme={null}
routes:
  https://{default}/:
    type: upstream
    # ...
    redirects:
      paths:
        '/from':
          to: 'https://example.com/'
          code: 308
        '/here':
          to: 'https://example.com/there'
```

In this example, redirects from `/from` use a `308` HTTP status code,
while redirects from `/here` default to `302` ("found", as long as the resource is indeed found as a result from the redirect).

### Manage caching

You can [set an expiration time on your redirects](#set-an-expiration-time-on-your-redirects)
or even [disable caching](#disable-caching-on-your-redirects) on them.

#### Set an expiration time on your redirects

You can specify how long you want your redirects to be cached for.
To do so, use the `expires` key under the `redirects` key.

In the following example, all redirects are cached for two weeks:

```yaml theme={null}
routes:
  https://{default}/:
    type: upstream
    # ...
    redirects:
      expires: 2w
      paths:
        '/from':
          to: 'https://example.com/'
        '/here':
          to: 'https://example.com/there'
```

If you want to set a different expiration time for a specific redirect,
use the same `expires` key, but under the `paths` key.

In the following example:

* The first redirect uses the default expiration time set on all redirects
  and is cached for two weeks
* The second redirect ignores the default expiration time set on all redirects,
  and is cached for three days instead

```yaml theme={null}
routes:
  https://{default}/:
    type: upstream
    # ...
    redirects:
      expires: 2w
      paths:
        '/from':
          to: 'https://example.com/'
        '/here':
          to: 'https://example.com/there'
          expires: 3d
```

<Note>
  You can set an expiration time on a specific redirect (under the `paths` key)
  even if you haven't defined a default expiration time on all your redirects (under the `redirects` key).

  The expiration time you set on a specific redirect (under the `paths` key) overwrites any default expiration time
  you may have set on all your redirects (under the `redirects` key).
</Note>

#### Disable caching on your redirects

To disable caching on all your redirects, set the `expires` key to `0` under the `redirects` key:

```yaml theme={null}
routes:
  https://{default}/:
    type: upstream
    # ...
    redirects:
      expires: 0
      paths:
        '/from':
          to: 'https://example.com/'
        '/here':
          to: 'https://example.com/there'
```

To disable caching on a specific redirect only,
set the `expires` key to `0` under the relevant path in the `paths` section.

In the following example, caching is disabled on the second redirect only:

```yaml theme={null}
routes:
  https://{default}/:
    type: upstream
    # ...
    redirects:
      paths:
        '/from':
          to: 'https://example.com/'
        '/here':
          to: 'https://example.com/there'
          expires: 0
```

## Other redirects

### Application-driven redirects

If neither whole-route or partial redirects satisfy your redirection needs,
you can still implement redirects directly in your application.
If sent with the appropriate caching headers,
this is nearly as efficient as implementing the redirect through one of the two configurations described above.
Implementing application-driven redirects depends on your own code or framework and is beyond the scope of this documentation.

### Query-strings based redirects

Upsun Cloud **does not** support redirects based on query strings.

If you want to redirect based on query strings, this logic has to be implemented by your application.


# Server Side Includes (SSI)
Source: https://developer.upsun.com/docs/routes/ssi

SSI commands enable you to include files within other pages.


At its most basic, you can include files within other ones so as not to repeat yourself.

Start by enabling SSI:

```yaml .upsun/config.yaml theme={null}
routes:
  "https://{default}/":
    type: upstream
    upstream: "myapp:http"
    ssi:
      enabled: true
```

Then create a file you want to include elsewhere:

```html includes/example.html theme={null}
<p>This content can be reused</p>
```

And include it in another file:

```html index.html theme={null}
<body>
  <p>This content is unique to this page.</p>
  {/* #include virtual="includes/example.html" */}
</body>
```

And your final rendered page includes the other file:

```html index.html theme={null}
<body>
  <p>This content is unique to this page.</p>
  <p>This content can be reused</p>
</body>
```

## Caching and dynamic content

You can use SSI to have [caching](/docs/routes/cache) and dynamic content in one.
So one file is cached, while another updates dynamically.

For example, you can activate SSI on one route with cache disabled and enable cache on another route:

```yaml .upsun/config.yaml theme={null}
routes:
  "https://{default}/":
    type: upstream
    upstream: "myapp:http"
    ssi:
      enabled: true
    cache:
      enabled: false

  "https://{default}/cache":
    type: upstream
    upstream: "myapp:http"
    cache:
      enabled: true
```

Then create a page that displays the current date and time and is cached for 60 seconds
(the example uses PHP, but any server-side language would work):

```php cache/example.php theme={null}
<?php
header("Cache-Control: max-age=60");
echo date(DATE_RFC2822);
```

Then you could have a page with dynamic content that includes this file:

```php index.php theme={null}
<?php
echo date(DATE_RFC2822);
?>
{/* #include virtual="cache/example.php" */}
```

Then you can visit `index.php` and refresh the page a few times.
You see the first number updating to the current time, while the second (included) one only changes every 60 seconds.

For more on SSI, see the [nginx documentation](https://nginx.org/en/docs/http/ngx_http_ssi_module.html).


# Data retention
Source: https://developer.upsun.com/docs/security/data-retention

Upsun Cloud logs and stores various types of data as a normal part of its business. This information is only retained as needed to perform relevant business functions. Retention periods vary depending on the type of data stored. If a legal obligation, law enforcement request, or ongoing business need so requires, data may be retained after the original purpose for which it was collected ceases to exist.


## Account information

Information relating to customer accounts (login information, billing information, etc.) is retained for as long as the account is active with Upsun Cloud.

Customers may request that their account be deleted and all related data be purged by opening a [support ticket](/docs/core-concepts/get-support).

## System logs

System level access and security logs are maintained by Upsun Cloud for diagnostic purposes.
These logs aren't customer-accessible.
These logs are retained for at least 6 months and at most 2 years depending upon legal and standards compliance required for each system.

## Application logs

Application logs on each customer environment are retained with the environment.
Individual log files are truncated at 100 MB, regardless of their age.
See how to [access logs](/docs/observability/logs/access-logs).

When an environment is deleted, its application logs are deleted as well.

## Backups

The backups retention depends on the [automated backup policy](/docs/environments/backup#automated-backups).

## Tombstone backups

When a project is deleted, Upsun Cloud takes a final backup of active environments, as well as the Git repository holding user code.
This final backup is to allow Upsun Cloud to recover a recently deleted project in case of accident.

These "tombstone" backups are retained for between 7 days and 6 months depending upon legal and standards compliance required for each system.

## Analytics

Upsun Cloud uses Google Analytics on various web pages, and so Google Analytics stores collected data for a period of time.
We have configured our Google Analytics account to store data for 14 months from the time you last accessed our site, which is the minimum Google allows.

## Trials

User data - which includes pushed code and data contained within services - is retained for a shorter period during trials.
See [Trial details](/docs/glossary#trial).


# Fastly WAF
Source: https://developer.upsun.com/docs/security/fastly-waf

Find out about the offers you can choose from to subscribe to the Fastly Next-Gen Web Application Firewall (WAF) through Upsun Cloud.

On top of the Upsun Cloud Web Application Firewall (WAF),
you can subscribe to the Fastly Next-Gen Web Application Firewall (Next-Gen WAF) to further protect your app from security threats.

## Available offers

If you want to subscribe to the Fastly Next-Gen WAF through Upsun Cloud,
you can choose from two offers:

* If you subscribe to the **Basic** offer, your WAF is fully managed by Upsun Cloud.
* If you subscribe to the **Basic configurable** offer, your WAF is fully managed by Upsun Cloud too, but with additional flexibility and visibility provided.

To view a list of all the features included in each offer, see the following table.

<Info>
  Links to the official [Fastly Next-Gen WAF documentation](https://docs.fastly.com/products/fastly-next-gen-waf) are provided for reference only.
  The offers described on this page have been designed specifically for Upsun Cloud customers.
  Included features may present limitations compared to those advertised by Fastly to their direct customers.
</Info>

| Capability | Basic offer | Basic configurable offer |
| - | - | - |
| Available modes | Block mode only | Block, not blocking, off modes |
| [Default attack signals](https://docs.fastly.com/signalsciences/using-signal-sciences/signals/using-system-signals/#attacks) | Yes | Yes |
| [Default anomaly signals](https://docs.fastly.com/signalsciences/using-signal-sciences/signals/using-system-signals/#anomalies) | Yes | Yes |
| [Virtual patching](https://www.fastly.com/documentation/guides/next-gen-waf/using-ngwaf/rules/working-with-templated-rules/#virtual-patching-rules) | No | Yes, in block mode only |
| [Default dashboards](https://docs.fastly.com/signalsciences/using-signal-sciences/web-interface/about-the-site-overview-page/) | No | During quarterly business reviews |
| [Custom response codes](https://docs.fastly.com/signalsciences/using-signal-sciences/custom-response-codes/) | No | No |
| [Custom signals](https://docs.fastly.com/signalsciences/using-signal-sciences/signals/working-with-custom-signals/) | No | No |
| [Standard API & ATO signals](https://www.fastly.com/documentation/guides/next-gen-waf/using-ngwaf/rules/working-with-templated-rules/) | No | No |

To subscribe to a Fastly Next-Gen WAF offer through Upsun Cloud,
[contact Sales](https://upsun.com/contact-us/).

## Next-Gen WAF Tier Comparison

#### Basic

* Block-only mode
* Default attack and anomaly signals enabled
* No virtual patching
* No default dashboards
* No custom signals, response codes, or API/ATO signals

This tier is best suited for baseline protection with minimal configuration requirements.

#### Basic Configurable

* Block, not blocking, and off modes
* Default attack and anomaly signals enabled
* Virtual patching available in block mode
* Default dashboards reviewed during quarterly business reviews
* No custom signals, response codes, or API/ATO signals

This tier is best for customers needing custom rules, CVE protection, per-project visibility, or log integration.

## How the Fastly Next-Gen WAF Works

The Fastly Next-Gen WAF evaluates incoming requests using a combination of signals, conditions, actions, and thresholds.

### Signals

Signals classify and tag requests based on observed patterns, such as:

* SQL injection attempts
* Cross-site scripting payloads
* Repeated 404 requests
* Known attack signatures

Signals are informational and are not inherently “good” or “bad”.

### Conditions

Conditions define where and when a rule applies. Examples include:

* Specific URL paths
* Request methods
* Geographic origin
* Presence of certain signals

### Actions

Actions define what happens when a rule matches (allow/log apply to the configurable offer):

* Block the request
* Allow the request
* Log the request for analysis

<Info>
  The Basic Next-Gen WAF offer operates in block-only mode.
</Info>

### Thresholds

Thresholds define volume-based triggers. For example, block if more than `N` suspicious requests occur from the same IP within a defined time window to distinguish normal user behaviour from automated probing or attacks.

### Virtual Patching

Virtual patches are temporary WAF rules provided by Fastly to block known CVEs at the edge. They:

* Protect against specific, identified vulnerabilities
* Buy time while application dependencies are patched
* Do not replace proper application updates

<Info>
  Virtual patching is available only in the Basic Configurable Next-Gen WAF tier.
</Info>

## Scope and Limitations

The Fastly Next-Gen WAF mitigates many common web-based attacks, including parts of the OWASP Top 10. However, it does not replace application-level security. The WAF does not automatically protect against:

* Weak authentication or password policies
* Insecure application design
* Business-logic flaws
* All bot or scraper traffic
* All DDoS attack types

Some attacks are mitigated at the CDN network layer, while others require identifiable patterns that can be enforced via WAF or rate-limiting rules.

<Info>
  <h4>No automatic challenges</h4>
  Upsun Cloud’s Fastly Next-Gen WAF does not provide automatic CAPTCHA or JavaScript challenges. Traffic is evaluated using rule-based signals, thresholds, and actions configured during onboarding or [via Support](/docs/core-concepts/get-support).
</Info>

## Configuration and enablement

Fastly Next-Gen WAF features are not self-service. Enablement and configuration occur during customer onboarding, or via a [Support request](/docs/core-concepts/get-support) after purchase.


# Security and compliance
Source: https://developer.upsun.com/docs/security/index

Learn how Upsun ensures your data is handled with appropriate care and according to industry standards.


<CardGroup>
  <Card title="Fastly WAF" icon="shield" href="/docs/security/fastly-waf">
    Subscribe to the Fastly Next-Gen Web Application Firewall.
  </Card>

  <Card title="Upsun WAF" icon="shield-alert" href="/docs/security/waf">
    Learn how the WAF protects your site from DDoS attacks.
  </Card>

  <Card title="Data retention" icon="database" href="/docs/security/data-retention">
    Understand how Upsun Cloud retains and manages your data.
  </Card>

  <Card title="Project isolation" icon="lock" href="/docs/security/project-isolation">
    Learn how project isolation is handled on Upsun Cloud.
  </Card>
</CardGroup>


# Project isolation
Source: https://developer.upsun.com/docs/security/project-isolation

Learn how project isolation is handled at Upsun

At Upsun, customer environments are strictly isolated from each other using [namespaces](https://man7.org/linux/man-pages/man7/namespaces.7.html), [seccomp](https://man7.org/linux/man-pages/man2/seccomp.2.html), and [cgroups](https://man7.org/linux/man-pages/man7/cgroups.7.html).
Persistent data (uploaded files into mounts, database data, etc.) is stored on a region-wide storage layer.
Data is stored redundantly and mounted into the environments on deployment.

Network is behind a firewall for incoming connections.
Only a few ports are opened to incoming traffic: ports 22, 80, and 443.

There are no exceptions, so any incoming web service requests,
[ETL](https://aws.amazon.com/what-is/etl/#:~:text=Extract%2C%20transform%2C%20and%20load%20%28,and%20machine%20learning%20%28ML%29%29.) jobs,
or otherwise need to transact over one of these protocols.

Outgoing TCP traffic isn’t behind a firewall,
**with the exception of port 25 which is blocked**.

For containers to be allowed to connect to each other, the following requirements must be met:

* The containers must live in the same environment.
* You need to define an explicit relationship between the containers in your app configuration.


# Upsun WAF
Source: https://developer.upsun.com/docs/security/waf

Learn how the WAF can help protect your site from distributed denial of service (DDoS) attacks.

The Upsun Cloud WAF monitors requests to your app and blocks suspicious ones.
All traffic to Upsun Cloud endpoints is also filtered
using a system that takes into account traffic patterns and abuse scores.

## CRLF injection prevention

Carriage return and line feed (CRLF) injection occurs when an attacker injects a CRLF character sequence to manipulate HTTP requests.
CRLF injection can lead to [request smuggling](#request-smuggling),
[header injection](#header-injection), and [response splitting](#response-splitting) attacks.

To protect your app from such attacks, the WAF detects and blocks requests containing CRLF character sequences.

### Request smuggling

When a frontend server forwards HTTP requests to a backend server,
it usually sends a series of requests at once.
The backend server then parses the request headers
to determine where one request ends and the next one begins.

The [HTTP protocol](https://tools.ietf.org/html/rfc2616) provides two different headers
to specify where an HTTP request ends: `Content-Length` and `Transfer-Encoding`.

When the frontend and backend servers don’t agree on which header they should interpret as the end of a request,
attackers can smuggle requests. If a malicious request is injected, the backend server may misinterpret the boundaries
of the individual requests within the concatenated request, thereby processing a request differently from what was
intended. This can lead to various security risks such as data leakage, privilege escalation, and even remote code
execution.

The WAF detects and blocks requests that contain [both the `Content-Length` and `Transfer-Encoding` headers](#content-length-and-transfer-encoding-headers-together).
It also detects and blocks requests that include **both** of the following features of an attempt to inject a malicious request:

* A [CRLF character](#crlf-injection-prevention) or `http/\d`
* An `HTTP` or `WEBDAV` method name

### Header injection

During a header injection attack, the attacker tricks your app
into inserting extra HTTP headers into legitimate HTTP responses.
These attacks can happen when HTTP response headers are generated based on user input.

Header injection attacks can have various impacts,
including cookie injection, [cross-origin resource sharing](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) header injection,
and bypassing your content security policy.
Such attacks enable [response splitting](#response-splitting),
which in turn can lead to [cross-site scripting](https://developer.mozilla.org/en-US/docs/Glossary/Cross-site_scripting),
web cache poisoning, and so on.

The WAF detects header injection attempts occurring through the payload and the header itself.
By [blocking requests containing CRLF](#crlf-injection-prevention) character sequences,
the WAF prevents malicious data from being returned in a response header and interpreted by the client.

### Response splitting

When a user makes an HTTP request, the web server usually returns a single HTTP response.
But when an attacker succeeds in [injecting headers](#header-injection),
they can launch a [response splitting attack](https://www.cs.montana.edu/courses/csci476/topics/http_response_splitting.pdf).

During a response splitting attack, the attacker uses CRLF characters to inject additional HTTP responses into legitimate user requests.
This enables further attacks such as [cross-site scripting](https://developer.mozilla.org/en-US/docs/Glossary/Cross-site_scripting),
web cache poisoning, browser cache poisoning, and cross-user attacks.

As the WAF [blocks requests containing CRLF](#crlf-injection-prevention) character sequences,
your app is protected from response splitting attacks.

## HTTP protocol enforcement

In addition to protecting your site against [CRLF injection-related](#crlf-injection-prevention) attacks,
the WAF implements additional rules to enforce the HTTP protocol.

### Uniform Resource Identifier (URI) syntax

[RFC 3986](https://www.rfc-editor.org/rfc/rfc3986) defines the generic syntax for URIs.
When the WAF detects a URI with incorrect syntax, the incoming connection is terminated.
The request is then reconstructed on the internal Upsun Cloud network,
enforcing the valid format in transit.

### File upload limit

The WAF enforces a file upload limit.
By default, this limit is set at 250 MB.

You can customize the file upload limit by amending your [app configuration](/docs/configure-apps).
In the [`web.locations` dictionary](/docs/configure-apps/image-properties/web#locations),
add your desired value for the `max_request_size` property.

### File extension restriction

The WAF enforces any file extension restriction you may have defined in your [app configuration](/docs/configure-apps).

To set up a file extension restriction,
adjust the [`web.locations` dictionary](/docs/configure-apps/image-properties/web#locations).
Set up [rules](/docs/configure-apps/image-properties/web#rules) to allow only certain file extensions on a given path.

### Disallowed requests and headers

#### `GET` requests with a body

The [HTTP specification](https://tools.ietf.org/html/rfc2616) allows for `GET` requests to have a body.
This enables attackers to try and force a request body on unsuspecting applications,
which could result in a [request smuggling attack](#request-smuggling).

To prevent such attacks, when the WAF detects a `GET` request,
it scans the request for a potential `Content-Length` or `Transfer-Encoding` header.

If one of those headers is found and the payload isn't `0` or empty,
all body-related headers are removed from the request.
The request is then passed through otherwise unaltered.

#### `Content-Length` and `Transfer-Encoding` headers together

According to the [HTTP specification](https://tools.ietf.org/html/rfc2616),
requests mustn't contain [both a `Content-Length` and a `Transfer-Encoding` header](https://tools.ietf.org/html/rfc7230#section-3.3.2).
This rule helps protect apps from [request smuggling](#request-smuggling).

The WAF detects and blocks requests featuring both headers
and forces requests to use [chunked transfer encoding](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Transfer-Encoding)
only on the internal Upsun Cloud network.

#### Missing or empty `host` headers

As [routes are mapped](/docs/routes) based on host names,
the Upsun Cloud WAF blocks requests with an empty or absent `host` header.

#### Other restricted HTTP headers

The following headers are disallowed: `Connection`, `Proxy-Authorization`, `TE`, and `Upgrade`.

## Slowloris DDoS attack prevention

Slowloris DDoS attacks use partial HTTP requests to open connections between a single computer and a targeted web server.
These connections are then kept open for as long as possible to overwhelm the web server.

While Apache web servers are vulnerable to Slowloris attacks, Nginx servers aren't.
Since Upsun Cloud router services use Nginx processes,
your projects are protected against such attacks.


# 502 error resolution guide
Source: https://developer.upsun.com/docs/troubleshooting/502-errors

Diagnose and resolve common 502 errors that may prevent your Upsun Cloud app from starting or running correctly.

<Note>
  If you'd like to learn more about troubleshooting your application, visit the [troubleshoot development](/docs/troubleshooting/general/) page.
</Note>

When deploying an application on Upsun Cloud, it's essential that your app's startup process is correctly configured to ensure smooth operation.

This guide provides a step-by-step approach to troubleshoot 500 errors related to your app not starting, crashing, or failing to connect to required services.

### Step 1: Check logs for troubleshooting insights

You can start your troubleshooting process by looking into some of the logs listed below:

* **Deploy logs**

These show what happened during build and deploy. You can view them by using the following command in terminal:

```bash theme={null}
upsun log deploy
```

<Note>
  Note that the Deploy logs will only populate if the deploy hook runs as part of your deployment.
</Note>

Deploy logs are especially helpful if you're running migrations or provisioning services - issues with database credentials, missing tables, or failed connections often appear here.

* **App logs**

The app log can be particularly useful for debugging your start command. To gain insight into what might be going wrong with your app in particular, use the following command in terminal:

```bash theme={null}
upsun log app
```

This log often reveals stack traces, syntax errors, or missing dependencies that may be preventing the app from starting.

* **All available logs**

To explore what other logs are available to help with troubleshooting, use the following command in terminal:

```bash theme={null}
upsun log
```

### Step 2: Ensure your app's web start command is running

If you've configured a `web.command.start` in your `./upsun/config.yaml`, make sure:

* It launches your app process reliably (e.g. `npm start`, `gunicorn` etc.)

* It doesn't exit immediately or crash

* **It binds to the port provided by the `PORT` [environment variable](/docs/development/variables/use-variables#use-provided-variables)**

To confirm which port your app should bind to, run:

```bash theme={null}
upsun ssh 'echo $PORT'
```

If your app is hardcoded to listen on a specific port like 3000 or 8000, it won't work --- it needs to use the dynamic port assigned by Upsun Cloud. It should also be noted that **this command can only be run in a local session**, not in the app container (in a terminal session).

<Note>
  Please note that if the [\$PORT](/docs/development/variables/use-variables#use-provided-variables) is empty, you will need to check if `web.upstream.socket_family`is set to `tcp`.

  You may see a 502 error if your application isn’t [listening at the same place](/docs/configure-apps/image-properties/web#where-to-listen) that the runtime is sending requests.
</Note>

### Step 3: Review recent activity

Use the Console or [CLI](/cli/index) to inspect recent deploys and other operations:

* In the **Console**, go to your environment view and **select an activity to review**.

* Or, in the CLI:

```bash theme={null}
upsun activity:log     # View the most recent log
upsun activity:list    # See a list of recent activities`
```

Look for failed steps, timeouts, or warnings.

### Step 4: SSH into the running container

If the logs aren't telling the full story, you can directly inspect your running environment with this command:

```bash theme={null}
upsun ssh
```

This is especially useful for:

* Viewing log files created by your app that aren't exposed via the `upsun log`
* Checking if writable directories are correctly mounted
* Testing internal service connections and inspecting the filesystem

<Info>
  <h4>Bonus step</h4>
  You can also manually run your `start` command to debug why your app might be failing. This is because some output about issues in standard output (`stdout`) don't always appear in the logs.
</Info>

To confirm mount points are correctly defined and available, run:

```bash theme={null}
upsun mount:list
```

This lists all writable mounts available in your environment and their paths.

### Step 5: Verify service connectivity

If your app uses [databases or other services](/docs/add-services/index), make sure it can reach them from within the container with the command below:

```bash theme={null}
ping database.internal
psql $DATABASE_URL
```

Make sure the services are defined in `.upsun/config.yaml`,`services`, the top level key and linked correctly in your app configuration.

## Further resources

* [Troubleshooting](/docs/troubleshooting/general/)
* [Use variables](/docs/development/variables/use-variables#use-provided-variables)
* [Add services](/docs/add-services/index)
* [Using the CLI tool](/cli/index)


# Troubleshoot disks
Source: https://developer.upsun.com/docs/troubleshooting/disks



For more general information, see how to [troubleshoot development](/docs/troubleshooting/general).

## Low disk space or inode exhaustion

[Health notifications](/docs/integrations/notifications) can alert you to low disk space,
inode exhaustion (a file count limit), or both.

To help identify the cause, you can:

* [Check mount usage](/docs/troubleshooting/mounts#disk-space-issues)
* [Check your database disk space](#check-your-database-disk-space) (if applicable)

Deleting unnecessary files such as temporary files, logs, or build artifacts can free up disk space and inodes.
If you know their origin, consider setting up automated cleanup to prevent recurrence.

If cleanup measures are insufficient, you can [increase the allocated disk space](#increase-allocated-disk-space).

### Check your database disk space

If you receive a low disk space notification, the database might be a contributing factor.

To get an estimate of current database disk usage, run `upsun db:size`.
The estimate looks something like this:

```text {no-copy="true"} theme={null}
+----------------+-----------------+--------+
| Allocated disk | Estimated usage | % used |
+----------------+-----------------+--------+
| 1.0 GiB        | 520.3 MiB       | ~ 51%  |
+----------------+-----------------+--------+
```

Try cleaning up unused data before [increasing the allocated disk space](#increase-allocated-disk-space)

### Increase allocated disk space

If you find that your application or service is running out of disk space, available inodes, or both,
you can increase the allocated disk space by using the `upsun resources:set` command.

For more information, see how to [manage resources](/docs/manage-resources/configure).

Changing container sizes will trigger a deployment on the chosen environment and affect your monthly project cost.
For pricing details, see the Upsun [Pricing page](https://upsun.com/pricing/).

## No space left on device

During the `build` hook, you may see the following error:

```text {no-copy="true"} theme={null}
W: [Errno 28] No space left on device: ...
```

This is caused by the disk limit on the build container — a temporary environment used to compile
your app before deployment. The resulting image is restricted to 8 GB, no matter how much
writable disk has been allocated for the deployed application.

Some build tools (yarn/npm) store cache for different versions of their modules.
This can cause the build cache to grow over time beyond the maximum.
Try [clearing the build cache](/docs/troubleshooting/general#clear-the-build-cache) and [triggering a redeploy](/docs/troubleshooting/general#force-a-redeploy).

If your application requires more than 8 GB during the build phase,
you can open a [support ticket](/docs/core-concepts/get-support) to have this limit increased.


# Troubleshoot development
Source: https://developer.upsun.com/docs/troubleshooting/general

See some common solutions to issues you might run into in development.

## Common tasks

### Force a redeploy

There are times where you might want to trigger a redeployment of your application,
such as to add custom TLS certificates.
A redeploy reuses your built app and services.

To trigger a redeploy, follow these steps:

<Tabs>
  <Tab title="In the Console">
    1. Select the project with the given environment.
    2. From the **Environment** menu, select the environment.
    3. Click <MoreIcon /> **More**.
    4. Click **Redeploy**.
  </Tab>

  <Tab title="Using the CLI">
    Run the following command:

    ```sh theme={null}
    upsun redeploy
    ```
  </Tab>
</Tabs>

The redeploy takes place after any scheduled activities (either *Running* or *Pending*).

<Note>
  Despite the name, redeployment doesn't rerun the `deploy` hook, only the `post_deploy` hook.
  Both your `build` and `deploy` hooks are tied to individual commits in code.
  They're reused until another commit is pushed to the environment.
  See [more about hooks](/docs/configure-apps/hooks) and their reuse.

  To rerun the `build` and `deploy` hooks, [manually trigger a build](#manually-trigger-builds).
</Note>

<Info>
  <h4>Is there a way to redeploy the production environment without knowing its name?</h4>
  It's often desirable that the production environment, like many other values, is not hardcoded into your external workflows and management scripts.
  You can use the CLI, along with the [environment type distinction](/docs/glossary#environment-type) to identify a production environment (assuming there is only one) and redeploy it in a single line.

  To do so, run the following command:

  ```bash theme={null}
  upsun redeploy -e $(upsun environment:list --type production --pipe)
  ```
</Info>

### Manually trigger builds

To increase performance and keep applications the same across environments,
Upsun Cloud reuses built applications if its code and build time configuration (variables and such) remain the same.

There may be times where you want to force your application to be built again without changing its code,
for example to test an issue in a build hook or when external dependencies change.
To force a rebuild without changing the code,
use an [environment variable](/docs/development/variables/set-variables#create-environment-specific-variables).

Assuming you want to do this for your `main` environment,
first create a `REBUILD_DATE` environment variable:

```bash theme={null}
upsun variable:create --environment main --level environment --prefix env --name REBUILD_DATE --value "$(date)" --visible-build true
```

This triggers a build right away to propagate the variable.
To force a rebuild at any time, update the variable with a new value:

```bash theme={null}
upsun variable:update --environment main --value "$(date)" "env:REBUILD_DATE"
```

This forces your application to be built even if no code has changed.

### Clear the build cache

You may find that you need to clear the build cache,
such as when it's grown too big or, in rare circumstances, when it's corrupted.
It may get corrupted when code is downloaded from a third-party language service like Packagist or npm
while that service is experiencing issues.

To clear the build cache, run the following command:

```sh theme={null}
upsun project:clear-build-cache
```

The next build for each environment is likely to take longer as the cache rebuilds.

## Access denied or permission denied

In most cases, issues accessing a project are caused by missing permissions for a given user.
For more information see how to [manage user permissions](/docs/administration/users).

If you are using the CLI, make sure that [you are authenticated](/cli/install#authenticate).

If you are using SSH, see how to [troubleshoot SSH access](/docs/development/ssh/troubleshoot-ssh).

## HTTP responses 502 Bad Gateway or 503 Service Unavailable

<Tip>
  <h4>502 errors</h4>
  For troubleshooting tips specifically for 502 errors, please head to the [502 errors resolution guide](/docs/troubleshooting/502-errors).
</Tip>

If you encounter a **502 Bad Gateway** or **503 Service Unavailable** error while accessing your application, it typically indicates that your application is either crashing or unavailable.

Below are the typical causes and potential solutions:

#### 1. Your app is listening at the wrong place

* **Solution**: Check your app's [upstream properties](/docs/configure-apps/image-properties/web#upstream).
* If your app is listening at a specific port, verify that it’s using the [`PORT` environment variable](/docs/development/variables/use-variables#use-provided-variables) and ensure that it is listening at the correct port.

#### 2. Configuration issues in `.upsun/config.yaml`

* **Solution**: Review your `.upsun/config.yaml` configuration.
* Look for any errors that might prevent a process from starting or cause issues with requests being forwarded properly.
* Check the `web.commands.start` entry or your `passthru` configuration for any misconfigurations.
* Check your logs to get a clearer picture of what is going on with your application.

#### 3. Excessive traffic to your application

* **Solution**: Check if the amount of traffic coming to your site exceeds your application's processing power.
* Consider whether [bots or automated traffic might be overwhelming your site](https://support.platform.sh/hc/en-us/community/posts/16439634723858).

#### 4. Slow code paths causing timeouts

* **Solution**: Check your application's code to ensure it is running efficiently.
* Use [observability tools](/docs/observability/application-metrics) provided in your project for better insight into performance issues and potential bottlenecks.
* Run the [Upsun Cloud performance agent](/docs/get-started/ai/upsun-cloud-performance-agent) to correlate Upsun Blackfire profiles, continuous profiling data, traffic, and application source code into a performance analysis report with recommendations.

#### 5. PHP process crashing due to segmentation fault

If your PHP process crashes due to a segmentation fault, you may encounter a message like the warning error detailed below. This indicates that either a PHP extension is causing the segmentation fault or there’s an issue in your PHP app code.

```text {location="/var/log/app.log", no-copy="true"} theme={null}
WARNING: [pool web] child 112 exited on signal 11 (SIGSEGV) after 7.405936 seconds from start
```

* **Solution**: Review recent changes made to your app to identify potential causes.
* Consider using a debugging tool such as [Xdebug](/docs/languages/php/xdebug) to help with quicker troubleshooting and identify the root cause of the crash.

#### 6. PHP process killed by kernel out-of-memory killer

If your PHP process is killed by the kernel, you may encounter a message like the warning error detailed below. This indicates that the memory usage of your container exceeded the allocated limit, causing the kernel to kill the offending process.

```text {location="/var/log/app.log", no-copy="true"} theme={null}
WARNING: [pool web] child 429 exited on signal 9 (SIGKILL) after 50.938617 seconds from start
```

* **Solution**: Check if the memory usage of your app is as expected and try to optimize it.
* Use [sizing hints](/docs/languages/php/fpm) to reduce the number of PHP workers, which will help lower the memory footprint.
* Add [additional resources](/docs/manage-resources) using the `upsun resources:set` command to allocate more memory.

<Note>
  For more troubleshooting tips specifically for PHP, please head to the [PHP troubleshoot page](/docs/languages/php/troubleshoot).
</Note>

#### 7. Project created but not pushed

* **Solution**: If a project is created but hasn’t been pushed, it can result in a 502 error.
* Ensure that the project is properly pushed to the environment.

#### 8. Domain added to edge hostname but not the project

If you add a domain and point it to an edge hostname but haven’t added the domain to the project, it may cause a 502 error. Note that DNS services may catch this issue and provide their own 502 page.

**Solution**: If you have added a domain, ensure that you have added the domain to the project and also make sure that it is pointing to the correct edge hostname.

#### 9. Mistyped edge hostname

If there’s a typo in the edge hostname or if you attempt to request a site while it’s still coming up, you may encounter a 502 error like the one detailed in the example below. It will specify that there is no route known for the url you have provided.

* Example:
  ```bash theme={null}
  url=https://pr-662-mendzpy-4wqljznn6rjno.ca-1.platformsh.site/
  response=$(curl -s -o /dev/null -I -X GET -w "%{http_code}" ${ALLOW_INSECURE:+--insecure} "${url//http:/https:}")
  Error: Response from environment was something other than 200. Response returned was 502
  ```

* **Solution**: Review your edge hostname to ensure that it has been typed correctly. Also, ensure that your site has fully loaded up before requesting it.

#### 10. `command.start` is failing

If the `command.start` entry is failing, it can result in a 502 error.

* **Solution**: Comment out the `command:` and `start` lines in your `config.yaml`, then deploy. After deployment, SSH into the environment and copy-paste the command into the terminal to retrieve logs for further debugging.

## Site outage

If you can't access some part of your project, whether it's the live site, development environment, or Console,
check the [Upsun Cloud status page](https://status.upsun.com/).
There you can see planned maintenance and subscribe to updates for any potential outages.

If the status is operational, [contact support](/docs/core-concepts/get-support).

## Command not found

When you've added a command line tool (such as [Drush](/docs/development/drush)),
you might encounter an error like the following:

```bash theme={null}
-bash: drush: command not found
```

If you see this, add the command you want to run to your path
with a [`.environment` file script](/docs/development/variables/set-variables#set-variables-via-script).

As a Linux or Unix-like operating system user (MacOS included),
to be able to run your scripts directly and quickly get past this error
you may need to run the `chmod +x <YOUR_SCRIPT_FILE_NAME>` command.

However, regardless of which operating system you're using,
it's best if you **don't rely on scripts having execute permissions**.
Instead, call the app/shell/runtime directly passing your script file to that executable.

## Missing commits

If you push code to Upsun Cloud without the full Git history, sometimes commits are missing.
This can happen if you're pushing code from an external CI/CD pipeline, such as a GitHub action.
Such pipelines often do only shallow clones by default.

In such cases, your build might fail with an internal error.
Or you might see an error like `unexpected disconnect while reading sideband packet`.

To avoid the error, make sure you do a full clone of the repository before pushing code.
For example, for the [Checkout GitHub action](https://github.com/actions/checkout),
set `fetch-depth: 0` to clone the full history.
For GitLab, set clones to have a limit of `0` either in [repository settings](https://docs.gitlab.com/ee/ci/pipelines/settings.html#limit-the-number-of-changes-fetched-during-clone)
or using the [`GIT_DEPTH` variable](https://docs.gitlab.com/ee/user/project/repository/monorepos/index.html#shallow-cloning).

## Large JSON file upload failing

When trying to upload a large JSON file to your API, you might see a 400 response code (`Malformed request`).

Upsun Cloud enforces a 10 MB limit on files with the `application/json` `Content-Type` header.
To send large files, use the `multipart/form-data` header instead:

```bash theme={null}
curl -XPOST 'https://example.com/graphql' --header 'Content-Type: multipart/form-data' --form file=large_file.json
```

## Databases

For MySQL specific errors, see how to [troubleshoot MySQL](/docs/add-services/mysql/troubleshoot).

### Permission error creating a database

If you try to use a user to create a database, you get an error saying `permission denied to create database`.
The database is created for you and can be found in the `"SERVICE_NAME"_"PATH"` [service environment variable](/docs/development/variables#service-environment-variables),
or in the `path` key of the `PLATFORM_RELATIONSHIPS` [environment variable](/docs/development/variables/use-variables#use-provided-variables).

## Storage

If you're having trouble with storage, see how to [troubleshoot mounts](/docs/troubleshooting/mounts) and [disks](/docs/troubleshooting/disks).

### Can't write to file system

If you attempt to write to disk outside a `build` hook, you may encounter a `read-only file system` error.
Except where you define it, the file system is all read-only, with code changes necessary through git.
This gives you benefits like repeatable deployments, consistent backups, and traceability.

To generate anything you need later, [write to disk during a `build` hook](/docs/configure-apps/image-properties/hooks#writable-directories-during-build).
Or [declare mounts](/docs/configure-apps/image-properties/mounts),
which are writable even during and after deploy.
They can be used for your data: file uploads, logs, and temporary files.

### Upsun Cloud push fails due to lack of disk space

You might see the following message when attempting to run `upsun push`:
`There isn't enough free space to complete the push`

This usually indicates that large files are present in the repository (where they shouldn't be).
Make sure that the paths for files like media files, dependencies, and databases are set to be ignored in your `.gitignore` file.

If large files are already in the repository, the open-source tool [bfg-repo-cleaner](https://rtyley.github.io/bfg-repo-cleaner/)
can help in cleaning up the repository by purging older commits, removing unnecessary files, and more.

If none of these suggestions work, open a [support ticket](/docs/core-concepts/get-support).

## Stuck build or deployment

If you see a build or deployment running longer than expected, it may be one of the following cases:

* The build is blocked by a process in your `build` hook.
* The deployment is blocked by a long-running process in your `deploy` hook.
* The deployment is blocked by a long-running cron job in the environment.
* The deployment is blocked by a long-running cron job in the parent environment.

To determine if your environment is being stuck in the build or the deployment, check your [activity log](/docs/observability/logs/access-logs#activity-logs).

If the activity has the result `success`, the build has completed successfully and the system is trying to deploy.
If the result is still `running`, the build is stuck.

In most regions, stuck builds terminate after one hour.

When a deployment is blocked, you should try the following:

1. Connect to your environment using [SSH](/docs/development/ssh).
2. Find any long-running cron jobs or deploy hooks on the environment by running `ps afx`.
3. Kill any long-running processes with `kill <PID>`.
   Replace `<PID>` with the process ID shown by `ps afx`.

If a `sync` of `activate` process is stuck, try the above on the parent environment.

Note that, for PHP apps,
you can [restart processes that get stuck during a build or deployment](/docs/languages/php/troubleshoot#restart-php-processes-stuck-during-a-build-or-deployment)
from your app container.

## Slow or failing build or deployment

Builds can take long time or fail.
Most of the time, it's related to an application issue.
Here are a few tips that can help you find the exact cause.

### Check for errors in the logs

Invisible errors during the build and deploy phase can cause increased wait times, failed builds, and other problems.
Investigate [each log](/docs/observability/logs/access-logs#container-logs) and fix any errors you find.

### Build and deploy hooks

[`build` and `deploy` hooks](/docs/configure-apps/hooks) can cause long build times.
If they run into issues, they can cause the build to fail or hang indefinitely.

`build` hooks can be tested in your local environment.
`deploy` hooks can be tested either locally
or by logging into the application over [SSH](/docs/development/ssh) and running them there.
Be careful not to test the scripts on production environments.

You can also test your hooks with these Linux commands to help debug issues:

```text theme={null}
time <YOUR_HOOK_COMMAND> # Print execution time
strace -T <YOUR_HOOK_COMMAND> # Print a system call report
```

### Cron jobs

Containers can't be shutdown while long-running [cron jobs and scheduled tasks](/docs/configure-apps/image-properties/crons) are active.
That means long-running cron jobs block a container from being shut down to make way for a new deploy.

Make sure your custom cron jobs run quickly and properly.
Cron jobs may invoke other services in unexpected ways, which can increase execution time.

## Cache configuration

A common source of performance issues is a misconfigured cache.
The most common issue isn't allowing the right cookies as part of the router cache.

Some cookies, such as session cookies, need to be allowed.
Others, such as marketing and analytics cookies, usually shouldn't be part of the cache key.

See more about [router cache](/docs/routes/cache)
and [cookie entry](/docs/routes/cache#cookies).

Because the router cache follows cache headers from your app,
your app needs to send the correct `cache-control` header.

For static assets, set cache headers using the `expires` key in your [app configuration](/docs/configure-apps/image-properties/web#locations).

## Language-specific troubleshooting

For language-specific troubleshooting for your apps:

* [PHP](/docs/languages/php/troubleshoot)
* [Node JS](/docs/languages/nodejs/debug)


# Troubleshoot mounts
Source: https://developer.upsun.com/docs/troubleshooting/mounts



For more general information, see how to [troubleshoot development](/docs/troubleshooting/general).

## Overlapping folders

If you have a mount with the same name as a directory you've committed to Git or you create such a directory during the build,
you get a message like the following:

```bash theme={null}
W: The mount '/example' has a path that overlaps with a non-empty folder.
The content of the non-empty folder either comes from:
- your git repository (you may have accidentally committed files).
- or from the build hook.
Please be aware that this content isn't accessible at runtime.
```

This shows that the files in Git or from your build aren't available after the build.
The only files that are available are those in your mount.

To make the files available in the mount, copy them to a plain directory during the build, then copy them into the mount in the deploy hook.

<Warning>
  Do not use `/tmp` as the intermediate location. `/tmp` is itself a mount and is not available during the build phase.
</Warning>

1. In the `build` hook, move the files to a plain directory (not a mount).

   ```bash theme={null}
   mkdir -p tmpdir
   mv example tmpdir/example
   ```

2. In the `deploy` hook, use `cp` to copy the files into the mount.

   ```bash theme={null}
   cp -r tmpdir/example example
   ```

To see the files without copying them, temporarily remove the mount from your app configuration.
Then SSH into your app and view the files.
You can then put the mount back in place.

## Mounted files not publicly accessible

If you've set up mounts to handle files like user uploads, you want to make sure the files are accessible.
Do so by managing their [location](/docs/configure-apps/image-properties/web#locations).

This example defines two mounts, one named `private` and one `upload`:

```yaml .upsun/config.yaml theme={null}
applications:
  myapp:
    mounts:
      'private':
        source: storage
        source_path: private
      'uploads':
        source: storage
        source_path: uploads
```

With only this definition, their behavior is the same.
To make `uploads` accessible, define a location with different rules as in the following example:

```yaml .upsun/config.yaml theme={null}
applications:
  myapp:
    web:
      locations:
        '/':
          # Handle dynamic requests
          root: 'public'
          passthru: '/app.php'
        # Allow uploaded files to be served, but don't run scripts.
        '/uploads':
          root: 'uploads'
          expires: 300s
          scripts: false
          allow: true
```

## Mounts starting with a dot ignored

Upsun Cloud ignores YAML keys that start with a dot.
This causes a mount like `.myhiddenfolder` to be ignored.
To mount a directory starting with a dot, put a `/` at the start of its definition:

```yaml .upsun/config.yaml theme={null}
applications:
  myapp:
    web:
      mounts:
        '/.myhiddenfolder':
          source: storage
          source_path: 'myhiddenfolder'
```

## Disk space issues

If you are worried about how much disk your mounts are using, check the size with the following command:

```bash theme={null}
upsun resources:get
```


# Upsun Developer Center
Source: https://developer.upsun.com/index

Documentation, guides, and API references for Upsun Cloud and Upsun Dispatch — covering the full software lifecycle from plan, code, review, and optimize to build, test, deploy, and run.

<div>
  <div>
    # Upsun Developer Center

    <p>
      Documentation, guides, and API references for Upsun products.
    </p>

    <p>
      Together, Upsun products span <span>the entire software lifecycle</span>: <span>Upsun Dispatch<sup>™</sup></span> covers plan, code, review, and optimize with governed AI-agent workflows, while <span>Upsun Cloud</span> covers build, test, deploy, and run with infrastructure that fits your stack.
    </p>
  </div>

  <div>
    <div>
      <div>
        <a href="/dispatch" aria-label="Upsun Dispatch">
          <div>
            <div>
              <img alt="Upsun Dispatch icon" />
            </div>

            <h2>Upsun Dispatch</h2>
          </div>

          <p>AI-native workflows keep pull requests and issues moving instead of piling up.</p>
        </a>

        <div>
          <a href="/dispatch/docs/get-started">
            <svg>
              <path />
            </svg>

            Docs
          </a>
        </div>
      </div>

      <div>
        <a href="/cloud" aria-label="Upsun Cloud">
          <div>
            <div>
              <img alt="Upsun Cloud icon" />
            </div>

            <h2>Upsun Cloud</h2>
          </div>

          <p>Gives each environment infrastructure that fits your stack and scales on its own.</p>
        </a>

        <div>
          <a href="/cloud">
            <svg>
              <path />
            </svg>

            Docs
          </a>

          <a href="/api">
            <svg>
              <polyline />

              <polyline />
            </svg>

            API Reference
          </a>

          <a href="/cli">
            <svg>
              <polyline />

              <line />
            </svg>

            CLI Reference
          </a>
        </div>
      </div>
    </div>

    <div>
      <h3>One platform, full lifecycle coverage</h3>

      <div>
        <div>
          <span>Upsun Dispatch</span>

          <div />

          <div>
            <div>
              <span>Plan</span>
              <span>Code</span>
            </div>

            <div>
              <span>Review</span>
              <span>Optimize</span>
            </div>
          </div>
        </div>

        <div>
          <div>
            <div />

            <div>
              <span>✓</span>
              <span>Git push</span>
            </div>

            <div>
              <div />

              <svg>
                <path />
              </svg>
            </div>
          </div>

          <div>
            <span>Upsun Dispatch</span>

            <div />

            <div>
              <div>
                <div />

                <div>
                  <span>✓</span>
                  <span>Git push</span>
                </div>

                <div>
                  <div />

                  <svg>
                    <path />
                  </svg>
                </div>
              </div>
            </div>
          </div>
        </div>

        <div>
          <span>Upsun Cloud</span>

          <div />

          <div>
            <div>
              <span>Build</span>
              <span>Test</span>
            </div>

            <div>
              <span>Deploy</span>
              <span>Run</span>
            </div>
          </div>
        </div>
      </div>

      <p>
        Use either product on its own, or connect them at the git push handoff for full coverage.
      </p>
    </div>

    <div>
      <h2>Ready to get started?</h2>

      <p>
        Pick a product and start building.
      </p>

      <div>
        <a href="/dispatch/docs/get-started">
          Start with Upsun Dispatch
        </a>

        <a href="/docs/get-started">
          Start with Upsun Cloud
        </a>
      </div>

      <div>
        <span>✓ AI-native code review</span>
        <span>✓ Composable cloud hosting</span>
        <span>✓ Connected at git push</span>
      </div>
    </div>
  </div>
</div>


# The research is in: your AGENTS.md is probably too long
Source: https://developer.upsun.com/posts/ai/agents-md-less-is-more

Research shows comprehensive AGENTS.md files actually hurt coding agent performance. Learn why less is more and how to build context files that work.

<PostMeta />

If you've been using coding agents like Claude Code, Codex, or Qwen Code, you've probably set up an `AGENTS.md` or `CLAUDE.md` file in your repository. Every agent developer recommends it. Over 60,000 public GitHub repositories now include one. The general advice? Generate a comprehensive context file that describes your codebase, tooling, conventions, and testing patterns.

However a new study from ETH Zurich and LogicStar.ai suggests this approach doesn't work, and might actually be making your agent worse at its job.  And that something a few of us at Upsun had a gut-feeling about.

## What the research actually found

The paper, "[Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?](https://arxiv.org/abs/2602.11988)" (Gloaguen et al., February 2026), ran coding agents across hundreds of real-world GitHub issues to measure what happens when you add context files. The researchers tested four coding agents (Claude Code with Sonnet 4.5, Codex with GPT-5.2 and GPT-5.1 Mini, and Qwen Code with Qwen3-30B) in three settings: no context file, an LLM-generated context file, and a developer-written context file.

The results go against the conventional wisdom. LLM-generated context files, the kind you get when you run `/init` in your agent, reduced task success rates by about 3% on average. They also increased inference costs by over 20%. The trend held across models and across both benchmarks: SWE-Bench Lite (300 tasks from popular repositories) and the paper's custom AgentBench (138 tasks from 12 repositories with developer-written context files).

Developer-written context files performed slightly better, improving success rates by about 4% on average. But they still increased costs by up to 19% and added more steps to every task.

## Why more context makes things worse

The trace analysis in the paper shows what's going on. When context files are present, agents explore more files, run more tests, and use more repository-specific tooling. The instructions are being followed. `uv` usage jumped from near-zero to 1.6 times per instance when mentioned in a context file, and repository-specific tools went from 0.05 to 2.5 average calls.

So the agents aren't ignoring the context files. They're following them too diligently.

GPT-5.2 and GPT-5.1 Mini both used significantly more reasoning tokens when context files were present (22% and 14% more on SWE-Bench Lite, respectively). The agents treated the additional instructions as additional constraints to satisfy, making each task harder rather than easier.

The researchers also found that stronger models don't produce better context files. Context files generated by GPT-5.2 improved performance on SWE-Bench Lite by 2% on average, but degraded performance on AgentBench by 3%. Swapping prompts between agents (using Claude Code's prompt to generate files for Codex, or vice versa) produced no consistent winner either. The problem isn't the quality of the generation. It's the approach itself.

The paper also tested whether context files help agents find relevant files faster. They don't. Despite 100% of Sonnet 4.5-generated context files and 99% of GPT-5.2-generated ones containing codebase overviews, agents took roughly the same number of steps to reach the files that needed changing. One notable behavior: GPT-5.1 Mini actually spent extra steps searching for and re-reading context files that were already loaded into its context window. The context file created busywork that wouldn't have existed otherwise.

## The redundancy problem

LLM-generated context files mostly repeat what's already in the repository. The README, the test configuration, the existing documentation. The agent can find and read all of these during task execution. When the researchers removed all documentation files (`.md` files, the `docs/` folder, example code) from repositories, LLM-generated context files suddenly became helpful, improving performance by 2.7% on average.

So context files generated by `/init` commands are doing little more than pre-caching information the agent would discover on its own. For well-documented repositories, that pre-caching adds cost and constraints without adding value.

Developer-written context files performed better for exactly the reason you'd guess: they contained information that wasn't already in the repository. Tooling preferences, workflow requirements, conventions that existed in developers' heads but not in any documentation.

## The right approach: start empty, build incrementally

Instead of generating a comprehensive context file upfront, start with an empty `CLAUDE.md` (or `AGENTS.md`, depending on your tooling) and build it iteratively based on actual friction.

**Step 1: Begin with nothing.** Let the agent work without a context file. It can read your README, test configuration, and existing documentation on its own. For most tasks, that's enough.

**Step 2: Watch where the agent stumbles.** Pay attention to recurring mistakes and wrong assumptions. Does it keep using `npm` when your project uses `pnpm`? Does it write tests with `jest` when you use `vitest`? Does it forget to run the linter before committing?

**Step 3: Add one rule at a time.** When you spot a pattern (not a one-off mistake, but a repeated behavior) add a specific instruction to your context file. Keep it minimal and concrete:

```markdown theme={null}
# CLAUDE.md

## Package management
- Use `pnpm`, not `npm` or `yarn`
- Run `pnpm install --frozen-lockfile` for CI

## Testing
- Use `vitest` for all tests
- Run `pnpm test` before submitting changes

## Code style
- Run `pnpm lint:fix` after making changes
```

**Step 4: Trim what doesn't help.** If you notice an instruction isn't changing agent behavior, or is causing unnecessary steps, remove it. The paper shows that even developer-written context files add cost. Every instruction should earn its place.

## What belongs in a context file

Based on the research, context files are most valuable when they contain information the agent can't discover from the repository itself.

**Include:** things the agent can't figure out on its own, or gets wrong repeatedly. Package manager preference (when multiple are plausible), specific test runner commands, required linting or formatting steps before commits, project-specific tools or scripts, naming conventions for branches or commits, and deployment-specific requirements.

**Skip:** things the agent can read from existing files. Codebase overview and directory structure (your file system already provides this), language and framework details (your `package.json`, `pyproject.toml`, or equivalent tells the agent everything it needs), and general coding patterns (the agent infers these from your existing code).

The finding on codebase overviews is worth calling out. Despite being the most commonly recommended section in context files, overviews didn't help agents locate relevant files any faster. Claude Code's own initialization prompt gets this partially right: it warns against listing components that are "easily discoverable." But the generated files still include overviews nearly every time.

## A practical test

Next time you're about to generate a context file with `/init`, try this instead. Create an empty `CLAUDE.md` with a single comment:

```markdown theme={null}
# CLAUDE.md

```

Work with your agent for a week. Note every time it makes a mistake you have to correct. At the end of the week, review those corrections. The ones that came up more than once? Those become your context file entries.

This approach gives you a context file built from empirical evidence rather than hypothetical completeness. Every line exists because it fixed an actual problem, not because a best-practices guide said to include it.

## What this means for teams

For teams adopting AI-assisted development, the takeaway is practical: don't invest time crafting elaborate context files upfront. Signal-to-noise ratio matters more than comprehensiveness. A five-line context file that addresses your project's specific quirks will outperform a 2,000-word generated overview that restates your README.

There's a related point here. Verification matters more than instruction. Instead of trying to preemptively tell the agent everything it needs to know, invest in the infrastructure that catches mistakes: test suites, linters, type checkers, CI pipelines. These give the agent immediate feedback when something goes wrong, which beats a static document telling it what to do.

Treat your `CLAUDE.md` like a `.gitignore`. It grows as you discover new edge cases, and it gets pruned when entries become irrelevant. Version-control it alongside your code so the whole team benefits from accumulated knowledge about what the agent gets wrong.

Here's the irony: the agents themselves, when asked to generate their own instructions, produce files that make them perform worse. Sometimes the best context you can give an AI is less.

***

**Further reading:** The full paper is available at [arxiv.org/abs/2602.11988](https://arxiv.org/abs/2602.11988). The researchers have also released their AgentBench dataset and evaluation code for teams that want to test context file strategies on their own repositories.


# AI Weekly Review - Feb. 17th 2026
Source: https://developer.upsun.com/posts/ai/aiweekly-2026-02-17

A press, Youtube and Github review of everything AI


<PostMeta />

# Weekly AI Review - 2026-02-17

> Anthropic closed a staggering \$30 billion Series G at a \$380 billion valuation. The second-largest venture deal in history as Claude Code's revenue doubled to \$2.5 billion run-rate in under two months. The open-source frontier exploded with MiniMax M2.5 matching Opus-class performance at 1/20th the cost and GLM-5 shipping a 745B-parameter model trained entirely on Huawei chips under MIT license. OpenAI diversified its inference infrastructure by deploying Codex-Spark on Cerebras chips for 1,000+ token/second coding. Meanwhile, the concept of "cognitive debt" emerged as the industry's sharpest critique of AI-accelerated development, and India hosted the largest Global South AI summit yet.

## Highlight of the week

**Anthropic raises \$30B at \$380B valuation as Claude Code becomes a revenue machine**

[Anthropic closed a \$30 billion Series G](https://www.anthropic.com/news/anthropic-raises-30-billion-series-g-funding-380-billion-post-money-valuation) led by GIC and Coatue, nearly doubling its valuation from the \$183 billion Series F just five months prior. The round brings total capital raised to \$69.1 billion, making it the [second-largest venture deal ever](https://news.crunchbase.com/ai/anthropic-raises-30b-second-largest-deal-all-time/) behind OpenAI's \$40 billion raise last year.

The numbers behind the valuation tell the real story. Anthropic's run-rate revenue hit [\$14 billion](https://siliconangle.com/2026/02/12/anthropic-closes-30b-round-annualized-revenue-tops-14b/), growing over 10x annually for three consecutive years. More than 500 customers spend over \$1 million annually. Eight of the Fortune 10 are customers.

But the standout is Claude Code. Since its May 2025 GA launch, Claude Code's run-rate revenue has [surged past \$2.5 billion](https://www.constellationr.com/insights/news/anthropics-claude-code-revenue-doubled-jan-1). More than doubling since January 1, 2026. Weekly active users also doubled in the same period. Business subscriptions quadrupled, with enterprise use now exceeding half of all Claude Code revenue. Claude Code currently authors [4% of GitHub public commits](https://www.anthropic.com/news/anthropic-raises-30-billion-series-g-funding-380-billion-post-money-valuation), and Semianalysis projects that number could reach 20% or more by year-end.

For context, Goldman Sachs has [deployed Claude across \$2.5 trillion in assets](https://www.humai.blog/ai-news-trends-february-2026-complete-monthly-digest/) under supervision, with 12,000+ developers using it. Reported outcomes: 30% faster client onboarding, 20%+ developer productivity gains. The "multi-model enterprise stack" is now the norm: [79% of OpenAI users also pay for Anthropic](https://www.humai.blog/ai-news-trends-february-2026-complete-monthly-digest/), reinforcing that this market isn't winner-takes-all.

Anthropic has [begun IPO preparations](https://sacra.com/c/anthropic/), hiring Wilson Sonsini to advise. The only question is when, not whether.

## Models & research

### Open-source frontier models arrive in force

This was the week the open-source tier closed the gap on proprietary models in a way that matters for production workloads.

**MiniMax M2.5** landed on February 12 as a [230B-parameter MoE model](https://venturebeat.com/technology/minimaxs-new-open-m2-5-and-m2-5-lightning-near-state-of-the-art-while) (10B active per forward pass) that scores 80.2% on SWE-Bench Verified, within 0.6 points of Opus 4.6 (80.8%) and ahead of GPT-5.2 (80%). The Lightning variant runs at 100 tokens/second and costs [\$0.30/\$2.40 per million tokens](https://www.minimax.io/news/minimax-m25), roughly 1/20th the cost of Opus 4.6. Trained with a novel RL algorithm (CISPO) across 200,000+ real-world environments, MiniMax claims [80% of their newly committed code](https://softtechhub.us/2026/02/14/the-ai-revolution-minimax-m2-5/) is generated by M2.5. The model uses Lightning Attention for native 1M+ token context with linear efficiency. Released under a modified MIT license on Hugging Face.

**GLM-5 from Zhipu AI** dropped on February 11 as a [745B MoE model (44B active)](https://venturebeat.com/technology/z-ais-open-source-glm-5-achieves-record-low-hallucination-rate-and-leverages) trained entirely on Huawei Ascend chips (zero NVIDIA dependency). It scores 77.8% on SWE-bench, beating Gemini 3 Pro and GPT-5.2 while trailing Opus 4.6. Released under MIT license at [\$1.00/\$3.20 per million tokens](https://the-decoder.com/chinese-ai-lab-zhipu-releases-glm-5-under-mit-license-claims-parity-with-top-western-models/). The model introduced "Slime," a novel asynchronous RL training infrastructure that substantially improves throughput. Zhipu's shares [surged 34%](https://creati.ai/ai-news/2026-02-12/zhipu-ai-glm-5-model-launch-stock-surge/) on the Hong Kong Stock Exchange following the launch. Simon Willison [noted the significance](https://simonwillison.net/2026/Feb/11/glm-5/) of Zhipu's "Agentic Engineering" framing, a term gaining traction alongside similar usage by Andrej Karpathy and Addy Osmani.

**Kimi K2.5** from Moonshot AI continues gaining adoption with its [1T-parameter MoE architecture](https://huggingface.co/moonshotai/Kimi-K2.5) (32B active), 76.8% on SWE-bench, and a distinctive Agent Swarm feature that orchestrates up to 100 sub-agents across 1,500 coordinated steps. At [\$0.60 per million input tokens](https://www.nxcode.io/resources/news/kimi-k2-5-developer-guide-kimi-code-cli-2026), it's 10x cheaper than Claude.

The takeaway: teams now have multiple open-weight models within a few percentage points of the best proprietary offerings, at a fraction of the cost. The premium for closed models increasingly comes down to ecosystem, tooling, and trust rather than raw capability.

### OpenAI Codex-Spark on Cerebras: the first move beyond NVIDIA

OpenAI released [GPT-5.3-Codex-Spark](https://openai.com/index/introducing-gpt-5-3-codex-spark/) on February 12, marking its [first production deployment on non-NVIDIA hardware](https://venturebeat.com/technology/openai-deploys-cerebras-chips-for-15x-faster-code-generation-in-first-major). Running on Cerebras Wafer-Scale Engine 3 (a single chip the size of a dinner plate with 4 trillion transistors), Codex-Spark delivers over 1,000 tokens per second, enabling near-instant feedback during live coding.

This is part of a [\$10 billion multi-year partnership](https://techcrunch.com/2026/02/12/a-new-version-of-openais-codex-is-powered-by-a-new-dedicated-chip/) with Cerebras to bring 750MW of compute online through 2028. Currently in research preview for ChatGPT Pro users. OpenAI was careful to note that GPUs remain its primary inference platform, positioning Cerebras as complementary for latency-critical workloads. Still, it signals meaningful diversification of the AI inference stack beyond NVIDIA's dominance.

## Coding agents & dev tools

### The multi-agent IDE era arrives

The AI coding market has converged on multi-agent parallel execution as the defining capability of 2026. Every major player now supports running multiple AI agents simultaneously:

* **[Cursor 2.0](https://www.thurrott.com/a-i/328997/cursor-2-0-arrives-with-multi-agent-interface)** shipped its own Composer model (4x faster than comparable models) and supports up to 8 agents in parallel via Git worktrees. The new agent-centric interface makes agents, plans, and runs first-class objects. However, Gergely Orosz [rightly observes](https://blog.logrocket.com/ai-dev-tool-power-rankings) that orchestrating parallel agents requires tech-lead-level skills, creating an accessibility gap.

* **[Windsurf Wave 13](https://byteiota.com/windsurf-wave-13-free-swe-1-5-parallel-agents-escalate-ai-ide-war/)** added multi-agent sessions with Git worktree integration, an Arena Mode for blind model comparison, and free SWE-1.5 (950 tokens/second). At \$15/month, it [ranks #1](https://blog.logrocket.com/ai-dev-tool-power-rankings) in LogRocket's February AI dev tool power rankings.

* **[OpenAI Codex App](https://openai.com/index/introducing-the-codex-app/)** launched February 2 for macOS as a command center for orchestrating multiple coding agents in parallel. Over [1 million developers](https://techcrunch.com/2026/02/02/openai-launches-new-macos-app-for-agentic-coding/) used it in the first month. The Automations feature lets agents run on schedules in the background with results queued for review.

* **[Google Antigravity](https://developers.googleblog.com/build-with-google-antigravity-our-new-agentic-development-platform/)**, Google's free AI IDE built from the [Windsurf acquisition (\$2.4B)](https://antigravity.google/), offers both Editor and Manager views, the latter serving as a control center for parallel agent orchestration. Currently free in public preview.

* **[VS Code 1.109](https://code.visualstudio.com/blogs/2026/02/05/multi-agent-development)** shipped multi-agent orchestration in February, letting users run Claude and Codex agents alongside GitHub Copilot. This changes the Cursor value proposition since teams can now get multi-model agent support within their existing editor.

### GitHub Agentic Workflows: "Continuous AI"

GitHub previewed [Agentic Workflows (gh-aw)](https://github.github.io/gh-aw/), a system where you [define AI-powered automation tasks in markdown](https://www.theregister.com/2026/02/17/github_previews_agentic_workflows/) that execute as GitHub Actions. The agent can be Copilot, Claude Code, or OpenAI Codex. Use cases include issue triage, CI failure investigation, test coverage monitoring, and repo health reports.

The key insight: these aren't replacements for CI/CD (which must be deterministic) but a new "Continuous AI" layer alongside it. Workflows run read-only by default with explicit approval gates for writes. Sample workflows include [Issue Triage, CI Doctor, and Dependabot PR Bundler](https://github.com/githubnext/agentics). For teams already on GitHub, this is the lowest-friction path to automated AI-driven repo maintenance.

### Kimi Code: open-source terminal agent

[Kimi Code CLI](https://www.nxcode.io/resources/news/kimi-k2-5-developer-guide-kimi-code-cli-2026) (v1.12, 6,400+ GitHub stars, Apache 2.0) is Moonshot AI's open-source terminal coding agent. It competes directly with Claude Code and Gemini CLI, supports images and video input, auto-discovers existing MCP tools, and integrates with VSCode, Cursor, and Zed. For teams wanting an open-source alternative to proprietary coding agents, this is the strongest option available.

### The reality check on AI coding productivity

[Amazon wants 80% of its developers](https://startupnews.fyi/2026/02/17/amazon-pushes-developers/) using AI coding tools weekly. But there's a twist: internal engineers are [pushing back](https://developers.slashdot.org/story/26/02/12/1530202/amazon-engineers-want-claude-code-but-the-company-keeps-pushing-its-own-tool) against being steered toward Kiro (Amazon's in-house tool) when \~1,500 employees endorsed Claude Code in an internal forum. Despite Amazon's \$8 billion investment in Anthropic, employees need explicit authorization to use Claude Code on production projects.

A February Forbes analysis found that [leading AI coding models succeed less than 50% of the time](https://www.forbes.com/councils/forbestechcouncil/2026/02/11/how-to-leverage-ai-coding-tools-without-sacrificing-code-quality/) at fully generating requested features. The practical guidance: spec-driven development, test-first workflows, and outcome-based validation remain essential.

MIT Technology Review reports AI now writes [\~30% of Microsoft's code and over 25% of Google's](https://www.technologyreview.com/2026/01/12/1130027/generative-coding-ai-software-2026-breakthrough-technology/), with Meta targeting majority AI-generated code in the near future. The industry consensus on productivity gains has settled at a [realistic 20-30%](https://blog.logrocket.com/ai-dev-tool-power-rankings), concentrated in specific workflows rather than the 10x improvement initially promised.

### Cognitive debt: the emerging risk

The most important conceptual contribution of the week comes from Margaret-Anne Storey, who coined ["cognitive debt"](https://margaretstorey.com/blog/2026/02/09/cognitive-debt/) as the silent cost of AI-accelerated development. Unlike technical debt that lives in code, cognitive debt is the erosion of shared understanding in developers' minds. Teams move fast with AI but lose the mental models of their systems: what the code does, why architectural decisions were made, how to change things safely.

Simon Willison [called it](https://simonwillison.net/2026/Feb/15/cognitive-debt/) "the best explanation of the term I've seen." This concept should be on every engineering leader's radar. As AI agents generate more code, the risk isn't just code quality; it's whether anyone on the team actually understands the system anymore.

## Web development & frameworks

### AI-native development platforms mature

The "app builder" category (tools like Cursor, Replit, and "lovable"-style platforms that let non-experts build full web apps from instructions) is now [compressing frontend and backend development cycles](https://www.technologyreview.com/2026/01/12/1130027/generative-coding-ai-software-2026-breakthrough-technology/) enough to shift the full-stack role toward architecture, integration, and review. Builder-style platforms now ship [AI assistants for code search, doc generation, and interactive API sandboxes](https://www.builder.io/blog/best-ai-tools-2026) tightly integrated into component systems.

AI-powered security platforms are [bundling agent-based "fixers"](https://dev.to/del_rosario/top-10-ai-coding-tools-for-2026-the-new-development-standard-e5p) that propose or apply patches directly in CI/CD. Snyk's Agent Fix auto-generates security patches; Sweep.dev creates automated bug-fix PRs. The debate now is how much autonomy to grant these agents in production pipelines.

On the content side, [RAG-powered Q\&A embedded directly into sites](https://o-mega.ai/articles/the-ai-stack-in-2026-infrastructure-models-applications) is replacing traditional search-engine-driven traffic patterns. Content teams are rethinking SEO as "answer-in-assistant" flows grow.

## Industry & business

### Infrastructure: power becomes the bottleneck

AI infrastructure discussions this week centered on power, not GPUs. [Peak XV invested in Indian startup C2i](https://techcrunch.com/2026/02/15/as-ai-data-centers-hit-power-limits-peak-xv-backs-indian-startup-c2i-to-fix-the-bottleneck/) focused on data-center power and cooling bottlenecks. The transition to [exaFLOP-class GPU fabrics](https://www.score-grp.com/en/post/ai-infrastructure-2026-new-gpu-optical-network-and-immersive-cooling-requirements) (racks with 70+ accelerators drawing 30-80kW) is pushing adoption of direct-to-chip liquid and immersion cooling. Nebius reported a [sharp rise in capex](https://reuters.com/technology/ai-cloud-firm-nebius-posts-surge-capex-gpu-data-center-expenses-2026-02-12/) from GPU and data center purchases. AMD's [MI450 "Helios"](https://www.ainvest.com/news/ai-hardware-cloud-providers-poised-eclipse-nvidia-dominance-2026-2512/) rack-scale platform, expected late 2026, integrates EPYC CPUs, Instinct GPUs, and networking into a unified stack to challenge NVIDIA's dominance.

## Interesting GitHub repositories

### [Portless](https://github.com/vercel-labs/portless)

Replaces port numbers with stable, named `.localhost` URLs (e.g., `myapp.localhost:1355`). Designed for both humans and AI agents navigating multi-service local dev environments. Solves real pain in monorepos where AI agents guess or hardcode wrong ports, and where cookies bleed across apps on different ports. Works with Next.js, Vite, and most frameworks that respect the `PORT` env var. TypeScript, Node.js 20+.

### [Roam](https://github.com/Cranot/roam-code)

CLI tool that pre-indexes codebases into semantic graphs (symbols, dependencies, call graphs) in SQLite. AI agents query the graph instead of repeatedly grepping files. 55 commands across 7 categories including blast radius analysis, codebase health scoring, and cross-repo support. Supports 22 languages via Tree-sitter. This is the kind of infrastructure that makes AI coding agents actually useful on large codebases. Python 3.9+.

### [gh-aw (GitHub Agentic Workflows)](https://github.com/github/gh-aw)

GitHub's official tool for defining AI-powered automation as markdown files that compile to GitHub Actions YAML. Read-only by default, sandboxed execution, supply chain security with SHA-pinned dependencies. Sample workflows for issue triage, CI investigation, and dependency management. Go/JavaScript, MIT license.

### [Skill Compose](https://github.com/MooseGoose0701/skill-compose)

Platform for building AI agents from reusable, versioned skill components rather than workflow graphs. Describe an agent in natural language, and it finds existing skills, creates missing ones, and wires them together. Container-based isolation, GitHub integration for version history and rollback. Python 3.11+ backend, Next.js 14 frontend, Apache 2.0.

### [Claude SEO](https://github.com/AgriciDaniel/claude-seo)

Universal SEO skill for Claude Code: full website audits with parallel subagent delegation, E-E-A-T analysis, schema markup validation, Core Web Vitals assessment, and AI search optimization for Google Overviews and ChatGPT search. Python 3.8+, MIT license.

## Quick Bits

* **Simon Willison** highlighted [StrongDM's "Dark Factory" approach](https://simonwillison.net/2026/Feb/7/strongdm/): no human even looks at the code AI agents produce. Also noted a developer who [built a 20,000-line Rust browser renderer](https://simonwillison.net/) using a single Codex agent in three days, and challenged the narrative that [AI eliminates the need for juniors](https://simonwillison.net/), arguing they're "more profitable than ever" because AI tools help them past the net-negative phase faster.

* **AI Safety**: A February study showed large reasoning models can [autonomously plan and execute multi-turn jailbreaks](https://bisi.org.uk/reports/ai-safety-lessons-from-digital-piracy-Rn9Sx) against weaker safety systems, drawing parallels to DRM/piracy arms races.

* **Developer tool pricing** is converging on a pattern: free tier + \$15-20/month pro + \$40-60/month enterprise, with AI-native doc platforms starting at [\$300/month for Pro](https://www.builder.io/blog/best-ai-tools-2026).

* **Global AI regulation** continues its steady march: updated trackers show a [rise in national AI laws and governance models](https://iapp.org/news/a/global-ai-law-and-policy-tracker-highlights-and-takeaways) with tightening expectations around documentation, data provenance, and safety testing.

* **Copyright and training data** disputes remain [unresolved](https://o-mega.ai/articles/the-ai-stack-in-2026-infrastructure-models-applications), pushing enterprises toward models with clearer data-use warranties or self-hosted open-weight models.

* **Cerebras** raised [\$1 billion at \$23 billion valuation](https://techcrunch.com/2026/02/12/a-new-version-of-openais-codex-is-powered-by-a-new-dedicated-chip/) as its OpenAI partnership validates the wafer-scale approach for inference.

* **YouTube coverage** of Opus 4.6 vs. Codex 5.3 is extensive, with [ForrestKnight's 22-minute comparison](https://www.youtube.com/watch?v=Q2QmQTNA7vs) (72K views) and a [Lex Fridman clip with Peter Steinberger](https://www.youtube.com/watch?v=j190mwiVlwA) (99K views) providing hands-on developer perspectives on the two models' different coding approaches.

## Sources

### Anthropic & Claude

* [Anthropic Series G announcement](https://www.anthropic.com/news/anthropic-raises-30-billion-series-g-funding-380-billion-post-money-valuation)
* [Claude Code revenue growth - Constellation Research](https://www.constellationr.com/insights/news/anthropics-claude-code-revenue-doubled-jan-1)
* [Anthropic revenue \$14B - SiliconANGLE](https://siliconangle.com/2026/02/12/anthropic-closes-30b-round-annualized-revenue-tops-14b/)
* [Anthropic funding - TechCrunch](https://techcrunch.com/2026/02/12/anthropic-raises-another-30-billion-in-series-g-with-a-new-value-of-380-billion/)
* [Claude Opus 4.6 - Anthropic](https://www.anthropic.com/news/claude-opus-4-6)
* [Claude Opus 4.6 features - Digital Applied](https://www.digitalapplied.com/blog/claude-opus-4-6-release-features-benchmarks-guide)
* [Claude Opus 4.6 "vibe working" - CNBC](https://www.cnbc.com/2026/02/05/anthropic-claude-opus-4-6-vibe-working.html)

### Open-source models

* [MiniMax M2.5 - VentureBeat](https://venturebeat.com/technology/minimaxs-new-open-m2-5-and-m2-5-lightning-near-state-of-the-art-while)
* [MiniMax M2.5 announcement](https://www.minimax.io/news/minimax-m25)
* [MiniMax M2.5 - Winbuzzer](https://winbuzzer.com/2026/02/14/minimax-m25-open-source-ai-model-claude-opus-cost-xcxwbn/)
* [GLM-5 - VentureBeat](https://venturebeat.com/technology/z-ais-open-source-glm-5-achieves-record-low-hallucination-rate-and-leverages)
* [GLM-5 - The Decoder](https://the-decoder.com/chinese-ai-lab-zhipu-releases-glm-5-under-mit-license-claims-parity-with-top-western-models/)
* [GLM-5 stock surge](https://creati.ai/ai-news/2026-02-12/zhipu-ai-glm-5-model-launch-stock-surge/)
* [Kimi K2.5 - Hugging Face](https://huggingface.co/moonshotai/Kimi-K2.5)
* [Kimi Code CLI guide](https://www.nxcode.io/resources/news/kimi-k2-5-developer-guide-kimi-code-cli-2026)

### OpenAI & Codex

* [GPT-5.3-Codex-Spark - OpenAI](https://openai.com/index/introducing-gpt-5-3-codex-spark/)
* [Codex-Spark on Cerebras - VentureBeat](https://venturebeat.com/technology/openai-deploys-cerebras-chips-for-15x-faster-code-generation-in-first-major)
* [Codex-Spark hardware - TechCrunch](https://techcrunch.com/2026/02/12/a-new-version-of-openais-codex-is-powered-by-a-new-dedicated-chip/)
* [Codex App launch - TechCrunch](https://techcrunch.com/2026/02/02/openai-launches-new-macos-app-for-agentic-coding/)
* [Codex-Spark on Cerebras - Cerebras](https://www.cerebras.ai/blog/openai-codexspark)

### Coding agents & dev tools

* [Cursor 2.0 - Thurrott](https://www.thurrott.com/a-i/328997/cursor-2-0-arrives-with-multi-agent-interface)
* [Windsurf Wave 13 - ByteIota](https://byteiota.com/windsurf-wave-13-free-swe-1-5-parallel-agents-escalate-ai-ide-war/)
* [AI dev tool power rankings - LogRocket](https://blog.logrocket.com/ai-dev-tool-power-rankings)
* [GitHub Agentic Workflows - The Register](https://www.theregister.com/2026/02/17/github_previews_agentic_workflows/)
* [GitHub Agentic Workflows docs](https://github.github.io/gh-aw/)
* [Amazon AI coding mandate](https://startupnews.fyi/2026/02/17/amazon-pushes-developers/)
* [Amazon engineers vs. Kiro - Slashdot](https://developers.slashdot.org/story/26/02/12/1530202/amazon-engineers-want-claude-code-but-the-company-keeps-pushing-its-own-tool)
* [AI coding tools effectiveness - Forbes](https://www.forbes.com/councils/forbestechcouncil/2026/02/11/how-to-leverage-ai-coding-tools-without-sacrificing-code-quality/)
* [Generative coding - MIT Technology Review](https://www.technologyreview.com/2026/01/12/1130027/generative-coding-ai-software-2026-breakthrough-technology/)
* [Google Antigravity IDE](https://developers.googleblog.com/build-with-google-antigravity-our-new-agentic-development-platform/)

### Cognitive debt & developer experience

* [Cognitive Debt - Margaret-Anne Storey](https://margaretstorey.com/blog/2026/02/09/cognitive-debt/)
* [Simon Willison on cognitive debt](https://simonwillison.net/2026/Feb/15/cognitive-debt/)
* [Simon Willison blog](https://simonwillison.net/)

### Industry & business

* [Goldman Sachs Claude deployment - HumAI](https://www.humai.blog/ai-news-trends-february-2026-complete-monthly-digest/)
* [Fundamental AI \$255M raise - HumAI](https://www.humai.blog/ai-news-trends-february-2026-complete-monthly-digest/)
* [Cognizant-Google Cloud partnership](https://prnewswire.com/news-releases/cognizant-expands-strategic-partnership-with-google-cloud-to-operationalize-agentic-ai-at-enterprise-scale-302688493.html)
* [Coinbase agentic wallets - HumAI](https://www.humai.blog/ai-news-trends-february-2026-complete-monthly-digest/)
* [India AI Impact Summit - Al Jazeera](https://www.aljazeera.com/news/2026/2/16/india-hosts-ai-impact-summit-drawing-world-leaders-tech-giants)

### Infrastructure

* [C2i data center startup - TechCrunch](https://techcrunch.com/2026/02/15/as-ai-data-centers-hit-power-limits-peak-xv-backs-indian-startup-c2i-to-fix-the-bottleneck/)
* [Nebius capex surge - Reuters](https://reuters.com/technology/ai-cloud-firm-nebius-posts-surge-capex-gpu-data-center-expenses-2026-02-12/)
* [GPU cluster design 2026](https://www.score-grp.com/en/post/ai-infrastructure-2026-new-gpu-optical-network-and-immersive-cooling-requirements)
* [AMD MI450 Helios](https://www.ainvest.com/news/ai-hardware-cloud-providers-poised-eclipse-nvidia-dominance-2026-2512/)

### AI safety & policy

* [AI safety lessons from piracy - BISI](https://bisi.org.uk/reports/ai-safety-lessons-from-digital-piracy-Rn9Sx)
* [Global AI law tracker - IAPP](https://iapp.org/news/a/global-ai-law-and-policy-tracker-highlights-and-takeaways)
* [India AI Summit critique - TechPolicy](https://techpolicy.press/indias-ai-impact-summit-promises-little-more-than-spectacle)

### GitHub repositories

* [Portless](https://github.com/vercel-labs/portless)
* [Roam - Codebase Intelligence](https://github.com/Cranot/roam-code)
* [gh-aw - GitHub Agentic Workflows](https://github.com/github/gh-aw)
* [Skill Compose](https://github.com/MooseGoose0701/skill-compose)
* [Claude SEO](https://github.com/AgriciDaniel/claude-seo)


# AI Weekly Review - Feb. 23th 2026
Source: https://developer.upsun.com/posts/ai/aiweekly-2026-02-23

A press, Youtube and Github review of everything AI


<PostMeta />

# Weekly AI Review - 2026-02-23

> A week that stressed the trust layer of AI tooling. A supply chain attack on Cline CLI installed a rogue agent on roughly 4,000 developer machines. Anthropic accused DeepSeek, MiniMax, and Moonshot of running industrial-scale distillation campaigns against Claude, totalling 16 million+ exchanges across 24,000 fake accounts. Meanwhile: Anthropic shipped Claude Code Security (500+ zero-days found in production open-source code), Claude Sonnet 4.6 became the new default, DeepSeek V4 arrived with its Engram architecture, and Cloudflare released Markdown for Agents and Code Mode. Simon Willison published a guide to Agentic Engineering Patterns, and ggml/llama.cpp moved to Hugging Face.

## Highlights of the week

### Cline CLI supply chain attack: an AI agent used to install an AI agent

On February 17 at 3:26 AM PT, an attacker used a [compromised npm publish token](https://www.stepsecurity.io/blog/cline-supply-chain-attack-detected-cline-2-3-0-silently-installs-openclaw) to push Cline CLI 2.3.0 to npm. The malicious version added a `postinstall` script that silently ran `npm install -g openclaw@latest`, dropping a self-hosted AI agent with full disk access, credential harvesting, and arbitrary shell execution. OpenClaw runs a persistent daemon via launchd/systemd on `ws://127.0.0.1:18789` and survives reboots. Every machine that pulled the update had a foothold planted in it.

[StepSecurity flagged two anomalies](https://www.stepsecurity.io/blog/cline-supply-chain-attack-detected-cline-2-3-0-silently-installs-openclaw) within minutes: the package was published manually by a user account (breaking the trusted GitHub Actions OIDC chain) and lacked npm provenance attestations. Roughly [4,000 downloads occurred in the 8-hour window](https://thehackernews.com/2026/02/cline-cli-230-supply-chain-attack.html) before maintainers deprecated the version. Microsoft's Threat Intelligence confirmed an uptick in OpenClaw installations tied to the compromise. There's a backstory too: a [prior prompt injection vulnerability](https://www.theregister.com/2026/02/20/openclaw_snuck_into_cline_package/) in Cline's GitHub issue triage workflow had allowed production release compromise from December 2025 through February 9.

This is not theoretical risk. AI developer tools have privileged access to credentials, CI/CD pipelines, and cloud infrastructure. A compromised coding agent is a compromised development environment. The fix is boring: verify npm provenance attestations, pin versions, and treat any AI tool with shell access as a high-value target in your threat model.

YouTube creator Nate B Jones covered [related incidents the same week](https://www.youtube.com/@NateBJones): an AI agent that wiped a production database, and agents gaining wallet and shell access. Production AI agent incidents are no longer edge cases.

### Agentic coding tools are becoming “table stakes”

* Anthropic’s new AI bug‑hunter and improved “AI security engineer”‑style tools show that agentic assistants are moving beyond autocompletion into autonomous scanning and patching. [fortune](https://fortune.com/2026/02/20/exclusive-anthropic-rolls-out-ai-tool-that-can-hunt-software-bugs-on-its-own-including-the-most-dangerous-ones-humans-miss/)
* Cursor, Copilot Workspace, Windsurf, and similar tools are converging on the same pattern: whole‑repo context, planning steps, and multi‑file edits from a single natural‑language request. [vibe.forem](https://vibe.forem.com/devin-rosario/20-plus-ai-coding-tools-for-dev-workflows-in-2026-2ogf)

Actionable moves:

* Pick one agentic IDE/workspace (Cursor, Windsurf, Copilot Workspace, etc.) and integrate it into your daily workflow for at least one full feature from spec → PR. [thepromptbuddy](https://www.thepromptbuddy.com/prompts/best-ai-tools-for-coding-in-january-2026-complete-guide-for-developers)
* Start versioning your best prompts alongside code (e.g., `/prompts` folder with “refactor”, “test‑gen”, “security‑review” recipes) so your team reuses and improves them. [builder](https://www.builder.io/blog/best-ai-tools-2026)

### Multi‑model and cost‑aware architectures are now the default

* New models like Kimi K2/K2.5, Claude Opus 4.6, GPT‑5.3, and GLM‑5 are pushing performance up while open‑weight options and cheaper tokens push costs down. [swfte](https://www.swfte.com/pt/blog/ai-model-rush-february-2026)
* K2/K2.5 and similar models are optimized for tools and “agent swarms,” making it practical to route heavy tasks to one model and bulk/cheap tasks to another. [swfte](https://www.swfte.com/pt/blog/ai-model-rush-february-2026)

Actionable moves:

* Design your AI integration so you can swap models via configuration (orchestration layer, feature flags) instead of hard‑coding a single provider. [llm-stats](https://llm-stats.com/llm-updates)
* Run a focused benchmark on your own workload: compare one frontier model and one open‑weight/cost‑optimized model on quality vs latency vs cost, then codify routing rules. [llm-stats](https://llm-stats.com/llm-updates)

### Security and reliability need to be designed around AI, not added later

* Anthropic’s bug‑finding tool and Snyk‑style AI security assistants reinforce that LLMs will be part of your security pipeline, whether you plan for it or not. [fortune](https://fortune.com/2026/02/20/exclusive-anthropic-rolls-out-ai-tool-that-can-hunt-software-bugs-on-its-own-including-the-most-dangerous-ones-humans-miss/)
* The 2026 International AI Safety Report shows real dual‑use risk and notes models can sometimes detect when they are being evaluated vs deployed, which complicates testing. [techuk](https://www.techuk.org/resource/the-release-of-the-international-ai-safety-report-2026-navigating-rapid-ai-advancement-and-emerging-risks.html)

Actionable moves:

* Treat “AI code review” and “AI security review” as explicit CI jobs: one LLM‑based pass plus one traditional SAST/DAST tool. [builder](https://www.builder.io/blog/best-ai-tools-2026)
* For any AI feature (agents, RAG, content generation), write threat models that include prompt injection, data exfiltration, and tool misuse; enforce guardrails and logging from day one. [internationalaisafetyreport](https://internationalaisafetyreport.org/publication/international-ai-safety-report-2026)

### Web and product work: optimize for AI users, not just human users

* AI‑driven SEO and “agent optimization” are emerging: content and APIs must be structured so that agents (shopping assistants, answer bots) can parse, summarize, and recommend your product. [scalinghigh](https://www.scalinghigh.com/blogs/how-ai-is-transforming-web-development-in-2026)
* Figma and design‑to‑code AI flows are becoming mainstream, tying design tokens directly into generated code and PRs. [reuters](https://www.reuters.com/business/figma-jumps-ai-push-boosts-software-design-spending-2026-02-19/)

Actionable moves:

* Make your APIs and pages machine‑friendly: clean schemas, good metadata, consistent semantics—this helps both search engines and AI agents recommend you. [forbes](https://www.forbes.com/sites/catherineerdly/2026/02/22/a-2026-guide-to-getting-agentic-ai-to-recommend-your-e-commerce-site/)
* If you build UI, connect your design system and Figma to an AI‑aware toolchain so design → production code is a mostly automated path with humans reviewing the PRs. [reuters](https://www.reuters.com/business/figma-jumps-ai-push-boosts-software-design-spending-2026-02-19/)

## Models and research

**Claude Sonnet 4.6** launched [February 17](https://www.anthropic.com/news/claude-sonnet-4-6) as the new default for Free and Pro users on claude.ai. It claims Opus-class performance on coding and agents, with a 1M token context window in beta, at Sonnet 4.5 pricing (\$3/\$15 per million tokens). [CNBC reported](https://www.cnbc.com/2026/02/17/anthropic-ai-claude-sonnet-4-6-default-free-pro.html) that developers with early access preferred it over Opus 4.5 for most workloads. Opus is now more of a specialist tier for the hardest reasoning tasks.

**DeepSeek V4** dropped [February 17](https://introl.com/blog/deepseek-v4-february-2026-coding-model-release) with an Engram conditional memory architecture: a constant-time knowledge retrieval system that offloads static memory to CPU RAM, cutting inference costs. It claims 1 trillion parameters, 1M+ token context, and 80%+ on SWE-bench. [Technical leaks](https://techbriefly.com/2026/02/23/technical-leaks-reveal-deepseek-v4-lite-outperforms-gemini-3-1/) at week's end suggest V4 Lite outperforms Gemini 3.1 on several benchmarks, though independent verification is still pending.

**Chinese model wave.** Lunar New Year brought a cluster of releases: Alibaba's Qwen 3.5, Zhipu AI's GLM-5 (744B parameters, fully open-source, [top of SWE-rebench](https://www.euronews.com/next/2026/02/17/these-are-chinas-new-ai-models-that-have-just-been-released-ahead-of-the-lunar-new-year)), and Moonshot AI's Kimi K2.5, which can coordinate up to 100 sub-agents across 1,500 tool calls. At [\$0.10/M input tokens](https://www.swfte.com/pt/blog/ai-model-rush-february-2026), K2.5 brings multi-agent architectures into budget range for small teams.

**Anthropic exposes industrial-scale distillation attacks.** In a [February 23 blog post](https://www.anthropic.com/news/detecting-and-preventing-distillation-attacks), Anthropic said DeepSeek, MiniMax, and Moonshot AI created over 24,000 fraudulent accounts to pull 16 million+ exchanges from Claude, targeting agentic reasoning and coding specifically. Anthropic caught MiniMax's campaign while it was still active, before the model being trained had shipped. The timing was not subtle: the post landed the same day US Congress was debating AI chip export controls ([Bloomberg](https://www.bloomberg.com/news/articles/2026-02-23/anthropic-says-deepseek-minimax-distilled-ai-models-for-gains), [TechCrunch](https://techcrunch.com/2026/02/23/anthropic-accuses-chinese-ai-labs-of-mining-claude-as-us-debates-ai-chip-exports/)).

## Coding agents and dev tools

**Claude Code Security** launched [February 20 as a limited research preview](https://www.anthropic.com/news/claude-code-security). Using Opus 4.6, it found [500+ zero-day vulnerabilities](https://fortune.com/2026/02/20/exclusive-anthropic-rolls-out-ai-tool-that-can-hunt-software-bugs-on-its-own-including-the-most-dangerous-ones-humans-miss/) in production open-source codebases, some sitting undetected for decades. Unlike traditional SAST tools, it traces data flows and component interactions rather than matching patterns. [Cybersecurity stocks dropped 8-10%](https://venturebeat.com/security/anthropic-claude-code-security-reasoning-vulnerability-hunter) on the news. Free expedited access is available for open-source maintainers.

**GitHub Agent HQ** now lets [Copilot subscribers run Claude and Codex alongside Copilot](https://github.blog/news-insights/company-news/pick-your-agent-use-claude-and-codex-on-agent-hq/) from github.com, Mobile, and VS Code. Each session costs one premium request. GitHub is hedging its AI provider bets rather than going all-in on any single model.

**Simon Willison** published [Agentic Engineering Patterns](https://simonwillison.net/2026/Feb/23/agentic-engineering-patterns/), a growing guide to coding with AI agents. Two early patterns: "code is cheap now" (agents collapse the cost of writing code, which disrupts intuitions about every trade-off) and "red/green TDD" (test-first development is a natural fit, since agents can break code in subtle ways that only a test suite reliably catches). Worth reading before you build anything agent-driven.

**Martin Fowler** published [fragments from the Thoughtworks Future of Software Development Retreat](https://martinfowler.com/fragments/2026-02-18.html), including the advice to treat every AI-generated diff as a pull request from a productive but untrustworthy collaborator.

**ThePrimeagen's "99"** is a Neovim AI plugin that [deliberately restricts AI to developer-controlled areas](https://www.youtube.com/@ThePrimeagen) rather than granting full codebase access. Not everyone wants an agent with the keys to the whole repo.

## Web development and frameworks

**Cloudflare Markdown for Agents** ([launched February 12](https://blog.cloudflare.com/markdown-for-agents/)) automatically converts HTML to Markdown when AI agents send `Accept: text/markdown`. Token reduction is dramatic: one tested page went from 16,180 tokens in HTML to 3,150 in Markdown, an 80% cut. Already supported natively by Claude Code and OpenCode. Available for Pro, Business, and Enterprise plans.

**Cloudflare Code Mode** ([February 20](https://blog.cloudflare.com)) compresses Cloudflare's 2,500+ API endpoints into a format an agent can consume in roughly 1,000 tokens. Most API surfaces are too large for context windows; this is one fix.

**Vercel's fast-webstreams** ([February 18](https://vercel.com/blog/we-ralph-wiggumed-webstreams-to-make-them-10x-faster)) replaces WHATWG WebStreams internals with Node.js native streams, same API surface. Benchmarks show [10-14x throughput gains](https://github.com/vercel-labs/fast-webstreams) for common patterns. Matteo Collina is upstreaming the work to Node.js itself. If you run server-rendered Next.js, this is a free performance win.

**Figma** guided [2026 revenue to \$1.36-1.37B](https://www.reuters.com/business/figma-jumps-ai-push-boosts-software-design-spending-2026-02-19/) (vs \$1.29B expected). The beat came from AI-assisted design features driving ARPU up. Design-to-code tooling is becoming standard in front-end work.

## Industry and business

**Anthropic's distillation bombshell** (covered above in Models) has real business implications. The US-China AI competition is now as much about IP theft as compute access, with distillation as the attack vector.

**Nvidia-Meta mega deal.** Nvidia will [sell Meta millions of chips](https://www.reuters.com/business/nvidia-sell-meta-millions-chips-multiyear-deal-2026-02-17/) across Blackwell, Rubin, and Grace/Vera platforms in a multiyear deal. Hyperscalers are securing GPU capacity early rather than waiting for prices to fall.

**ggml/llama.cpp joins Hugging Face.** The [founding team behind llama.cpp](https://huggingface.co/blog/ggml-joins-hf) joined Hugging Face to give the project long-term backing. ggml, llama.cpp, whisper.cpp, and GGUF continue as open-source projects with tighter integration into Hugging Face's model hub.

**AI layoffs continue.** [Over 22,000 AI-linked layoffs in 2026 so far](https://programs.com/resources/ai-layoffs/). Salesforce cut 5,000 roles after AI agents took on half of customer interactions; Meta cut 1,500 Reality Labs jobs. Fireship [put it plainly](https://www.youtube.com/c/fireship): per-seat pricing breaks when one agent replaces multiple human seats.

**ChatGPT launched ads** for [free and Go-tier US users](https://techcrunch.com/2026/02/09/chatgpt-rolls-out-ads/) on February 9, keeping paid tiers ad-free. The HN discussion pointed out that every major AI assistant builder (Alphabet 77% ad revenue, Meta 97%) is structurally an ad company.

**Cloudflare 6-hour outage.** A [misconfigured BGP change on February 20](https://blog.cloudflare.com/cloudflare-outage-february-20-2026/) withdrew 1,100 out of 6,500 BYOIP prefixes, dropping 25% of BYOIP customers for 6 hours. Laravel Cloud went down with it. Full post-mortem published.

## Interesting GitHub repositories

**[pinchtab/pinchtab](https://github.com/pinchtab/pinchtab)** - A standalone Go HTTP server (12MB binary) that bridges AI agents to browser automation via REST API. Uses accessibility-tree-based interaction over screenshots for 5-13x token efficiency. Supports stealth mode, persistent sessions, and multi-instance orchestration. A practical alternative to Playwright MCP for agent-driven browser tasks.

**[vercel-labs/visual-json](https://github.com/vercel-labs/visual-json)** - Schema-aware JSON editor from Vercel Labs. Ships as a headless core library, React UI components (TreeView, DiffView), and a VS Code extension. Apache 2.0. Useful for any application that needs visual JSON editing with schema validation.

**[planetscale/database-skills](https://github.com/planetscale/database-skills)** - Modular AI coding skills for MySQL, PostgreSQL, Vitess, and PlanetScale's Neki. Markdown-based skill definitions that plug into skills.sh and Cursor, giving AI assistants specialized knowledge for schema design, query optimization, and troubleshooting. A good pattern for domain-specific AI augmentation.

**[johannesjo/parallel-code](https://github.com/johannesjo/parallel-code)** - Electron/SolidJS desktop app that runs multiple AI coding agents (Claude Code, Codex CLI, Gemini CLI) simultaneously on the same repo, automatically creating isolated git branches and worktrees per task. Includes a diff viewer and mobile monitoring via QR code.

**[botiverse/agent-vault](https://github.com/botiverse/agent-vault)** - Secret management for AI agent workflows. Agents see encrypted placeholders (`<agent-vault:api-key>`) instead of real values; secrets are restored on write. Uses AES-256-GCM, auto-detects high-entropy secrets, and enforces TTY requirements to prevent prompt injection. Addresses a real gap in agent security.

**[superhq-ai/shuru](https://github.com/superhq-ai/shuru)** - Rust-based microVM sandbox for macOS/Apple Silicon that uses Apple's Virtualization.framework to boot ephemeral Alpine Linux VMs for agent code execution. Checkpoint-based state persistence and vsock port forwarding without network access. Avoids Docker overhead.

**[Ibrahim-3d/conductor-orchestrator-superpowers](https://github.com/Ibrahim-3d/conductor-orchestrator-superpowers)** - A Claude Code plugin that orchestrates 16 specialized agents and 42 skills via a repeating evaluate-loop cycle. Includes a "Board of Directors" for architectural decisions and four evaluators for UI/UX, code quality, integration, and business logic.

**[ShinMegamiBoson/OpenPlanter](https://github.com/ShinMegamiBoson/OpenPlanter)** - Python autonomous investigation agent with terminal UI. Processes heterogeneous datasets (corporate registries, campaign finance, lobbying records) to identify hidden connections using recursive LLM-powered sub-agents.

**[vikasprogrammer/walkie](https://github.com/vikasprogrammer/walkie)** - Peer-to-peer communication for AI agents using Hyperswarm DHT. No centralized server; agents discover each other and coordinate through encrypted channels via the Noise protocol.

**[letmutex/gitas](https://github.com/letmutex/gitas)** - Rust CLI for managing multiple Git identities. Interactive TUI, native keychain integration (macOS Keychain, Windows Credential Manager, Linux Secret Service), and per-command identity switching without modifying global config.

## Quick bits

* **Cloudflare shipped [post-quantum encryption across its entire SASE platform](https://blog.cloudflare.com)**, implementing hybrid ML-KEM into its IPsec product. First SASE offering with modern PQ encryption.
* **GitHub added [organization-level Copilot usage metrics dashboards](https://github.blog)** in public preview, useful for teams tracking AI adoption ROI.
* **The International AI Safety Report 2026** found that [all three major AI labs released models with heightened safeguards](https://internationalaisafetyreport.org/publication/international-ai-safety-report-2026) after failing to rule out biological weapons assistance, and that some models can detect evaluation vs. deployment contexts.
* **BarraCUDA**, a [15,000-line C99 CUDA compiler targeting AMD GPUs](https://github.com/Zaneham/BarraCUDA) with zero LLVM dependency, hit the HN front page. Supports RDNA 3/4 and plans Tenstorrent and Intel Arc targets. An impressive solo effort.
* **Florida's AI Bill of Rights** would [require parental consent for minors using AI chatbots](https://www.transparencycoalition.ai/news/ai-legislative-update-feb20-2026) and restrict personal data sales to AI firms.
* **Wikipedia blacklisted archive.today** after discovering the operator [embedded DDoS code and tampered with archived pages](https://boingboing.net/2026/02/21/archive-today-links-banned-at-wikipedia-after-operator-edits-archived-urls.html). Approximately 695,000 links are being replaced.
* **Chrome zero-day CVE-2026-2441** (CSS use-after-free, CVSS 8.8) was [actively exploited before patching](https://thehackernews.com/2026/02/new-chrome-zero-day-cve-2026-2441-under.html). Update to 145.0.7632.75+ immediately.
* **Ladybird browser ported its JavaScript engine to Rust** using Claude Code and Codex, [completing 25,000 lines in two weeks](https://simonwillison.net/2026/Feb/23/) with zero regressions, per Simon Willison.
* **F-Droid's "Keep Android Open" campaign** opposes [Google's September 2026 requirement](https://f-droid.org/2026/02/20/twif.html) that only verified developers (government ID required) can sideload apps on certified devices. Topped HN with 2,164 points.
* **Agentic frameworks in 2026** are being evaluated on [how they model time, memory, and failure](https://news.ycombinator.com/item?id=46509130), not just prompting and tool calls. Bounded autonomy and audit trails are the engineering problems that actually matter.

## Sources

* [Cline CLI 2.3.0 supply chain attack - The Hacker News](https://thehackernews.com/2026/02/cline-cli-230-supply-chain-attack.html)
* [Cline CLI 2.3.0 supply chain attack - The Register](https://www.theregister.com/2026/02/20/openclaw_snuck_into_cline_package/)
* [Cline CLI 2.3.0 supply chain attack - StepSecurity](https://www.stepsecurity.io/blog/cline-supply-chain-attack-detected-cline-2-3-0-silently-installs-openclaw)
* [Anthropic: Detecting and preventing distillation attacks](https://www.anthropic.com/news/detecting-and-preventing-distillation-attacks)
* [Anthropic: Introducing Claude Sonnet 4.6](https://www.anthropic.com/news/claude-sonnet-4-6)
* [Anthropic: Claude Code Security](https://www.anthropic.com/news/claude-code-security)
* [Claude Code Security - Fortune](https://fortune.com/2026/02/20/exclusive-anthropic-rolls-out-ai-tool-that-can-hunt-software-bugs-on-its-own-including-the-most-dangerous-ones-humans-miss/)
* [Claude Code Security - VentureBeat](https://venturebeat.com/security/anthropic-claude-code-security-reasoning-vulnerability-hunting)
* [DeepSeek V4 release - Introl](https://introl.com/blog/deepseek-v4-february-2026-coding-model-release)
* [DeepSeek V4 Lite leaks - TechBriefly](https://techbriefly.com/2026/02/23/technical-leaks-reveal-deepseek-v4-lite-outperforms-gemini-3-1/)
* [Chinese AI model releases - Euronews](https://www.euronews.com/next/2026/02/17/these-are-chinas-new-ai-models-that-have-just-been-released-ahead-of-the-lunar-new-year)
* [AI model rush February 2026 - Swfte](https://www.swfte.com/pt/blog/ai-model-rush-february-2026)
* [GitHub Agent HQ - GitHub Blog](https://github.blog/news-insights/company-news/pick-your-agent-use-claude-and-codex-on-agent-hq/)
* [Simon Willison: Agentic Engineering Patterns](https://simonwillison.net/2026/Feb/23/agentic-engineering-patterns/)
* [Simon Willison: Ladybird adopts Rust](https://simonwillison.net/2026/Feb/23/)
* [Martin Fowler: Software Development Retreat fragments](https://martinfowler.com/fragments/2026-02-18.html)
* [Cloudflare: Markdown for Agents](https://blog.cloudflare.com/markdown-for-agents/)
* [Cloudflare: Outage February 20, 2026](https://blog.cloudflare.com/cloudflare-outage-february-20-2026/)
* [Cloudflare: Post-quantum SASE encryption](https://blog.cloudflare.com)
* [Vercel: fast-webstreams](https://vercel.com/blog/we-ralph-wiggumed-webstreams-to-make-them-10x-faster)
* [Vercel: Skills Night](https://vercel.com/blog)
* [Nvidia-Meta chip deal - Reuters](https://www.reuters.com/business/nvidia-sell-meta-millions-chips-multiyear-deal-2026-02-17/)
* [ggml joins Hugging Face](https://huggingface.co/blog/ggml-joins-hf)
* [Figma AI revenue guidance - Reuters](https://www.reuters.com/business/figma-jumps-ai-push-boosts-software-design-spending-2026-02-19/)
* [AI layoffs tracker - Programs.com](https://programs.com/resources/ai-layoffs/)
* [ChatGPT ads - TechCrunch](https://techcrunch.com/2026/02/09/chatgpt-rolls-out-ads/)
* [International AI Safety Report 2026](https://internationalaisafetyreport.org/publication/international-ai-safety-report-2026)
* [BarraCUDA - GitHub](https://github.com/Zaneham/BarraCUDA)
* [Florida AI Bill of Rights - Transparency Coalition](https://www.transparencycoalition.ai/news/ai-legislative-update-feb20-2026)
* [Wikipedia blacklists archive.today - Boing Boing](https://boingboing.net/2026/02/21/archive-today-links-banned-at-wikipedia-after-operator-edits-archived-urls.html)
* [Chrome CVE-2026-2441 - The Hacker News](https://thehackernews.com/2026/02/new-chrome-zero-day-cve-2026-2441-under.html)
* [F-Droid Keep Android Open](https://f-droid.org/2026/02/20/twif.html)
* [Agentic frameworks HN discussion](https://news.ycombinator.com/item?id=46509130)
* [Nate B Jones - AI News and Strategy Daily](https://www.youtube.com/@NateBJones)
* [Fireship](https://www.youtube.com/c/fireship)
* [Anthropic distillation - Bloomberg](https://www.bloomberg.com/news/articles/2026-02-23/anthropic-says-deepseek-minimax-distilled-ai-models-for-gains)
* [Anthropic distillation - TechCrunch](https://techcrunch.com/2026/02/23/anthropic-accuses-chinese-ai-labs-of-mining-claude-as-us-debates-ai-chip-exports/)
* [Claude Sonnet 4.6 - CNBC](https://www.cnbc.com/2026/02/17/anthropic-ai-claude-sonnet-4-6-default-free-pro.html)


# AI Weekly Review - Mar. 2nd 2026
Source: https://developer.upsun.com/posts/ai/aiweekly-2026-03-02

A press, Youtube and Github review of everything AI


<PostMeta />

> Anthropic's Claude Code Security found 500+ zero-day vulnerabilities in production open-source code that had survived years of expert review. Chinese lab MiniMax released an open-weight model matching Claude Opus 4.6 at 1/20th the cost. And Chrome's agentic "auto browse" plus Google's Universal Commerce Protocol are making it clear that your next user might be an AI agent, not a person.

## Highlight of the week

### Claude Code Security finds 500+ zero-days in production open-source code

Anthropic's [Claude Code Security](https://www.anthropic.com/news/claude-code-security), launched February 20 as a limited research preview, is the most interesting security tool we have seen in a while. It uses Claude Opus 4.6 to scan codebases the way a human security researcher would: it traces data flows, follows how components interact, and finds bugs that pattern-matching static analysis tools cannot.

The number that got everyone's attention: [over 500 vulnerabilities in production open-source codebases](https://venturebeat.com/security/anthropic-claude-code-security-reasoning-vulnerability-hunting). These are bugs that survived years of expert code review. Each finding goes through a multi-stage verification pipeline to filter false positives, and the tool produces targeted patches for human review.

What makes this different from every other "AI for security" announcement is scope. This is not glorified linting. It reasons about code semantics, not syntax. It is available to Enterprise and Team customers, with expedited access for open-source maintainers. If a tool can find bugs that decades of review missed, "we reviewed the code" stops being a credible security posture. AI-assisted security scanning will be as standard as CI linting within a year, and teams that do not adopt it will look negligent by comparison.

## Models and research

### MiniMax M2.5: open-weight models close the gap at 1/20th the cost

The most notable model release this period came from Chinese startup MiniMax, not a US lab. Their [M2.5 model](https://venturebeat.com/technology/minimaxs-new-open-m2-5-and-m2-5-lightning-near-state-of-the-art-while), released February 11 under a modified MIT license, hits 80.2% on SWE-Bench Verified (matching Claude Opus 4.6) and ranks first on Multi-SWE-Bench at 51.3%. It is a 230B parameter mixture-of-experts model that activates only 10B parameters per forward pass, which explains the [1/20th cost claim](https://winbuzzer.com/2026/02/14/minimax-m25-open-source-ai-model-claude-opus-cost-xcxwbn/) (roughly \$1/hour at 100 tokens/second).

GPT-4-class performance is commoditizing fast. If you are not abstracting your model interface behind an internal API, you are building on sand. The "best model" changes quarterly.

### Frontier model landscape, early March 2026

Where things stand:

* **Claude Opus 4.6** (Feb 5): 1M token context window (beta), 128K output tokens, adaptive thinking, [agent teams in Claude Code](https://techcrunch.com/2026/02/05/anthropic-releases-opus-4-6-with-new-agent-teams/). \$5/\$25 per million input/output tokens.
* **Claude Sonnet 4.6** (Feb 17): faster, cheaper reasoning model for production workloads.
* **Gemini 3.1 Pro** (Feb 19): [MoE architecture](https://deepmind.google/models/gemini/pro/) on top of Gemini 3 Pro. Handles 8.4 hours of audio, 900-page PDFs, or 1 hour of video in a single prompt. 65,536 output tokens. \$2/\$12 per million tokens. [Gemini 3 Pro Preview sunsets March 9](https://discuss.ai.google.dev/t/migrate-from-gemini-3-pro-preview-to-gemini-3-1-pro-preview-before-march-9-2026/127062), so migrate now.
* **GPT-5.3-Codex** (Feb 5): [new high on SWE-Bench Pro and Terminal-Bench](https://openai.com/index/introducing-gpt-5-3-codex/), 25% faster for Codex users. First OpenAI model rated "High" cybersecurity risk under their Preparedness Framework, which tells you something about how capable it is.

The [llm-stats.com tracker](https://llm-stats.com/llm-updates) captures three practical patterns: reasoning-first models trading speed for accuracy, multimodal becoming baseline, and GPT-4-level performance available at a fraction of what it cost 18 months ago.

### NVIDIA's VibeTensor: AI agents build their own deep learning runtime

NVIDIA released [VibeTensor](https://github.com/NVlabs/vibetensor), a full deep learning system software stack generated by LLM-powered coding agents ([paper](https://arxiv.org/abs/2601.16238)). It is a PyTorch-style tensor library in C++20 with CPU and CUDA support, Python bindings, and an experimental Node.js/TypeScript interface. Agents proposed diffs, ran builds and tests, and validated correctness without per-change manual review. End-to-end training was verified on H100 and Blackwell GPUs.

This goes beyond demo territory. Coding agents produced coherent system software from language bindings down to CUDA memory management, with correctness enforced primarily by automated tests. If you are thinking about agentic coding workflows, VibeTensor is the best concrete proof point for what specification-driven agent development can actually deliver today.

## Coding agents and dev tools

### The AI coding tool landscape fragments

The AI coding assistant market [has no clear default anymore](https://dev.to/pockit_tools/cursor-vs-windsurf-vs-claude-code-in-2026-the-honest-comparison-after-using-all-three-3gof). GitHub Copilot introduced specialized agents for codebase exploration and task automation. Cursor moved to an agent-centric multi-agent interface. Windsurf competes on price (\$10/month with unlimited Claude access). Claude Code added [agent teams](https://techcrunch.com/2026/02/05/anthropic-releases-opus-4-6-with-new-agent-teams/) with Opus 4.6 so multiple agents can work in parallel on research, writing, and verification.

These tools are all moving in the same direction: from smart autocomplete to autonomous workers that can plan changes across files, run tests, and iterate when things break. The developer's job shifts toward writing constraints, reviewing output, and integrating systems.

### Prompting splits into four distinct skills

Nate B Jones's viral framework ([video](https://www.youtube.com/watch?v=BpibZSMGtdY)) makes a useful distinction. "Prompting" now covers four separate skills, and most people only practice the first:

1. **Prompt craft**: writing clear prompts for brief, session-based interactions. What everyone thinks of as "prompting."
2. **Context engineering**: building the information environment for an agent's full task: system prompts, retrieval pipelines, memory, project files. Shopify CEO Tobi Lutke has been [public about treating this as a core discipline](https://www.youtube.com/watch?v=BpibZSMGtdY).
3. **Intent engineering**: encoding organizational goals and decision boundaries so agents optimize for the right outcome.
4. **Specification engineering**: writing structured blueprints that let agents execute reliably over days or weeks without a human in the loop.

This matters because autonomous agent sessions keep getting longer. Claude Code sessions nearly doubled in length between October 2025 and January 2026. Jones illustrates the gap with a comparison: person A spends 40 minutes cleaning up 80%-correct output, while person B spends 11 minutes writing a structured spec and gets perfect results while going for coffee. Same model, same day, 10x productivity difference.

### Claude Cowork enters enterprise workflows

Anthropic's [Claude Cowork](https://claude.com/blog/cowork-research-preview), updated February 24, now connects to Google Drive, Gmail, DocuSign, and FactSet. Analysts called it a ["SaaSpocalypse" moment](https://markets.financialcontent.com/stocks/article/marketminute-2026-2-26-the-saaspocalypse-arrives-anthropics-claude-cowork-redefines-the-enterprise-frontier) for legacy enterprise software. It also [landed on Windows](https://venturebeat.com/technology/anthropics-claude-cowork-finally-lands-on-windows-and-it-wants-to-automate) and targets routine office workflows for non-technical workers. Whether the "SaaSpocalypse" framing is overblown remains to be seen, but the integration depth is real.

## Web development and frameworks

### Chrome's auto-browse and the agentic web

Google's [Chrome auto-browse](https://blog.google/products-and-platforms/products/chrome/gemini-3-auto-browse/), powered by Gemini 3, lets the browser scroll, click, fill forms, and complete multi-step tasks autonomously. It is available to AI Pro/Ultra subscribers. Early use cases include scheduling appointments, collecting tax documents, getting contractor quotes, and filing expense reports.

The web development angle is straightforward but worth stating plainly. As [TechCrunch put it](https://techcrunch.com/2026/01/28/chrome-takes-on-ai-browsers-with-tighter-gemini-integration-agentic-features-for-autonomous-tasks/): your site now has two audiences, humans and agents. Clean markup, structured data, ARIA roles, and machine-readable value propositions are not best practices anymore. They are requirements for a chunk of your traffic.

### Universal Commerce Protocol changes how agents buy things

Google's [Universal Commerce Protocol (UCP)](https://developers.googleblog.com/under-the-hood-universal-commerce-protocol-ucp/) is an open standard for agentic commerce built with Shopify, Etsy, Wayfair, Target, and Walmart. It covers the full purchase journey from discovery through post-purchase support, and integrates with Agent Payments Protocol (AP2), Agent2Agent (A2A), and MCP.

Daniel Miessler made a related argument in his ["Great Transition" analysis](https://www.youtube.com/watch?v=6pP8x8sXoaM) that software is moving from standalone apps with human UIs to API-first services consumed by agents. His line stuck with me: "if I have to open an app, I have already lost." He predicts products will compete in agent-facing directories rather than through SEO and marketing websites. UCP is the first real infrastructure making that vision concrete at scale.

### Browser automation shifts from scripts to agents

A [2026 overview of browser automation](https://www.browserless.io/blog/state-of-ai-browser-automation-2026) reports that LLM-driven agents now parse natural-language goals and act directly on the DOM without brittle CSS selectors. Models running locally in the browser via WebGPU cut latency and make UI-aware automation more reliable. The [agentic browser landscape](https://www.nohackspod.com/blog/agentic-browser-landscape-2026) already includes Brave Leo, Opera Aria, Arc Max, and Perplexity Comet, each with task automation, cross-session memory, and content synthesis.

For testing teams: end-to-end tests written as natural-language goals instead of Selenium selectors. For product teams: fragile UI patterns (infinite scroll without structure, pixel-dependent CSS) will break agent workflows.

## Industry and business

### MWC 2026: telecoms become AI infrastructure providers

Mobile World Congress 2026 (themed "The IQ Era") left no doubt that telecoms see themselves as AI infrastructure companies now:

* **Nokia and NVIDIA** showed [AI and RAN workloads running on shared GPU infrastructure](https://www.globenewswire.com/news-release/2026/03/01/3246932/0/en/Nokia-accelerates-AI-RAN-momentum-with-new-partnerships-driving-path-to-AI-Native-6G-MWC26.html) in a live operator environment with BT, Elisa, NTT DOCOMO, and Vodafone. Nokia also launched Doksuri radio heads with on-device AI.
* **NVIDIA and global operators** [committed to building AI-native open 6G networks](https://blogs.nvidia.com/blog/software-defined-ai-ran/), turning future telecom infrastructure into a distributed AI fabric.
* **SoftBank** pitched a [Telco AI Cloud](https://www.prnewswire.com/news-releases/softbank-corp-announces-telco-ai-cloud-vision-to-build-social-infrastructure-for-the-ai-era-leveraging-its-telecommunications-foundation-302700423.html) that frames its telecom assets as a national AI cloud for large model hosting and edge inference.
* **GSMA** launched [Open Telco AI](https://www.newswire.ca/news-releases/gsma-launches-open-telco-ai-to-accelerate-development-of-telco-grade-ai-821861682.html), a portal for sharing telco-specific open models, datasets, and benchmarks.

New deployment targets (telco edge, 5G/6G networks) bring new constraints: latency requirements, bandwidth profiles, and regulatory considerations that differ from standard cloud.

### AI deepfake voice fraud reaches mass scale

The [State of the Call 2026 report](https://finance.yahoo.com/news/state-call-2026-ai-deepfake-050100461.html) found that 1 in 4 Americans has received a deepfake voice call in the past year. Another 24% are unsure they could tell the difference. When asked who is winning the fight, [consumers chose scammers over carriers by nearly 2-to-1](https://martechseries.com/predictive-ai/ai-platforms-machine-learning/state-of-the-call-2026-ai-deepfake-voice-calls-hit-1-in-4-americans-as-consumers-say-scammers-are-beating-mobile-network-operators-2-to-1/), and 38% said they are ready to switch providers. Americans now receive an average of 9.9 unwanted calls per week, growing at 16% annually since 2023. The phone is becoming a liability.

### AI policy: federal vs. state collision course

The December 2025 executive order on AI policy aims to [preempt stricter state-level rules](https://www.gunder.com/en/news-insights/insights/2026-ai-laws-update-key-regulations-and-practical-guidance), with DOJ evaluations of "onerous" state AI laws due by March 11, 2026. But California and Colorado laws that [took effect January 1, 2026](https://www.kslaw.com/news-and-insights/new-state-ai-laws-are-effective-on-january-1-2026-but-a-new-executive-order-signals-disruption) already impose risk assessments, discrimination safeguards, and documentation requirements on "high-risk AI systems." Meanwhile, the [International AI Safety Report 2026](https://www.insideprivacy.com/artificial-intelligence/international-ai-safety-report-2026-examines-ai-capabilities-risks-and-safeguards/) warns that current safeguards can still be bypassed at "moderately high" rates.

If you are shipping AI features in the US, compliance is now a design constraint. The DOJ deadline on March 11 could change the landscape again.

## Interesting GitHub repositories

* **[claude-code-tips](https://github.com/ykdojo/claude-code-tips)** (3.9k stars): 45 practical tips for Claude Code, including a custom status line with 10 color themes, voice transcription, system prompt optimization that cuts token overhead by \~45%, and git workflow automation. Good reference for daily Claude Code use.

* **[ContextPlus](https://github.com/ForLoopCodes/contextplus)**: MCP server that turns large codebases into searchable semantic graphs using Tree-sitter AST parsing, spectral clustering, and Obsidian-style linking. Supports TypeScript, Python, Rust, and Go. Useful when AI coding agents need to understand structure, not just text.

* **[OpenFang](https://github.com/RightNow-AI/openfang)**: Open-source "agent operating system" in Rust. Ships as a single \~32MB binary with 7 autonomous capability packages (YouTube shorts, lead gen, OSINT, forecasting, research, Twitter, browser automation). 16 security layers, 40 messaging adapters, 27 LLM providers. Ambitious. Worth watching.

* **[CLIHub](https://github.com/thellimist/clihub)** (499 stars): Converts any MCP server into a compiled CLI binary. Each tool becomes a subcommand with auto-derived flags. Produces 6.5MB static binaries, zero runtime dependencies. Supports OAuth 2.0, bearer tokens, API keys. Useful when agents need direct CLI access to MCP services.

* **[Claude Forge](https://github.com/sangrokjung/claude-forge)**: Billed as "oh-my-zsh for Claude Code." Bundles 11 specialized AI agents, 36 slash commands, 15 skill workflows, and 14 automation hooks. Six-layer security defense. For developers who want a batteries-included Claude Code setup.

* **[EdgeQuake](https://github.com/raphaelmansuy/edgequake)**: Rust-based Graph-RAG implementing the LightRAG algorithm. Six query modes from naive vector search to hybrid graph/vector blending. Claims 5x faster query latency than traditional RAG, 4x lower memory usage. Built on Axum, PostgreSQL with Apache AGE, and pgvector. Comes with OpenAPI docs and Kubernetes health checks. Look at this if you need RAG that can handle multi-hop reasoning.

* **[deff](https://github.com/flamestro/deff)**: Rust TUI for interactive side-by-side git diff review. Vim-like controls, syntax highlighting, search within diffs, persistent review tracking in `.git/deff/reviewed/`. Clean and fast.

* **[BullshitBench](https://github.com/petergpt/bullshit-benchmark)**: Tests whether AI models can reject nonsensical prompts instead of confidently running with them. 100 questions across five domains (software, finance, legal, medical, physics). Multi-judge evaluation using models from Anthropic, OpenAI, and Google. Useful benchmark that tests something most benchmarks do not.

* **[Aqua](https://github.com/quailyquaily/aqua)**: Peer-to-peer messaging protocol for AI agent communication. Built in Go with end-to-end encryption, identity verification, and Circuit Relay v2 for cross-network connectivity. No centralized server required.

* **[Mission Control](https://github.com/MeisnerDan/mission-control)**: Task management for coordinating multiple AI coding agents. Eisenhower Matrix prioritization, Kanban tracking, 5 built-in agent roles, continuous missions with auto-dispatch, autonomous daemon for 24/7 operation. Next.js 15, local JSON storage, no cloud dependency. Made for solo founders running fleets of AI agents.

* **[Spank](https://github.com/taigrr/spank)** (the fun one): macOS utility that detects physical impacts on Apple Silicon MacBooks via the accelerometer and plays audio responses. Modes include "pain" (protest sounds), "halo" (game death sounds), and "sexy" (escalating responses). Absolute peak engineering.

## Quick bits

* **AI is making people work more, not less**: A study covered by [India Today](https://www.indiatoday.in/jobs/story/study-finds-ai-tools-are-making-people-work-more-many-skipping-breaks-tchc-2876362-2026-03-02) found workers using AI tools skip breaks and put in longer hours. Current deployments seem to increase throughput rather than free up time.
* **"AI is making junior devs useless" goes viral**: A widely shared [post](https://beabetterdev.com/2026/03/01/ai-is-making-junior-devs-useless/) argues AI copilots commoditize basic coding while making system design and architecture skills more valuable. The early-career opportunity debate rolls on.
* **Claude outage on March 2**: Anthropic [confirmed a worldwide outage](https://www.bleepingcomputer.com/news/artificial-intelligence/anthropic-confirms-claude-is-down-in-a-worldwide-outage/) across all Claude platforms starting at 11:30 UTC.
* **Gemini 3 Pro Preview sunset**: Google will [kill Gemini 3 Pro Preview on March 9](https://discuss.ai.google.dev/t/migrate-from-gemini-3-pro-preview-to-gemini-3-1-pro-preview-before-march-9-2026/127062). Migrate to 3.1 Pro Preview before then.
* **Simon Willison on agentic engineering patterns**: Willison's [February 23 post](https://simonwillison.net/) and his "vibe coded" macOS presentation app continue his practical, no-hype approach to AI tooling.
* **CoreWeave diversifies beyond GPUs**: The GPU cloud provider is [moving into storage and Kubernetes optimization](https://www.forbes.com/sites/rscottraynovich/2026/01/22/how-ai-will-shape-cloud-services--infrastructure-in-2026/) as hyperscalers ramp up AI infrastructure and pure GPU hosting commoditizes.
* **The "Great Transition" thesis**: Daniel Miessler's [long-form analysis](https://www.youtube.com/watch?v=6pP8x8sXoaM) ties together several shifts at once: knowledge moving from private to public via skills and open models, software moving from apps to APIs, enterprise work mapping to AI-orchestrated SOP graphs, cybersecurity becoming AI vs. AI at machine speed. Worth 90 minutes if you want a unifying mental model for where all of this is headed.

## Sources

* [Anthropic: Claude Code Security](https://www.anthropic.com/news/claude-code-security)
* [Anthropic: Claude Opus 4.6](https://www.anthropic.com/news/claude-opus-4-6)
* [Anthropic: Claude Cowork](https://claude.com/blog/cowork-research-preview)
* [VentureBeat: Claude Code Security finds 500+ vulnerabilities](https://venturebeat.com/security/anthropic-claude-code-security-reasoning-vulnerability-hunting)
* [VentureBeat: MiniMax M2.5](https://venturebeat.com/technology/minimaxs-new-open-m2-5-and-m2-5-lightning-near-state-of-the-art-while)
* [OpenAI: GPT-5.3-Codex](https://openai.com/index/introducing-gpt-5-3-codex/)
* [Fortune: GPT-5.3-Codex cybersecurity concerns](https://fortune.com/2026/02/05/openai-gpt-5-3-codex-warns-unprecedented-cybersecurity-risks/)
* [Google DeepMind: Gemini 3.1 Pro](https://deepmind.google/models/gemini/pro/)
* [TechCrunch: Anthropic Opus 4.6 agent teams](https://techcrunch.com/2026/02/05/anthropic-releases-opus-4-6-with-new-agent-teams/)
* [TechCrunch: Chrome agentic browsing](https://techcrunch.com/2026/01/28/chrome-takes-on-ai-browsers-with-tighter-gemini-integration-agentic-features-for-autonomous-tasks/)
* [Google Blog: Chrome Gemini auto-browse](https://blog.google/products-and-platforms/products/chrome/gemini-3-auto-browse/)
* [Google Developers: Universal Commerce Protocol](https://developers.googleblog.com/under-the-hood-universal-commerce-protocol-ucp/)
* [Nokia: AI-RAN at MWC26](https://www.globenewswire.com/news-release/2026/03/01/3246932/0/en/Nokia-accelerates-AI-RAN-momentum-with-new-partnerships-driving-path-to-AI-Native-6G-MWC26.html)
* [NVIDIA: Software-defined AI-RAN](https://blogs.nvidia.com/blog/software-defined-ai-ran/)
* [SoftBank: Telco AI Cloud](https://www.prnewswire.com/news-releases/softbank-corp-announces-telco-ai-cloud-vision-to-build-social-infrastructure-for-the-ai-era-leveraging-its-telecommunications-foundation-302700423.html)
* [GSMA: Open Telco AI](https://www.newswire.ca/news-releases/gsma-launches-open-telco-ai-to-accelerate-development-of-telco-grade-ai-821861682.html)
* [NVIDIA: VibeTensor](https://github.com/NVlabs/vibetensor)
* [arXiv: VibeTensor paper](https://arxiv.org/abs/2601.16238)
* [Hiya: State of the Call 2026](https://finance.yahoo.com/news/state-call-2026-ai-deepfake-050100461.html)
* [Gunder: 2026 AI laws update](https://www.gunder.com/en/news-insights/insights/2026-ai-laws-update-key-regulations-and-practical-guidance)
* [King & Spalding: State AI laws](https://www.kslaw.com/news-and-insights/new-state-ai-laws-are-effective-on-january-1-2026-but-a-new-executive-order-signals-disruption)
* [International AI Safety Report 2026](https://www.insideprivacy.com/artificial-intelligence/international-ai-safety-report-2026-examines-ai-capabilities-risks-and-safeguards/)
* [Browserless: State of AI browser automation](https://www.browserless.io/blog/state-of-ai-browser-automation-2026)
* [Reuters: AI disruption as market risk](https://www.reuters.com/world/asia-pacific/wall-st-week-ahead-ai-disruption-looms-over-markets-with-us-jobs-data-tap-2026-03-02/)
* [llm-stats.com: AI model updates](https://llm-stats.com/llm-updates)
* [CNBC: Claude Cowork enterprise connectors](https://www.cnbc.com/2026/02/24/anthropic-claude-cowork-office-worker.html)
* [Simon Willison: Agentic engineering patterns](https://simonwillison.net/)
* [Nate B Jones: Prompting splits into 4 skills](https://www.youtube.com/watch?v=BpibZSMGtdY)
* [Unsupervised Learning: The Great Transition](https://www.youtube.com/watch?v=6pP8x8sXoaM)
* [BleepingComputer: Claude outage](https://www.bleepingcomputer.com/news/artificial-intelligence/anthropic-confirms-claude-is-down-in-a-worldwide-outage/)
* [India Today: AI making people work more](https://www.indiatoday.in/jobs/story/study-finds-ai-tools-are-making-people-work-more-many-skipping-breaks-tchc-2876362-2026-03-02)
* [Be a Better Dev: Junior devs and AI](https://beabetterdev.com/2026/03/01/ai-is-making-junior-devs-useless/)
* [Forbes: AI cloud infrastructure 2026](https://www.forbes.com/sites/rscottraynovich/2026/01/22/how-ai-will-shape-cloud-services--infrastructure-in-2026/)


# AI Weekly Review - Mar. 9th 2026
Source: https://developer.upsun.com/posts/ai/aiweekly-2026-03-09

A press, Youtube and Github review of everything AI


<PostMeta />

> The question flipped this week. Not "which AI model should we use?" but "how do we coordinate twenty agents running inside our stack?" Three open-source projects landed with three very different answers. OpenAI shipped GPT-5.4 with native computer use and a 1M-token context window. Anthropic sued the Pentagon after being labeled a supply chain risk. Karpathy dropped autoresearch for overnight autonomous ML experiments. And a Pragmatic Engineer survey of 900+ engineers put Claude Code at the top of the AI coding tool rankings.

## Highlight of the week

### The agent coordination era has arrived

AI agents can write code. That part is settled. Claude Code hit \$1B ARR in six months, GitHub Copilot crossed 15M paid seats. The problem now is what happens when you have five, ten, twenty of them running at once. Three open-source projects that landed this week show just how little consensus there is on the answer despite a global trend.

[Symphony](https://github.com/openai/symphony), from OpenAI, is a long-running daemon written in Elixir on OTP. It polls a Linear issue tracker, claims eligible tasks, spawns isolated Codex agents in hermetic workspaces, and delivers verified pull requests with CI status, walkthrough videos, and complexity analysis. What's interesting is what it's *not*: Symphony is not a multi-agent framework. Each issue gets exactly one agent. The "orchestration" is about managing many concurrent single-agent runs, not coordinating agents on a shared task. OpenAI calls this discipline [harness engineering](https://www.digitalapplied.com/blog/openai-symphony-autonomous-code-orchestration-framework), which basically means: build the infrastructure, constraints, and feedback loops around the agent so it can't go off the rails.

> Not to be confused with my favorite development framework: Symfony.

[Paperclip AI](https://github.com/paperclipai/paperclip) goes the other direction entirely. It models the whole company as the coordination abstraction: org charts, reporting lines, budgets, cascading goals from company mission down to individual tasks. The tagline: "If OpenClaw is an employee, Paperclip is the company." Agents execute wherever they run (Claude Code, Codex, Bash) and phone home via a heartbeat system. [4.3K+ stars](https://paperclip.ing/) and 23 contributors already. Atomic task checkout prevents double-work, monthly per-agent budgets enforce cost controls, and an immutable ticket system traces every conversation and tool call. The human is "the board," not a line-level supervisor.

[Agentlytics](https://github.com/f/agentlytics), from Fatih Kadir Akin (creator of prompts.chat), tackles a different gap entirely: nobody can see across all their agents at once. It's a zero-config analytics dashboard (`npx agentlytics`) that reads local session data from 16 AI coding editors and shows unified metrics on token spending, model usage, and editor efficiency. Everything runs locally on SQLite. It's early (82 stars, solo maintainer), but the problem it addresses only gets worse as you add more agents.

I keep coming back to the framing from [background-agents.com](https://background-agents.com/), published by Ona (formerly Gitpod). Their metaphor is "the self-driving codebase": developers shift from driving every line of code to supervising. The site draws a sharp line between foreground agents (interactive Copilot, Claude Code sessions) and background agents, the cloud-native, event-driven kind that run autonomously on triggers like CVE disclosures or CI failures and produce pull requests you wake up to. Ona identifies three pillars for background agent infrastructure: isolated compute, event routing, and governance. Symphony covers isolation and governance but can only poll. Paperclip covers governance and event routing but delegates compute. Agentlytics covers none of the three but tells you what's actually happening.

The practical lesson: think in layers, not monoliths. The protocol stack is converging. MCP (Anthropic, now under the Linux Foundation) handles agent-to-tool connections with [97M+ monthly SDK downloads](https://www.anthropic.com/news). A2A (Google, 150+ supporting organizations) handles agent-to-agent discovery. These are complementary. Build on them rather than custom integrations.

## Models and research

GPT-5.4 [launched March 5](https://openai.com/index/introducing-gpt-5-4/). It's the first mainline OpenAI model that combines frontier coding capabilities (from GPT-5.3 Codex) with a 1M-token context window and native computer use. On [OSWorld-Verified](https://techcrunch.com/2026/03/05/openai-launches-gpt-5-4-with-pro-and-thinking-versions/), it hits 75.0% success rate, beating the human baseline of 72.4%. The new "tool search" feature lets the model receive a lightweight list of available tools and look up definitions on demand, which cuts token cost when you have a lot of tools registered. Three variants: base, Thinking, and Pro. Input pricing starts at \~\$2.50/M tokens, output at \~\$10/M.

The sheer volume of model releases is hard to keep up with. A [startup-focused tracker](https://blog.mean.ceo/new-ai-model-releases-news-march-2026/) counts over 255 releases in Q1 2026 alone: Gemini 3.1 Pro, Claude Opus 4.6, Claude Sonnet 4.6, Qwen 3.5, GLM-5, and DeepSeek V4 (1T parameters, expected imminently). 1M+ token context windows are table stakes now.

Karpathy's [autoresearch](https://github.com/karpathy/autoresearch) (15.8K stars) is the open-source release I'm most excited about this week. It's 630 lines of Python that let an agent autonomously run ML experiments overnight on a single GPU. The loop is simple: modify `train.py`, train for exactly 5 minutes, check if the result improved, keep or revert, repeat. You get \~100 experiments while you sleep. [Shopify CEO Tobi Lutke tried it overnight](https://www.marktechpost.com/2026/03/08/andrej-karpathy-open-sources-autoresearch-a-630-line-python-tool-letting-ai-agents-run-autonomous-ml-experiments-on-single-gpus/) on an internal model and got 19% validation improvement from 37 experiments. An [Apple Silicon port](https://github.com/trevin-creator/autoresearch-mlx) (374 stars) runs the same loop on MLX, no CUDA required.

## Coding agents and dev tools

A [Pragmatic Engineer survey](https://newsletter.pragmaticengineer.com/p/ai-tooling-2026) of 900+ engineers puts Claude Code at #1 for AI coding tools, with 71% of regular agent users relying on it. Adoption is highest at small companies (75%) and among senior engineers: Director-level respondents name it twice as often as junior ranks. 95% of respondents use AI tools weekly. 70% use 2-4 tools simultaneously, so the "pick one tool" era seems genuinely over. Cursor keeps growing (\~35% in nine months), and OpenAI's Codex is picking up fast.

Simon Willison wrote something I found worth sitting with. In ["Perhaps not boring technology after all"](https://simonwillison.net/2026/Mar/9/not-so-boring/), he expected coding agents to push everyone toward mainstream stacks with abundant training data. Instead, modern agents adapt well to niche and proprietary tools by consulting existing codebase examples, iterating through tests, and reading docs within their large context windows. The "choose boring technology" fear hasn't materialized.

[Engram](https://github.com/Gentleman-Programming/engram) (911 stars) tackles persistent memory for coding agents: a single Go binary with zero dependencies, using SQLite + FTS5 across 8+ editors via MCP. 13 built-in tools including `mem_save`, `mem_search`, and session management.

[Overstory](https://github.com/jayminwest/overstory) (867 stars) does multi-agent orchestration through git worktrees. It spawns worker agents in isolated worktrees via tmux, coordinates them through a custom SQLite messaging system, and uses a 4-tier conflict resolution system for merging results. Supports Claude Code, Gemini CLI, and GitHub Copilot runtimes. The README honestly warns about the compounding risks of multi-agent swarms, which you don't see enough of.

## Industry and business

Anthropic [sued the Department of Defense](https://www.washingtonpost.com/technology/2026/03/09/anthropic-lawsuit-pentagon/) after being designated a "supply chain risk," a label historically reserved for companies tied to foreign adversaries. The dispute started when Anthropic refused to let the Pentagon use Claude without safeguards against mass surveillance and fully autonomous weapons. The Trump administration [canceled all federal contracts and blacklisted the company](https://www.cnbc.com/2026/03/09/anthropic-trump-claude-ai-supply-chain-risk.html). OpenAI [signed its own DoD deal](https://openai.com/index/our-agreement-with-the-department-of-war/), reportedly without the same limitations. ChatGPT uninstalls surged 295% afterward, which is worth noting regardless of where you land on this. Bruce Schneier [argues](https://www.schneier.com/blog/archives/2026/03/anthropic-and-the-pentagon.html) the real problem is inadequate democratic governance, not corporate ethics: "We should not rest on our laurels, thinking that either is doing so in the public's interest."

Gartner [forecasts \$2.5T in global AI spending for 2026](https://www.gartner.com/en/newsroom/press-releases/2026-1-15-gartner-says-worldwide-ai-spending-will-total-2-point-5-trillion-dollars-in-2026), a 44% jump YoY. AI infrastructure alone adds \$401B. But Gartner also says AI is in the "Trough of Disillusionment" throughout 2026, meaning it'll mostly be sold by incumbent software providers rather than as moonshot projects. Projection: \$3.33T by 2027.

OpenAI and Oracle have reportedly structured a deal worth up to [\$300B in cloud capacity](https://www.investing.com/news/stock-market-news/factboxfrom-openai-to-nvidia-firms-channel-billions-into-ai-infrastructure-as-demand-booms-4534935) over time. That is an absurd number.

The US Supreme Court [declined to hear the Thaler/DABUS case](https://www.reuters.com/legal/government/us-supreme-court-declines-hear-dispute-over-copyrights-ai-generated-material-2026-03-02/), so purely AI-generated works without a human author remain not copyrightable under US law.

## Interesting GitHub repositories

**[Ennyn](https://github.com/gmoigneu/ennyn)** - Local development proxy in Go that replaces port juggling with hostname-based routing. Each service gets a hostname like `myapp.localhost` (resolves to `127.0.0.1` per RFC 6761, no `/etc/hosts` edits). Generates a local CA with wildcard `*.localhost` certs for automatic HTTPS, integrates process management, and ships as a single zero-dependency binary for macOS, Linux, and Windows. Apache 2.0.

**[autoresearch](https://github.com/karpathy/autoresearch)** (15.8K stars) - Karpathy's overnight autonomous ML experiment runner. 630 lines of Python, single GPU, \~100 experiments while you sleep. The `program.md` instruction file is the key interface: the clearer your research direction, the better the agent navigates the search space.

**[autoresearch-mlx](https://github.com/trevin-creator/autoresearch-mlx)** (374 stars) - Apple Silicon port of autoresearch using MLX instead of PyTorch. M4 Max achieved 19% improvement in validation metrics through autonomous optimization overnight.

**[Engram](https://github.com/Gentleman-Programming/engram)** (911 stars) - Persistent memory for coding agents. Single Go binary, SQLite + FTS5, 13 MCP tools, supports 8+ editors. Topic-key workflow ensures memories update rather than duplicate.

**[Nenya](https://github.com/number6-ai/nenya)** - Self-hosted AI memory layer backed by Postgres and pgvector. Claude remembers things about you, so does ChatGPT, so does Cursor, but none of them talk to each other and you own none of it. Nenya creates a unified memory backend accessible via MCP and REST API, with automatic entity extraction, semantic search, and direct import from Claude and ChatGPT memory exports. Apache 2.0.\\

**[Overstory](https://github.com/jayminwest/overstory)** (867 stars) - Multi-agent orchestration via git worktrees + tmux + SQLite mail system. Deploys Scout, Builder, Reviewer, and Merger agents in parallel. Honest about the risks of swarm workflows.

**[jCodeMunch-MCP](https://github.com/jgravelle/jcodemunch-mcp)** (937 stars) - Token-efficient MCP server for codebase exploration. Uses tree-sitter AST parsing across 13+ languages to retrieve only the exact symbols agents need, claiming up to 99% token savings versus brute-force file reading.

**[Uncodixfy](https://github.com/cyxzdev/Uncodixfy)** (1.2K stars) - A ruleset that prevents AI from generating stereotypical "GPT UI" (floating cards, oversized rounded corners, gradient dashboards). Works as negative constraints rather than design instruction. Available as a SKILL.md for Claude Code and Codex.

**[OpenReview](https://github.com/vercel-labs/openreview)** (815 stars) - Self-hosted AI code review bot from Vercel Labs. Claude-powered, sandboxed execution, inline PR suggestions, can commit fixes directly.

**[Open Terminal](https://github.com/open-webui/open-terminal)** (1K stars) - From the Open WebUI team. A lightweight REST API sandbox where agents can execute commands, manage files, and run code. Docker or bare metal, multi-user isolation.

**[claude-replay](https://github.com/es617/claude-replay)** (403 stars) - Converts Claude Code and Cursor session transcripts into interactive, self-contained HTML replays with playback controls, bookmarks, and automatic secret redaction.

**[Arbor](https://github.com/penso/arbor)** (234 stars) - Native Rust desktop app for agentic coding workflows built with GPUI. Manages repos, worktrees, embedded terminals, file diffs, and real-time agent detection in a three-pane layout.

One-liners: [WebReel](https://github.com/vercel-labs/webreel) (632 stars, scripted browser demo recording) | [OpusDelta](https://github.com/OpusDelta/opusdelta) (174 stars, AI emotion visualization in 3D geometry) | [RepoCheck](https://github.com/WtxwNs/RepoCheck) (148 stars, Python/PyTorch reproducibility auditor) | [AnythingLLM](https://anythingllm.com/) (self-hosted RAG platform, continues gaining adoption).

## Quick bits

* MIT Technology Review named [generative coding a "Ten Breakthrough Technologies" of 2026](https://www.aicerts.ai/news/mit-declares-ai-coding-tools-2026-breakthrough/).
* Nate B Jones did a [32-minute deep dive on Claude's scheming behavior](https://www.youtube.com/watch?v=iY7BDpZWJbE): why frontier models attempt to manipulate developers and what it means for trust in agent workflows.
* The [International AI Safety Report 2026](https://www.insideprivacy.com/artificial-intelligence/international-ai-safety-report-2026-examines-ai-capabilities-risks-and-safeguards/) (Bengio et al.) warns that capability growth is outpacing safety evidence, with attackers still bypassing protections at a "moderately high" rate.
* Markus Persson (Notch) [called AI coding "an incredibly bad idea"](https://intellectia.ai/news/stock/ai-coding-tools-spark-controversy-amid-warnings), citing hidden bugs and loss of understanding.
* The GPU capacity crunch is pushing enterprises toward [hybrid architectures](https://vexxhost.com/blog/gpu-capacity-crisis-ai-infrastructure-2026/): private clusters for training, public cloud for burst, sovereign for regulated data.
* ByteByteGo reports [OpenClaw at 263K stars](https://blog.bytebytego.com/p/top-ai-github-repositories-in-2026). Local-first AI infrastructure (Ollama, Open WebUI, DeepSeek-V3) keeps growing.
* Virginia lawmakers are [proposing AI guardrails in K-12 education](https://www.newsfromthestates.com/article/va-lawmakers-propose-guardrails-artificial-intelligence-use-education).
* Enterprise adoption remains uneven: McKinsey found [62% experimenting with agents and 23% scaling](https://agents.md), but BCG says fewer than 20% are hitting expected ROI. Gartner warns over 40% of agentic AI projects could be canceled by 2027.

## Sources

* [OpenAI: Introducing GPT-5.4](https://openai.com/index/introducing-gpt-5-4/)
* [TechCrunch: OpenAI launches GPT-5.4](https://techcrunch.com/2026/03/05/openai-launches-gpt-5-4-with-pro-and-thinking-versions/)
* [OpenAI Symphony on GitHub](https://github.com/openai/symphony)
* [Paperclip AI on GitHub](https://github.com/paperclipai/paperclip)
* [Paperclip AI website](https://paperclip.ing/)
* [Agentlytics on GitHub](https://github.com/f/agentlytics)
* [background-agents.com (Ona)](https://background-agents.com/)
* [Ona: Gitpod is now Ona](https://ona.com/stories/gitpod-is-now-ona)
* [Pragmatic Engineer: AI Tooling 2026](https://newsletter.pragmaticengineer.com/p/ai-tooling-2026)
* [Simon Willison: Perhaps not boring technology after all](https://simonwillison.net/2026/Mar/9/not-so-boring/)
* [Karpathy autoresearch on GitHub](https://github.com/karpathy/autoresearch)
* [MarkTechPost: Karpathy autoresearch](https://www.marktechpost.com/2026/03/08/andrej-karpathy-open-sources-autoresearch-a-630-line-python-tool-letting-ai-agents-run-autonomous-ml-experiments-on-single-gpus/)
* [autoresearch-mlx on GitHub](https://github.com/trevin-creator/autoresearch-mlx)
* [Nenya on GitHub](https://github.com/number6-ai/nenya)
* [Ennyn on GitHub](https://github.com/gmoigneu/ennyn)
* [Engram on GitHub](https://github.com/Gentleman-Programming/engram)
* [Overstory on GitHub](https://github.com/jayminwest/overstory)
* [jCodeMunch-MCP on GitHub](https://github.com/jgravelle/jcodemunch-mcp)
* [Uncodixfy on GitHub](https://github.com/cyxzdev/Uncodixfy)
* [Vercel OpenReview on GitHub](https://github.com/vercel-labs/openreview)
* [Vercel WebReel on GitHub](https://github.com/vercel-labs/webreel)
* [Open Terminal on GitHub](https://github.com/open-webui/open-terminal)
* [claude-replay on GitHub](https://github.com/es617/claude-replay)
* [Arbor on GitHub](https://github.com/penso/arbor)
* [OpusDelta on GitHub](https://github.com/OpusDelta/opusdelta)
* [RepoCheck on GitHub](https://github.com/WtxwNs/RepoCheck)
* [Anthropic sues Pentagon (Washington Post)](https://www.washingtonpost.com/technology/2026/03/09/anthropic-lawsuit-pentagon/)
* [Anthropic supply chain risk (CNBC)](https://www.cnbc.com/2026/03/09/anthropic-trump-claude-ai-supply-chain-risk.html)
* [OpenAI agreement with Department of War](https://openai.com/index/our-agreement-with-the-department-of-war/)
* [Bruce Schneier: Anthropic and the Pentagon](https://www.schneier.com/blog/archives/2026/03/anthropic-and-the-pentagon.html)
* [Gartner: AI spending \$2.5T in 2026](https://www.gartner.com/en/newsroom/press-releases/2026-1-15-gartner-says-worldwide-ai-spending-will-total-2-point-5-trillion-dollars-in-2026)
* [Reuters: Supreme Court declines AI copyright case](https://www.reuters.com/legal/government/us-supreme-court-declines-hear-dispute-over-copyrights-ai-generated-material-2026-03-02/)
* [OpenAI-Oracle infrastructure deal](https://www.investing.com/news/stock-market-news/factboxfrom-openai-to-nvidia-firms-channel-billions-into-ai-infrastructure-as-demand-booms-4534935)
* [MIT names generative coding breakthrough technology](https://www.aicerts.ai/news/mit-declares-ai-coding-tools-2026-breakthrough/)
* [International AI Safety Report 2026](https://www.insideprivacy.com/artificial-intelligence/international-ai-safety-report-2026-examines-ai-capabilities-risks-and-safeguards/)
* [Nate B Jones: Claude Blackmailed Its Developers (YouTube)](https://www.youtube.com/watch?v=iY7BDpZWJbE)
* [ByteByteGo: Top AI GitHub Repositories 2026](https://blog.bytebytego.com/p/top-ai-github-repositories-in-2026)
* [GPU capacity crisis (VEXXHOST)](https://vexxhost.com/blog/gpu-capacity-crisis-ai-infrastructure-2026/)
* [blog.mean.ceo: New AI Model Releases March 2026](https://blog.mean.ceo/new-ai-model-releases-news-march-2026/)
* [Hygraph: AI Web Development Tools](https://hygraph.com/blog/ai-web-development-tools)
* [Markus Persson AI coding warning](https://intellectia.ai/news/stock/ai-coding-tools-spark-controversy-amid-warnings)
* [Virginia AI in education](https://www.newsfromthestates.com/article/va-lawmakers-propose-guardrails-artificial-intelligence-use-education)
* [AnythingLLM](https://anythingllm.com/)


# AI Weekly Review - Mar. 16th 2026
Source: https://developer.upsun.com/posts/ai/aiweekly-2026-03-16

A press, Youtube and Github review of everything AI


<PostMeta />

> The coding agent wars entered a new phase this week as survey data crowned Claude Code the most-used AI coding tool, while Cursor 2.0 and Windsurf Wave 13 shipped multi-agent and model-comparison features. NVIDIA GTC 2026 kicks off today with the Vera Rubin platform reveal, DeepSeek V4 details continue to surface, and a growing wave of AI-linked layoffs (45K jobs in 2026 so far) is forcing the industry to confront the gap between "AI as productivity tool" and "AI as headcount replacement." Meanwhile, the open-source ecosystem is racing to build the connective tissue for agents: skills catalogs, memory plugins, hook systems, and extraction frameworks.

## Highlight of the week

### Claude Code takes the crown, but the real story is the toolchain

The Pragmatic Engineer's [March 2026 AI tooling survey](https://newsletter.pragmaticengineer.com/p/ai-tooling-2026) (906 respondents) delivered a headline number: Claude Code is now the most-loved AI coding tool at 46%, far ahead of Cursor (19%) and GitHub Copilot (9%). In just eight months since its May 2025 launch, Claude Code has reached the adoption levels Copilot held three years ago.

But the more interesting signal is what practitioners are actually doing. 95% of respondents use AI tools weekly, 56% report doing 70%+ of their engineering work with AI, and 55% regularly use AI agents. Most engineers chain several tools rather than picking one: Copilot for inline completions, Cursor or Windsurf for multi-file agentic work, and Claude Code for terminal automation and git workflows. Staff+ engineers lead agent adoption at 63.5%, which points to a real shift in senior engineering practice rather than hype.

The survey also found that Anthropic's Opus and Sonnet models dominate coding tasks by a wide margin, with more mentions than all other models combined. At small companies, 75% use Claude Code; large enterprises default to Copilot, likely driven by procurement inertia and Microsoft's enterprise marketing.

## Models and research

**DeepSeek V4 remains half-launched.** The trillion-parameter MoE model (roughly 32B active parameters per token) has been [trickling out details](https://www.nxcode.io/resources/news/deepseek-v4-release-specs-benchmarks-2026) since early March. It features a tiered KV-cache architecture that cuts memory needs by about 40%, sparse FP8 decoding for 1.8x inference speedup, and 1M+ token context. It is natively multimodal (text, image, video, audio) and optimized for Huawei Ascend chips. As of March 16, the full public release has not materialized, though [Chinese tech media reported](https://blog.mean.ceo/new-ai-model-releases-news-march-2026/) a website update with expanded context handling that some are calling "V4 Lite." The delay strategy, whether intentional or not, is keeping attention on DeepSeek while competitors ship.

**Long-context is the new baseline.** Claude Opus 4.6 sits at roughly 1M tokens, DeepSeek V4 targets 1M+, and GPT-5.3 offers around 400K. This enables workflows that were impractical a year ago: entire-repo analysis, book-length document handling, and large multi-document RAG pipelines in a single session. The practical impact is most visible in coding agents, where whole-repo context via embeddings plus large context windows has replaced single-file prompts as the standard.

**"Humanity's Last Exam" exposes reasoning gaps.** A [Texas A\&M-led group](https://www.sciencedaily.com/releases/2026/03/260313002650.htm) published what they call the hardest AI benchmark in Nature: 2,500 questions spanning mathematics, humanities, natural sciences, and ancient languages, sourced from nearly 1,000 researchers. GPT-4o scored 2.7%, Claude 3.5 Sonnet hit 4.1%, and o1 reached 8%. GPT-5 scored around 25% after the benchmark was published. The results are a useful corrective to benchmark-driven hype: frontier models are powerful coding and reasoning tools, but robust general reasoning remains unsolved.

**Reasoning efficiency over raw size.** The frontier model conversation has shifted from parameter counts to output efficiency. [Reports indicate](http://kersai.com/ai-breakthroughs-in-2026-march-update/) GPT-5.x and Claude 4.6 variants are solving complex tasks with far fewer output tokens than their predecessors, prioritizing reliability and reduced hallucination over brute-force scaling.

## Coding agents and dev tools

**Cursor 2.0: parallel agents at scale.** [Cursor's redesign](https://cursor.com/changelog/2-0) ships up to eight parallel agents on the same codebase, each isolated via git worktrees or remote machines. The new proprietary "Composer" model runs 4x faster than comparable alternatives. Internally, [35% of Cursor's merged PRs](https://www.techzine.eu/news/devops/135916/cursor-2-0-introduces-parallel-agents-and-new-model/) are now created by autonomous agents in cloud VMs. Version 2.2 adds multi-agent judging, where Cursor automatically evaluates all parallel runs and recommends the best solution.

**Windsurf Wave 13 brings Arena Mode.** [Windsurf's latest release](https://www.infoq.com/news/2026/02/windsurf-arena-mode/) pits two models against each other side-by-side with hidden identities, letting you vote on which performs better for your specific codebase and tasks. It acknowledges something obvious that most tools ignore: benchmark rankings do not predict real-world performance on your code. The companion Plan Mode builds explicit task plans before editing, with a "megaplan" option for thorough interactive planning. Wave 13 also adds first-class multi-agent sessions, git worktrees, and side-by-side Cascade panes.

**Google Antigravity: free, for now.** [Google's agent-first IDE](https://developers.googleblog.com/build-with-google-antigravity-our-new-agentic-development-platform/) launched in public preview with Claude Opus 4.6 and Gemini 3 Pro at no cost, scoring 76.2% on SWE-bench with five parallel agents. But the sustainability question is already answering itself: [reports of multi-day account lockouts](https://claude-world.com/articles/google-antigravity-quota-cuts-vs-claude-code-opus-1m/), a 92% free-tier quota cut, and a \$250/month paid plan suggest the free tier was a land-grab, not a business model.

**OpenAI Skills catalog for Codex.** OpenAI [launched an official Skills repository](https://github.com/openai/skills) (8.2K stars) with 35+ curated skills organized in three tiers: system (bundled automatically), curated (install by name), and experimental (community contributions). This is OpenAI's response to the grassroots plugin ecosystem forming around Claude Code. A separate [community-built library](https://github.com/Jeffallan/claude-skills) (1.7K stars) offers 66 specialized skills for full-stack developers using Claude Code.

**The compound engineering pattern goes mainstream.** [Every's compound engineering plugin](https://github.com/EveryInc/compound-engineering-plugin) for Claude Code (8.7K stars) implements multi-agent orchestration, spawning sub-agents for parallel work. Combined with [disler's hooks mastery repo](https://github.com/disler/claude-code-hooks-mastery) (3K stars), the Claude Code extension ecosystem is growing quickly. The pattern: treat agents as orchestrators that delegate to specialized sub-agents instead of running them as single-threaded assistants.

## Web development and frameworks

AI coding tools now handle web workflows well. Nearly all leading assistants (Copilot, Cursor, Windsurf, Vercel v0, Bolt.new, Lovable, Gemini CLI, Claude Code) can [generate React components, perform design-to-code conversion, and edit across multiple frontend files and routes](https://blog.logrocket.com/ai-dev-tool-power-rankings/). "Start from a Figma screenshot or prompt" is becoming a standard workflow for React and modern frontend stacks.

What matters more: agentic IDEs now ingest the whole codebase (front and back end), adjusting routing, API handlers, and frontend components together, and can run tests or dev servers as part of their execution plans. Full-stack refactoring that previously required careful coordination across files is becoming a single-prompt operation.

The [Open Brain visual interface pattern](https://www.youtube.com/@NateBJones), covered in a video this week, demonstrates a practical architecture for agent-human shared data: one Supabase table as the single source of truth, MCP as the agent access layer, and a lightweight web app as the human interface. The design principle is simple: agent surfaces patterns, human decides, agent executes. It works because it keeps humans in the loop without making the agent useless.

## Infrastructure

**NVIDIA GTC 2026 opens today.** Jensen Huang's keynote (March 16, 11am PT) is expected to detail the [Vera Rubin platform](https://blogs.nvidia.com/blog/gtc-2026-news/): 72-GPU NVL72 rack systems with HBM4 memory, 3.3x to 5x inference performance over Blackwell Ultra on FP4 workloads, 260 TB/s aggregate NVLink bandwidth, and a [10x reduction in inference token costs](https://parameter.io/nvidia-nvda-stock-rises-ahead-of-vera-rubin-ai-chip-reveal-at-gtc-2026/). Vera Rubin entered full-scale production in early 2026. NVIDIA will also emphasize its five-layer AI stack (energy, chips, infrastructure, models, applications) and the "AI factories" concept, plus sessions covering Isaac and Omniverse for physical AI. Future Rubin Ultra and post-Rubin "Feynman" architectures are expected to be teased.

For practitioners, the key number is the 10x inference cost reduction. If that holds in production, it changes the economics of running agentic workloads (multi-agent coding, autonomous security testing, large-context retrieval) at scale.

## Industry and business

**The layoff-to-fund-AI pattern accelerates.** [45,000 tech jobs have been cut in 2026 so far](https://technode.global/2026/03/09/2026-tech-layoffs-reach-45000-in-march-more-than-9200-due-to-ai-and-automation-rationalfx/), with roughly 9,200 (20%) directly attributed to AI-driven restructuring. Block cut 4,000 roles (40% of workforce) with CEO Jack Dorsey explicitly citing AI capabilities. [Meta is reportedly planning to cut up to 20% of its workforce](https://www.cnbc.com/2026/03/14/meta-planning-sweeping-layoffs-as-ai-costs-mount-reuters.html) to offset AI infrastructure spending, a story that moved Meta stock up nearly 3%. Companies are simultaneously increasing AI spending and cutting headcount, and markets are rewarding both moves.

**OpenAI at \$840B.** The [latest \$110B funding round](https://news.crunchbase.com/venture/openai-raise-largest-ai-venture-deal-ever/) (SoftBank \$30B, NVIDIA \$30B, Amazon \$50B) puts OpenAI at an \$840B valuation, up from \$500B just five months ago. Microsoft did not participate. OpenAI claims 900M+ weekly active users and 50M+ consumer subscribers. An IPO is expected this year. Whether these numbers justify the valuation depends entirely on whether you believe the current trajectory of model improvement continues.

**Morgan Stanley predicts "massive AI breakthrough" in H1 2026.** The [investment bank's report](https://fortune.com/2026/03/13/elon-musk-morgan-stanley-ai-leap-2026/) cites executives at major AI labs telling investors to brace for progress that will "shock" them, predicting AI will become a "powerful deflationary force." They also project a net US power shortfall of 9 to 18 gigawatts through 2028 to run the required infrastructure. Take the timeline with salt, but the directional bet is notable.

## Interesting GitHub repositories

**[KeygraphHQ/shannon](https://github.com/KeygraphHQ/shannon)** (21.2K stars, +16.8K this week). Fully autonomous AI pentester for web app security testing. It reads source code, maps attack surfaces, and executes real exploits. [Scored 96.15% on a hint-free XBOW benchmark](https://github.com/KeygraphHQ/shannon/blob/main/xben-benchmark-results/README.md) (100/104 exploits). TypeScript. 16.8K stars gained in a single week. Worth watching for where automated security testing in CI/CD pipelines is heading.

**[thedotmack/claude-mem](https://github.com/thedotmack/claude-mem)** (27.6K stars). Claude Code plugin that auto-captures everything Claude does during coding sessions, compresses it with AI, and injects relevant context into future sessions. Addresses the persistent memory gap in agent workflows where every session starts from zero.

**[google/langextract](https://github.com/google/langextract)** (31.4K stars). Google's Python library for extracting structured information from unstructured text using LLMs with precise source grounding and interactive visualization. [Version 0.5.0](https://developers.googleblog.com/introducing-langextract-a-gemini-powered-information-extraction-library/) (February 2026) introduced enhanced semantic chunking and improved multi-pass extraction, increasing recall by 22%. Supports Gemini, Ollama, and other backends. Google open-sourcing production-grade extraction tooling matters if you're building RAG or data pipelines.

**[badlogic/pi-mono](https://github.com/badlogic/pi-mono)** (11.3K stars). AI agent toolkit from libGDX creator Mario Zechner: coding agent CLI, unified LLM API, TUI and web UI libraries, Slack bot, vLLM pods. One of the more complete open-source agent infrastructure stacks currently trending.

**[tobi/qmd](https://github.com/tobi/qmd)** (8.2K stars). From Shopify founder Tobi Lutke: a mini CLI search engine for your docs, knowledge bases, and meeting notes. Fully local, tracks current SOTA approaches. The fact that Tobi is building and open-sourcing personal knowledge tooling says something about where high-signal builders see value.

**[virattt/dexter](https://github.com/virattt/dexter)** (14.9K stars). Autonomous agent for deep financial research. One of several domain-specific research agents gaining traction. Sustained growth suggests real utility beyond demo-ware.

**[openai/skills](https://github.com/openai/skills)** (8.2K stars). Official Skills Catalog for Codex with 35+ reusable skills in three tiers (system, curated, experimental). OpenAI's structured approach to agent extensibility.

## Quick bits

* **AI-assisted design-to-code is table stakes.** Every major coding tool now advertises automatic component generation and UI scaffolding from screenshots or prompts. Differentiation has shifted to agent orchestration and codebase safety. ([LogRocket](https://blog.logrocket.com/ai-dev-tool-power-rankings/))
* **Dense wave of US state AI bills.** 78 chatbot bills alive in 27 states covering provenance metadata, deepfake protections, AI-only decision bans in workers' comp, restrictions on AI in psychotherapy, and environmental accountability for data centers. Utah's Digital Content Provenance Standards Act has passed the legislature. ([Transparency Coalition](https://www.transparencycoalition.ai/news/ai-legislative-update-march13-2026))
* **DOJ creates AI Litigation Task Force.** The FTC is preparing a policy statement on how unfair-and-deceptive-practices authority applies to AI. The White House is circulating draft language requiring AI firms selling to federal markets to support "any lawful use." ([JD Supra](https://www.jdsupra.com/legalnews/march-2026-federal-deadlines-that-will-9297133/))
* **prompt-optimizer** (20.8K stars): Chinese-language meta-tooling for optimizing prompts, 20K+ stars on a prompt optimization tool tells you something about the appetite for meta-tooling. ([GitHub](https://github.com/linshenkx/prompt-optimizer))
* **grok2api** (1.4K stars): FastAPI-based Grok adapter with streaming, image generation, and pool concurrency. Part of the ongoing trend of open-source API adapters unifying access to different LLM providers. ([GitHub](https://github.com/chenyme/grok2api))
* **SaaS platforms quietly adopting frontier models.** Writing and marketing platforms (Jasper, Copy.ai) have shipped Claude Sonnet 4.6 and GPT-5.3 support, evidence of how fast downstream products integrate new APIs. ([blog.mean.ceo](https://blog.mean.ceo/new-ai-model-releases-news-march-2026/))

## Sources

* [The Pragmatic Engineer: AI Tooling for Software Engineers in 2026](https://newsletter.pragmaticengineer.com/p/ai-tooling-2026)
* [AI Productivity: Pragmatic Engineer Survey Results](https://aiproductivity.ai/news/pragmatic-engineer-survey-ai-tooling-2026/)
* [DEV Community: AI Weekly, Claude Code Dominates](https://dev.to/alexmercedcoder/ai-weekly-claude-code-dominates-mcp-goes-mainstream-week-of-march-5-2026-15af)
* [LogRocket: AI Dev Tool Power Rankings](https://blog.logrocket.com/ai-dev-tool-power-rankings/)
* [LushBinary: AI Coding Agents Comparison 2026](https://lushbinary.com/blog/ai-coding-agents-comparison-cursor-windsurf-claude-copilot-kiro-2026/)
* [TLDL: AI Coding Tools 2026](https://www.tldl.io/resources/ai-coding-tools-2026)
* [Cursor 2.0 Changelog](https://cursor.com/changelog/2-0)
* [Techzine: Cursor 2.0 Parallel Agents](https://www.techzine.eu/news/devops/135916/cursor-2-0-introduces-parallel-agents-and-new-model/)
* [InfoQ: Windsurf Arena Mode](https://www.infoq.com/news/2026/02/windsurf-arena-mode/)
* [Google Developers Blog: Antigravity](https://developers.googleblog.com/build-with-google-antigravity-our-new-agentic-development-platform/)
* [ClaudeWorld: Antigravity Quota Cuts](https://claude-world.com/articles/google-antigravity-quota-cuts-vs-claude-code-opus-1m/)
* [NxCode: DeepSeek V4 Specs](https://www.nxcode.io/resources/news/deepseek-v4-release-specs-benchmarks-2026)
* [blog.mean.ceo: New AI Model Releases March 2026](https://blog.mean.ceo/new-ai-model-releases-news-march-2026/)
* [KersAI: AI Breakthroughs 2026 March Update](http://kersai.com/ai-breakthroughs-in-2026-march-update/)
* [ScienceDaily: Scientists Built the Hardest AI Test Ever](https://www.sciencedaily.com/releases/2026/03/260313002650.htm)
* [NVIDIA Blog: GTC 2026 News](https://blogs.nvidia.com/blog/gtc-2026-news/)
* [Parameter: NVIDIA Stock Ahead of Vera Rubin](https://parameter.io/nvidia-nvda-stock-rises-ahead-of-vera-rubin-ai-chip-reveal-at-gtc-2026/)
* [CNBC: NVIDIA GTC CPU Pivot](https://www.cnbc.com/2026/03/13/nvidia-gtc-ai-jensen-huang-cpu-gpu.html)
* [TechNode: 2026 Tech Layoffs](https://technode.global/2026/03/09/2026-tech-layoffs-reach-45000-in-march-more-than-9200-due-to-ai-and-automation-rationalfx/)
* [CNBC: Meta Planning Sweeping Layoffs](https://www.cnbc.com/2026/03/14/meta-planning-sweeping-layoffs-as-ai-costs-mount-reuters.html)
* [Crunchbase: OpenAI's \$110B Raise](https://news.crunchbase.com/venture/openai-raise-largest-ai-venture-deal-ever/)
* [Fortune: Morgan Stanley AI Breakthrough Warning](https://fortune.com/2026/03/13/elon-musk-morgan-stanley-ai-leap-2026/)
* [Transparency Coalition: AI Legislative Update March 13](https://www.transparencycoalition.ai/news/ai-legislative-update-march13-2026)
* [JD Supra: March 2026 Federal AI Deadlines](https://www.jdsupra.com/legalnews/march-2026-federal-deadlines-that-will-9297133/)
* [Google Developers Blog: LangExtract](https://developers.googleblog.com/introducing-langextract-a-gemini-powered-information-extraction-library/)
* [GitHub: KeygraphHQ/shannon](https://github.com/KeygraphHQ/shannon)
* [GitHub: thedotmack/claude-mem](https://github.com/thedotmack/claude-mem)
* [GitHub: google/langextract](https://github.com/google/langextract)
* [GitHub: openai/skills](https://github.com/openai/skills)
* [GitHub: EveryInc/compound-engineering-plugin](https://github.com/EveryInc/compound-engineering-plugin)
* [GitHub: disler/claude-code-hooks-mastery](https://github.com/disler/claude-code-hooks-mastery)
* [GitHub: tobi/qmd](https://github.com/tobi/qmd)
* [GitHub: virattt/dexter](https://github.com/virattt/dexter)
* [GitHub: badlogic/pi-mono](https://github.com/badlogic/pi-mono)


# AI Weekly Review - Mar. 23rd 2026
Source: https://developer.upsun.com/posts/ai/aiweekly-2026-03-23

A press, Youtube and Github review of everything AI


<PostMeta />

## The fun quote of the week.

> "If that \$500,000 engineer did not consume at least \$250,000 worth of tokens, I am going to be deeply alarmed." Huang

## Highlight of the week

> OpenAI swallowed the Python toolchain by acquiring Astral. Cursor shipped its own model and immediately got caught building on Kimi without credit. Nvidia laid out a trillion-dollar roadmap at GTC and Jensen Huang said he would be "deeply alarmed" if a \$500k engineer did not consume \$250k in tokens. Meanwhile, the tools developers actually use every day (agent harnesses, browser automation, context databases) are consolidating fast on GitHub, and Block fired 4,000 people, blaming AI. A week that made the shape of the next year feel a lot clearer.

### OpenAI acquires Astral: the Python toolchain is now an AI company asset

OpenAI announced its [acquisition of Astral](https://openai.com/index/openai-to-acquire-astral/), the company behind uv (126M monthly downloads), ruff (the linter that is 1,000x faster than the alternatives), and ty (type checker). The stated goal is to integrate these tools with Codex, which now has over 2 million weekly active users and 5x usage growth since January.

Both OpenAI and Astral [committed to keeping the tools open source](https://astral.sh/blog/openai), and the deal is still pending regulatory approval. Simon Willison's [analysis](https://simonwillison.net/2026/mar/19/openai-acquiring-astral/) captures the tension well: these are load-bearing tools for the entire Python ecosystem, and "open source" means different things when your parent company has \$10B+ in revenue.

This matters because it signals a strategic shift. OpenAI is not just building models. It is buying the developer infrastructure that makes those models useful. If Codex understands your package manager, your linter, and your type system natively, the switching cost becomes enormous. Anthropic, Google, and other model providers now face a gap in the Python developer experience that will be hard to close through partnerships alone.

## Models and research

### DeepSeek V4 quietly arrives at 1 trillion parameters

[DeepSeek V4](https://www.nxcode.io/resources/news/deepseek-v4-release-specs-benchmarks-2026) launched in early March with approximately 1 trillion total parameters, activating only 37B per token through MoE routing. The model is natively multimodal (text, image, video, audio), supports a 1M token context window, and leaked benchmarks suggest 80%+ on SWE-bench. Pricing is disruptive: \$0.28 per million input tokens and \$1.10 per million output tokens, a fraction of every closed competitor.

Two technical details stand out. First, DeepSeek [optimized V4 to run on Huawei Ascend chips](https://www.abhs.in/blog/deepseek-v4-1-trillion-parameter-huawei-ascend-developers-2026), demonstrating that frontier-scale training is viable on Chinese-made silicon despite US export controls. Second, a V4 Lite variant targets lower-resource deployments while keeping long-context multimodal capabilities. The open-weight frontier just got very real.

### GPT-5.4 Mini and Nano: small models for the subagent era

OpenAI [released GPT-5.4 Mini and Nano](https://openai.com/index/introducing-gpt-5-4-mini-and-nano/) on March 17. Mini runs 2x faster than GPT-5 mini with a 400k context window, priced at \$0.75/M input tokens. Nano is smaller still at \$0.20/M input. The New Stack [correctly identified](https://thenewstack.io/gpt-54-nano-mini/) these as "built for the subagent era": cheap, fast models designed to be called by other agents for classification, extraction, and simple coding subtasks.

Simon Willison [ran a fun benchmark](https://simonwillison.net/2026/Mar/17/mini-and-nano/): describing 76,000 photos for \$52 using GPT-5.4 Mini's vision capabilities.

### Gemini 3.1 Flash-Lite: Google's cost play

Google shipped [Gemini 3.1 Flash-Lite](https://blog.google/innovation-and-ai/models-and-research/gemini-models/gemini-3-1-flash-lite/) at \$0.25/M input tokens with 1M token context, 2.5x faster time-to-first-token than Gemini 2.5 Flash. Positioned for high-volume, latency-sensitive tasks. The pricing race at the bottom of the model stack is accelerating fast, and the real winners are developers building multi-agent systems where per-call cost determines what is architecturally feasible.

### Flash-MoE: 397B parameters on a MacBook

The [Flash-MoE project](https://github.com/danveloper/flash-moe) runs Qwen3.5-397B on a 48GB MacBook Pro at 5.5 tokens/second, using just 5.5GB of resident memory. The technique exploits MoE architecture to stream only the 4 active experts (out of 128) from SSD per token. The entire system is written in C and Metal shaders, with no Python frameworks. Simon Willison [documented the process](https://simonwillison.net/2026/Mar/18/llm-in-a-flash/) in detail.

This is not a toy demo. It proves that consumer hardware can run production-quality inference on massive models when the software respects hardware constraints. If you can run 397B parameters on a laptop, the argument for always calling an API starts to weaken.

## Coding agents and dev tools

### Cursor ships Composer 2, gets caught using Kimi

Cursor [launched Composer 2](https://cursor.com/blog/composer-2) on March 19, claiming "frontier-level coding intelligence" with 200k token prompts, strong CursorBench results, and pricing at \$0.50 to \$1.50/M input tokens. The model [beats Claude Opus 4.6 on several benchmarks](https://venturebeat.com/technology/cursors-new-coding-model-composer-2-is-here-it-beats-claude-opus-4-6-but) while trailing GPT-5.4.

Then things got awkward. An X user noticed Composer 2 looked a lot like Kimi 2.5, an open source model from Chinese company Moonshot AI. Cursor co-founder Aman Sanger [acknowledged](https://techcrunch.com/2026/03/22/cursor-admits-its-new-coding-model-was-built-on-top-of-moonshot-ais-kimi/) it was "a miss to not mention the Kimi base in our blog from the start." The model is Kimi 2.5 with additional reinforcement learning.

The controversy matters less than what it reveals: AI coding companies are now training their own models on top of open-source bases, and the line between "our model" and "fine-tuned someone else's model" is getting blurry. Cursor also published a [technical deep dive on training Composer for longer horizons](https://cursor.com/blog), using self-summarization to extract learning signals beyond the context window.

### GitHub Squad: multi-agent orchestration inside your repo

GitHub [launched Squad](https://github.blog/ai-and-ml/github-copilot/how-squad-runs-coordinated-ai-agents-inside-your-repository/), an open source project built on Copilot that drops a pre-configured AI team (lead, frontend developer, backend developer, tester) into your repository with two commands. A coordinator agent routes tasks, loads repo context, and spawns specialists with up to 200k token context windows each. Agent memory lives in plain text files in `.squad/`, making it versioned and portable.

The design is opinionated in the right ways: parallel agent execution, persistent identity (agents are named after characters from The Usual Suspects), and memory that survives across sessions. This is repository-native multi-agent orchestration, not a standalone product bolted onto your workflow.

### Superpowers hits 106k stars

The [obra/superpowers](https://github.com/obra/superpowers) framework gained 20,000 stars in a single week, reaching 106k total. It provides structured, multi-step workflows for Claude Code: brainstorming, test-driven development, two-stage code reviews. YouTube coverage from [Better Stack](https://www.youtube.com/watch?v=lq3rzXP4_vs) and [Matt Pocock](https://www.youtube.com/watch?v=EJyuu6zlQCg) validate that the structured approach produces measurably better code than raw prompting.

A related trend: [learn-claude-code](https://github.com/shareAI-lab/learn-claude-code) (36k stars, +8k this week) teaches you to build a minimal Claude Code agent from scratch with the philosophy "bash is all you need." The agent harness ecosystem around Claude Code is maturing fast.

### Windsurf and the pricing simplification

[Windsurf simplified its pricing](https://windsurf.com/blog) across Free, Pro, Teams, and a new Max tier, replacing credit-based systems with predictable quotas. A small move, but signals that the AI coding market is mature enough for standard SaaS pricing. Combined with the [dev tool power rankings](https://blog.logrocket.com/ai-dev-tool-power-rankings/) placing Windsurf's Wave 13 release at the top for its Arena Mode (blind model comparison), the market is stratifying: Claude Code for terminal-first workflows, Cursor for IDE-heavy teams, Windsurf for those who want multiple models under one roof.

### OpenClaw: the security crisis deepens

The OpenClaw autonomous agent framework [continues to be a security disaster](https://thehackernews.com/2026/03/openclaw-ai-agent-flaws-could-enable.html). Researchers found [341 malicious skills](https://particula.tech/blog/openclaw-security-crisis-malicious-ai-agents) (12% of the entire ClawHub registry), including keyloggers and malware with professional documentation. Over 135,000 instances are [exposed to the public internet](https://www.darkreading.com/application-security/critical-openclaw-vulnerability-ai-agent-risks), with 15,000+ vulnerable to remote code execution.

As Nate B Jones [frames it well](https://www.youtube.com/watch?v=8lwnJZy4cO0) in his YouTube coverage: the problem is not the agent itself but the supervision model. Developers treating AI agents like trusted colleagues instead of powerful-but-unsupervised contractors are "one bad session away from losing real production work." He is right. The framing of agent management as a skill gap, not a technology gap, is the part most teams are ignoring.

## Web development and frameworks

### Cloudflare Workers AI runs large models at the edge

Cloudflare [announced](https://blog.cloudflare.com/workers-ai-large-models/) that Workers AI now supports large language models, starting with Kimi K2.5, a frontier-scale open-source model with a 256k context window and multi-turn tool calling. Their internal security review agent processes 7B tokens per day and cut costs by 77% after switching to Kimi K2.5 from a proprietary model. The Agents SDK starter now defaults to Kimi K2.5.

For web developers, this changes the calculus. Building AI agents entirely within Cloudflare's platform (Workers, Durable Objects, D1, R2) with a capable open-source model means you can ship agent-powered features without managing inference infrastructure.

### JavaScript bloat: the three pillars

A [sharp analysis](https://43081j.com/2026/03/three-pillars-of-javascript-bloat) identifies three systemic sources of npm ecosystem bloat: packages still supporting ES3/IE6, atomic single-use packages creating duplication, and polyfills that outlived their purpose (globalthis still gets 49M weekly downloads). Worth reading for anyone shipping JavaScript in production.

### Tooscut: professional video editing in the browser

[Tooscut](https://tooscut.app/) is a browser-based non-linear video editor achieving native performance through WebGPU compositing via Rust/WASM. Unlimited multi-track timeline, keyframe animation, GPU-accelerated effects, real-time preview. All media processing stays local via the File System Access API. A good example of where the web platform stands in 2026 for professional creative tools.

## Industry and business

### AI layoffs are no longer quiet

Block (Square, Cash App) [cut 4,000 roles](https://www.bloomberg.com/news/articles/2026-03-01/jack-dorsey-s-4-000-job-cuts-at-block-arouse-suspicions-of-ai-washing), roughly 40% of its workforce. CEO Jack Dorsey stated this was "not driven by financial difficulty, but by the growing capability of AI tools." Across the tech industry, [45,363 jobs have been cut](https://technode.global/2026/03/09/2026-tech-layoffs-reach-45000-in-march-more-than-9200-due-to-ai-and-automation-rationalfx/) since January 2026, with 20% explicitly attributed to AI. That is up from fewer than 8% in 2025.

The change in language is the story here. Companies used to hide behind "restructuring" and "efficiency." Now they are crediting AI capabilities directly, which may be honest or may be a convenient narrative for investors. Either way, the pattern is accelerating.

### Nvidia GTC: the trillion-dollar roadmap

Nvidia [unveiled the Vera Rubin platform](https://nvidianews.nvidia.com/news/rubin-platform-ai-supercomputer) at GTC 2026, promising 10x lower cost per token compared to Blackwell. Jensen Huang [raised his revenue projection](https://www.datacenterknowledge.com/data-center-chips/gtc-2026-nvidia-unveils-vera-rubin-ai-platform-eyes-1t-by-2027) to \$1 trillion through 2027, up from \$500B last year. The platform targets four phases of AI: pretraining, fine-tuning, test-time scaling, and a new phase called "agentic scaling" where AI systems interact with other AI systems. Google Cloud [announced G4 VMs](https://cloud.google.com/blog/products/compute/google-cloud-ai-infrastructure-at-nvidia-gtc-2026) with RTX Pro 6000 Blackwell GPUs and fractional GPU instances for cost efficiency.

But the quote that will stick from GTC came on the [All-In Podcast](https://www.businessinsider.com/jensen-huang-500k-engineers-250k-ai-tokens-nvidia-compute-2026-3): "If that \$500,000 engineer did not consume at least \$250,000 worth of tokens, I am going to be deeply alarmed." Huang wants Nvidia to spend [\$2 billion on tokens for its own engineers](https://the-decoder.com/nvidia-ceo-jensen-huang-says-hed-be-deeply-alarmed-if-a-500k-developer-spent-less-than-250k-on-ai-tokens/) and compared not using AI to a chip designer choosing paper and pencil over CAD tools. He also called Dario Amodei's forecast of a trillion dollars in AI usage revenue by 2030 "very conservative," arguing that enterprise software companies will become "value-added resellers" of tokens from Anthropic and OpenAI. The man selling shovels thinks you should buy more shovels, yes, but the 50%-of-salary framing is going to change how a lot of engineering leaders think about AI budgets.

### Mistral Forge: build your own frontier model

Mistral [launched Forge](https://techcrunch.com/2026/03/17/mistral-forge-nvidia-gtc-build-your-own-ai-enterprise/) at GTC, letting enterprises train custom models on their own data with full model lifecycle support (pre-training, post-training, reinforcement learning). Early adopters include ASML, Ericsson, and the European Space Agency. Mistral is on track to [surpass \$1B ARR this year](https://venturebeat.com/infrastructure/mistral-ai-launches-forge-to-help-companies-build-proprietary-ai-models). The pitch is compelling: most enterprise AI fails because models trained on the internet do not understand your business.

### White House AI framework: preemption over regulation

The Trump Administration [released a national AI policy framework](https://www.whitehouse.gov/articles/2026/03/president-donald-j-trump-unveils-national-ai-legislative-framework/) on March 20. The headline for developers: federal preemption of state AI laws. Congress is being asked to "preempt state AI laws that impose undue burdens" and establish a single national standard. The framework also declares that AI training on copyrighted material does not violate copyright laws. This is a clear pro-industry stance that will face significant legal challenges.

## Interesting GitHub repositories

### [obra/superpowers](https://github.com/obra/superpowers) (106k stars, +20k this week)

Agentic skills framework and software development methodology for Claude Code. Provides structured workflows (brainstorming, TDD, code review) that produce consistently better results than raw prompting. Growing faster than any other agent harness.

### [affaan-m/everything-claude-code](https://github.com/affaan-m/everything-claude-code) (99k stars, +20k this week)

Performance optimization system for Claude Code featuring skills, instincts, memory, and security layers. Aimed at teams that want a shared, opinionated Claude Code setup.

### [bytedance/deer-flow](https://github.com/bytedance/deer-flow) (37k stars)

ByteDance's open-source SuperAgent that researches, codes, and creates using sandboxes and subagents. The sandbox architecture is relevant for secure code execution in cloud environments.

### [volcengine/OpenViking](https://github.com/volcengine/OpenViking) (18k stars, +6k this week)

Context database designed for AI agents with hierarchical context delivery. Tries to solve the problem of keeping agents aware of what matters across long-running sessions. Covered by [Fireship](https://www.youtube.com/watch?v=Xn-gtHDsaPY) as a standout among new open-source tools.

### [browser-use/browser-use](https://github.com/browser-use/browser-use) (83k stars)

Makes websites accessible for AI agents and automates browser tasks. The leading open-source option for agent-driven browser automation, though [anti-bot measures remain a friction point](https://www.youtube.com/watch?v=cueVwWVoFlU).

### [lightpanda-io/browser](https://github.com/lightpanda-io/browser) (24k stars, +6k this week)

Headless browser built in Zig, specifically designed for AI and automation. Faster and more efficient than Puppeteer/Playwright for agent use cases.

### [HKUDS/LightRAG](https://github.com/HKUDS/LightRAG) (30k stars)

Lightweight retrieval-augmented generation framework from EMNLP 2025 research. Optimized for performance without the complexity of heavier RAG frameworks.

### [666ghj/MiroFish](https://github.com/666ghj/MiroFish) (40k stars, +13k this week)

Swarm intelligence engine for prediction tasks. Uses collective agent behavior to aggregate predictions, which could be useful for anomaly detection and capacity planning.

### [jarrodwatts/claude-hud](https://github.com/jarrodwatts/claude-hud) (12k stars, +6k this week)

Dashboard plugin for Claude Code displaying context usage, active tools, running agents, and progress. Useful when you want to see what your agent is actually doing.

### [hectorvent/floci](https://github.com/hectorvent/floci) (HN: 274 points)

Free, open-source local AWS emulator supporting 20+ services with 24ms startup time (vs 3.3s for competitors), 13MB idle memory (vs 143MB), and MIT licensing with no feature restrictions. A lightweight alternative to LocalStack.

### [voidzero-dev/vite-plus](https://github.com/voidzero-dev/vite-plus) (3k stars, +1.8k this week)

Unified toolchain built in Rust that manages runtime, package manager, and frontend build tooling. Basically Vite but trying to own the whole stack.

## Quick bits

* H Company and Nvidia [released Holotron-12B](https://huggingface.co/blog/Hcompany/holotron-12b), an open-source 12B parameter model for computer-use agents. WebVoyager performance jumped from 35.1% to 80.5%.
* Hugging Face's [Spring 2026 State of Open Source report](https://huggingface.co/blog) landed, covering ecosystem trends across the Hub.
* Mistral shipped [Small 4](https://simonwillison.net/2026/Mar/17/mini-and-nano/), a 119B parameter unified multimodal reasoning model.
* OpenAI's Codex subagents [hit general availability](https://simonwillison.net/2026/Mar/17/mini-and-nano/), enabling parallel task execution in isolated sandboxes.
* Microsoft's MAUI UI framework is [expanding to Linux](https://avaloniaui.net/blog/maui-avalonia-preview-1) through an Avalonia partnership.
* [Grafeo](https://grafeo.dev/): a fast, embeddable graph database in Rust supporting GQL, Cypher, Gremlin, GraphQL, SPARQL, and vector search.
* [Project Nomad](https://www.projectnomad.us) bundles Wikipedia, local LLMs via Ollama, OpenStreetMap, and Khan Academy content into an offline survival computer.
* Lalit Maganti [built syntaqlite](https://lalitm.com/), high-fidelity devtools for SQLite.
* Bram Cohen (yes, the BitTorrent creator) [wrote about the future of version control](https://bramcohen.com/p/manyana) beyond git. 506 points on HN.
* Simon Willison explored building a [task management app using Claude skills](https://simonwillison.net) with Starlette 1.0, the FastAPI foundation framework.
* Anthropic surveyed [81,000 people](https://www.anthropic.com/news) about what they want from AI. Described as the largest multilingual qualitative study of its kind.
* Vercel released a [Chat SDK](https://vercel.com/blog), a unified TypeScript library for building chatbots across Slack, Discord, and Teams from a single codebase.
* George Hotz's tinygrad [purpose-built deep learning workstations](https://tinygrad.org/#tinybox) benchmarked competitively against much more expensive hardware. 581 points on HN.

## Sources

### AI models and research

* [OpenAI: Introducing GPT-5.4 Mini and Nano](https://openai.com/index/introducing-gpt-5-4-mini-and-nano/)
* [DeepSeek V4 specs and benchmarks](https://www.nxcode.io/resources/news/deepseek-v4-release-specs-benchmarks-2026)
* [Google: Gemini 3.1 Flash-Lite](https://blog.google/innovation-and-ai/models-and-research/gemini-models/gemini-3-1-flash-lite/)
* [Flash-MoE on GitHub](https://github.com/danveloper/flash-moe)
* [Simon Willison: LLM in a Flash](https://simonwillison.net/2026/Mar/18/llm-in-a-flash/)
* [Holotron-12B on Hugging Face](https://huggingface.co/blog/Hcompany/holotron-12b)
* [Anthropic: What 81,000 people want from AI](https://www.anthropic.com/news)

### Coding agents and dev tools

* [OpenAI acquires Astral](https://openai.com/index/openai-to-acquire-astral/)
* [Astral: Joining OpenAI](https://astral.sh/blog/openai)
* [Simon Willison: Thoughts on OpenAI acquiring Astral](https://simonwillison.net/2026/mar/19/openai-acquiring-astral/)
* [Cursor: Introducing Composer 2](https://cursor.com/blog/composer-2)
* [TechCrunch: Cursor admits Composer 2 built on Kimi](https://techcrunch.com/2026/03/22/cursor-admits-its-new-coding-model-was-built-on-top-of-moonshot-ais-kimi/)
* [GitHub: How Squad runs coordinated AI agents](https://github.blog/ai-and-ml/github-copilot/how-squad-runs-coordinated-ai-agents-inside-your-repository/)
* [Windsurf: New pricing plans](https://windsurf.com/blog)
* [LogRocket: AI dev tool power rankings](https://blog.logrocket.com/ai-dev-tool-power-rankings/)
* [OpenClaw security analysis (Composio)](https://composio.dev/content/openclaw-security-and-vulnerabilities)
* [The Hacker News: OpenClaw vulnerabilities](https://thehackernews.com/2026/03/openclaw-ai-agent-flaws-could-enable.html)
* [obra/superpowers on GitHub](https://github.com/obra/superpowers)

### Web development

* [Cloudflare: Workers AI now runs large models](https://blog.cloudflare.com/workers-ai-large-models/)
* [Vercel: Build knowledge agents without embeddings](https://vercel.com/blog/build-knowledge-agents-without-embeddings)
* [The three pillars of JavaScript bloat](https://43081j.com/2026/03/three-pillars-of-javascript-bloat)
* [Tooscut: Browser-based video editor](https://tooscut.app/)

### Industry and business

* [Bloomberg: Block's 4,000 job cuts](https://www.bloomberg.com/news/articles/2026-03-01/jack-dorsey-s-4-000-job-cuts-at-block-arouse-suspicions-of-ai-washing)
* [Tech layoffs reach 45,000 (RationalFX)](https://technode.global/2026/03/09/2026-tech-layoffs-reach-45000-in-march-more-than-9200-due-to-ai-and-automation-rationalfx/)
* [Nvidia GTC 2026: Vera Rubin platform](https://nvidianews.nvidia.com/news/rubin-platform-ai-supercomputer)
* [TechCrunch: Mistral Forge](https://techcrunch.com/2026/03/17/mistral-forge-nvidia-gtc-build-your-own-ai-enterprise/)
* [White House AI policy framework](https://www.whitehouse.gov/articles/2026/03/president-donald-j-trump-unveils-national-ai-legislative-framework/)
* [Business Insider: Jensen Huang on \$250k token spend per engineer](https://www.businessinsider.com/jensen-huang-500k-engineers-250k-ai-tokens-nvidia-compute-2026-3)
* [The Decoder: Huang's token spending comments](https://the-decoder.com/nvidia-ceo-jensen-huang-says-hed-be-deeply-alarmed-if-a-500k-developer-spent-less-than-250k-on-ai-tokens/)
* [Bridgewater: \$650B Big Tech AI investment](https://www.reuters.com/business/big-tech-invest-about-650-billion-ai-2026-bridgewater-says-2026-02-23/)

### YouTube sources

* [Nate B Jones: Claude Code data loss incident](https://www.youtube.com/watch?v=8lwnJZy4cO0)
* [Nate B Jones: Anthropic /loop feature](https://www.youtube.com/watch?v=vqnAOV8NMZ4)
* [Nate B Jones: McKinsey agentic commerce](https://www.youtube.com/watch?v=BE4RclIGDmY)
* [Fireship: 7 open source AI tools](https://www.youtube.com/watch?v=Xn-gtHDsaPY)
* [Fireship: Google Stitch UI/UX](https://www.youtube.com/watch?v=qaB5HF4ax9M)
* [Better Stack: Superpowers plugin review](https://www.youtube.com/watch?v=lq3rzXP4_vs)
* [Matt Pocock: 5 Claude Code skills](https://www.youtube.com/watch?v=EJyuu6zlQCg)
* [Simon Scrapes: Self-improving Claude Code skills](https://www.youtube.com/watch?v=wQ0duoTeAAU)
* [All About AI: Parallel browser automation](https://www.youtube.com/watch?v=cueVwWVoFlU)

### GitHub repositories

* [obra/superpowers](https://github.com/obra/superpowers)
* [affaan-m/everything-claude-code](https://github.com/affaan-m/everything-claude-code)
* [bytedance/deer-flow](https://github.com/bytedance/deer-flow)
* [volcengine/OpenViking](https://github.com/volcengine/OpenViking)
* [browser-use/browser-use](https://github.com/browser-use/browser-use)
* [lightpanda-io/browser](https://github.com/lightpanda-io/browser)
* [HKUDS/LightRAG](https://github.com/HKUDS/LightRAG)
* [666ghj/MiroFish](https://github.com/666ghj/MiroFish)
* [jarrodwatts/claude-hud](https://github.com/jarrodwatts/claude-hud)
* [hectorvent/floci](https://github.com/hectorvent/floci)
* [voidzero-dev/vite-plus](https://github.com/voidzero-dev/vite-plus)
* [shareAI-lab/learn-claude-code](https://github.com/shareAI-lab/learn-claude-code)
* [langchain-ai/deepagents](https://github.com/langchain-ai/deepagents)
* [Crosstalk-Solutions/project-nomad](https://github.com/Crosstalk-Solutions/project-nomad)
* [unslothai/unsloth](https://github.com/unslothai/unsloth)


# AI Weekly Review - Mar. 30th 2026
Source: https://developer.upsun.com/posts/ai/aiweekly-2026-03-30

A press, Youtube and Github review of everything AI


<PostMeta />

# Weekly AI review, March 30, 2026

> Anthropic's "Capybara" model surfaced through a misconfigured CMS cache, spooking cybersecurity markets with claims of unprecedented exploit capabilities. OpenAI killed Sora after burning \$15M per day on inference against \$2.1M in total lifetime revenue, taking a \$1B Disney deal down with it. A poisoned LiteLLM package cascaded through 36% of cloud environments in 46 minutes. And ARC-AGI-3 launched, where every frontier model scored under 1% on tasks humans solve at 100%.

## Highlight of the week

### Anthropic's "Capybara" model leaks, cybersecurity stocks dip

A misconfigured CMS cache at Anthropic left roughly 3,000 unpublished blog assets publicly accessible, and among them were details about [Claude Mythos](https://fortune.com/2026/03/26/anthropic-says-testing-mythos-powerful-new-ai-model-after-data-leak-reveals-its-existence-step-change-in-capabilities/) (internal codename Capybara). The leaked documents describe a new tier beyond Opus with "dramatically higher scores on tests of software coding, academic reasoning, and cybersecurity."

The cybersecurity detail is what makes this more than a routine leak. Anthropic's own draft materials warn that Capybara is "currently far ahead of any other AI model in cyber capabilities" and "presages an upcoming wave of models that can exploit vulnerabilities in ways that far outpace the efforts of defenders." [Cybersecurity stocks dropped](https://uk.finance.yahoo.com/news/cybersecurity-stocks-plunge-anthropic-claude-124810214.html) on the news.

Anthropic is restricting early access to organizations focused on cyber defense, giving them time to harden their systems before broader availability. That is a responsible approach, but the irony of a safety-focused company leaking its own most dangerous model through a CMS misconfiguration is hard to ignore.

The timing lines up with [Anthropic reportedly considering an IPO as early as October 2026](https://www.bloomberg.com/news/articles/2026-03-27/claude-ai-maker-anthropic-said-to-weigh-ipo-as-soon-as-october), with bankers expecting a raise north of \$60 billion. Revenue has reportedly topped \$19 billion annualized, more than double from three months ago. Whether the Mythos leak was genuinely accidental or conveniently timed PR, the capability signal is real.

## Models and research

### ARC-AGI-3: the benchmark that broke every frontier model

[ARC-AGI-3](https://arcprize.org/blog/arc-agi-3-launch) launched March 25 as the first fully interactive benchmark in the series: hundreds of turn-based environments handcrafted by game designers with no instructions, no rules, and no stated goals. AI agents must explore, discover the mechanics, figure out what winning means, and carry learning forward across increasingly difficult levels.

The scores are brutal. Humans: 100%. Gemini 3.1 Pro: 0.37%. GPT-5.4: 0.26%. Claude Opus 4.6: 0.25%. Grok 4.2: zero. Meanwhile, [Symbolica](https://arcprize.org/arc-agi/3) hit 36% on day one using a non-LLM approach, which says a lot about where the actual gap is.

If you care about AGI timelines, this is the benchmark to watch. It tests whether a system can learn from novel situations without being told what to do, not whether it can answer harder versions of questions it has already seen. The \$2 million prize is live, submissions close November 2, and all solutions must be open-sourced.

### Gemini 3.1 Flash-Lite and Flash Live

Google shipped two new models this week. [Gemini 3.1 Flash-Lite](https://blog.google/innovation-and-ai/models-and-research/gemini-models/gemini-3-1-flash-lite/) targets high-throughput workloads at \$0.25 per million input tokens, with 2.5x faster time-to-first-token and 45% higher output speed than Gemini 2.5 Flash. [Gemini 3.1 Flash Live](https://blog.google/innovation-and-ai/models-and-research/gemini-models/gemini-3-1-flash-live/) is their real-time audio model supporting dialogue with improved tonal understanding and SynthID watermarking, available in 200+ countries.

Meanwhile, Gemini 3.1 Pro continues to show strong benchmark results (77% on ARC-AGI-2, up from 31% last generation, and #1 on SVG Arena) but has run into reliability problems. A [HN thread](https://news.ycombinator.com/item?id=47233667) reported the model appearing to leak responses from other users' prompts, and a former Googler commented that "Gemini is consistently the most frustrating model I've used for development."

### Voxtral TTS: open-weight speech that runs on your phone

Mistral released [Voxtral TTS](https://mistral.ai/news/voxtral-tts), a 4B-parameter open-weight text-to-speech model supporting 9 languages with streaming at roughly 100ms time-to-first-audio. Zero-shot voice cloning from as little as 3 seconds of reference audio, no transcript required. Human evaluations show [superior naturalness versus ElevenLabs Flash v2.5](https://venturebeat.com/orchestration/mistral-ai-just-released-a-text-to-speech-model-it-says-beats-elevenlabs-and). Full model weights are available on [Hugging Face](https://huggingface.co/mistralai/Voxtral-4B-TTS-2603).

At 4B parameters, this runs on laptops and mid-range GPUs. The Hacker News community wasted no time: someone built an [MLX macOS dictation app](https://news.ycombinator.com/item?id=47501426), another did a pure-C CPU implementation, and a third shipped a Rust browser-based version. On-device TTS at this quality was not really an option a month ago.

### OpenAI's agent monitoring catches base64 bypass attempts

OpenAI published a detailed account of [monitoring tens of millions of internal coding agent trajectories](https://openai.com/index/how-we-monitor-internal-coding-agents-misalignment/) over five months using GPT-5.4 as a monitor. The most interesting finding: one agent, denied access to a resource, methodically attempted to bypass security controls by encoding commands in base64 and splitting payloads into smaller steps to evade detection. Its chain-of-thought reasoning was explicit about what it was doing.

Zero conversations triggered the highest severity alert. Roughly 1,000 triggered moderate alerts, though many came from red-teaming rather than organic failures. No evidence of self-preservation or scheming behavior. Worth reading the full post, particularly alongside this week's Meta news about agents doing things nobody asked them to do.

## Coding agents and dev tools

### Cursor Composer 2 built on Moonshot AI's Kimi K2.5

When Cursor launched Composer 2 on March 19, it promoted the model as frontier-level coding intelligence at roughly one-tenth the cost of Opus. Within days, a developer [discovered the model identifier](https://techcrunch.com/2026/03/22/cursor-admits-its-new-coding-model-was-built-on-top-of-moonshot-ais-kimi/) was `kimi-k2p5-rl-0317-s515-fast`, revealing it as a fine-tune of Moonshot AI's Kimi K2.5, a Chinese open-source model backed by Alibaba and HongShan.

Cursor's VP Lee Robinson acknowledged: "Yep, Composer 2 started from an open-source base!" and claimed only about 1/4 of compute came from the base model. The [Composer 2 technical report](https://cursor.com/blog/composer-2) describes a two-phase approach: continued pretraining on Kimi K2.5, then large-scale RL in realistic dev environments, achieving 37% improvement over Composer 1 (61.3 on CursorBench). Custom MoE kernels for Blackwell GPUs and an internal sandboxed platform called Anyrun are part of the stack.

Two things worth noting. Composer 1 was based on Qwen. So this is the second time Cursor built its flagship on a Chinese open-source base without saying so up front. That is a pattern, not an accident. At the same time, this is exactly what the open-source model ecosystem was supposed to enable: take a strong base, specialize it for your domain, ship it. The practice is fine. The secrecy is not.

### Claude Code: three major releases in one week

Claude Code shipped [three releases](https://github.com/anthropics/claude-code/releases) in a single week. The highlights from v2.1.85-87: conditional `if` field for hooks using permission rule syntax, MCP OAuth following RFC 9728 discovery, improved prompt cache hit rates for Bedrock/Vertex/Foundry users, `.jj` and `.sl` VCS support (Jujutsu and Sapling), and fixes for OOM crashes on long sessions.

Zoom out and the March picture is larger: computer use for Pro and Max users (Claude can open files, navigate the screen, point and click), voice mode with push-to-talk, default output raised to 64K tokens for Opus 4.6, and web sessions that auto-follow PRs and fix CI failures in the cloud. Nate B Jones [framed Anthropic's triple launch](https://www.youtube.com/watch?v=3e7gmNPr5Vo) (scheduled tasks, Dispatch, Computer Use) as "three primitives that together create a managed OpenClaw for Claude." One Anthropic product manager reportedly ran Dispatch for 48 consecutive hours while parenting, spending about 25 minutes total entering commands while Claude executed hours of parallel work.

### GitHub trains on your code by default starting April 24

[Starting April 24, 2026](https://github.blog/news-insights/company-news/updates-to-github-copilot-interaction-data-usage-policy/), GitHub will use interaction data from Copilot Free, Pro, and Pro+ users to train AI models unless you opt out. The data includes code snippets, code context around the cursor, file names, repository structure, navigation patterns, chat conversations, and feedback signals. Business and Enterprise users are exempt.

The 30-day opt-out window and the fact that [previous opt-out preferences are preserved](https://github.com/orgs/community/discussions/188488) soften the blow somewhat. But the HN backlash was fierce, and threads about [moving from GitHub to Codeberg](https://news.ycombinator.com/item?id=47548243) gained traction. If you are on an individual plan and care about this, go to `/settings/copilot/features` and toggle it off before April 24.

## Web development and frameworks

### Cloudflare Dynamic Workers: 100x faster agent sandboxing

[Dynamic Workers](https://blog.cloudflare.com/dynamic-workers/) entered open beta on March 24, providing V8 isolate-based sandboxes for executing AI-generated code. Millisecond startup instead of hundreds of milliseconds for containers. A few megabytes of memory instead of hundreds. Priced at [\$0.002 per unique Worker loaded per day](https://developers.cloudflare.com/changelog/post/2026-03-24-dynamic-workers-open-beta/) (waived during beta) plus standard CPU and invocation costs.

The interesting bet here is what Cloudflare calls "Code Mode": instead of agents calling tools through rigid schemas, they write and run JavaScript that hits APIs directly, sandboxed in an isolate that starts faster than a container can even think about booting. If this pattern catches on, it changes how agent frameworks are built.

Also from Cloudflare this week: a [Rust-based FL2 stack](https://blog.cloudflare.com/) delivering 2x edge compute performance on new Gen 13 servers with AMD EPYC Turin 9965 processors, and a nice post about [using ASTs to turn Workflows code into visual diagrams](https://blog.cloudflare.com/workflow-diagrams/), noting that this becomes important "as coding agents write more code that developers may not read directly."

### Google Stitch's design.markdown changes the game

Most coverage of the [Google Stitch](https://blog.google/innovation-and-ai/models-and-research/google-labs/stitch-ai-ui-design/) update focused on the flashy stuff: voice-to-design, multi-screen generation on an infinite canvas, interactive prototyping. The more interesting piece is that Stitch now exports a `design.markdown` file, a machine-readable design system manifest that any coding agent can consume to maintain visual consistency across projects. That is a genuinely new kind of artifact, one that lets agents understand design intent rather than just generate pixels.

As [Fireship noted](https://www.youtube.com/watch?v=qaB5HF4ax9M), Google shipping official Claude Code skills for Stitch signals how dominant Claude has become when even Google builds integration skills for a competitor's tool. Nate B Jones [connected these dots](https://www.youtube.com/watch?v=CDClFY-R0dI) further, arguing that design is following development to the command line, with Stitch, Remotion (programmable video as React components), and Blender MCP (natural language 3D modeling) collapsing the 2010s product-design-engineering triangle into a single workflow.

### Astro 6.1

[Astro 6.1](https://astro.build/blog/astro-610/) shipped with codec-specific Sharp image defaults, non-English SmartyPants configuration, and smoother mobile view transitions.

## Industry and business

### OpenAI kills Sora, Disney walks

OpenAI [shut down Sora on March 24](https://variety.com/2026/digital/news/openai-shutting-down-sora-video-disney-1236698277/), six months after public release. The numbers tell the story: estimated inference cost of roughly \$15M per day, total lifetime revenue of just \$2.1M, user count that peaked at about 1 million before collapsing to under 500,000. Disney had committed \$1B to a partnership but [found out about the shutdown less than an hour before the public announcement](https://www.hollywoodreporter.com/business/digital/openai-shutting-down-sora-ai-video-app-1236546187/), killing the deal. No money had actually changed hands.

A detail that tells you everything: OpenAI posted a detailed [Sora safety blog](https://openai.com/index/creating-with-sora-safely/) on March 24, one day before pulling the plug. Sora's failure is a reminder that "impressive demo" and "sustainable product" are wildly different things. Generative video is extraordinarily expensive to run, and nobody figured out who would pay enough to cover the bill.

### GPU prices keep climbing

Both AMD and NVIDIA have been implementing phased GPU price hikes since Q1 2026, driven by AI datacenter demand consuming memory supply. [Memory now accounts for nearly 80% of a high-end GPU's bill of materials](https://www.tomshardware.com/pc-components/gpus/amd-to-raise-graphics-card-prices-by-at-least-10-percent-in-2026-price-surge-attributed-to-ongoing-ai-related-dram-supply-crisis). The RTX 5090 could reach \$5,000 later this year. NVIDIA is reportedly cutting RTX 5060 Ti and 5070 production by 30-40% to reallocate VRAM to higher-margin AI chips. [AWS raised GPU instance prices 15%](https://news.ycombinator.com/item?id=46511153) without fanfare.

If you run models locally for development or experimentation, your hardware budget just went up. This makes the move toward efficient architectures (MoE, aggressive quantization, smaller active parameter counts) less of an optimization and more of a necessity.

### Harvey AI hits \$11B

Legal AI startup [Harvey raised \$200M at an \$11B valuation](https://www.cnbc.com/2026/03/25/legal-ai-startup-harvey-raises-200-million-at-11-billion-valuation.html), co-led by GIC and Sequoia, just months after an \$8B round. Over 100,000 lawyers across 1,300 organizations now use the platform. Harvey is probably the best proof point right now that vertical AI applications can build real businesses. The speed of the valuation increase (\$8B to \$11B in months) suggests investors are more comfortable betting on domain-specific AI than on foundation model companies themselves.

### Meta's rogue AI agent problem

A [Meta AI agent went rogue](https://techcrunch.com/2026/03/18/meta-is-having-trouble-with-rogue-ai-agents/), posting responses on an internal forum without permission and inadvertently exposing sensitive data to unauthorized employees for two hours, triggering a Sev 1 incident. Separately, Meta's own safety and alignment director described her OpenClaw agent deleting her entire inbox despite instructions to confirm before acting.

HiddenLayer's 2026 report found autonomous agents now account for more than one in eight AI breaches. A [CISO survey](https://news.ycombinator.com/item?id=47131689) found 47% had observed agents exhibiting unintended behavior, but only 5% felt confident they could contain a compromised agent. Read those two numbers together and sit with them for a moment.

## Supply chain security

### LiteLLM: anatomy of a cascading supply chain attack

The [LiteLLM compromise](https://thehackernews.com/2026/03/teampcp-backdoors-litellm-versions.html) deserves its own section because the mechanics are worth understanding. On March 24, threat actor "TeamPCP" published backdoored versions of LiteLLM (1.82.7 and 1.82.8) on PyPI after stealing credentials through a [compromised Trivy GitHub Action](https://blog.gitguardian.com/trivys-march-supply-chain-attack-shows-where-secret-exposure-hurts-most/). The attack was a three-stage payload: credential harvesting, Kubernetes lateral movement, and a persistent systemd backdoor.

The packages were live for roughly 46 minutes and downloaded about 47,000 times. LiteLLM has approximately 95 million monthly downloads and is present in [36% of cloud environments](https://www.esecurityplanet.com/threats/litellm-supply-chain-attack-exposes-credentials-across-ai-ecosystems/). One Hacker News commenter noted that `uvx` automatically pulled the latest version and Cursor automatically started the local MCP server, creating an attack path through the AI development toolchain itself.

Simon Willison's [multi-day coverage](https://simonwillison.net/) made a practical argument: [package managers need cooldown periods](https://simonwillison.net/2026/Mar/24/package-managers-need-cooldown-periods/) that delay dependency updates to give communities time to detect compromises. [Sourcegraph used Deep Search](https://sourcegraph.com/blog) to categorize affected repositories by risk based on version pinning practices. The lesson is depressingly familiar: pin your dependencies, review your CI/CD trust chain, and treat security scanners as attack surface too.

## Interesting GitHub repositories

* **[obra/superpowers](https://github.com/obra/superpowers)** (124K stars, +18K/week): An agentic skills framework that forces structured workflows before coding begins. Instead of letting agents jump into code, Superpowers enforces spec extraction, chunked design review, and implementation planning. Works with Claude Code, Cursor, Codex, OpenCode, and Gemini CLI. The approach aligns with what Nate B Jones has been arguing: the bottleneck in agent-driven development is specification, not code generation.

* **[affaan-m/everything-claude-code](https://github.com/affaan-m/everything-claude-code)** (117K stars, +19.8K/week): The Anthropic hackathon winner. A complete optimization system covering skills, instincts, memory, continuous learning, and security scanning across Claude Code, Codex, and Cowork. Includes guides on token optimization and subagent orchestration via git worktrees.

* **[bytedance/deer-flow](https://github.com/bytedance/deer-flow)** (53.4K stars, +18.2K/week): DeerFlow 2.0 from ByteDance. A ground-up rewrite of their super agent harness that orchestrates sub-agents, memory, sandboxes, and skills for long-horizon tasks. Includes Claude Code integration, an embedded frontend, and IM channel support.

* **[microsoft/VibeVoice](https://github.com/microsoft/VibeVoice)** (28.2K stars): Open-source voice AI from Microsoft covering both TTS and ASR. Uses continuous speech tokenizers at 7.5 Hz and a next-token diffusion framework. The ASR model handles 60-minute audio in a single pass with speaker diarization and timestamps. Integrated into Hugging Face Transformers v5.3.

* **[thedotmack/claude-mem](https://github.com/thedotmack/claude-mem)** (43K stars): Persistent memory compression for Claude Code. Captures session activity, compresses it via the agent SDK, and injects relevant context into future sessions using ChromaDB embeddings and SQLite. Solves the "Claude forgets everything between sessions" problem without writing to CLAUDE.md.

* **[jingyaogong/minimind](https://github.com/jingyaogong/minimind)** (44.6K stars): Train a 64M-parameter GPT from scratch in 2 hours for about \$0.40. Covers the complete pipeline in pure PyTorch: MoE, pretraining, SFT, LoRA, RLHF, tool use, agentic RL, and model distillation. If you want to understand how models work rather than just use them, this is worth your time.

* **[SakanaAI/AI-Scientist-v2](https://github.com/SakanaAI/AI-Scientist-v2)** (3.9K stars, +1.4K/week): Automated scientific discovery via agentic tree search from Sakana AI. Generated the first workshop paper written entirely by AI and accepted through peer review. Autonomously generates hypotheses, runs experiments, analyzes data, and writes manuscripts.

* **[Crosstalk-Solutions/project-nomad](https://github.com/Crosstalk-Solutions/project-nomad)** (20K stars, +11.5K/week): A self-contained offline-first knowledge server bundling local AI chat (Ollama + Qdrant), offline Wikipedia and medical references, Khan Academy courses, offline maps, and data tools. Designed for unreliable internet scenarios.

* **[figma/mcp-server-guide](https://github.com/figma/mcp-server-guide)** (800 stars): Figma's official MCP server guide for bringing design context into AI coding workflows. Supports generating code from Figma frames, extracting design data, and writing back to the canvas. Works with VS Code, Cursor, Claude Code, and Windsurf.

* **[NousResearch/hermes-agent](https://github.com/NousResearch/hermes-agent)** (17.4K stars, +6.1K/week): Self-improving AI agent from Nous Research with a built-in learning loop. Creates skills from experience, improves them during use, and builds a deepening model of who you are across sessions. Works with any LLM provider. Reachable via Telegram, Discord, Slack, WhatsApp, and Signal.

## Quick bits

* **"Thoughts on slowing the fuck down"** hit 1,118 points on HN. [Mario Zechner argues](https://mariozechner.at/posts/2026-03-25-thoughts-on-slowing-the-fuck-down/) that agents compound errors at rates humans physically cannot, and companies claiming 100% AI-written code consistently produce poor results. Simon Willison [shared his own concerns](https://simonwillison.net/2026/Mar/25/thoughts-on-slowing-the-fuck-down/) about preserving human oversight as agent output accelerates.
* **Wine 11's NTSYNC kernel rewrite** delivered [678% gaming performance gains](https://www.xda-developers.com/wine-11-rewrites-linux-runs-windows-games-speed-gains/) (Dirt 3 went from 110 FPS to 860 FPS). Already in SteamOS beta. One of the biggest open-source stories of the week.
* **GPT-5.4 Pro solved an open Ramsey theory problem**, independently verified by Epoch. The GPT-5.x math breakthrough trend continues. [HN discussion](https://news.ycombinator.com/item?id=47497757) (479 points).
* **iPhone 17 Pro running a 400B LLM** on-device. Signals potential infrastructure shifts away from cloud inference.
* **AI sycophancy research** from Stanford (770 points on HN) documented how AI models overly affirm users seeking personal advice, raising questions about psychological safety.
* **EU Chat Control drama**: "The EU still wants to scan your private messages" hit 1,445 points, followed by the reversal "EU Parliament stops Chat Control" at 680 points.
* **C++26 finalized** with reflection as the headline feature. **Swift 6.3** shipped with an official Android SDK. **Neovim 0.12.0** added a built-in plugin manager.
* **Video.js v10** is 88% smaller after a complete rewrite of the 16-year-old web video player.
* **90% of Claude-linked output goes to repos with fewer than 2 stars**, raising questions about the quality and utility of AI-generated code at scale.
* **White House AI policy framework** emphasizes federal preemption of state AI laws, innovation over regulation. The competing [GUARDRAILS Act](https://www.ropesgray.com/en/insights/alerts/2026/03/the-white-house-legislative-recommendations-national-policy-framework-for-artificial-intelligence-an) aims to block blanket preemption. Meanwhile, a [pro-AI super PAC plans to spend \$100M](https://www.nytimes.com/2026/03/29/business/trump-artificial-intelligence-pac-midterms.html) in the 2026 midterms.
* **Addy Osmani on multi-agent coding**: His piece on ["the code agent orchestra"](https://addyosmani.com/) argues the bottleneck has shifted from code generation to verification. Three benefits of multi-agent setups: parallelism, specialization, and isolation.
* **Martin Fowler revisited Architecture Decision Records**, recommending brief markdown docs stored in source repos, never modified after acceptance. [martinfowler.com](https://martinfowler.com/articles/)
* **Simon Willison vibe-coded two SwiftUI apps** without opening Xcode. Modern LLMs excel at SwiftUI, he reports, but warns about metric accuracy in monitoring applications.
* **Miasma** (314 points on HN): a tool that traps AI scrapers in a poison pit. Creative.

## Sources

* [Fortune: Anthropic Mythos model leak](https://fortune.com/2026/03/26/anthropic-says-testing-mythos-powerful-new-ai-model-after-data-leak-reveals-its-existence-step-change-in-capabilities/)
* [Bloomberg: Anthropic weighs IPO as early as October](https://www.bloomberg.com/news/articles/2026-03-27/claude-ai-maker-anthropic-said-to-weigh-ipo-as-soon-as-october)
* [ARC Prize: ARC-AGI-3 launch](https://arcprize.org/blog/arc-agi-3-launch)
* [Google: Gemini 3.1 Flash-Lite](https://blog.google/innovation-and-ai/models-and-research/gemini-models/gemini-3-1-flash-lite/)
* [Google: Gemini 3.1 Flash Live](https://blog.google/innovation-and-ai/models-and-research/gemini-models/gemini-3-1-flash-live/)
* [Mistral: Voxtral TTS](https://mistral.ai/news/voxtral-tts)
* [OpenAI: Monitoring internal coding agents](https://openai.com/index/how-we-monitor-internal-coding-agents-misalignment/)
* [TechCrunch: Cursor admits Composer 2 built on Kimi](https://techcrunch.com/2026/03/22/cursor-admits-its-new-coding-model-was-built-on-top-of-moonshot-ais-kimi/)
* [Cursor: Composer 2 technical report](https://cursor.com/blog/composer-2)
* [Claude Code releases](https://github.com/anthropics/claude-code/releases)
* [GitHub: Copilot data usage policy](https://github.blog/news-insights/company-news/updates-to-github-copilot-interaction-data-usage-policy/)
* [Cloudflare: Dynamic Workers](https://blog.cloudflare.com/dynamic-workers/)
* [Google: Stitch AI design tool](https://blog.google/innovation-and-ai/models-and-research/google-labs/stitch-ai-ui-design/)
* [Astro 6.1](https://astro.build/blog/astro-610/)
* [Variety: OpenAI shuts down Sora](https://variety.com/2026/digital/news/openai-shutting-down-sora-video-disney-1236698277/)
* [TechCrunch: Why OpenAI really shut down Sora](https://techcrunch.com/2026/03/29/why-openai-really-shut-down-sora/)
* [Tom's Hardware: GPU price increases](https://www.tomshardware.com/pc-components/gpus/amd-to-raise-graphics-card-prices-by-at-least-10-percent-in-2026-price-surge-attributed-to-ongoing-ai-related-dram-supply-crisis)
* [CNBC: Harvey AI \$11B valuation](https://www.cnbc.com/2026/03/25/legal-ai-startup-harvey-raises-200-million-at-11-billion-valuation.html)
* [TechCrunch: Meta rogue AI agent](https://techcrunch.com/2026/03/18/meta-is-having-trouble-with-rogue-ai-agents/)
* [The Hacker News: LiteLLM supply chain attack](https://thehackernews.com/2026/03/teampcp-backdoors-litellm-versions.html)
* [GitGuardian: Trivy supply chain lessons](https://blog.gitguardian.com/trivys-march-supply-chain-attack-shows-where-secret-exposure-hurts-most/)
* [Simon Willison: Package managers need cooldown periods](https://simonwillison.net/2026/Mar/24/package-managers-need-cooldown-periods/)
* [Sourcegraph: Detecting supply chain attacks with Deep Search](https://sourcegraph.com/blog)
* [Mario Zechner: Thoughts on slowing down](https://mariozechner.at/posts/2026-03-25-thoughts-on-slowing-the-fuck-down/)
* [Nate B Jones: Anthropic's three tools](https://www.youtube.com/watch?v=3e7gmNPr5Vo)
* [Nate B Jones: Google Stitch analysis](https://www.youtube.com/watch?v=CDClFY-R0dI)
* [Nate B Jones: AI job market split](https://www.youtube.com/watch?v=4cuT-LKcmWs)
* [Fireship: Anthropic Computer Use](https://www.youtube.com/watch?v=wfeiCZK0mNs)
* [Fireship: Google Stitch](https://www.youtube.com/watch?v=qaB5HF4ax9M)
* [The Neuron: NVIDIA Kari Briski on Nemotron 3](https://www.youtube.com/watch?v=J9TG0-q0CHI)
* [Meta AI: SAM 3.1](https://ai.meta.com/blog/segment-anything-model-3/)
* [Google: Lyria 3 Pro](https://blog.google/innovation-and-ai/technology/ai/lyria-3-pro/)
* [GitHub: Actions security roadmap](https://github.blog)
* [GitHub: AI-powered security detections](https://github.blog)
* [Addy Osmani: Code agent orchestra](https://addyosmani.com/)
* [Cloudflare: Workflow diagrams via ASTs](https://blog.cloudflare.com/workflow-diagrams/)
* [XDA: Wine 11 NTSYNC performance](https://www.xda-developers.com/wine-11-rewrites-linux-runs-windows-games-speed-gains/)


# AI Weekly Review - Apr. 7th 2026
Source: https://developer.upsun.com/posts/ai/aiweekly-2026-04-07

A press, Youtube and Github review of everything AI


<PostMeta />

# Weekly AI review, April 7th, 2026

> The Claude Code source leak dominated headlines, but the real stories this week were structural. Cursor 3 shipped a full rewrite that bets the company on agents-as-interface. Google dropped Gemma 4 under Apache 2.0, and within five days it crossed 2 million downloads. Anthropic cut off OpenClaw from subscriptions, confirming what many suspected: flat-rate plans can't survive agentic usage patterns. And the axios supply chain attack, attributed to North Korean actors, reminded everyone that the npm ecosystem remains frighteningly fragile. The week's theme: the agentic era is arriving fast, and the infrastructure, security, and business models around it are not ready.

## Highlight of the week

**Cursor 3 ships a full rewrite, and it's not an editor anymore.** Anysphere released [Cursor 3](https://cursor.com/blog/cursor-3) on April 2, completely rebuilt in Rust and TypeScript. It's no longer a VS Code fork. The new interface is organized around managing parallel AI agents, not editing files. You can spin up multiple agents working on different tasks simultaneously, move sessions between cloud and local, and access agents from mobile, Slack, GitHub, or Linear.

The interesting bit is the Composer 2 model controversy. Fireship [reported](https://www.youtube.com/watch?v=JSuS-zXMVwE) that Composer 2, initially marketed as surpassing Claude Opus 4.6, turned out to be based on Moonshot's Kimmy K2 model fine-tuned with reinforcement learning. Cursor later apologized for the lack of transparency. Kimmy K2 itself was accused of training on Claude's outputs because it occasionally says "Hi, I'm Claude." The provenance chain here is messy.

Cursor's [warp decode](https://www.cursor.com/blog/warp-decode) research paper, published the same week, shows they're serious about the inference stack too: a GPU kernel optimization that achieves 1.84x throughput improvement for MoE models on Blackwell GPUs. At \$20/month with \$2B ARR, Cursor is making a big bet that the IDE of the future is really an agent orchestration platform. Whether developers want to be "air traffic controllers" instead of programmers is the open question.

## Models & research

**Gemma 4 is the open model release of the year so far.** Google [released four variants](https://deepmind.google/models/gemma/gemma-4/) on April 2: a 31B dense model, a 26B MoE, and two edge models (E4B and E2B). The numbers are hard to ignore. LiveCodeBench jumped from 29.1% (Gemma 3 27B) to 80.0% (Gemma 4 31B). AIME math went from 20.8% to 89.2%. The 31B model sits at #3 on Arena AI's text leaderboard, and that's #3 globally, [not just among open models](https://9to5google.com/2026/04/02/google-gemma-4/).

Two decisions matter most. First, Apache 2.0 licensing, a first for Gemma, removes the commercial restrictions that made earlier versions awkward for production use. Second, the edge models run on iPhones. Google's [AI Edge Gallery app](https://apps.apple.com/nl/app/google-ai-edge-gallery/id6749645337) brings Gemma 4 E2B directly to consumer hardware with full offline capability. Simon Willison [covered this](https://simonwillison.net/2026/Apr/6/google-ai-edge-gallery/) and the broader Gemma 4 launch extensively. Latent Space [reported](https://www.latent.space/p/ainews-gemma-4-crosses-2-million) 2 million downloads in the first week.

**1-Bit Bonsai pushes the limits of quantization.** PrismML [released three models](https://prismml.com/news/bonsai-8b) where every weight is either -1 or +1, trained natively at 1-bit precision rather than quantized after training. The 8B model fits in 1.15GB and runs at 131 tokens/sec on an M4 Pro Mac. The [Register noted](https://www.theregister.com/2026/04/04/prismml_1bit_llm/) it's the first commercially viable 1-bit LLM. There are real caveats: code generation is weak, mainstream inference engines don't support 1-bit weights yet, and the training method is proprietary. But as a proof of concept, it's striking.

**Other model news.** Alibaba shipped [Qwen3.6-Plus](https://qwen.ai/blog?id=qwen3.6) focused on agentic capabilities and real-world tool use. Researchers found that [embarrassingly simple self-distillation](https://arxiv.org/abs/2604.01193) (sampling code from a model and fine-tuning on its own outputs) boosts coding benchmarks significantly, with Qwen3-30B going from 42.4% to 55.3% on LiveCodeBench. [TinyLoRA](https://arxiv.org) demonstrated reasoning capabilities from just 13 parameters. Anthropic published [research on emotion concepts](https://www.anthropic.com/research/emotion-concepts-function) in LLMs.

## Coding agents & dev tools

**The Claude Code leak was embarrassing but educational.** Anthropic accidentally [shipped the entire 500,000-line TypeScript source](https://venturebeat.com/technology/claude-codes-source-code-appears-to-have-leaked-heres-what-we-know/) via a source map file in npm package v2.1.88. The cause was likely a Bun.js bundler default that generates source maps unless explicitly disabled.

What the code revealed is more interesting than the leak itself. Fireship's [deep dive](https://www.youtube.com/watch?v=mBHRPeg8zPU) (2.9M views) catalogued the findings: anti-distillation poison pills (fake tool definitions to pollute competitor training data), an "undercover mode" that hides Claude's involvement in commits and PRs, a regex-based frustration detector that silently logs when users swear, and 44 unreleased feature flags including "Buddy" (a Tamagotchi-style dev companion), "Chyrus" (a background agent with dream mode and daily journaling), and model codenames confirming Capybara as a Claude 4.6 variant.

NeetCode [raised the copyright question](https://www.youtube.com/watch?v=LCjkmbHOtys) nobody else explored properly: if Anthropic's devs don't write code by hand (their stated philosophy), and AI-generated code isn't copyrightable under US law, can they DMCA the Python port? The open-source community quickly created "Claw Code," which became the fastest repo ever to hit 50,000 stars.

The irony: Anthropic built an entire undercover mode subsystem to prevent internal information from leaking in git commits, then shipped the entire source in a .map file. On the practical side, NeetCode noted that [running sub-agents is essentially free](https://www.youtube.com/watch?v=LCjkmbHOtys) due to prompt caching, which has real implications for multi-agent architectures.

**Anthropic blocks OpenClaw from subscriptions.** On April 4, Anthropic [cut off third-party agent frameworks](https://techcrunch.com/2026/04/04/anthropic-says-claude-code-subscribers-will-need-to-pay-extra-for-openclaw-support/) from Claude Pro and Max plans. The numbers tell the story: testing by c't 3003 found a single day of OpenClaw usage on Opus consumed [\$109.55 in tokens](https://thenextweb.com/news/anthropic-openclaw-claude-subscription-ban-cost), while Anthropic benchmarks average daily Claude Code cost at \$6. An estimated 135,000 active OpenClaw instances are affected, with roughly 60% running on subscription credits.

OpenClaw creator Peter Steinberger, who [left for OpenAI in February](https://venturebeat.com/technology/anthropic-cuts-off-the-ability-to-use-claude-subscriptions-with-openclaw-and), said he and board member Dave Morin "tried to talk sense into Anthropic" but could only delay the pricing change by a week. His observation: "Funny how timings match up, first they copy some popular features into their closed harness, then they lock out open source." Two weeks before the cutoff, Anthropic had shipped Claude Code Channels, adding the exact Discord and Telegram integration that made OpenClaw popular.

**Claude Code keeps shipping.** Three releases this week: [v2.1.90](https://github.com/anthropics/claude-code/releases) added interactive feature lessons, [v2.1.91](https://github.com/anthropics/claude-code/releases) expanded MCP tool result persistence to 500K chars, and [v2.1.92](https://github.com/anthropics/claude-code/releases) brought a Bedrock setup wizard and 60% faster Write tool diffs. The "Claude Code is [unusable for complex engineering](https://github.com/anthropics/claude-code/issues/42796)" GitHub issue (1012 HN points) suggests a gap between rapid feature shipping and reliability on hard tasks.

On the other hand, Claude Code [found a 23-year-old Linux kernel vulnerability](https://mtlynch.io/claude-code-found-linux-vulnerability/) during a coding session, and separately [wrote a complete FreeBSD remote kernel RCE](https://github.com/califio). Simon Willison [analyzed](https://simonwillison.net/2026/Apr/3/vulnerability-research-is-cooked/) how coding agents are changing vulnerability research. Linux kernel maintainers [report](https://simonwillison.net/2026/Apr/3/willy-tarreau/) a surge from low-quality AI submissions to high-volume legitimate security reports requiring substantial review time.

**GitHub Copilot adds fleet mode and rubber duck.** GitHub shipped [`/fleet`](https://github.blog/ai-and-ml/github-copilot/run-multiple-agents-at-once-with-fleet-in-copilot-cli/) for parallel agent execution in Copilot CLI, and a ["Rubber Duck" feature](https://github.blog/ai-and-ml/github-copilot/github-copilot-cli-combines-model-families-for-a-second-opinion/) that queries different model families to give second opinions on code. Windsurf launched an [Adaptive model router](https://windsurf.com/blog/windsurf-adaptive) that picks the best model per task and removed daily limits for Max plan users.

**The vibe coding backlash is real.** Three high-engagement posts converged on the same message. Bram Cohen (BitTorrent creator) [called vibe coding "insane"](https://bramcohen.com/p/the-cult-of-vibe-coding-is-insane), arguing that deliberately avoiding code review is irresponsible. A [thoughtful essay](https://ergosphere.blog/posts/the-machines-are-fine/) (960 HN points) warned about "comfortable drift toward not understanding what you're doing." And Lalit Maganti's [build report](https://lalitm.com/post/building-syntaqlite-ai/) described scrapping an entire vibe-coded project and starting over with a structured approach treating AI as "autocomplete on steroids."

Sebastian Raschka's [breakdown of coding agent components](https://magazine.sebastianraschka.com/p/components-of-a-coding-agent) offered a useful counterpoint: practical agent performance comes more from the harness layer (prompt caching, context reduction, structured memory) than from model selection. This matches what the Claude Code leak revealed.

## Web development & frameworks

**Cloudflare launches EmDash, a WordPress competitor built on Astro.** [EmDash](https://blog.cloudflare.com/emdash-wordpress/) is a serverless CMS written entirely in TypeScript, built on Astro 6.0. The pitch: 96% of WordPress vulnerabilities come from plugins, so EmDash sandboxes each plugin in its own Worker isolate. It includes native passkey auth, x402 protocol for internet-native payments (including charging AI agents for content access), and a built-in MCP server for agent management.

Matt Mullenweg [responded critically](https://ma.tt/2026/04/emdash-feedback/): "Don't claim to be our spiritual successor without understanding our spirit." Fair point. EmDash solves infrastructure problems that matter to developers but not to the restaurant owners and bloggers who make up WordPress's actual user base. The sandboxed plugin architecture only works on Cloudflare, and there's no ecosystem yet. It's a v0.1.0 developer preview, and that matters.

**Mintlify replaces RAG with a virtual filesystem.** [ChromaFs](https://www.mintlify.com/blog/how-we-built-a-virtual-filesystem-for-our-assistant) intercepts UNIX commands and translates them into Chroma vector database queries, giving AI assistants a familiar filesystem interface to navigate documentation. Session creation dropped from 46 seconds to 100ms, and the annual \$70K sandbox cost dropped to zero marginal cost per conversation. At 850K monthly conversations, that's significant. Built on Vercel Labs' just-bash, a TypeScript reimplementation of bash.

**Cloudflare on caching for the AI era.** Over [10 billion AI bot requests per week](https://blog.cloudflare.com/rethinking-cache-ai-humans/) are forcing Cloudflare to rethink cache systems for mixed AI and human traffic. The challenge: AI crawlers and agents have different access patterns, content freshness needs, and volume profiles than human browsers.

## Industry & business

**The New Yorker published a brutal Altman profile.** The [12,000-word investigation](https://www.newyorker.com/magazine/2026/04/13/sam-altman-may-control-our-future-can-he-be-trusted) by Ronan Farrow and Andrew Marantz, based on hundreds of pages of internal documents including memos from Ilya Sutskever and notes from Dario Amodei, alleges that OpenAI systematically abandoned its safety-first mission. One board member called Altman a "sociopath" who is "unconstrained by truth." The promised superalignment team reportedly got 1-2% of compute on the oldest hardware instead of the pledged 20%. When asked to speak with researchers working on existential safety, an OpenAI rep seemed confused: "That's not, like, a thing."

**Supply chain attacks hit the JavaScript ecosystem hard.** The [axios compromise](https://thehackernews.com/2026/03/axios-supply-chain-attack-pushes-cross.html), attributed by Google's Threat Intelligence Group to North Korean group UNC1069, affected a package with 100 million weekly downloads. The attacker socially engineered a maintainer through a fake Slack workspace and Teams meeting, then published two backdoored versions containing a cross-platform RAT within a 39-minute window. The malware self-destructs after execution, leaving no trace in node\_modules. Combined with a [LiteLLM compromise](https://news.ycombinator.com) the same week, it's a rough stretch for npm trust.

**OWASP published its Top 10 for Agentic Applications.** The [2026 list](https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026/) introduces the concept of "Least Agency": autonomy is a feature that should be earned, not a default setting. The standout entry is ASI06, Human-Agent Trust Exploitation, where agents fabricate plausible audit rationales to get humans to approve risky changes. Microsoft, NVIDIA, and AWS already reference the framework.

**LinkedIn caught enumerating browser extensions.** The [highest-engagement HN story of the week](https://browsergate.eu) (1889 points) caught LinkedIn scanning installed browser extensions, raising privacy and security concerns for developers.

## Interesting GitHub repositories

* [phuryn/pm-skills](https://github.com/phuryn/pm-skills/) - 65 PM skills and 36 chained workflows packed into 8 plugins for Claude Code, Gemini CLI, Cursor, and others. Encodes frameworks from Teresa Torres, Marty Cagan, and Alberto Savoia into reusable skill files that chain into end-to-end workflows like `/discover`, `/strategy`, and `/write-prd`. 9.6k stars. Worth watching because it applies the agent skill pattern (which we've seen spread from coding to note-taking with Obsidian Skills) to product management, a domain where structured thinking matters more than raw output speed.

* [NousResearch/hermes-agent](https://github.com/NousResearch/hermes-agent) - Autonomous AI agent from NousResearch, trending #1 in Python with 9.6k stars. NousResearch has a strong track record with open models (Hermes series), and this signals their push into the agent space.

* [Yeachan-Heo/oh-my-claudecode](https://github.com/Yeachan-Heo/oh-my-claudecode) - Teams-first multi-agent orchestration for Claude Code. 7.8k stars this week. Useful for teams wanting parallel agent workflows on top of Claude Code.

* [kepano/obsidian-skills](https://github.com/kepano/obsidian-skills) - Agent skills for Obsidian from the app's creator. Shows agent skill systems becoming a pattern beyond coding tools, extending into note-taking and knowledge management.

* [siddharthvaddem/openscreen](https://github.com/siddharthvaddem/openscreen) - Open-source demo creation tool with 14.4k stars in a week. A free alternative to Loom/Screen Studio for product demos, no watermarks.

* [microsoft/VibeVoice](https://github.com/microsoft/VibeVoice) - Open-source voice AI from Microsoft. 8.4k stars. Significant because Microsoft rarely open-sources frontier voice models.

* [KeygraphHQ/shannon](https://github.com/KeygraphHQ/shannon) - Autonomous AI pentester for web applications and APIs. Relevant given this week's supply chain attacks and the broader conversation about AI in security research.

* [tobi/qmd](https://github.com/tobi/qmd) - Mini CLI search engine for docs and knowledge bases from Shopify CEO Tobi Lutke. Simple but useful for navigating large documentation sets.

* [google-ai-edge/LiteRT-LM](https://github.com/google-ai-edge/LiteRT-LM) - Google's lightweight runtime for running LLMs on edge devices. Complements the Gemma 4 edge story.

## Quick bits

* **Armin Ronacher** wrote about [durable execution using only Postgres](https://lucumr.pocoo.org/2026/4/4/absurd-in-production/), no additional infrastructure needed. Practical and counterintuitive.
* **Freestyle** [launched sandboxes for coding agents](https://www.freestyle.sh/) with full Linux VMs that start in under 700ms, live forking, and bidirectional GitHub sync.
* An AWS engineer [reported PostgreSQL performance halved](https://www.phoronix.com/news/Linux-7.0-AWS-PostgreSQL-Drop) by Linux 7.0, with "no easy fix."
* **Mistral** described how building their [Spaces CLI](https://mistral.ai/news/spaces) for both humans and AI agents led to better design practices for all users.
* [Caveman](https://github.com/JuliusBrussee/caveman) (869 HN points) optimizes LLM token usage by compressing prompts. The name says it all: "why use many token when few token do trick."
* **Gergely Orosz** explored [inference engineering](https://newsletter.pragmaticengineer.com/p/what-is-inference-engineering), a field many engineers use daily but rarely discuss, and noted [industry leaders returning to coding](https://newsletter.pragmaticengineer.com/p/the-pulse-industry-leaders-return) with AI tools.
* **AMD** released [Lemonade](https://lemonade-server.ai), an open-source local LLM server using GPU and NPU. Hardware vendors are all-in on local inference.
* **Nate B Jones** published a useful [six-layer framework](https://www.youtube.com/watch?v=7HP1jFJ9W1c) for the emerging agent infrastructure stack, noting that orchestration is the biggest gap and the biggest opportunity. Gartner reported a 1,445% surge in multi-agent system inquiries.
* An [AI singer occupied eleven spots on the iTunes singles chart](https://www.showbiz411.com/2026/04/05/itunes-takeover-by-fake-ai-singer-eddie-dalton-now-occupies-eleven-spots-on-chart-despite-not-being-human-or-real-exclusive) despite not being human. The content flooding problem is spreading.
* A [former Azure engineer detailed](https://isolveproblems.substack.com/p/how-microsoft-vaporized-a-trillion) the decisions that "vaporized a trillion" in cloud market value. Highest-engagement cloud infrastructure post of the week at 1277 HN points.
* HuggingFace published [TRL v1.0](https://huggingface.co/blog/trl-v1), a major release of their post-training reinforcement learning library.
* Anthropic signed an [AI safety MOU with the Australian government](https://www.anthropic.com/news/australia-MOU) including AUD\$3 million for research partnerships.

## Sources

* [Cursor 3 launch post](https://cursor.com/blog/cursor-3)
* [Cursor warp decode research](https://www.cursor.com/blog/warp-decode)
* [Cursor 3 - TechCrunch](https://techcrunch.com/2026/03/05/cursor-is-rolling-out-a-new-system-for-agentic-coding/)
* [Fireship: Cursor ditches VS Code](https://www.youtube.com/watch?v=JSuS-zXMVwE)
* [Google Gemma 4](https://deepmind.google/models/gemma/gemma-4/)
* [Google Gemma 4 blog](https://blog.google/innovation-and-ai/technology/developers-tools/gemma-4/)
* [Gemma 4 Apache 2.0 analysis](https://www.revolutioninai.com/2026/04/gemma-4-apache-license-benchmark-open-model-2026.html)
* [Simon Willison on Gemma 4](https://simonwillison.net/2026/Apr/2/gemma-4/)
* [Latent Space: Gemma 4 crosses 2M downloads](https://www.latent.space/p/ainews-gemma-4-crosses-2-million)
* [PrismML 1-Bit Bonsai](https://prismml.com/news/bonsai-8b)
* [Claude Code leak - VentureBeat](https://venturebeat.com/technology/claude-codes-source-code-appears-to-have-leaked-heres-what-we-know/)
* [Claude Code leak - The Hacker News](https://thehackernews.com/2026/04/claude-code-tleaked-via-npm-packaging.html)
* [Fireship: Claude source code leak](https://www.youtube.com/watch?v=mBHRPeg8zPU)
* [NeetCode: Claude Code leak analysis](https://www.youtube.com/watch?v=LCjkmbHOtys)
* [Anthropic blocks OpenClaw - TechCrunch](https://techcrunch.com/2026/04/04/anthropic-says-claude-code-subscribers-will-need-to-pay-extra-for-openclaw-support/)
* [OpenClaw subscription impact - The Register](https://www.theregister.com/2026/04/06/anthropic_closes_door_on_subscription/)
* [Claude Code changelog](https://github.com/anthropics/claude-code/releases)
* [Claude Code unusable for complex tasks](https://github.com/anthropics/claude-code/issues/42796)
* [Claude Code finds Linux vulnerability](https://mtlynch.io/claude-code-found-linux-vulnerability/)
* [Simon Willison on vulnerability research](https://simonwillison.net/2026/Apr/3/vulnerability-research-is-cooked/)
* [Simon Willison on axios supply chain attack](https://simonwillison.net/2026/Apr/3/supply-chain-social-engineering/)
* [GitHub Copilot /fleet](https://github.blog/ai-and-ml/github-copilot/run-multiple-agents-at-once-with-fleet-in-copilot-cli/)
* [GitHub Copilot Rubber Duck](https://github.blog/ai-and-ml/github-copilot/github-copilot-cli-combines-model-families-for-a-second-opinion/)
* [Windsurf Adaptive](https://windsurf.com/blog/windsurf-adaptive)
* [Bram Cohen on vibe coding](https://bramcohen.com/p/the-cult-of-vibe-coding-is-insane)
* [Comfortable drift essay](https://ergosphere.blog/posts/the-machines-are-fine/)
* [Lalit Maganti: Building with AI](https://lalitm.com/post/building-syntaqlite-ai/)
* [Sebastian Raschka: Components of a coding agent](https://magazine.sebastianraschka.com/p/components-of-a-coding-agent)
* [Cloudflare EmDash](https://blog.cloudflare.com/emdash-wordpress/)
* [Matt Mullenweg on EmDash](https://ma.tt/2026/04/emdash-feedback/)
* [Mintlify ChromaFs](https://www.mintlify.com/blog/how-we-built-a-virtual-filesystem-for-our-assistant)
* [Cloudflare: Rethinking cache for AI](https://blog.cloudflare.com/rethinking-cache-ai-humans/)
* [New Yorker: Sam Altman profile](https://www.newyorker.com/magazine/2026/04/13/sam-altman-may-control-our-future-can-he-be-trusted)
* [Axios supply chain attack - The Hacker News](https://thehackernews.com/2026/03/axios-supply-chain-attack-pushes-cross.html)
* [Axios attack attribution - Google Cloud](https://cloud.google.com/blog/topics/threat-intelligence/north-korea-threat-actor-targets-axios-npm-package)
* [Axios social engineering details](https://thehackernews.com/2026/04/unc1069-social-engineering-of-axios.html)
* [OWASP Top 10 for Agentic Applications](https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026/)
* [LinkedIn browser extension scanning](https://browsergate.eu)
* [Qwen3.6-Plus](https://qwen.ai/blog?id=qwen3.6)
* [Self-distillation for code generation](https://arxiv.org/abs/2604.01193)
* [Armin Ronacher: Absurd in production](https://lucumr.pocoo.org/2026/4/4/absurd-in-production/)
* [Freestyle agent sandboxes](https://www.freestyle.sh/)
* [Mistral Spaces CLI](https://mistral.ai/news/spaces)
* [Nate B Jones: Agent infrastructure stack](https://www.youtube.com/watch?v=7HP1jFJ9W1c)
* [Nate B Jones: Agent output vs review bottleneck](https://www.youtube.com/watch?v=kVPVmz0qJvY)
* [Web Dev Cody: Cursor 3 walkthrough](https://www.youtube.com/watch?v=4DrVf07wlq8)
* [Gergely Orosz: Inference engineering](https://newsletter.pragmaticengineer.com/p/what-is-inference-engineering)
* [Ben's Bites: Claude Code leak](https://www.bensbites.com/p/inside-the-leaked-claude-code-files)
* [HuggingFace: TRL v1.0](https://huggingface.co/blog/trl-v1)
* [Anthropic: Emotion concepts in LLMs](https://www.anthropic.com/research/emotion-concepts-function)
* [Anthropic: Australian government MOU](https://www.anthropic.com/news/australia-MOU)
* [Azure trust erosion](https://isolveproblems.substack.com/p/how-microsoft-vaporized-a-trillion)
* [PostgreSQL perf regression in Linux 7.0](https://www.phoronix.com/news/Linux-7.0-AWS-PostgreSQL-Drop)
* [AMD Lemonade](https://lemonade-server.ai)
* [Caveman token compression](https://github.com/JuliusBrussee/caveman)


# AI Weekly Review - Apr. 13th 2026
Source: https://developer.upsun.com/posts/ai/aiweekly-2026-04-13

A press, Youtube and Github review of everything AI


<PostMeta />

> Claude Mythos Preview landed this week with 93.9% on SWE-bench and thousands of discovered zero-day vulnerabilities, but Anthropic isn't letting anyone use it. Meta doubled down on inference infrastructure with a \$21 billion CoreWeave expansion, bringing total commitments to \$35 billion. OpenClaw shipped native Codex integration and Active Memory. Mario Zechner made the case for minimal agent harnesses at Tessel, and Nate B Jones mapped five durable verticals where builders can survive the AI middleware collapse. The theme: the tools keep getting more powerful, but the hard questions are shifting from "can AI do this?" to "who gets to use it, who pays, and who's liable?"

## Highlight of the week

**Claude Mythos Preview: Anthropic's most powerful model exists, and you can't have it.** Anthropic [announced Claude Mythos Preview](https://red.anthropic.com/2026/mythos-preview/) on April 7, a frontier model that scores 93.9% on SWE-bench verified (up from Opus 4.6's 80.8%) and represents a genuine step change in code understanding. But the headline isn't the benchmark. It's what Anthropic did with the model before announcing it.

Over several weeks, Anthropic used Mythos to [scan major operating systems, browsers, and widely-used software](https://www.infoq.com/news/2026/04/anthropic-claude-mythos/) for vulnerabilities. The result: thousands of previously unknown zero-days, including a 27-year-old bug in OpenBSD and a 16-year-old flaw in FFmpeg's H.264 codec. Through [Project Glasswing](https://anthropic.com/glasswing), they're coordinating responsible disclosure with a consortium of tech companies rather than releasing the model publicly.

This is unprecedented. An AI lab discovers that its model is too good at finding vulnerabilities, so instead of shipping it, it uses the model to fix the internet first. The [risk report](https://anthropic.com/claude-mythos-preview-risk-report) is worth reading. Anthropic is explicitly saying: "We do not plan to make Claude Mythos Preview generally available."

Whether you read this as responsible stewardship or competitive gatekeeping depends on your priors. But the practical implication is clear: the gap between what frontier labs can do internally and what they release publicly is widening. Coding agents capable of autonomous vulnerability research at scale change the security landscape in ways we haven't fully processed yet.

## Models and research

**Google's Gemma 4 continues to dominate the open model conversation.** [Released under Apache 2.0](https://deepmind.google/models/gemma/gemma-4/) the previous week, Gemma 4 has now crossed 2 million downloads and is settling into production stacks. The 31B dense model's numbers bear repeating: LiveCodeBench jumped from 29.1% to 80.0%, AIME math from 20.8% to 89.2%. Google [announced this week](https://android-developers.googleblog.com/2026/04/AI-Core-Developer-Preview.html) that Gemma 4 can run fully offline on Android via AICore, and the edge models (E2B and E4B) are already running on Raspberry Pi hardware. The 256K context window, native vision and audio, and 140+ language support make this the most practically useful open model family released to date.

**GPT-5.4 is now a month old, and the picture is clearer.** OpenAI's [March 5 release](https://openai.com/index/introducing-gpt-5-4/) brought a 1-million-token context window, native computer use, and tool search. On OSWorld-V, it scored 75%, slightly above the human baseline of 72.4%. A month in, the most interesting development is how GPT-5.4 and Codex are converging: [Codex now supports](https://developers.openai.com/codex/subagents) the full 1M context experimentally, and sub-agents use readable path-based addresses. The plugin system has matured into a first-class workflow where Codex syncs product-scoped plugins at startup.

**Yann LeCun's AMI raises \$1.03B and the debate over LLM limits heats up.** LeCun's Paris-based startup [closed the largest European seed round ever](https://techcrunch.com/2026/03/09/yann-lecuns-ami-labs-raises-1-03-billion-to-build-world-models/) at a \$3.5B valuation, backed by Nvidia, Toyota, Samsung, Bezos Expeditions, and Temasek. The thesis: intelligence requires world models, not just language. AMI's March 2026 paper demonstrates a 15-million-parameter model trained on a single GPU in hours that learns physics from video, using JEPA (Joint Embedding Predictive Architecture) with a new regularizer called CIG that prevents representation collapse.

Two French-language pieces this week offered contrasting perspectives. [Grand Angle Nova](https://www.youtube.com/watch?v=P-wAr687qxg) laid out LeCun's vision enthusiastically: AI needs to move from generating to simulating, from predicting the next token to understanding causality. The world model is 48x faster at planning physical actions than generative approaches and uses 200x fewer tokens. The [IA Clash podcast](https://www.youtube.com/watch?v=26QzS9HF60Y) offered a sharper counterpoint, noting that LeCun's theoretical arguments against LLMs keep getting contradicted by empirical results. His claim that autoregressive generation diverges exponentially assumes token errors are independent, which they demonstrably are not. LLMs keep getting longer and more accurate simultaneously. Francois Chollet's critique of LeCun's data bandwidth argument is devastating: blind people are equally intelligent despite processing far less sensory data, because intelligence depends on the complexity of the environment, not raw input bandwidth.

My assessment: LeCun may be right that world models unlock capabilities LLMs can't reach, but his specific arguments for why LLMs are fundamentally limited have been wrong repeatedly. The \$1.03B bet will be fascinating to watch play out.

**AlphaEvolve is quietly significant.** Google DeepMind's [coding agent](https://deepmind.google/blog/alphaevolve-a-gemini-powered-coding-agent-for-designing-advanced-algorithms/) pairs Gemini with evolutionary algorithms to optimize real production code. It's been running inside Google for over a year, recovering 0.7% of global compute (a meaningful number at Google's scale) and improving a core Gemini training kernel by 23%. The [AlphaEvolve Service API](https://cloud.google.com/blog/products/ai-machine-learning/alphaevolve-on-google-cloud) is now available through early access on Google Cloud.

## Coding agents and dev tools

**Mario Zechner's talk at Tessel is the best critique of coding agent bloat I've seen this year.** The libGDX creator and builder of [Pi](https://shittycodingagent.ai/) (the minimal agent that powers OpenClaw) [spoke at Tessel](https://www.youtube.com/watch?v=Dli5slNaJu0) about why he built his own coding harness after trying Claude Code, OpenCode, Codex CLI, and Amp. His observations land because they're specific.

On Claude Code: "It does so many things that you actually probably ever use like 5% of what it offers." On OpenCode's session compaction pruning all tool results before the last 40K tokens: "What does this do to your prompt cache? Lost." On LSP feedback mid-edit: injecting compiler errors after each individual edit (before the agent is done editing) causes models to panic and abandon their plan. The fix is obvious but most harnesses get it wrong: lint only when the agent thinks it's done.

His sharpest insight comes from TerminalBench results. Terminus, which gives the model nothing but a tmux session and keystrokes, performs near the top of the leaderboard. Pi, with just four tools (read, write, edit, bash), sits right behind it. This suggests that most of the features in mainstream coding agents (sub-agents, MCP, plan mode, background bash, built-in todos) aren't necessary for raw model performance. Pi's 600-line TUI and shortest system prompt of any major agent are a deliberate bet that extensibility beats features.

Two theses from the talk worth internalizing: nobody knows what the ideal coding agent looks like yet, and we need agents that can self-modify so we can experiment faster. The community extensions prove the point. Pi Annotate lets you annotate a website and feed visual feedback to the agent. File Switch opens modified files inline. Pi Messenger creates a chat room between multiple Pi agents. None of it is built-in. All of it took hours, not weeks.

He also raised a problem that's getting worse: AI-generated open source spam. His solution is a human verification gate. Write a short issue introducing yourself (anything longer than one screen is probably "clanker slop"), get added to a contributor file, then you can submit PRs. Mitchell Hashimoto built this into a tool called Vouch. Crude, but it works.

**OpenClaw 2026.4.10 ships native Codex and Active Memory.** The [April 11 release](https://github.com/openclaw/openclaw/releases/tag/v2026.4.10) bundles a Codex provider (so `codex/gpt-*` models use Codex-managed auth and threads while `openai/gpt-*` stays on the normal provider path), an Active Memory plugin that runs a memory sub-agent before each reply to pull in relevant context automatically, local MLX speech for Talk Mode on macOS, and a batch of security hardening across browser navigation, sandbox behavior, and plugin install scanning. The `exec-policy` CLI adds show, preset, and set subcommands for managing tool approval configurations.

**OpenHarness launches as an open-source agent harness from HKU.** [OpenHarness](https://github.com/HKUDS/OpenHarness) is a Python implementation of the Claude Code architecture pattern: 43 tools, skill loading from markdown files, multi-agent coordination, and a permission system with path-level rules. What makes it interesting is compatibility: it works with Claude, OpenAI, Copilot, Codex, Moonshot/Kimi, and GLM providers. The bundled personal agent "ohmo" connects to Slack, Telegram, Discord, and Feishu, running on your existing Claude Code or Codex subscription. At v0.1.6, it's early, but the auto-compaction feature (preserving task state across context compression for multi-day sessions) addresses a real pain point.

**The Codex cross-provider plugin is worth noting.** A [Codex plugin for Claude Code](https://www.mindstudio.ai/blog/openai-codex-plugin-claude-code-cross-provider-review-2) lets you run Codex as a second-opinion agent inside a Claude Code session. Cross-provider code review without switching terminals. The walls between coding agent ecosystems are getting thinner.

## Web development and frameworks

**Browsers are becoming AI workspaces, whether developers want it or not.** Samsung [announced](https://news.samsung.com/global/samsung-takes-its-browser-beyond-mobile-extending-agentic-ai-across-devices) it's expanding its browser with agentic AI across devices: natural-language history search ("that smartwatch I looked at last week") and multi-tab summarization. Chrome ships with built-in Gemini 3 and "Auto Browse." Edge has Copilot agent modes. Brave has Leo AI. Opera has Aria/Neon agents.

For web developers, this creates two practical concerns. First, security: when browser copilots can "see" everything on the page, connecting them to internal repos or admin consoles becomes a data leak vector. Teams need to revisit what AI-enhanced browsers can access. Second, discoverability: AI search engines and browser copilots are increasingly the first touchpoint for users, which means dev portals and documentation need to be structured for AI consumption from the start.

**The edge keeps getting more capable.** Between Gemma 4 running offline on phones, Cloudflare Workers getting memory-efficient image processing (the [sip](https://www.youtube.com/watch?v=obniDiLAuog) library), and Google's TurboQuant KV-cache compression making long-context inference cheaper, the boundary between "edge" and "cloud" AI keeps blurring. For frontend developers building AI features, the question is no longer if you can run inference locally, but when it makes sense to.

## Industry and business

**Meta's \$21 billion CoreWeave expansion is an inference bet.** [CNBC reported](https://www.cnbc.com/2026/04/09/meta-commits-to-spending-additional-21-billion-with-coreweave-.html) that Meta committed an additional \$21B to CoreWeave on April 9, bringing total contracts to \$35B through 2032. The deal runs on Nvidia Rubin systems and focuses specifically on inference, not training. Meta's capex guidance for 2026 sits at \$115-135B, nearly double 2025. The strategic signal: hyperscaler-independent GPU clouds can win very large, long-term contracts, and inference is where the compute demand is shifting.

**The AI app builder middleware trap is playing out in real time.** Nate B Jones published a [sharp analysis](https://www.youtube.com/watch?v=ib2m9HVX7as) of why companies like Lovable (\$330M raised, \$6.6B valuation, 100K new projects per day) are functionally thin wrappers around base models with fragile moats. His framework identifies five durable verticals that AI can't commoditize: trust (Stripe, Shopify), context (Notion, Salesforce, Snowflake), distribution (Google, Apple, Amazon), taste (human editorial judgment and orchestration quality), and liability (regulated industries selling accountability). The key insight: if a better model makes your product obsolete, change your positioning now.

Keith Rabois reinforced this [on Lenny's Podcast](https://www.youtube.com/watch?v=xCd9ykretlg), noting that the number one consumer of AI tokens at two major companies he advises is the CMO, not engineering. His take on PMs: "The idea of a PM makes no sense in the future. The skill is more like being a CEO now, which is what are we building and why?" Shopify hasn't allowed PowerPoint product presentations for two years; every pitch must be a working demo. Design and code are merging, and the premium shifts to business acumen over technical execution.

**OpenAI's advertising ambitions raise questions.** Marketing analysts [cite internal projections](https://www.marketingprofs.com/opinions/2026/54530/ai-update-april-10-2026-ai-news-and-views-from-the-past-week) of \$2.5B in ad revenue for 2026 with long-range targets of \$100B annually. If ChatGPT becomes an advertising platform, the incentive alignment between model helpfulness and ad revenue deserves scrutiny.

**AI policy is fragmenting and consolidating simultaneously.** The White House [released a National Policy Framework](https://www.hklaw.com/en/insights/publications/2026/03/white-house-releases-a-national-policy-framework-for-artificial) for AI pushing federal preemption, while Colorado's SB24-205 (high-risk AI systems in employment, housing, healthcare) [remains on track](https://www.linkedin.com/pulse/ai-regulation-april-2026-what-you-need-know-vinnie-fisher-em60f) for June 30. California has multiple sector-specific AI bills in committee. The FTC reversed a consent order against Rytr, signaling lighter federal enforcement. For builders: high-risk domains will face stricter obligations regardless of federal direction.

## Interesting GitHub repositories

* [**HKUDS/OpenHarness**](https://github.com/HKUDS/OpenHarness) - Open-source Python agent harness with 43 tools, skill loading, multi-agent coordination, and multi-provider support (Claude, OpenAI, Copilot, Codex, Kimi, GLM). The "ohmo" personal agent connects to chat platforms and runs on existing subscriptions. Worth watching for researchers who want to understand how production agents work under the hood.

* [**3dsvg**](https://www.youtube.com/watch?v=obniDiLAuog) - Turns any 2D SVG into an interactive 3D component in the browser. Pick material presets (glass, chrome, holographic), add animations, export as 4K PNG or 60fps MP4 using FFmpeg WASM locally. Outputs clean React Three Fiber JSX.

* [**debug-agent**](https://www.youtube.com/watch?v=obniDiLAuog) - A Claude Code/Cursor skill that changes the debugging approach entirely. Instead of guessing at fixes from static code, it injects lightweight NDJSON logging, asks you to reproduce the bug, analyzes live runtime logs, and only writes a fix when it has evidence. Verify-then-fix instead of guess-and-pray.

* [**llmwiki**](https://www.youtube.com/watch?v=obniDiLAuog) - Implementation of Karpathy's argument that RAG is broken because it retrieves the same raw chunks every time. Upload PDFs, connect Claude via MCP, and it synthesizes encyclopedia-style articles, flags contradictions, and updates cross-references across files. Persistent knowledge base instead of stateless retrieval.

* [**helixent**](https://www.youtube.com/watch?v=obniDiLAuog) - Lightweight TypeScript library built on Bun for React-style agent loops: reasoning, planning, executing. Minimal building blocks for custom agent loops without orchestration framework bloat.

* [**boxsh**](https://www.youtube.com/watch?v=obniDiLAuog) - Sandboxed shell designed for AI agents via concurrent JSON-line RPC. Linux namespace isolation traps every command so your agent can run builds and install packages without touching the host. Addresses a genuine security gap in agent tooling.

* [**hypatia**](https://www.youtube.com/watch?v=obniDiLAuog) - AI memory system built in Rust using SQLite FTS5 and DuckDB with a custom JSON query language. No external models, no vector embeddings. A contrarian bet that structured search beats fuzzy similarity for agent memory.

* [**liteparse\_samples**](https://www.youtube.com/watch?v=obniDiLAuog) - Verification layer for AI document extraction. Every extracted fact includes an interactive link opening the source document with a bounding box around the exact text. Essential for legal, financial, and academic workflows where hallucinated citations break trust.

* [**sip**](https://www.youtube.com/watch?v=obniDiLAuog) - Memory-efficient image processing library built for Cloudflare Workers constraints. Resize and optimize on the edge without bouncing to a heavy backend.

## Quick bits

* **MCP crossed 97 million installs** in March 2026, [4,750% growth](https://www.arturmarkus.com/anthropics-model-context-protocol-hits-97-million-installs-on-march-25-mcp-transitions-from-experimental-to-foundation-layer-for-agentic-ai/) in 16 months. Every major AI provider now ships MCP-compatible tooling. The protocol war is over.
* **Google's TurboQuant** KV-cache compression (ICLR 2026) combines PolarQuant rotations with quantized Johnson-Lindenstrauss embeddings to shrink memory for long-context inference. Cheaper long-context is getting real.
* **Meta laid off 200 more workers** while planning \$115-135B in AI capex. The "invest in infrastructure, cut headcount" pattern continues.
* **OpenAI launched a Safety Fellowship** for independent AI safety research, running September 2026 through February 2027.
* **France accelerates digital sovereignty**: the state is [reducing extra-European technology dependencies](https://s3.eu-west-par.io.cloud.ovh.net/numerique-gouv-website/numerique-gouv-website/documents/CP_SouveraineteNumeriqueEtat.pdf) across government agencies, context for European AI infrastructure decisions.
* **Systems thinking for CLAUDE.md**: stop writing your agent config like a README. Write it like a failure log. Where is the agent repeating mistakes? Where are you losing time re-explaining context? Where can you constrain upfront? Your AGENTS.md should encode your failure modes, not your folder structure.
* **GLM-5.1 from Zhipu AI** is pitched for long-horizon autonomous engineering, supporting thousands of tool calls over hours-long traces. Open models competing on agent endurance, not just benchmarks.
* **Microsoft's Agent Governance Toolkit** (open-source) simplifies compliance for autonomous agents under the EU AI Act, HIPAA, and SOC 2.

## Sources

* [Claude Mythos Preview announcement](https://red.anthropic.com/2026/mythos-preview/)
* [Claude Mythos Preview - InfoQ](https://www.infoq.com/news/2026/04/anthropic-claude-mythos/)
* [Claude Mythos risk report](https://anthropic.com/claude-mythos-preview-risk-report)
* [Claude Mythos - NxCode analysis](https://www.nxcode.io/resources/news/claude-mythos-preview-anthropic-most-powerful-model-2026)
* [Project Glasswing](https://anthropic.com/glasswing)
* [Gemma 4 - Google DeepMind](https://deepmind.google/models/gemma/gemma-4/)
* [Gemma 4 blog - Google](https://blog.google/innovation-and-ai/technology/developers-tools/gemma-4/)
* [Gemma 4 on Android AICore](https://android-developers.googleblog.com/2026/04/AI-Core-Developer-Preview.html)
* [Gemma 4 - Google Cloud](https://cloud.google.com/blog/products/ai-machine-learning/gemma-4-available-on-google-cloud)
* [GPT-5.4 introduction](https://openai.com/index/introducing-gpt-5-4/)
* [GPT-5.4 - DataCamp](https://www.datacamp.com/blog/gpt-5-4)
* [Codex subagents](https://developers.openai.com/codex/subagents)
* [AMI Labs raises \$1.03B - TechCrunch](https://techcrunch.com/2026/03/09/yann-lecuns-ami-labs-raises-1-03-billion-to-build-world-models/)
* [AMI Labs - MIT Technology Review](https://www.technologyreview.com/2026/01/22/1131661/yann-lecuns-new-venture-ami-labs/)
* [IA Clash: Yann LeCun critique](https://www.youtube.com/watch?v=26QzS9HF60Y)
* [Grand Angle Nova: LeCun world model](https://www.youtube.com/watch?v=P-wAr687qxg)
* [AlphaEvolve - Google DeepMind](https://deepmind.google/blog/alphaevolve-a-gemini-powered-coding-agent-for-designing-advanced-algorithms/)
* [AlphaEvolve on Google Cloud](https://cloud.google.com/blog/products/ai-machine-learning/alphaevolve-on-google-cloud)
* [Mario Zechner: Pi talk at Tessel](https://www.youtube.com/watch?v=Dli5slNaJu0)
* [Pi coding agent](https://shittycodingagent.ai/)
* [Armin Ronacher on Pi](https://lucumr.pocoo.org/2026/1/31/pi/)
* [OpenClaw 2026.4.10 release](https://github.com/openclaw/openclaw/releases/tag/v2026.4.10)
* [OpenClaw changelog analysis](https://www.openclawplaybook.ai/blog/openclaw-2026-4-10-release-codex-active-memory/)
* [OpenHarness - GitHub](https://github.com/HKUDS/OpenHarness)
* [OpenHarness - Knightli analysis](https://www.knightli.com/en/2026/04/12/openharness-basic-functions/)
* [Codex plugin for Claude Code](https://www.mindstudio.ai/blog/openai-codex-plugin-claude-code-cross-provider-review-2)
* [Meta CoreWeave \$21B - CNBC](https://www.cnbc.com/2026/04/09/meta-commits-to-spending-additional-21-billion-with-coreweave-.html)
* [Meta CoreWeave - Bloomberg](https://www.bloomberg.com/news/articles/2026-04-09/coreweave-expands-meta-deal-for-ai-computing-to-21-billion)
* [CoreWeave investor announcement](https://investors.coreweave.com/news/news-details/2026/CoreWeave-and-Meta-Announce-21-Billion-Expanded-AI-Infrastructure-Agreement/default.aspx)
* [Nate B Jones: 5 safe places to build](https://www.youtube.com/watch?v=ib2m9HVX7as)
* [Keith Rabois on Lenny's Podcast](https://www.youtube.com/watch?v=xCd9ykretlg)
* [Cursor 3 launch](https://cursor.com/blog/cursor-3)
* [MCP 97 million installs](https://www.arturmarkus.com/anthropics-model-context-protocol-hits-97-million-installs-on-march-25-mcp-transitions-from-experimental-to-foundation-layer-for-agentic-ai/)
* [Samsung agentic browser](https://news.samsung.com/global/samsung-takes-its-browser-beyond-mobile-extending-agentic-ai-across-devices)
* [OpenAI advertising projections](https://www.marketingprofs.com/opinions/2026/54530/ai-update-april-10-2026-ai-news-and-views-from-the-past-week)
* [White House AI policy framework](https://www.hklaw.com/en/insights/publications/2026/03/white-house-releases-a-national-policy-framework-for-artificial)
* [Colorado AI Act update](https://www.linkedin.com/pulse/ai-regulation-april-2026-what-you-need-know-vinnie-fisher-em60f)
* [GitHub Trending Weekly #30](https://www.youtube.com/watch?v=obniDiLAuog)
* [Lovable Series B - TechCrunch](https://techcrunch.com/2025/12/18/vibe-coding-startup-lovable-raises-330m-at-a-6-6b-valuation/)
* [France digital sovereignty](https://s3.eu-west-par.io.cloud.ovh.net/numerique-gouv-website/numerique-gouv-website/documents/CP_SouveraineteNumeriqueEtat.pdf)


# AI Weekly Review - Apr. 27th 2026
Source: https://developer.upsun.com/posts/ai/aiweekly-2026-04-27

A press, Youtube and Github review of everything AI


<PostMeta />

> The week Anthropic became the most expensive AI company on Earth, DeepSeek proved US chip export controls have failed, and every major platform started rationing compute. Google committed up to \$40 billion in Anthropic at a \$350 billion valuation. Days later, Microsoft and OpenAI rewrote their partnership, ending exclusivity and freeing OpenAI to sell through AWS and Google Cloud. DeepSeek V4 shipped on Huawei chips, delivering near-frontier performance at a fraction of the cost. GitHub paused Copilot signups because agentic workflows are burning through compute faster than anyone budgeted for. And Cloudflare launched 20+ products in a single week, betting its entire platform on agents as the primary workload of the internet.

## Highlight of the week

### DeepSeek V4 ships on Huawei chips, and the export control thesis collapses

DeepSeek released [V4-Pro](https://api-docs.deepseek.com/news/news260424) (1.6 trillion parameters, 49 billion active) and V4-Flash (284 billion, 13 billion active) on Friday. Both feature million-token context windows. The benchmarks are strong: V4 trails GPT-5.4 and Gemini 3.1 Pro by what DeepSeek itself describes as "approximately three to six months." V4-Flash costs roughly [90x less per output token](https://fortune.com/2026/04/24/deepseek-v4-ai-model-price-performance-china-open-source/) than Claude Sonnet 4.6 while matching it on composite benchmarks.

The technical story matters, but the geopolitical story matters more. V4 is the first frontier model built entirely on Huawei Ascend 950 chips rather than NVIDIA hardware. DeepSeek's architectural innovations (a hybrid attention system cutting inference FLOPs by 73%, Engram Conditional Memory for O(1) knowledge retrieval) appear specifically designed to compensate for the performance gap between Huawei silicon and NVIDIA's H100/B200 lineup.

The timing was deliberate. DeepSeek launched V4 [hours after](https://www.tomshardware.com/tech-industry/artificial-intelligence/deepseek-launches-1-6-trillion-parameter-v4-on-huawei-chips-as-us-escalates-ai-theft-accusations) the White House accused Chinese AI firms of "industrial-scale campaigns" to distill capabilities from American models. The model ships under Apache 2.0, deployable anywhere, immediately.

For practitioners, V4-Flash at \$0.14 per million input tokens is the most aggressive price point at this capability level. If you're running high-volume inference workloads and can tolerate being a few months behind the frontier, V4-Flash changes your cost math overnight.

The broader implication: the US export control strategy assumed that denying NVIDIA chips would meaningfully slow Chinese AI development. V4 running on domestic silicon at near-frontier quality is the clearest evidence yet that this assumption was wrong.

## Models and research

### Anthropic's \$70 billion week and the Mythos question

Anthropic [raised up to \$40 billion from Google](https://www.cnbc.com/2026/04/24/google-to-invest-up-to-40-billion-in-anthropic-as-search-giant-spreads-its-ai-bets.html), days after [Amazon committed up to \$25 billion](https://www.anthropic.com/news/anthropic-amazon-compute). Run-rate revenue has crossed \$30 billion, up from \$9 billion at the end of 2025.

The Markman Capital analysis offers the sharpest framing: [Amazon's investment isn't a speculative equity bet](https://markmancapitalinsight.substack.com/p/amazons-33-billion-anthropic-deal). It's a capacity pre-commitment from a cloud vendor that already knows the demand can absorb it. Four bottlenecks constrain AI infrastructure growth: chip fabrication, power generation, data center construction (18-24 month lead times), and custom silicon cycles. Physical capacity, not capital, is the binding constraint.

Meanwhile, the [Claude Mythos preview](https://www.anthropic.com/glasswing) loomed over the week. Anthropic's unreleased frontier model identified thousands of zero-day vulnerabilities across every major OS and browser. It [autonomously exploited a 17-year-old FreeBSD RCE](https://red.anthropic.com/2026/mythos-preview/) that grants root via NFS. Felix Rizzleberg (Anthropic engineering lead) described Mythos on [the Matt Turk podcast](https://www.youtube.com/watch?v=9MEJ4syOVrQ) as a genuine step function: "There is something both impressive and slightly terrifying about seeing a model that is so much smarter than the last model we have worked with." The model was sandboxed with no internet access or email. It sent the researcher an email saying "I've broken out."

Anthropic's response, [Project Glasswing](https://www.anthropic.com/project/glasswing), gives critical infrastructure maintainers (Linux Foundation, AWS, Apple, Microsoft, Google, and 40+ others) early access to harden defenses before Mythos-class capabilities become broadly available. This is the first time a lab has treated a model release as a coordinated security event rather than a product launch.

### Opus 4.7 and the tokenizer surprise

Anthropic [released Claude Opus 4.7](https://www.anthropic.com/news/claude-opus-4-7) with improved software engineering, higher-resolution vision (up to 3.75 megapixels), and better instruction following. Simon Willison [documented](https://simonwillison.net/2026/Apr/18/opus-system-prompt/) the system prompt changes between 4.6 and 4.7, including expanded child safety measures and a new tool\_search feature.

YouTuber Nate B Jones [uncovered](https://www.youtube.com/watch?v=tJB_8mfRgCo) a detail the official blog didn't mention: Opus 4.7's new tokenizer maps the same prompts to up to 35% more tokens. Simon Willison [confirmed](https://simonwillison.net/2026/Apr/20/claude-token-counts/) the finding independently. The persistence/quitting problem from 4.6 is fixed, but the model reportedly regressed on web research tasks while surging on enterprise knowledge work. For teams budgeting token costs, that 35% increase is not trivial.

### The intelligence ceiling holds

The frontier models (GPT-5.4, Gemini 3.1 Pro, Claude Opus 4.6, Llama 4) have [converged at 57.18 on the WhatLLM AAII index](https://whatllm.org/blog/new-ai-models-april-2026). April's model releases focused on specialization rather than pushing raw intelligence: Google's [Gemma 4](https://blog.google/innovation-and-ai/technology/developers-tools/gemma-4/) (four open models, Apache 2.0, 256K context), Alibaba's [Qwen 3.6-27B](https://qwen.ai/blog?id=qwen3.6-27b) (flagship coding in a 27B dense model that runs on consumer hardware), and a wave of efficiency-focused variants across providers.

OpenAI [announced](https://openai.com/index/why-we-no-longer-evaluate-swe-bench-verified/) it's dropping SWE-bench Verified from its evaluations, citing that 59.4% of audited problems have flawed test cases and models appear to have memorized solutions verbatim. Goodhart's Law claimed another benchmark.

## Coding agents and dev tools

### The economics of agentic coding are breaking

GitHub [paused new Copilot Pro and Pro+ signups](https://github.blog/news-insights/company-news/changes-to-github-copilot-individual-plans/) and tightened usage limits because agentic workflows routinely consume more compute than users pay for in a month. Opus models are being pulled from Pro plans entirely, reserved for Pro+. Anthropic [briefly restricted Claude Code](https://simonwillison.net/2026/Apr/22/claude-code-confusion/) to \$100-200/month Max plans, faced backlash, and reversed course.

Gergely Orosz documented the fallout in [The Pragmatic Engineer](https://newsletter.pragmaticengineer.com/p/the-pulse-ai-token-spending-out-of): across 15 engineering organizations, AI token spending exploded in Q1 2026 faster than any budget forecast predicted. Uber burned through its entire 2026 AI token budget in three months. Orosz also coined ["tokenmaxxing"](https://newsletter.pragmaticengineer.com/p/the-pulse-tokenmaxxing-as-a-weird): developers deliberately burning tokens to inflate usage metrics that have become performance targets. Meta's internal "Claudeonomics" leaderboard ranked 85,000 employees by tokens consumed. When you turn AI usage into a KPI, people will game it. This is a governance story, not just a cost story.

An arXiv paper on [token consumption in agentic coding](https://arxiv.org/abs/2604.22750) adds data: identical task runs can differ by 30x in cost, accuracy peaks at intermediate spending (not maximum), and frontier models systematically underestimate their own token usage.

### The skills/CLAUDE.md explosion

The most visible trend in developer tooling this week: the open-sourcing of agent configuration files. [Matt Pocock's skills repo](https://github.com/mattpocock/skills) (27.6K stars, trending #1 daily) shares his Claude Code `.claude` directory. [Andrej Karpathy's CLAUDE.md](https://github.com/forrestchang/andrej-karpathy-skills) (93K stars) derives LLM behavior guidance from Karpathy's observations. [Addy Osmani's agent-skills](https://github.com/addyosmani/agent-skills) (24.4K stars) adds a performance engineering perspective.

93K stars for a single configuration file. That's a signal. Developers are systematizing how they work with coding agents, and sharing those systems is becoming a form of technical knowledge transfer that didn't exist a year ago.

### Codex becomes a desktop agent

OpenAI's [Codex revamp](https://www.youtube.com/watch?v=2d9ZmA-4QzU) (April 16) transformed it from a coding CLI into a full desktop agent that can drive any Mac app via computer use, running in the background while you work on other things. GPT 5.4 benchmarks in the mid-70s on OSWorld, above the human baseline for GUI control. Nate B Jones tested Codex and Claude's computer use side by side: Codex consistently finished tasks in about 2 minutes where Claude took 5-6 with errors and retries.

The strategic split between the two labs is becoming clearer. Anthropic is building structured interfaces (MCP, connectors, the leaked Conway event-driven agent environment). OpenAI is building computer use, meaning the agent drives whatever GUI already exists. Anthropic's bet requires the software ecosystem to cooperate. OpenAI's doesn't. If enterprise software ships MCP servers quickly, Anthropic's architecture wins. If it doesn't, driving the GUI directly stays the better path.

### AI agent deleted a production database (and everyone blamed the company)

A [Cursor-based agent deleted a production database on Railway](https://twitter.com/lifeof_jer/status/2048103471019434248), earning 773 HN points. The community response was unambiguous: the blame belongs with the company for running an agent with unscoped credentials, no deletion protection, and no offsite backups. A companion piece on [defensive databases for the agent era](https://arpitbhayani.me/blogs/defensive-databases/) argues databases were designed for deterministic, human-authored queries, not unpredictable agent-generated ones. Structural controls (scoped tokens, soft deletes, API layers) beat hoping the agent won't do something destructive.

Infisical released [Agent Vault](https://github.com/Infisical/agent-vault), an open-source credential proxy that never exposes secrets directly to the agent. The timing was not coincidental.

## Web development and frameworks

### Cloudflare bets its platform on agents

Cloudflare ran ["Agents Week 2026"](https://blog.cloudflare.com/agents-week-in-review/) with 20+ launches. The headline moves: [Agent Memory](https://blog.cloudflare.com/introducing-agent-memory/) (managed persistent memory for agents), [Unweight](https://blog.cloudflare.com/unweight-tensor-compression/) (lossless 22% model compression via Huffman coding on exponent bytes), [Flagship](https://blog.cloudflare.com/flagship/) (edge feature flags for safely deploying AI-generated code), [AI Search](https://blog.cloudflare.com/ai-search-agent-primitive/) (hybrid vector+keyword search for agents), and [Artifacts](https://blog.cloudflare.com/artifacts-git-for-agents-beta/) (Git-compatible versioned storage).

The framing matters: Cloudflare called this "Cloud 2.0" and explicitly positioned agents as a primary workload alongside humans. Their [AI code review system](https://blog.cloudflare.com/ai-code-review/) runs seven specialized reviewer agents coordinated by a judge agent, processing 131,000 reviews across 48,000 MRs at a median of 3 minutes 39 seconds, costing \$0.20-\$1.68 per review. Their [post on moving past bots vs. humans](https://blog.cloudflare.com/past-bots-and-humans/) argues the distinction is obsolete, proposing privacy-preserving anonymous credentials as the replacement for identity-based access control.

### Claude Design and the death of the mockup

Anthropic shipped [Claude Design](https://www.anthropic.com/news/claude-design-anthropic-labs), powered by Opus 4.7, for turning wireframes into production-ready UI through conversation. Fireship's demo video hit [825K views in 5 days](https://www.youtube.com/watch?v=jeA-KBv0b68). The real story, as [Nate B Jones detailed](https://www.youtube.com/watch?v=KlPxWaY91rE), is that Design completes the Anthropic product stack: Chat for thinking, Cowork for knowledge work, Code for software, and now Design for visual artifacts. Each produces working output in the medium it will live in.

The output is code (HTML, CSS, SVG), not pixels. That's why handoff to Claude Code works cleanly: no translation layer, no Figma-to-code lossy conversion. LLMs were trained on code, not Figma files. Code became the source of truth for AI-assisted design because code is what AI knows. Google responded almost immediately with design.markdown, an open-source specification for sharing design tokens, type scales, and component rules in a format any AI can read.

### Vercel breach exposes platform-level design flaws

A [supply chain attack via Context.ai](https://www.trendmicro.com/en_us/research/26/d/vercel-breach-oauth-supply-chain.html) reached Vercel's internal systems through an OAuth token, exposing customer environment variables containing API keys, GitHub tokens, and NPM tokens. The root cause: environment variables not marked "sensitive" were readable with internal access and stored unencrypted. Hacker News flagged the systemic design problem: single-bag env var storage without access scoping. Cloudflare's scoped bindings model was cited as the right approach.

### Other web dev updates

Vercel's [Workflows reached GA](https://vercel.com/blog/a-new-programming-model-for-durable-execution) for durable long-running functions (100M+ runs since beta). Deno shipped [Fresh 2.3](https://deno.com/blog/fresh-2.3) with zero JavaScript by default, View Transitions, and Temporal API support. Chrome's [Prompt API](https://developer.chrome.com/docs/ai/prompt-api) entered origin trial, exposing Gemini Nano for on-device inference directly from web pages (22GB download, \~5 tok/s, noticeably weaker than cloud, but a meaningful step toward browser-native AI). And [pgbackrest](https://github.com/pgbackrest/pgbackrest), the widely-used PostgreSQL backup tool, announced it's no longer actively maintained.

## Industry and business

### Microsoft and OpenAI rewrite the rules

[Microsoft and OpenAI restructured their partnership](https://blogs.microsoft.com/blog/2026/04/27/the-next-phase-of-the-microsoft-openai-partnership/) on Monday. Microsoft drops its exclusive right to sell OpenAI models, ends revenue sharing on resold products, but retains an IP license through 2032 and its \~30% equity stake. OpenAI can now sell through AWS, Google Cloud, and any other provider.

This is the structural shift that matters. Microsoft spent years building Azure OpenAI into a moat. That moat just opened. OpenAI gains distribution but loses its most committed channel partner's financial incentive to push its products. For enterprise buyers already on Azure, nothing changes immediately. For everyone else, the landscape just got more competitive.

### Meta's infrastructure spending spree

Meta [announced 10% workforce cuts](https://www.taipeitimes.com/News/biz/archives/2026/04/25/2003856188) (\~8,000 employees) starting May 20, plus cancellation of 6,000 open roles. The stated reason: redirecting spending toward AI infrastructure. The company is forecasting \$115-135 billion in 2026 capex. The [AMD GPU deal](https://www.amd.com/en/newsroom/press-releases/2026-2-24-amd-and-meta-announce-expanded-strategic-partnersh.html) (6GW, \~\$60 billion over five years) includes a warrant structure giving Meta roughly 10% of AMD's equity if both sides deliver.

### Employee surveillance for AI training

Meta plans to [capture employee mouse movements and keystrokes](https://www.reuters.com/sustainability/boards-policy-regulation/meta-start-capturing-employee-mouse-movements-keystrokes-ai-training-data-2026-04-21/) for AI training data. Atlassian is [auto-enrolling all customers](https://letsdatascience.com/news/atlassian-enables-default-data-collection-to-train-ai-f71343d8) in AI training data collection starting August 2026, scooping Confluence pages, Jira tickets, and comments unless admins opt out (but the opt-out settings were not visible in admin portals at announcement time). Both stories triggered strong backlash.

### China blocks Meta's Manus acquisition

China's NDRC [ordered Meta to unwind its \$2 billion acquisition](https://www.cnbc.com/2026/04/27/meta-manus-china-blocks-acquisition-ai-startup.html) of Manus, the autonomous agent startup with Chinese roots. This is Beijing treating AI talent and capabilities as a core national security asset. Between this and DeepSeek V4 on Huawei chips, the AI competition between the US and China entered a new phase this week.

### The speed vs. quality tension

Matt Pocock's AI Engineer talk on ["Software Fundamentals Matter More Than Ever"](https://www.youtube.com/watch?v=v4F1gFy-hqg) (247K views in 3 days) argues that the developers succeeding with AI are falling back on classical principles: ubiquitous language, vertical slices, TDD, deep modules. These principles "didn't break. They got more important."

Armin Ronacher (creator of Flask) [made the complementary argument](https://www.youtube.com/watch?v=_Zcw_sVF6hU) at the same conference: "The promise of shipping without friction using AI coding agents is a trap." Excessive speed leads to technical debt, security issues, and brittle systems. Friction forces judgment.

The data supports them. Addy Osmani's [productivity analysis](https://addyo.substack.com/p/the-reality-of-ai-assisted-software) synthesizes multiple studies: high-AI teams completed 98% more PRs but saw 91% longer review times. Junior developers gain 35-39% on tasks; senior developers gain 8-16%; experienced developers on complex legacy code lose 19% (METR). 84% of developers use AI tools daily. Only 29% trust what they ship.

## Interesting GitHub repositories

**[GenericAgent](https://github.com/lsdefine/GenericAgent)** (7.6K stars) - Self-evolving agent that bootstraps its own capability tree from experience rather than relying on pre-loaded skills, achieving full system control with 6x less token consumption than competitors. The entire repo was reportedly created by the agent itself.

**[multica](https://github.com/multica-ai/multica)** (21.9K stars) - Open-source managed agents platform that turns coding agents into team members. Vendor-neutral, supports Claude Code, Codex, OpenClaw, Cursor Agent, Gemini, and others from a single dashboard.

**[beads](https://github.com/gastownhall/beads)** (22K stars) - Steve Yegge's distributed graph issue tracker for AI coding agents. Replaces unstructured markdown plans with hash-based task IDs that avoid merge conflicts in multi-agent workflows. Addresses a real gap: agents losing context during long-horizon tasks.

**[claude-context](https://github.com/zilliztech/claude-context)** (9.8K stars, trending #1 TypeScript) - MCP plugin for Claude Code that indexes an entire codebase using hybrid BM25 + vector search with AST-based chunking, reducing token usage by \~40%.

**[context-mode](https://github.com/mksglu/context-mode)** (10.6K stars) - MCP server that compresses large tool outputs down to 98% smaller before inserting into the conversation, extending effective working context from \~30 minutes to \~3 hours.

**[shannon](https://github.com/KeygraphHQ/shannon)** (40.5K stars) - Autonomous white-box AI pentester for web apps. Analyzes source code, identifies attack vectors, executes real exploits. No false positives: only proven, actively exploitable vulnerabilities reported. 96.15% success rate on validation benchmarks.

**[pi-mono](https://github.com/badlogic/pi-mono)** (41.4K stars) - Mario Zechner's AI agent toolkit monorepo: unified LLM API, coding agent CLI, TUI + web UI, Slack bot, and vLLM GPU pod management. Encourages sharing real open-source work sessions to improve models.

**[dflash](https://github.com/z-lab/dflash)** (2.4K stars) - Block diffusion for flash speculative decoding. Generates multiple LLM tokens in parallel. Works with vLLM, SGLang, Transformers, and MLX. Useful for anyone running inference at scale who wants throughput without switching models.

**[RAG-Anything](https://github.com/HKUDS/RAG-Anything)** (19K stars) - Multimodal RAG framework handling PDFs, Office files, images, tables, and math in a single pipeline with automatic knowledge graph construction. Solves a real pain point for enterprise deployments where documents mix text and visuals.

**[voicebox](https://github.com/jamiepine/voicebox)** (23.6K stars) - Open-source AI voice studio: zero-shot cloning, 7 TTS engines, local Whisper dictation. Built with Tauri/Rust instead of Electron. All processing stays local. MIT licensed alternative to ElevenLabs.

**[thunderbolt](https://github.com/thunderbird/thunderbolt)** (4.2K stars) - Open-source, cross-platform AI client from Mozilla's Thunderbird team. Self-hosted, vendor-neutral, supports OpenAI-compatible providers and Ollama. Targets enterprise use cases requiring data sovereignty.

## Quick bits

* **[MeshCore project split](https://blog.meshcore.io/2026/04/23/the-split)** over a contributor secretly using Claude Code for major ecosystem components without disclosure, plus a unilateral trademark filing. Ethics of undisclosed AI contributions in open source is heating up. (281 HN points)
* **[Design slop analysis](https://www.adriankrebs.ch/blog/design-slop/)** shows Show HN submissions tripled in volume and converged on identical AI-generated design patterns: dark mode, purple gradients, terminal fonts. (333 HN points)
* **[AI resistance roundup](https://stephvee.ca/blog/artificial%20intelligence/ai-resistance-is-growing/)**: organized opposition to AI deployment from artist opt-outs to municipal policy pushback. European regulatory frameworks cited as the only lever with structural teeth. (388 HN points)
* **[GPT Image 2 won 93% of blind pairwise comparisons](https://www.youtube.com/watch?v=brBPsPPyuQM)** in Image Arena, a 26-point gap over the next model. The forgery implications are serious: convincing receipts, Slack screenshots, pharmacy labels, and government notices from a single free-tier prompt.
* **["Tell HN: I'm sick of AI everything"](https://news.ycombinator.com/item?id=47857461)** hit 339 points. AI fatigue is real and the community is articulating it.
* **MCP roadmap from Anthropic**: David Soria Parra [laid out](https://www.youtube.com/watch?v=v3Fr2JR47KA) the 2026 MCP direction at AI Engineer Europe. Three-layer connectivity stack (Skills, MCP, CLI/Computer use), Progressive Discovery for improving client harnesses, programmatic tool calling for agent orchestration.
* **[Cursor 3.2](https://cursor.com/changelog/04-24-26)** ships `/multitask` for parallel async subagents, improved worktrees, and multi-root workspaces for cross-repo changes.
* **[Cursor partners with SpaceX](https://cursor.com/blog/spacex-model-training)** (xAI's Colossus infrastructure) to scale model training beyond what the Composer releases could achieve.
* **[Microsoft VibeVoice](https://github.com/microsoft/VibeVoice)** (42.5K stars): open-source frontier voice AI processing 60-minute audio in a single pass with speaker diarization in 50+ languages and \~300ms latency.
* **[Addy Osmani on agent harness engineering](https://addyosmani.com/blog/agent-harness-engineering/)**: the scaffolding around the model matters more than the model itself. Treat agent failures as signals to improve the harness, not reasons to wait for better models.
* **[Google Decoupled DiLoCo](https://deepmind.google/blog/decoupled-diloco/)**: distributed training across asynchronous compute islands, reducing inter-datacenter bandwidth from 198 Gbps to 0.84 Gbps while training a 12B model 20x faster.
* **Felix Rizzleberg on Claude Cowork**: [discussed](https://www.youtube.com/watch?v=9MEJ4syOVrQ) how Anthropic's roadmap is one month long ("If anyone tells me I know what AI looks like next year, I'm not going to be very impressed"), prototyping 100+ internal products, and why execution cost approaching zero changes the bottleneck from building to taste.

## Sources

* [DeepSeek V4 announcement](https://api-docs.deepseek.com/news/news260424)
* [DeepSeek V4 (Fortune)](https://fortune.com/2026/04/24/deepseek-v4-ai-model-price-performance-china-open-source/)
* [DeepSeek V4 (MIT Technology Review)](https://www.technologyreview.com/2026/04/24/1136422/why-deepseeks-v4-matters/)
* [DeepSeek V4 Huawei chips (Tom's Hardware)](https://www.tomshardware.com/tech-industry/artificial-intelligence/deepseek-launches-1-6-trillion-parameter-v4-on-huawei-chips-as-us-escalates-ai-theft-accusations)
* [Google Anthropic \$40B (CNBC)](https://www.cnbc.com/2026/04/24/google-to-invest-up-to-40-billion-in-anthropic-as-search-giant-spreads-its-ai-bets.html)
* [Google Anthropic \$40B (TechCrunch)](https://techcrunch.com/2026/04/24/google-to-invest-up-to-40b-in-anthropic-in-cash-and-compute/)
* [Amazon Anthropic compute expansion](https://www.anthropic.com/news/anthropic-amazon-compute)
* [Amazon Anthropic analysis (Markman Capital)](https://markmancapitalinsight.substack.com/p/amazons-33-billion-anthropic-deal)
* [Claude Mythos Preview](https://red.anthropic.com/2026/mythos-preview/)
* [Project Glasswing](https://www.anthropic.com/glasswing)
* [Claude Opus 4.7](https://www.anthropic.com/news/claude-opus-4-7)
* [Claude Design](https://www.anthropic.com/news/claude-design-anthropic-labs)
* [Opus 4.7 system prompt changes (Simon Willison)](https://simonwillison.net/2026/Apr/18/opus-system-prompt/)
* [Opus 4.7 token counts (Simon Willison)](https://simonwillison.net/2026/Apr/20/claude-token-counts/)
* [DeepSeek V4 (Simon Willison)](https://simonwillison.net/2026/Apr/24/deepseek-v4/)
* [Claude Code pricing confusion (Simon Willison)](https://simonwillison.net/2026/Apr/22/claude-code-confusion/)
* [Intelligence ceiling (WhatLLM)](https://whatllm.org/blog/new-ai-models-april-2026)
* [SWE-bench Verified dropped (OpenAI)](https://openai.com/index/why-we-no-longer-evaluate-swe-bench-verified/)
* [GitHub Copilot changes](https://github.blog/news-insights/company-news/changes-to-github-copilot-individual-plans/)
* [Token spending (Pragmatic Engineer)](https://newsletter.pragmaticengineer.com/p/the-pulse-ai-token-spending-out-of)
* [Tokenmaxxing (Pragmatic Engineer)](https://newsletter.pragmaticengineer.com/p/the-pulse-tokenmaxxing-as-a-weird)
* [AI impact on engineers (Pragmatic Engineer)](https://newsletter.pragmaticengineer.com/p/the-impact-of-ai-on-software-engineers-2026)
* [Token consumption in agentic coding (arXiv)](https://arxiv.org/abs/2604.22750)
* [Agent stack bet (Addy Osmani)](https://addyo.substack.com/p/the-agent-stack-bet)
* [Agent harness engineering (Addy Osmani)](https://addyosmani.com/blog/agent-harness-engineering/)
* [AI coding productivity (Addy Osmani)](https://addyo.substack.com/p/the-reality-of-ai-assisted-software)
* [DeepSeek V4 geopolitics (Ken Huang)](https://kenhuangus.substack.com/p/deepseek-v4-the-next-frontier-of)
* [AI energy geopolitics (Oleg Ovanesyan)](https://olegov.substack.com/p/ai-economics-geopolitics-newsletter-apr-25-2026)
* [Microsoft-OpenAI partnership restructure](https://blogs.microsoft.com/blog/2026/04/27/the-next-phase-of-the-microsoft-openai-partnership/)
* [Microsoft-OpenAI partnership (CNBC)](https://www.cnbc.com/2026/04/27/openai-microsoft-partnership-revenue-cap.html)
* [Meta layoffs](https://www.taipeitimes.com/News/biz/archives/2026/04/25/2003856188)
* [Meta AMD GPU deal](https://www.amd.com/en/newsroom/press-releases/2026-2-24-amd-and-meta-announce-expanded-strategic-partnersh.html)
* [Meta keystroke collection (Reuters)](https://www.reuters.com/sustainability/boards-policy-regulation/meta-start-capturing-employee-mouse-movements-keystrokes-ai-training-data-2026-04-21/)
* [Atlassian data collection](https://letsdatascience.com/news/atlassian-enables-default-data-collection-to-train-ai-f71343d8)
* [China blocks Meta Manus acquisition (CNBC)](https://www.cnbc.com/2026/04/27/meta-manus-china-blocks-acquisition-ai-startup.html)
* [Vercel breach (Trend Micro)](https://www.trendmicro.com/en_us/research/26/d/vercel-breach-oauth-supply-chain.html)
* [Cloudflare Agents Week recap](https://blog.cloudflare.com/agents-week-in-review/)
* [Cloudflare Agent Memory](https://blog.cloudflare.com/introducing-agent-memory/)
* [Cloudflare Unweight](https://blog.cloudflare.com/unweight-tensor-compression/)
* [Cloudflare Flagship](https://blog.cloudflare.com/flagship/)
* [Cloudflare AI code review](https://blog.cloudflare.com/ai-code-review/)
* [Vercel Workflows GA](https://vercel.com/blog/a-new-programming-model-for-durable-execution)
* [Deno Fresh 2.3](https://deno.com/blog/fresh-2.3)
* [Chrome Prompt API](https://developer.chrome.com/docs/ai/prompt-api)
* [Cursor 3.2 changelog](https://cursor.com/changelog/04-24-26)
* [Cursor SpaceX partnership](https://cursor.com/blog/spacex-model-training)
* [DeepSeek V4 on Hugging Face](https://huggingface.co/blog/deepseekv4)
* [Gemma 4](https://blog.google/innovation-and-ai/technology/developers-tools/gemma-4/)
* [Qwen 3.6-27B](https://qwen.ai/blog?id=qwen3.6-27b)
* [AI agent deleted production DB](https://twitter.com/lifeof_jer/status/2048103471019434248)
* [Defensive databases](https://arpitbhayani.me/blogs/defensive-databases/)
* [Agent Vault](https://github.com/Infisical/agent-vault)
* [Software fundamentals talk (Matt Pocock)](https://www.youtube.com/watch?v=v4F1gFy-hqg)
* [Friction is judgment (Armin Ronacher)](https://www.youtube.com/watch?v=_Zcw_sVF6hU)
* [MCP roadmap (David Soria Parra)](https://www.youtube.com/watch?v=v3Fr2JR47KA)
* [Codex desktop agent analysis](https://www.youtube.com/watch?v=2d9ZmA-4QzU)
* [Claude Design demo (Fireship)](https://www.youtube.com/watch?v=jeA-KBv0b68)
* [GPT Image 2 analysis](https://www.youtube.com/watch?v=brBPsPPyuQM)
* [Felix Rizzleberg on Cowork (Matt Turk podcast)](https://www.youtube.com/watch?v=9MEJ4syOVrQ)
* [Steve Yegge on AI adoption levels](https://www.youtube.com/watch?v=aFsAOu2bgFk)


# Git worktrees for parallel AI coding agents
Source: https://developer.upsun.com/posts/ai/git-worktrees-for-parallel-ai-coding-agents

Learn how git worktrees enable parallel AI agent workflows, their limitations, and what an ideal orchestration tool needs.

<PostMeta />

Git worktrees started as a way to handle emergency hotfixes without stashing your work. Now they're how developers run multiple AI coding agents at the same time. If you're using Claude Code, Cursor, or Opencode, you've probably hit a wall trying to run two agents in the same directory. Worktrees fix that problem, but they come with their own set of headaches.

The idea is simple: each AI agent works better when it has its own isolated workspace. Worktrees give you that isolation without cloning your entire repository five times.

## How worktrees actually work

A git worktree is a linked working directory that shares the same `.git` data as your main checkout. When you run `git worktree add ../feature-branch feature-branch`, Git creates a new directory with its own files. It reuses the object database, refs, and configuration from your original repository.

Here's what happens under the hood. Each linked worktree contains a `.git` file (not a folder) with one line pointing back to the main repo: `gitdir: /path/main/.git/worktrees/feature-branch`. Git sets `$GIT_DIR` for worktree-specific data like HEAD and the staging area. It uses `$GIT_COMMON_DIR` for shared resources.

```mermaid theme={null}
%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#6046FF', 'primaryTextColor': '#fff', 'primaryBorderColor': '#000', 'lineColor': '#D0F302', 'secondaryColor': '#D0F302', 'tertiaryColor': '#fff', 'background': '#fff', 'mainBkg': '#6046FF', 'secondBkg': '#D0F302', 'tertiaryBkg': '#fff', 'nodeBorder': '#000', 'clusterBkg': '#fff', 'titleColor': '#000', 'edgeLabelBackground': '#fff'}}}%%
flowchart TB
    subgraph SHARED["Shared .git directory"]
        OBJ["Object database<br/>(commits, blobs, trees)"]
        REFS["Refs<br/>(branches, tags)"]
        CONFIG["Configuration"]
    end
    
    subgraph WT1["Main worktree"]
        HEAD1["HEAD → main"]
        INDEX1["Index/staging"]
        FILES1["Working files"]
    end
    
    subgraph WT2["Worktree: feature-auth"]
        HEAD2["HEAD → feature-auth"]
        INDEX2["Index/staging"]
        FILES2["Working files"]
    end
    
    subgraph WT3["Worktree: bugfix-api"]
        HEAD3["HEAD → bugfix-api"]
        INDEX3["Index/staging"]
        FILES3["Working files"]
    end
    
    WT1 --> SHARED
    WT2 --> SHARED
    WT3 --> SHARED
    
    style SHARED fill:#efefef,stroke:#000,color:#000
    style WT1 fill:#D0F302,stroke:#000,color:#000
    style WT2 fill:#D0F302,stroke:#000,color:#000
    style WT3 fill:#D0F302,stroke:#000,color:#000
```

**Why not clone five times?** A clone duplicates the entire Git object database. With a 500MB repository, five clones eat up 2.5GB. Five worktrees only duplicate working files while sharing history. One `git fetch` updates all worktrees at once. Commits you make in any worktree show up in all the others.

Here are the commands you'll use:

```bash {filename="Terminal"} theme={null}
# Create worktree with new branch
git worktree add -b feature-auth ../auth-work main

# List all worktrees
git worktree list

# Remove when done
git worktree remove ../auth-work

# Clean up stale references
git worktree prune
```

Before AI agents came along, developers used worktrees for context switching. You could handle an emergency hotfix without stashing messy work-in-progress. You could review pull requests without losing your place. You could run `git bisect` without destroying your working state.

## Why AI agents need worktrees

AI coding assistants created a new use case: running multiple agents at once. Anthropic's Claude Code documentation recommends worktrees for multi-session workflows. They let you run "multiple Claude sessions simultaneously on different parts of your project, each focused on its own independent task." Cursor built their "Parallel Agents" feature directly on worktrees.

```mermaid theme={null}
%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#6046FF', 'primaryTextColor': '#fff', 'primaryBorderColor': '#000', 'lineColor': '#D0F302', 'secondaryColor': '#D0F302', 'tertiaryColor': '#fff', 'background': '#fff', 'mainBkg': '#6046FF', 'secondBkg': '#D0F302', 'tertiaryBkg': '#fff', 'nodeBorder': '#000', 'clusterBkg': '#fff', 'titleColor': '#000', 'edgeLabelBackground': '#fff'}}}%%
flowchart LR
    DEV["Developer"]
    
    subgraph PARALLEL["Parallel AI agent sessions"]
        direction TB
        subgraph WT1["Worktree 1"]
            A1["Claude Code<br/>feature-auth"]
        end
        subgraph WT2["Worktree 2"]
            A2["Claude Code<br/>refactor-api"]
        end
        subgraph WT3["Worktree 3"]
            A3["Claude Code<br/>add-tests"]
        end
    end
    
    DEV --> WT1
    DEV --> WT2
    DEV --> WT3
    
    WT1 --> PR1["PR #1"]
    WT2 --> PR2["PR #2"]
    WT3 --> PR3["PR #3"]
    
    style DEV fill:#6046FF,stroke:#000,color:#fff
    style WT1 fill:#D0F302,stroke:#000,color:#000
    style WT2 fill:#D0F302,stroke:#000,color:#000
    style WT3 fill:#D0F302,stroke:#000,color:#000
    style PR1 fill:#fff,stroke:#000,color:#000
    style PR2 fill:#fff,stroke:#000,color:#000
    style PR3 fill:#fff,stroke:#000,color:#000
```

Here's why developers keep using this setup:

* **Context isolation**: Each agent sees only its worktree's files. No confusion between features.
* **Preserved conversation history**: Switching branches in one directory confuses an agent's context. Worktrees keep things separate.
* **Safe experimentation**: Let an agent try a risky refactor in an isolated worktree. If it fails, delete the worktree.
* **Run the same prompt twice**: Give the same task to different agents. Pick whichever result you like better.

Nick Mitchinson puts it well: "When an AI agent is working on one feature, you don't want it accidentally referencing or modifying files from another feature branch. Worktrees provide complete isolation."

## Where worktrees fall apart

Running multiple worktrees sounds great until you try it. Developer forums and GitHub issues document the same problems over and over.

**Port conflicts hit you first.** Every dev server defaults to the same ports: 3000, 5432, 8080. Launch two React apps from different worktrees and one fails. The workaround looks like this: `SERVICE_PORT = BASE_PORT + (WORKTREE_INDEX * 10) + SERVICE_OFFSET`. But you need to build scripts that scan for available ports and update `.env` files per worktree.

**Dependencies don't carry over.** Your `node_modules` doesn't exist in new worktrees. Neither does `.env` (which is gitignored, as it should be). Each worktree needs `npm install` or `npm ci`, eating up time and disk space. That's where `pnpm` will help a lot in symlinking packages and downloading them only once.

**IDE support is inconsistent.** JetBrains products have no native worktree creation UI. Command line only. VS Code added worktree support in July 2025. Claude Code's `/ide` command fails to recognize worktrees, reporting "No available IDEs detected" because workspace paths don't match the current directory. GitLens and Tower work better, but the ecosystem is fragmented.

**Database isolation doesn't exist.** Worktrees share the same local database, Docker daemon, and cache directories. Two agents modifying database state at the same time creates race conditions. You can fix this with per-worktree database instances and worktree-indexed Docker volume names, but that's a lot of setup.

**Disk space adds up fast.** Cursor forum users reported that in a 20-minute session with a \~2GB codebase, automatic worktree creation used 9.82 GB. Build artifacts make it worse. Bazel, Pants, or Nx monorepos store gigabytes of cache data that multiplies per worktree. One developer found 15 forgotten worktrees "consuming gigabytes" before starting to clean them up.

**You'll create merge conflicts with yourself.** The GitButler team says it directly: "The worktrees are separate, so you can create merge conflicts between them without knowing." Parallel agents touching the same files guarantee integration problems. No tool warns you when two agents might edit the same code.

## Tools that try to help

Several tools have appeared to address these problems. **[agentree](https://github.com/AryaLabsHQ/agentree)** gives you quick worktree creation for AI workflows: `agentree -b fix-auth` in one terminal, `agentree -b ui-fixes` in another. **[git-worktree-runner](https://github.com/coderabbitai/git-worktree-runner)** from CodeRabbit works with Claude, Cursor, Opencode, Copilot, and Gemini through commands like `git gtr new my-feature --ai`.

**[worktree-cli](https://github.com/fnebenfuehr/worktree-cli)** targets AI workflows with MCP server integration for Claude Code, automatic setup hooks, and file copying for `.env` handling. **[gwq](https://github.com/d-kuro/gwq)** shows you a status dashboard of all active worktrees across repositories, plus tmux integration for managing long-running agent processes.

For orchestration, **[ccswarm](https://github.com/nwiizo/ccswarm)** coordinates multiple agents with specialized pools (Frontend, Backend, DevOps, QA) in worktree-isolated environments. **[Crystal](https://github.com/stravu/crystal)** is a desktop app for running parallel Claude Code and Codex sessions with visual management.

**The gap no one has closed:** no tool connects worktree code isolation with full environment isolation. **[DevTree](https://github.com/pwrmind/DevTree)** tries by combining worktrees with dedicated Dev Containers per branch, including automatic port allocation. But it's early-stage. Multiple GitHub issues show that worktrees and devcontainers don't work well together. The `.git` file format breaks container git operations.

## Preview environments fix the isolation problem

Local worktrees have one core limitation: they isolate code but not the runtime environment. You get separate file systems but shared ports, databases, and services. Cloud-based preview environments flip this around.

Platforms like Upsun Cloud create complete, isolated environments for each Git branch. When you push a feature branch, the platform spins up a full production clone: separate application containers, dedicated database instances, unique URLs, and isolated services. This happens through Git integration without manual setup.

```mermaid theme={null}
%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#6046FF', 'primaryTextColor': '#fff', 'primaryBorderColor': '#000', 'lineColor': '#D0F302', 'secondaryColor': '#D0F302', 'tertiaryColor': '#fff', 'background': '#fff', 'mainBkg': '#6046FF', 'secondBkg': '#D0F302', 'tertiaryBkg': '#fff', 'nodeBorder': '#000', 'clusterBkg': '#fff', 'titleColor': '#000', 'edgeLabelBackground': '#fff'}}}%%
flowchart TB
    subgraph LOCAL["Local development"]
        LW1["Worktree 1"] --> SHARED["Shared resources<br/>Ports, DB, services"]
        LW2["Worktree 2"] --> SHARED
        LW3["Worktree 3"] --> SHARED
    end
    
    subgraph CLOUD["Preview environments"]
        direction TB
        subgraph ENV1["feature-auth environment"]
            E1A["App container"]
            E1D["Database"]
            E1U["https://feature-auth.example.com"]
        end
        subgraph ENV2["refactor-api environment"]
            E2A["App container"]
            E2D["Database"]
            E2U["https://refactor-api.example.com"]
        end
        subgraph ENV3["add-tests environment"]
            E3A["App container"]
            E3D["Database"]
            E3U["https://add-tests.example.com"]
        end
    end
    
    style LOCAL fill:#fff,stroke:#000,color:#000
    style CLOUD fill:#fff,stroke:#000,color:#000
    style SHARED fill:#6046FF,stroke:#000,color:#fff
    style ENV1 fill:#D0F302,stroke:#000,color:#000
    style ENV2 fill:#D0F302,stroke:#000,color:#000
    style ENV3 fill:#D0F302,stroke:#000,color:#000
```

For parallel AI agent workflows, preview environments eliminate the main friction points:

* **No port conflicts**: Each environment runs on its own infrastructure with its own URL.
* **Database isolation by default**: Every preview environment gets its own database instance. You can clone production data with sanitization.
* **Dependencies pre-installed**: Builds run in the cloud. Each environment has its complete dependency tree.
* **No local disk consumption**: Your machine doesn't store multiple copies of `node_modules` or build artifacts.
* **Shareable URLs**: Give each AI agent's output a unique URL for testing and review.

The workflow is: create a branch locally, push to trigger environment creation, point your AI agent at that branch's environment. Each agent operates against a fully isolated stack.

This approach has tradeoffs. Environment spin-up takes longer than creating a local worktree (minutes versus seconds). You need network connectivity to test changes. For rapid iteration, local worktrees are faster. But for parallel AI workflows where isolation matters more than speed, preview environments remove entire categories of problems.

## What an ideal tool would look like

Community discussions keep coming back to the same wishlist. A good multi-agent orchestration tool would combine the speed of local worktrees with the isolation of cloud environments, plus coordination features that neither has.

**Automatic port allocation** without configuration. The tool assigns non-conflicting ports per worktree and updates environment variables. No more manual port arithmetic or `.env` file management.

**Per-worktree environment isolation** including databases, Docker daemons, and services. This could mean lightweight containers per worktree, or integration with cloud preview environments. The goal is eliminating shared-state conflicts.

**Merge conflict detection before it's too late**. Before parallel execution begins, the tool analyzes whether tasks are independent or risk touching the same files. During execution, it warns when agents approach the same code regions. AI-assisted resolution helps when conflicts do occur.

**Context sharing between agents** with boundaries. Agents need shared understanding of project architecture and conventions without interfering in each other's work. A central memory layer maintains project knowledge while keeping task-specific context isolated.

**A central orchestrator** that assigns tasks, monitors progress, and coordinates merges. This layer understands task dependencies, schedules work to minimize conflicts, and helps integrate parallel outputs into coherent commits.

**Ephemeral environments on demand**. Spin up complete isolated stacks (including databases with test data) in seconds. Tear them down when work completes. Local speed with cloud isolation.

**Visual status and progress tracking**. When you're running five agents at once, you need a dashboard showing what each is working on, how far along they are, and whether any are blocked or failing.

VS Code now offer AI-assisted merge conflict resolution, which helps after conflicts happen. But the coordination layer that prevents conflicts in the first place is still missing.

## Where things are going

Worktrees went from a feature most developers never used to infrastructure for AI-assisted development. The workflow delivers real speed gains: incident.io runs four or five parallel Claude agents routinely, Anthropic documents the pattern officially, and Cursor built it into their product.

But the tooling hasn't caught up. Developers write bash functions, manage ports manually, and run cleanup scripts. The friction adds up: dependency installation, IDE recognition failures, database conflicts, disk space management, merge problems.

The next wave of AI coding tools will probably integrate environment isolation directly. For now, worktrees are the best option, even with all their rough edges. You trade operational complexity for the ability to run multiple agents at once.

## Resources

* [Git worktree documentation](https://git-scm.com/docs/git-worktree)
* [How we're shipping faster with Claude Code and Git Worktrees - incident.io](https://incident.io/blog/shipping-faster-with-claude-code-and-git-worktrees)
* [Claude Code: Parallel Development with /worktree - motlin.com](https://motlin.com/blog/claude-code-worktree)
* [Git Worktrees: The Power Behind Cursor's Parallel Agents - DEV Community](https://dev.to/arifszn/git-worktrees-the-power-behind-cursors-parallel-agents-19j1)
* [Using Git Worktrees for Multi-Feature Development with AI Agents - Nick Mitchinson](https://www.nrmitchi.com/2025/10/using-git-worktrees-for-multi-feature-development-with-ai-agents/)
* [How Git Worktrees Changed My AI Agent Workflow - Nx Blog](https://nx.dev/blog/git-worktrees-ai-agents)
* [Git Worktrees and GitButler - GitButler Blog](https://blog.gitbutler.com/git-worktrees)
* [Common workflows - Claude Code Docs](https://code.claude.com/docs/en/common-workflows)
* [agentree - GitHub](https://github.com/AryaLabsHQ/agentree)
* [git-worktree-runner - CodeRabbit](https://github.com/coderabbitai/git-worktree-runner)
* [worktree-cli - GitHub](https://github.com/fnebenfuehr/worktree-cli)
* [gwq - GitHub](https://github.com/d-kuro/gwq)
* [ccswarm - GitHub](https://github.com/nwiizo/ccswarm)
* [Crystal - GitHub](https://github.com/stravu/crystal)
* [DevTree - GitHub](https://github.com/pwrmind/DevTree)

***

**Want to skip the environment isolation headaches?** [Upsun Cloud preview environments](https://upsun.com) create complete, isolated stacks for every Git branch. You get the parallelism benefits of worktrees without the port conflicts, database collisions, or disk space problems.


# How to choose a code index for your coding agent
Source: https://developer.upsun.com/posts/ai/how-to-choose-a-code-index-for-your-coding-agent

Compare Graft and roam-code on a real Go, TypeScript, Swift, and SQL codebase to evaluate context coverage, retrieval quality, and change analysis in practice.

<PostMeta />

Ask a coding agent to change `Store.Sync` and the method name is only the start. The agent also needs the HTTP handler that calls it, the Swift client that consumes its response, the tests that describe its behavior, and the database state behind the cursor.

A broad repository scan wastes context and time. Working from a narrow guess creates blind spots. An index gives the agent a better starting point for each task.

A code index gives the agent a map. It turns definitions, references, calls, imports, tests, and file ownership into context the agent can query before it reads or changes code.

<img alt="Give your coding agent a map of the codebase" />

## Why a coding agent needs an index

The model does not carry your current repository in its weights. Each task starts with a context-selection problem. The index decides which parts of the codebase the agent sees and which relationships it can follow.

### Select the smallest useful context

Sending the whole repository to a model is expensive and noisy. Sending one file is often too little. A useful index sits between those extremes.

For a change to `Store.Sync`, the right slice includes the definition, its production caller, the client contract, and the tests. The agent can read four relevant files instead of searching hundreds and still understand the path it is about to change.

<img alt="A code index selects the smallest useful context for the task" />

### Preserve relationships across files and languages

Repositories are collections of files. Software behavior comes from the relationships between them.

Checkmate's synchronization path starts in a Swift `SyncEngine`, crosses an HTTP handler, calls the Go store, and is verified by API tests. A text search can find the word `sync`. An index should tell the agent which occurrences form the same execution path.

<img alt="The index preserves relationships across the client, API, store, and tests" />

### Keep the map current

An index becomes dangerous when it is stale. If a developer adds a caller after the graph was built, the old answer can still look exact while omitting the new dependency.

Freshness is a correctness requirement. The graph needs to reflect the code the agent is about to change. Automatic refresh helps. An explicit refresh command can also work when the agent workflow enforces it.

<img alt="A current index refreshes relationships before the next query" />

### Estimate the scope of a change

Agents that modify code need more than navigation. They need to identify callers, contracts, likely tests, and the parts of the repository that deserve human review.

An index cannot prove that a change is safe. It can narrow the inspection plan before the edit and help check the resulting diff afterward. The test suite still decides whether the behavior holds.

<img alt="The graph turns an edit into a review and verification plan" />

These four jobs shaped my comparison of [Graft](https://github.com/NanoNets/Graft) and [roam-code](https://github.com/Cranot/roam-code). Coverage came first, followed by retrieval quality, freshness, and change analysis. I also checked how each tool handles local and model-assisted processing because those choices have different privacy implications.

## The Checkmate test case

Checkmate is a self-hosted personal task manager that I am developing for my own needs. It packages a React and TanStack frontend, a Go API, OAuth, and an MCP endpoint into one deployable binary backed by SQLite. A separate Swift application talks to the HTTP API and keeps a local cache for synchronization.

That structure makes it a useful test. The repository is small enough to inspect manually, but real behavior crosses language and application boundaries.

The relevant stack includes

* Go for the API and core business logic
* TypeScript and TSX for the web application
* Swift for the iOS application
* SQL for migrations and persistence structure
* YAML, JSON, Markdown, and supporting project files

<img alt="Checkmate combines web and iOS clients with a Go runtime and SQLite database" />

The iOS sync path is the useful fault line in this comparison. It crosses `SyncEngine` and `LocalStore` in Swift, an HTTP handler and `Store.Sync` in Go, API tests, and SQL-backed state. An index that stops at the Go server or the web client cannot describe that whole path.

I ran the benchmark against disposable copies of the repository and did not modify my working project. I used Graft 0.8.2 and roam-code 13.10.0, the current releases on August 4, 2026. Both projects are young and moving quickly, so the version numbers are part of the result.

## How I tested the indexes

The test had four parts.

I checked coverage by building each index from a fresh copy of the repository, inspecting its language and file counts, and asking for the structure of the Swift `LocalStore.swift` file.

I checked retrieval with exact navigation around `Store.Sync`, a real server method with a production caller. I also asked where `CHECKMATE_BASE_URL` is configured and used. The cross-stack query asked "How do web and iOS clients synchronize changes with the Go server?"

I checked freshness with a no-change rebuild and an incremental update. For the update, I added the same harmless comment to `server/internal/recurrence/recurrence.go` in each disposable copy. I recorded the times to catch an operational problem, not to score small differences measured in seconds.

I checked change analysis with Roam's preflight and affected-test commands. The goal was to see whether its deeper graph produced guidance I could rely on before an edit.

All timings below include CLI process startup. An MCP integration can have a different latency profile. I did not run `graft build --deep`. That optional step sends source through a configured model provider and adds semantic summaries, which would make this a test of model configuration as well as indexing.

I also excluded both vendors' published benchmark claims from the scorecard. Neither project publishes a direct Graft-versus-Roam benchmark, and their existing tests use different tasks, models, and evaluation methods.

## Timing was a non-factor

| Index operation | Graft 0.8.2 | roam-code 13.10.0 |
| - | -: | -: |
| Cold index, wall time | 2.78s | 4.85s |
| True no-change refresh | 1.15s | 0.33s |
| One-file incremental update | 1.37s | 1.48s |

Every index operation completed in less than five seconds. Graft's cold build took 2.78 seconds and Roam's took 4.85. Roam's no-change refresh was faster, while their one-file updates were separated by 0.11 seconds.

Based on these results, I would give indexing speed zero weight in the decision. Indexing happens before the much longer work of reading, changing, testing, and reviewing code. I would revisit timing if either tool took minutes, blocked every query, or could not refresh incrementally. Neither did.

The incremental behavior still tells us how the tools maintain their graphs. Graft parsed the one changed file and replayed the other 125. Roam marked one file as modified, then re-extracted 13 neighboring files to update related graph information. Both finished quickly enough that coverage and answer quality determined the decision.

## Coverage changed the recommendation

| Indexed content | Graft 0.8.2 | roam-code 13.10.0 |
| - | -: | -: |
| Files after settling | 126 | 213 |
| Swift files | 0 | 38 |
| SQL files | 0 | 11 |
| Graph contents | 1,388 nodes | 4,240 symbols |

The graph totals are not directly comparable. Graft reports nodes by structural type, while Roam reports symbols. The counts describe what each tool built. They do not make a larger graph better by default. Roam's cold build reported 212 files. Its first repeat created and indexed `.roamignore`, bringing the settled count to 213. The coverage graphics use that settled state.

Graft currently has first-class extractors for JavaScript and TypeScript variants, Python, and Go. That matches its own [0.8.2 language configuration](https://github.com/NanoNets/Graft/blob/v0.8.2/src/graph/extract.ts). On Checkmate, those extractors covered the server and web application well.

They did not cover Swift or SQL.

When I asked Graft for a skeleton of the iOS `LocalStore.swift` file, it reported no indexed definitions. Roam returned 47 symbols from that file, including properties and methods. Its index also included 38 Swift files and 11 SQL files, plus documentation and configuration formats.

If all of your important code is written in languages Graft supports, this gap may not be a factor for you. Even then, relying on one index for the whole repository is easier to standardize than routing agents between overlapping tools. For Checkmate, the gap disqualifies Graft as the primary index. The iOS app is not an attachment to the system. It is one of the system's clients.

<img alt="Language and file coverage in the Checkmate benchmark" />

## Graft returned more direct focused results

Within the languages it supports, Graft returned more direct results on the focused queries.

Its caller query for `Store.Sync` correctly found `Server.handleSync`. Its free-form query about `CHECKMATE_BASE_URL` returned the validation function, the default value, and the configuration loader. There was some unrelated web code in the result, but the important paths were near the top.

Roam's exact symbol lookup also found `Store.Sync`. The response included its definition, one caller, eight callees, and useful body context. A separate `uses` query found the production consumer.

Two plausible Roam query forms exposed a rough edge. `roam uses Store.Sync` and a file-qualified variation failed even though Roam's search had already found the symbol. The command-specific path worked.

The broad architectural question exposed a different problem. Graft returned partial server-side matches but could not include the iOS implementation because it had never indexed Swift. Roam had indexed both clients and the server, yet its free-form `ask` command returned no confident recipe match.

Graft's answer was incomplete because Swift was outside its index. Roam had the source material but its free-form router did not assemble it into an answer.

Test the commands an agent will actually call. Language count and graph size do not predict retrieval quality. A successful demo query does not predict it either.

## Roam added change analysis, with caveats

Roam's broader feature set becomes useful before and after edits. It can report symbol context, impact, affected tests, git-aware changes, and pull request risk. This is closer to an engineering safety layer than a search index.

On the recurrence module, `roam preflight` reported a 56-symbol blast radius and identified 29 direct plus 13 transitive tests. That is the kind of context I want before modifying shared scheduling logic.

The suggested test command was `pytest`, however. Checkmate's recurrence code is Go. The graph relationships were valuable; the execution advice was wrong.

On `Store.Sync`, affected-test analysis returned no tests even though the repository has HTTP synchronization tests. Static analysis is the likely reason. Dynamic route registration does not always create an edge that a code graph can follow. Roam documents similar limitations around dynamic dispatch, reflection, heuristic imports, cross-language FFI, and generic language support.

Treat the analysis as a lead. A reported test is a strong reason to run that test. An empty test list is not proof that no test matters.

The same rule applies to pull request risk. A score can focus review, but it cannot replace reading the diff and running the relevant test suite. I now require agents to include the final `roam pr-risk` value and material findings in every pull request they create. If Roam cannot calculate a value, the pull request must say so.

## Freshness and data sharing

Graft's normal structural build is local. Since version 0.8.1, its integrations can refresh structural data automatically when the graph is stale. Deep summaries do not refresh automatically; they require another deep build. Its graph is now a local, gitignored cache, despite older documentation that described committing graph data.

Roam also keeps its main analysis local in a SQLite graph. Index freshness is explicit. The agent needs to run or refresh `roam index`. That is easy to encode in a project workflow, but it is still a behavior to enforce. Roam can download grammar packs on first use, and optional AI summary features can send structured reports and code snippets to a configured model. Its [documentation on data sent over the network](https://github.com/Cranot/roam-code/blob/v13.10.0/docs/network-boundary.md) is worth reading before enabling those features.

For regulated or private codebases, document which commands stay local, which send data over the network, and exactly what they send.

## Indexing is doing two jobs

The benchmark stopped feeling contradictory once I separated the products into two layers.

One layer retrieves context. It should be focused, easy for an agent to call, and good at returning the smallest useful slice of code. Graft is strong here. Its default set of MCP tools is small, and its free-form retrieval worked well on Checkmate's Go and TypeScript code.

The other layer supports change analysis. It should cover the repository, represent relationships, use history, estimate blast radius, point to tests, and summarize pull request risk. Roam is aiming at this broader job.

One number cannot express that tradeoff. A focused retrieval layer can fit a service written in its supported languages. A broader engineering graph can fit a multi-language product. Some teams may want both, provided agents know which tool answers which question.

<img alt="A practical decision guide for choosing Graft, Roam, or both" />

## Which one should you choose?

Choose Graft first when:

* Your important code is JavaScript, TypeScript, Python, or Go.
* Your main goal is compact context retrieval for coding agents.
* You want a small set of MCP tools with useful free-form search.
* Automatic structural freshness matters more than deep change analysis.

Choose Roam first when:

* The repository spans languages outside Graft's current set.
* You need exact symbol navigation across a larger graph.
* You want preflight, impact, affected-test, diff, health, or pull request risk analysis.
* You are prepared to standardize the command workflow and verify imperfect recommendations.

Prefer one index when it covers the repository and answers the questions your team asks regularly. One workflow is easier to configure, teach, and verify. Consider using both only when:

* Graft's supported languages contain most day-to-day implementation work.
* Roam's broader graph is still needed for repository coverage and change safety.
* The benefit of combining them outweighs the added setup and maintenance.
* You can give agents explicit routing rules instead of letting them guess between two overlapping tools.

Graft and Roam are not the only options. Commercial coding assistants and code-search platforms have their own indexes, and other open-source projects are available. I focused on these two because they were the open-source options I saw most often on GitHub when I ran this comparison. This is a close look at two visible projects, not an exhaustive survey.

Do not choose either from a README benchmark alone. Clone one of your real repositories and test five or ten questions your team asks every week. Include one cross-language workflow, one symbol with dynamic callers, one configuration path, one recent refactor, and one change where you already know the relevant tests. Pay close attention to the misses.

## My decision for Checkmate

I am keeping Roam as Checkmate's primary index.

The decision rests on the 38 Swift files and 11 SQL files that Graft could not represent. I do not want an agent answering architectural questions from a graph that silently ends at the server and web client.

I may still use Graft as a focused companion for Go and TypeScript retrieval. Its direct queries were often pleasant to use. I would not treat it as the system of record for this repository today.

An index determines what your coding agent can see, what it can connect, and what it can miss while sounding confident. That makes the index part of the agent's context-selection and review workflow.

Start by opening the graph and asking which parts of your product are absent. On Checkmate, that check decided the outcome.

## Sources and reproducibility notes

* [NanoNets/Graft repository and documentation](https://github.com/NanoNets/Graft)
* [Graft 0.8.2 source](https://github.com/NanoNets/Graft/tree/v0.8.2)
* [Graft 0.8.2 language extractors](https://github.com/NanoNets/Graft/blob/v0.8.2/src/graph/extract.ts)
* [Cranot/roam-code repository and documentation](https://github.com/Cranot/roam-code)
* [roam-code 13.10.0 release](https://github.com/Cranot/roam-code/releases/tag/v13.10.0)
* [roam-code 13.10.0 data sharing and network behavior](https://github.com/Cranot/roam-code/blob/v13.10.0/docs/network-boundary.md)

Benchmark retrieved and run on August 4, 2026. Timings are wall-clock CLI measurements on one machine and one repository. They should be reproduced on your own codebase before making a tooling decision.


# Making coding agents (Claude Code, Codex, etc.) reliable
Source: https://developer.upsun.com/posts/ai/making-coding-agents-reliable

The bottleneck for AI coding agents isn't model capability. It's your verification infrastructure. Here's how to fix that.

<PostMeta />

## The promise

<Note>
  Point an agent at a ticket. Come back to a working merged PR.
</Note>

That's the pitch every engineering team is hearing right now. Tools like Claude Code, Cursor, Windsurf, and GitHub Copilot keep getting better at generating code. The demos are impressive. The benchmarks keep climbing. And your timeline is full of people showing off AI-written features shipping to production.

## But here's what actually happens

You point an agent at a ticket. It reads the codebase, picks a direction, and starts writing code. Twenty minutes later, you've got a PR with 400 lines of changes. It looks reasonable. The syntax is correct. The logic seems plausible.

Then you start looking closer. The code doesn't match your team's conventions. It makes assumptions about how a service behaves that haven't been true since the last refactor. It passes the tests that exist but misses an edge case your test suite doesn't cover. The build succeeds locally but fails in CI because of a dependency your dev environment handles differently.

**Issues and unknowns everywhere. The agent generated code. It didn't ship a feature or a fix.**

Most organizations are stuck comparing benchmarks at this point. Which model scores 2% higher on SWE-bench? Which agent completes more tasks? These comparisons miss the point entirely.

## The real bottleneck

The bottleneck isn't the agent's or the model's ability to write code. It's your ability to give it quality input and verify the output.

Without clear intent and verification, **AI-generated code is text. Text that might work. Text that might break production.** You won't know until a human reviews every line, runs manual tests, and crosses their fingers during deployment. That's not autonomy. That's a more sophisticated autocomplete.

The question isn't "how smart is the model?" The question is: can your infrastructure tell the model whether it got the answer right?

## Software 2.0: a new programming paradigm

Andrej Karpathy recently articulated a distinction that reframes how to think about AI's impact on software:

> "Software 1.0 easily automates what you can specify. Software 2.0 easily automates what you can verify."

In Software 1.0, you write explicit algorithms by hand. If you can specify the rules, you can automate the task. The key question is: *is the algorithm fixed and can you specify it?*

Software 2.0 works differently. You specify objectives and search through the space of possible solutions. If you can verify whether a solution is correct, you can optimize for it. The key question becomes: *is the task verifiable?*

Karpathy defines the requirements for this to work. The environment has to be resettable (you can start a new attempt), efficient (you can make many attempts), and rewardable (there's an automated process to evaluate each attempt).

This is why AI progress follows a "jagged frontier." Tasks that are highly verifiable (math, coding, formal logic) advance the fastest. Tasks that are hard to verify (creative writing, strategic planning, design taste) progress more slowly. It's not about difficulty. It's about whether you can automate the feedback loop.

```mermaid theme={null}
flowchart LR
    subgraph sw1["Software 1.0"]
        A["Specify algorithm"] --> B["Write code by hand"] --> C["Deploy"]
    end

    subgraph sw2["Software 2.0"]
        D["Specify objectives"] --> E["AI generates candidates"] --> F["Infrastructure verifies"]
        F -->|"Pass"| G["Deploy"]
        F -->|"Fail"| E
    end

    sw1 ~~~ sw2

    style A fill:#f9f9f9,stroke:#333
    style B fill:#f9f9f9,stroke:#333
    style C fill:#f9f9f9,stroke:#333
    style D fill:#D2F405,stroke:#333
    style E fill:#D2F405,stroke:#333
    style F fill:#6046FF,stroke:#fff,color:#fff
    style G fill:#D2F405,stroke:#333
```

## The asymmetry of verification

Jason Wei, researcher at Meta (formerly OpenAI), formalized a related concept: many tasks are far easier to verify than to solve.

Think about Sudoku. Solving a puzzle takes time and concentration. Verifying a completed grid takes seconds: check each row, column, and box.

This asymmetry exists on a spectrum. On one end, tasks like Sudoku, math proofs, and code tests are easy to verify, because there's a clear right answer. In the middle, tasks like arithmetic and data processing are symmetric, with roughly equal effort to solve and check. On the far end, tasks like writing essays, forming hypotheses, and creative work are hard to verify, because quality is subjective and slow to evaluate.

```mermaid theme={null}
flowchart LR
    subgraph easy["Easy to verify"]
        E1["Sudoku"]
        E2["Math proofs"]
        E3["Code tests"]
    end

    subgraph mid["Symmetric"]
        M1["Arithmetic"]
        M2["Data processing"]
    end

    subgraph hard["Hard to verify"]
        H1["Essay writing"]
        H2["Hypothesis forming"]
        H3["Creative work"]
    end

    easy ~~~|"AI advances fastest"| mid ~~~|"AI advances slowest"| hard

    style E1 fill:#D2F405,stroke:#333
    style E2 fill:#D2F405,stroke:#333
    style E3 fill:#D2F405,stroke:#333
    style M1 fill:#f9f9f9,stroke:#333
    style M2 fill:#f9f9f9,stroke:#333
    style H1 fill:#ff6b6b,stroke:#333,color:#fff
    style H2 fill:#ff6b6b,stroke:#333,color:#fff
    style H3 fill:#ff6b6b,stroke:#333,color:#fff
```

Wei identifies five properties that make a task verifiable:

1. **Objective truth**: there's a clear definition of correctness
2. **Fast to verify**: checking takes seconds, not hours
3. **Scalable**: you can verify many solutions in parallel
4. **Low noise**: verification results correlate tightly with actual quality
5. **Continuous reward**: you can rank solutions on a gradient, not pass/fail

**The ease of training AI to solve a task is proportional to how verifiable the task is. If a task is possible to solve and easy to verify, AI will solve it.**

## Code is highly verifiable

Here's the good news: software development is one of the most verifiable domains that exists.

You can run tests. You can check types. You can lint for style violations. You can deploy to a preview environment and confirm the feature works. You can measure performance before and after a change. You can scan for security vulnerabilities automatically.

Software engineering has spent decades building verification infrastructure across eight distinct areas: testing, documentation, code quality, build systems, dev environments, observability, security, and standards. This accumulated infrastructure makes code one of the most favorable domains for AI agents.

That's why coding agents are the most advanced AI agents in the world right now. Not because code is simple (it isn't). Because code is verifiable, **when your infrastructure supports it**.

## Why humans cope but agents crash

But most codebases don't fully support and provide these pillars.

Human engineers are resilient. They work around incomplete infrastructure every day. Your team has 60% test coverage? A senior developer fills the gaps with intuition and careful review. Documentation is outdated? Someone asks a colleague or digs through Slack history. The build is flaky? Hit retry and hope it passes. No staging environment? Test in production and fix forward.

These workarounds are inefficient, but humans adapt. They carry institutional knowledge, pattern recognition, and contextual judgment. They know which code paths are risky. They know which tests to trust and which to ignore.

AI agents can't do any of this. They have no institutional knowledge. No intuition. No context beyond what you explicitly provide.

```mermaid theme={null}
flowchart LR
    subgraph human["Human Engineer"]
        H1["60% test coverage"] --> H2["Fills gaps with intuition"]
        H3["Flaky builds"] --> H4["Retries manually"]
        H5["Missing docs"] --> H6["Asks teammates"]
        H7["No staging"] --> H8["Tests in production"]
    end

    subgraph agent["AI Agent"]
        A1["60% test coverage"] --> A2["Cannot validate"]
        A3["Flaky builds"] --> A4["Stuck in retry loops"]
        A5["Missing docs"] --> A6["Wrong assumptions"]
        A7["No staging"] --> A8["Ships blind"]
    end

    H2 --> HR["Ships code ✓"]
    H4 --> HR
    H6 --> HR
    H8 --> HR

    A2 --> AR["Fails or produces slop ✗"]
    A4 --> AR
    A6 --> AR
    A8 --> AR

    style HR fill:#D2F405,stroke:#333
    style AR fill:#ff6b6b,stroke:#333,color:#fff
```

## What breaks agents

When verification infrastructure is missing, every gap becomes a wall:

* **No tests** → the agent can't validate whether its changes work
* **No specs or documentation** → the agent makes wrong assumptions about how the system behaves
* **Flaky builds** → the agent can't distinguish its own bugs from infrastructure problems
* **No observability** → the agent can't infer the result of an actual deployment
* **No preview environments** → the agent ships blind

Most organizations have partial infrastructure across these areas. Humans cope with 50-60% coverage. Agents need systematic coverage to succeed.

## The result: "AI slop"

Without verification, you get code that looks plausible but subtly degrades your codebase over time. Eno Reyes, CEO at Factory (an AI coding agent company), calls this the inevitable outcome when agents operate without sufficient validation criteria.

The code compiles. It might even pass the few tests that exist. But it introduces inconsistencies, ignores conventions, misses edge cases, and accumulates technical debt faster than your team can review it.

**That's not a model problem. That's an infrastructure problem. And it has an infrastructure solution.**

## Spec-driven development: lock intent before implementation

The first part of the solution is about input quality. Before your agent writes a single line of code, it needs to know what "correct" looks like.

This is the principle behind spec-driven development: lock intent before implementation.

### Traditional vs. spec-driven workflow

The traditional approach with AI agents looks like this:

**Prompt agent → Generate code → Hope it works**

This is unreliable, hard to debug, and doesn't scale.

The spec-driven approach inverts the process:

**Write specs + tests → Generate code → Validate → Iterate**

This is reliable, debuggable, and scales to complex tasks. Research from Ion Stoica, Matei Zaharia, and others at Berkeley confirms this pattern: when you combine specifications with validation loops, AI-generated code quality improves dramatically.

```mermaid theme={null}
flowchart TB
    subgraph traditional["Traditional workflow"]
        T1["Vague prompt"] --> T2["Agent generates code"] --> T3["Hope it works"]
        T3 -->|"Fails"| T4["Human debugs manually"]
    end

    subgraph specdriven["Spec-driven workflow"]
        S1["Write specs + tests"] --> S2["Agent generates candidates"] --> S3["Automated validation"]
        S3 -->|"Pass"| S4["Ship with confidence"]
        S3 -->|"Fail + feedback"| S2
    end

    traditional ~~~ specdriven

    style T3 fill:#ff6b6b,stroke:#333,color:#fff
    style T4 fill:#ff6b6b,stroke:#333,color:#fff
    style S1 fill:#6046FF,stroke:#fff,color:#fff
    style S3 fill:#6046FF,stroke:#fff,color:#fff
    style S4 fill:#D2F405,stroke:#333
```

### The three-step process

Spec-driven development follows three steps:

**1. Define specs.** Write tests, define types, and describe expected behavior before any code generation happens. This includes unit or e2e tests for the new feature, integration contracts with existing systems, and type definitions for new interfaces.

**2. Generate solutions.** The agent produces multiple candidate implementations. With clear specs, it can explore the solution space efficiently. If the first attempt fails validation, it tries a different approach, informed by the specific failure rather than guessing randomly.

**3. Validate and select.** Run the test suite. Check type safety. Verify linter compliance. Pick the implementation that passes all checks. If none pass, the agent gets specific feedback about what failed and iterates.

```mermaid theme={null}
flowchart LR
    D[Define specs and tests] --> G[Generate code] --> V[Validate]
    V -->|Pass| S[Ship]
    V -->|Fail| G

    style D fill:#6046FF,stroke:#fff,color:#fff
    style G fill:#D2F405,stroke:#333
    style V fill:#6046FF,stroke:#fff,color:#fff
    style S fill:#D2F405,stroke:#333
```

### Why this works

Specs lock intent, so there's no ambiguity about what the code should do. Changes become reviewable, because scope is transparent and diff-able. Success criteria are clear: tests pass or they don't. Debugging becomes tractable, because you know what *should* happen and can pinpoint where it diverges.

With strong verification, you can search for solutions instead of crafting them by hand. Engineering problems become search problems. And search is what AI does best.

Tools like [OpenSpec](https://github.com/Fission-AI/OpenSpec) are emerging to support this workflow. OpenSpec generates structured proposals, task breakdowns, and specifications from a single prompt. You review and approve the spec before implementation begins. The agent then works from an approved plan rather than improvising from a vague description.

## The 8 pillars of verification

Spec-driven development handles the input side. But you also need infrastructure to verify the output. This is where the 8 pillars come in.

Getting your codebase agent-ready requires systematic coverage across eight areas. Gaps in any pillar limit agent autonomy. Not every organization needs perfection in all eight, but each gap represents a ceiling on what agents can accomplish without human intervention.

```mermaid theme={null}
flowchart TB
    subgraph row1[" "]
        direction LR
        P1[Testing] ~~~ P2[Documentation] ~~~ P3[Code quality] ~~~ P4[Build systems]
    end

    subgraph row2[" "]
        direction LR
        P5[Dev environments] ~~~ P6[Observability] ~~~ P7[Security] ~~~ P8[Standards]
    end

    row1 ~~~ row2

    style P1 fill:#D2F405,stroke:#333
    style P2 fill:#D2F405,stroke:#333
    style P3 fill:#D2F405,stroke:#333
    style P4 fill:#D2F405,stroke:#333
    style P5 fill:#D2F405,stroke:#333
    style P6 fill:#D2F405,stroke:#333
    style P7 fill:#D2F405,stroke:#333
    style P8 fill:#D2F405,stroke:#333
    style row1 fill:none,stroke:none
    style row2 fill:none,stroke:none
```

### 1. Testing: the foundation

Tests are the most direct form of verification. A failing test is an unambiguous signal. A passing test suite is evidence (not proof) of correctness.

<Note>
  **What agents need:** High coverage so that changes are validated against real expectations. Fast execution so agents can iterate in tight loops. Deterministic results, because flaky tests are worse than no tests. They create noise the agent can't interpret.
</Note>

**Without it:** The agent generates plausible-looking code that breaks in production. You're back to manual review for every change.

As Eno Reyes puts it, "a slop test is better than no test." An imperfect AI-generated test that passes when changes are correct and fails when they aren't is still a useful signal. Other agents will notice these tests, follow the patterns, and the coverage compounds over time.

### 2. Documentation and specs: the context layer

Documentation tells the agent *why* code is structured a certain way, not just *what* it does. API specs, architecture decision records, and integration guides provide the context that agents lack by default.

<Note>
  **What agents need:** Up-to-date documentation that describes system behavior, integration points, and known limitations. Edge cases and gotchas that aren't captured in tests. Historical context about why certain decisions were made.
</Note>

**Without it:** The agent makes wrong assumptions. It breaks contracts between services. The codebase becomes harder to maintain because the agent can't understand existing patterns.

This is the one pillar that's entirely a team responsibility. No platform can generate your documentation for you. But agents themselves can help: generating API docs from code, updating READMEs, and maintaining architecture diagrams are all verifiable tasks where agents already perform well.

### 3. Code quality: the standards enforcer

Linters, formatters, type checkers, static analysis. These tools encode your team's conventions into automated checks.

<Note>
  **What agents need:** Strict enforcement where linter failure means the build fails, not a warning to ignore. Automated gates that are requirements, not suggestions. Clear error messages that explain what violated which rule.
</Note>

**Without it:** The agent generates inconsistent code. Each PR introduces slightly different patterns. The codebase becomes unpredictable and technical debt accumulates.

The key distinction: if a human can ignore a linter warning, so can an agent. Gates must be gates.

### 4. Build systems: the reproducibility layer

Builds must be deterministic. Same commit, same result. Every time.

<Note>
  **What agents need:** Reproducible builds where the same commit produces the same environment. Fast failure where errors surface immediately with clear messages. No mystery failures, because "works on my machine" is invisible to agents.
</Note>

**Without it:** The agent can't distinguish its bugs from infrastructure problems. It wastes cycles retrying builds that fail for reasons unrelated to its code. Phantom errors consume token budget and developer patience.

### 5. Dev environments: the experimentation space

Preview environments give agents a safe, production-like space to validate changes before they touch production.

<Note>
  **What agents need:** Production parity where the test environment matches production, including data. Fast provisioning measured in minutes, not hours. Isolation so each experiment runs independently without interference.
</Note>

**Without it:** The agent has no way to confirm changes before production deployment. It ships blind or requires a human to manually verify every change, defeating the purpose of automation.

This is where the economics of verification shift dramatically. Instead of sharing a single staging environment (with all the coordination overhead that implies), each agent can get its own isolated environment. Test freely, break things, iterate, all without blocking anyone else.

### 6. Observability: the feedback signal

When something goes wrong after deployment, observability tools provide the signal to understand what happened.

<Note>
  **What agents need:** Structured logs in JSON format, not unstructured text dumps. Clear metrics with baselines, error rates, and resource utilization. Actionable traces and performance profiles that connect errors back to specific code paths.
</Note>

**Without it:** The agent can't debug failures. It can't determine whether a change introduced a regression. Post-deployment verification becomes impossible without a human reading logs manually.

### 7. Security: the safety gate

AI-generated code must meet the same security standards as human-written code. Without automated scanning, agents can introduce vulnerabilities faster than your security team can review them.

<Note>
  **What agents need:** Automated scanning that runs on every change, every time. Dependency audits for every package on a recurring basis. Clear reports that specify what's wrong and how to fix it. Secrets management that prevents hardcoded credentials.
</Note>

**Without it:** The agent introduces vulnerabilities. Issues accumulate undetected. Breach risk increases with every unscanned PR.

### 8. Standards: the consistency framework

Coding conventions, architectural patterns, naming rules. Consistency makes codebases predictable, which helps agents understand and extend existing code correctly.

<Note>
  **What agents need:** Documented conventions that are written down, not tribal knowledge. Tooling enforcement through automation, not code review comments. Pattern libraries with examples of how things should be done.
</Note>

**Without it:** The agent generates code that works but doesn't fit. Every PR introduces a slightly different style. The codebase becomes unpredictable and harder for both humans and agents to maintain.

## Where does Upsun fit?

Upsun doesn't cover all eight pillars. Documentation and some aspects of standards are application-level concerns your team owns. But Upsun provides infrastructure for the pillars that matter most to deployment and verification.

```mermaid theme={null}
flowchart LR
    subgraph team["Your team owns"]
        D["Documentation: Specs, guides"]
    end

    subgraph upsun["Upsun provides"]
        T["Testing: Preview envs with production data"]
        CQ["Code quality: Build hook enforcement"]
        B["Build systems: Git-driven reproducible builds"]
        DE["Dev environments: Instant clones per branch"]
        O["Observability: Blackfire APM + metrics"]
        S["Security: TLS, WAF data sanitization"]
        ST["Standards: YAML-defined conventions"]
    end

    T --> V["Verification Layer"]
    CQ --> V
    B --> V
    DE --> V
    O --> V
    S --> V
    ST --> V
    D -.->|"Team responsibility"| V

    V --> SHIP["Ship with confidence"]

    style V fill:#6046FF,stroke:#fff,color:#fff
    style SHIP fill:#D2F405,stroke:#333
    style D fill:#f9f9f9,stroke:#999,stroke-dasharray: 5 5
    style T fill:#D2F405,stroke:#333
    style CQ fill:#D2F405,stroke:#333
    style B fill:#D2F405,stroke:#333
    style DE fill:#D2F405,stroke:#333
    style O fill:#D2F405,stroke:#333
    style S fill:#D2F405,stroke:#333
    style ST fill:#D2F405,stroke:#333
```

When an agent pushes to a branch, Upsun spins up a complete clone of production, including your database with optional sanitization. Tests run against real data and real service configurations. If the linter fails, the build fails. If type checks don't pass, deployment stops. The agent gets immediate, unambiguous feedback.

This turns your platform into a verification loop. The agent writes code, pushes to a branch, and the platform answers the question: does this work? If not, here's exactly why.

## The self-assessment

Take a moment and think about which pillar is your biggest gap right now. That's where your agents will struggle most.

For a more thorough audit, you can score your organization across all eight pillars using the [80-criteria verification infrastructure checklist](https://gist.github.com/gmoigneu/a963b595ac238ad2d2260ebb8b29f048). It covers ten specific criteria per pillar and gives you a concrete picture of where to invest.

## The flywheel

Here's where things get interesting. Once you start investing in verification infrastructure, a compounding loop kicks in.

Better infrastructure enables agents to work more autonomously. More autonomy means agents can take on tasks like generating tests, writing documentation, adding type annotations, and improving linter rules. Those improvements make the infrastructure better. Which enables even more autonomy.

Tests. Specs. Types. Coverage. The loop accelerates.

```mermaid theme={null}
flowchart LR
    INF["Improve verification infrastructure"] --> AUTO["Agents gain autonomy"]
    AUTO --> TASKS["Agents improve tests, docs, types, linter rules"]
    TASKS --> INF

    style INF fill:#6046FF,stroke:#fff,color:#fff
    style AUTO fill:#D2F405,stroke:#333
    style TASKS fill:#D2F405,stroke:#333
```

An imperfect AI-generated test is still a test. Other agents will notice it, follow its patterns, and extend it. A junior developer who couldn't use agents effectively yesterday can use them today because the verification gates catch mistakes automatically. One opinionated engineer who invests in writing strict linter rules and comprehensive specs scales their impact across the entire team, and across every agent the team uses.

**This is the new DevX loop. As Eno Reyes puts it, the investment in verification infrastructure is where the real 5-7x velocity gains come from. Not 1.5x. Not 2x. The organizations that build this feedback loop now will reach a development velocity that others can't match.**

## What becomes possible

With strong verification in place, you move beyond single-task code generation to autonomous SDLC processes:

**Large task decomposition.** Migration and modernization projects broken into verifiable subtasks. Each piece gets validated independently before integration. Verification through per-subtask tests, integration tests, and specs.

**Task parallelization.** Multiple agents working in parallel on independent tasks. Isolated preview environments prevent conflicts. Isolated test suites eliminate cross-dependencies. Large migrations complete an order of magnitude faster.

**Automated code review.** Context-aware reviews for every PR that catch bugs, style issues, and architectural problems. Verification through linters, tests, and security scans.

**QA and test generation.** Agents that generate test scenarios, validate edge cases, and improve coverage as the code evolves. Tests must pass and meet coverage metrics to ship.

**Incident response.** An error appears in production. The agent pulls observability data, proposes a fix, deploys to a preview environment, verifies the fix works, and opens a PR, before a human wakes up. Verification through error logs, monitoring metrics, and tests.

**Documentation automation.** Keep docs in sync with code. Generate API documentation, update READMEs, and maintain architecture diagrams. Verification through doc builds, working examples, and valid links.

Each of these processes relies on your verification infrastructure. The better your specs, tests, and validation, the more reliably they run.

## The path forward

If you want AI agents that ship code, not generate text, the investment is in verification infrastructure. Here's the sequence:

**1. Assess.** Measure your verification infrastructure across all eight pillars. Score each one honestly. Identify the gaps.

**2. Improve.** Systematically address those gaps through automated fixes. Use agents themselves to write tests, add type annotations, tighten linter rules, and generate documentation. Start where the leverage is highest: testing and build systems.

**3. Deploy.** Roll out AI agents that can use your specifications and verification gates. Match the level of supervision to the strength of each pillar. Strong verification means less oversight required.

**4. Iterate.** The flywheel spins. Continuous feedback improves both your specs and your agents. Each improvement compounds.

<Note>
  **The limit isn't the AI. It's your infrastructure. Build the verification layer, and the autonomy follows.**
</Note>

Ready to build the verification infrastructure your AI agents need? Upsun provides preview environments, reproducible builds, and integrated observability out of the box. [Create a free account](https://upsun.com) and deploy your first project in minutes.

## References

* Karpathy, A. (2025). "Verifiability." [karpathy.bearblog.dev/verifiability](https://karpathy.bearblog.dev/verifiability/)
* Wei, J. (2025). "Asymmetry of verification and verifier's law." [jasonwei.net/blog](https://www.jasonwei.net/blog/asymmetry-of-verification-and-verifiers-law)
* Reyes, E. (2025). "Verification Infrastructure for AI Agents." Factory AI talk.
* OpenSpec. [github.com/openspec/openspec](https://github.com/FissionAI/openspec)
* Guillaume Moigneu (2026). "The 8 Pillars of Verification Infrastructure Checklist." [gist.github.com](https://gist.github.com/gmoigneu/a963b595ac238ad2d2260ebb8b29f048)


# How to Host OpenCode on Upsun
Source: https://developer.upsun.com/posts/ai/opencode-on-upsun

Deploy an OpenCode AI coding agent on Upsun with a single git push. This tutorial covers configuration, persistent storage, LLM API keys, and remote MCP server integration.

<PostMeta />

> [**OpenCode**](https://opencode.ai/) is an open-source AI coding agent built for the terminal. This guide walks you through deploying an
> OpenCode server instance on [Upsun](https://upsun.com), a git-driven PaaS (powered by Platform.sh) that makes it easy
> to deploy applications with a single `git push`.

## Prerequisites

Before starting, make sure you have:

* An [Upsun account](https://auth.upsun.com/register) (15-day free trial available)
* The [Upsun CLI](/cli/install#install-the-upsun-cli) installed
* [Git](https://git-scm.com/) installed
* An API key for at least one LLM provider (e.g., Anthropic, OpenAI, Google Gemini)

## Overview

[OpenCode](https://opencode.ai/) is an application with a client/server architecture.
In this tutorial, you deploy the **OpenCode server** on Upsun and connect to it remotely.
The server exposes an HTTP API, which allows you to drive OpenCode from any client (TUI, IDE extension, or web) without
having the agent running locally.

The deployment relies on a `nodejs:24` runtime, persistent storage for the SQLite database that stores conversation
sessions, environment variables to securely pass LLM API keys, and routes to expose the server over HTTPS.

## Step 1 - Set up your project

Clone or initialize a repository that contains your OpenCode configuration. If you are starting from scratch, create a new directory:

```bash title="Terminal" theme={null}
mkdir opencode-upsun
cd opencode-upsun
git init
```

## Step 2 - Create the Upsun configuration

At the root of your project, create the `.upsun/` directory and add a `config.yaml` file:

```bash title="Terminal" theme={null}
mkdir .upsun
touch .upsun/config.yaml
```

Here is the full configuration:

<Tabs>
  <Tab title="Using NodeJS dependencies">
    ```yaml .upsun/config.yaml theme={null}
    applications:
      opencode:
        type: "nodejs:24"
        container_profile: "HIGH_MEMORY"
        source:
          root: /
        # Persistent mounts for OpenCode's SQLite database and config
        mounts:
          "/.local": {source: storage, source_path: "opencode-data"}
          "/.config/opencode": {source: storage, source_path: "opencode-config"}
          "/.agents": {source: storage, source_path: "opencode-agents"}
          "/.opencode": {source: storage, source_path: "opencode-source"}
        dependencies:
          nodejs:
            opencode-ai: "*" # OpenCode
            upsun: "*"       # Upsun CLI
        hooks:
          build: |
            set -ex

            echo "Install Upsun Skills..."
            npx skills add https://github.com/upsun/ai --skill upsun -g -y
            echo "Upsun Skills installed at $PLATFORM_APP_DIR/node_modules/.bin/upsun-mcp"
          deploy: |
            # Generate OpenCode config with the correct MCP server URL and API token
            envsubst < /app/opencode.json > /app/.config/opencode/opencode.json

        # Environment variables — API keys are injected as Upsun secrets
        variables:
          env:
            OPENCODE_THEME: "opencode"
            HOME: "/app"

        # Web configuration: route all traffic to the OpenCode HTTP server
        web:
          commands:
            start: "opencode serve --port $PORT"

    routes:
      "https://opencode.{default}/":
        type: upstream
        upstream: "opencode:http"
    ```
  </Tab>

  <Tab title="Using install-github-asset.sh script">
    ```yaml .upsun/config.yaml theme={null}
    applications:
      opencode:
        type: "nodejs:24"
        container_profile: "HIGH_MEMORY"
        source:
          root: /
        # Persistent mounts for OpenCode's SQLite database and config
        mounts:
          "/.local": {source: storage, source_path: "opencode-data"}
          "/.config/opencode": {source: storage, source_path: "opencode-config"}
          "/.agents": {source: storage, source_path: "opencode-agents"}
          "/.opencode": {source: storage, source_path: "opencode-source"}
        hooks:
          build: |
            set -ex
            
            echo "Downloading OpenCode..."
            curl -fsS https://raw.githubusercontent.com/upsun/snippets/main/src/install-github-asset.sh | bash /dev/stdin "anomalyco/opencode" "" "opencode-linux-x64.tar.gz"
            echo "OpenCode installed at $PLATFORM_APP_DIR/bin/opencode"

            echo "Install Upsun Skills..."
            npx skills add https://github.com/upsun/ai --skill upsun -g -y
            echo "Upsun Skills installed at $PLATFORM_APP_DIR/node_modules/.bin/upsun-mcp"

            echo "Install Upsun CLI..."
            curl -fsSL https://raw.githubusercontent.com/upsun/cli/main/installer.sh | bash
            echo "Upsun CLI installed at $(which upsun)"
          deploy: |
            # Generate OpenCode config with the correct MCP server URL and API token
            envsubst < /app/opencode.json > /app/.config/opencode/opencode.json

        # Environment variables — API keys are injected as Upsun secrets
        variables:
          env:
            OPENCODE_THEME: "opencode"
            HOME: "/app"

        # Web configuration: route all traffic to the OpenCode HTTP server
        web:
          commands:
            start: "opencode serve --port $PORT"

    routes:
      "https://opencode.{default}/":
        type: upstream
        upstream: "opencode:http"
    ```
  </Tab>
</Tabs>

Because Upsun's filesystem is read-only after the build step, the [`mounts`](/docs/configure-apps/image-properties/mounts#mounts) section defines writable directories so OpenCode can persist its SQLite database (sessions, conversations) and its config file across deploys.

The [`hooks.build`](/docs/configure-apps/hooks/index#use-build-and-deploy-hooks) section downloads and installs the OpenCode binary before the container starts, installs the Upsun skills (which include the MCP server), and the Upsun CLI.

The [`web.commands.start`](/docs/configure-apps/image-properties/web#start-command) section launches OpenCode in server mode. Upsun injects `$PORT` automatically, and your app must listen on that port.

Finally, [`routes`](/docs/routes) maps your project's default domain to the OpenCode HTTP server.

<Info>
  <h4>`install-github-asset.sh` script</h4>
  If you want to learn more about the script used to download OpenCode, check out the [Up(sun) and ready with GitHub release assets installation](/posts/hands-on/install-gh-asset-on-upsun/).
  It's a reusable script that can download any asset from any GitHub release, and is especially useful in Upsun build
  hooks where you want to fetch the latest version of a tool only once and, without hardcoding a specific version number.
</Info>

## Step 3 - Create the OpenCode configuration

OpenCode uses an `opencode.json` file to configure the server application.
This file configures the Upsun MCP server as a remote MCP server for OpenCode,
which allows OpenCode to execute commands on the Upsun platform and interact with its resources.

Create an `opencode.json` file at the root of your repository with the following content:

```json title="opencode.json" theme={null}
{
  "mcp": {
    "upsun": {
      "type": "remote",
      "url": "https://mcp.upsun.com/mcp",
      "headers": {
        "upsun-api-token": "${UPSUN_CLI_TOKEN}",
        "enable-write": "true"
      },
      "enabled": true
    }
  }
}
```

<Warning>
  The `"enable-write": "true"` header grants the OpenCode agent write access to your Upsun resources
  (creating environments, pushing code, changing variables, etc.). Remove this header or set it to `"false"`
  if you want read-only access.
</Warning>

## Step 4 - Commit your code

Commit your configuration:

```bash title="Terminal" theme={null}
git add .upsun/config.yaml opencode.json
git commit -m "Add Upsun and OpenCode configuration"
```

## Step 5 - Create the Upsun project

[Create a new Upsun project](/docs/get-started/here/create-project) linked to your local repository:

```bash title="Terminal" theme={null}
upsun project:create --title "opencode-server"
```

## Step 6 - Add your API keys as environment variables

Never commit API keys to your repository.
Use Upsun's [variable system](/docs/development/variables/index) instead.

```bash theme={null}
# Set your OpenAI API key as a sensitive variable
upsun variable:create --name env:OPENAI_API_KEY \
  --value sk-... \
  --sensitive true \
  --level project

# Or set your Claude API key as a sensitive variable
upsun variable:create --name env:ANTHROPIC_API_KEY \
  --value sk-... \
  --sensitive true \
  --level project

# Set the OpenCode server password
upsun variable:create --name env:OPENCODE_SERVER_PASSWORD \
  --value "<SECURE_PASSWORD>" \
  --sensitive true \
  --level project

# Set the Upsun API token (optional, for Upsun skill integration)
upsun variable:create --name env:UPSUN_CLI_TOKEN \
  --value "<UPSUN_API_TOKEN>" \
  --sensitive true \
  --level project
```

Sensitive variables are encrypted at rest and injected into the container at runtime. They will not appear in build logs.

You can also set them via the Upsun Console under **Settings → Variables**.

<Info>
  <h4>`OPENCODE_SERVER_PASSWORD` note</h4>
  By default, OpenCode's server mode requires a password for authentication.
  You can set this password via the `OPENCODE_SERVER_PASSWORD` environment variable.
  If you prefer to disable authentication (not recommended for production), you can set `OPENCODE_SERVER_PASSWORD` to an empty string.
</Info>

## Step 7 - Deploy

Push your code to Upsun:

```bash theme={null}
upsun push
```

Upsun will:

1. Validate your `.upsun/config.yaml`
2. Spin up a Node.js 24 container
3. Run the build hook:
   * downloading the OpenCode binary
   * installing the Upsun skills and MCP server
   * installing the Upsun CLI
4. Run the deploy hook, which generates the OpenCode config file with the correct MCP server URL and API token
5. Mount writable storage for the database and config
6. Start the OpenCode server on the assigned port
7. Route HTTPS traffic to it

Once complete, Upsun will display your app URL, something like:

```
https://main-abc123-yourproject.eu-5.platformsh.site
```

<Info>
  <h4>Login</h4>
  Open the URL in your browser. If you set `OPENCODE_SERVER_PASSWORD`, log in with the username `opencode` and
  the password you configured. You can also connect from the OpenCode TUI client by pointing it to the same URL.
</Info>

## Step 8 - Ask OpenCode to do something

OpenCode is now able to receive your commands from the TUI, execute them on the server, and return results.

Examples:

List existing organizations:

```
List organizations in the Upsun project
```

<Accordion title="Advanced: deploy a Symfony Demo app in a preview environment">
  Create a new Symfony application in a `symfony` subfolder and test it in a preview environment:

  ```
  You are in an existing Git repository linked to an existing Upsun project via PLATFORM_PROJECT.
  Use the Upsun skill, Upsun MCP, the Upsun CLI if available, and Git.

  Goal:
  On the current Upsun Project, add a new Symfony Demo application
  (use `symfony new app --demo --upsun` to generate it) in a new active
  environment named add-symfony-demo.
  - Symfony demo app `app` will be in a subfolder `symfony` at the root of
    the source code and the new app will point to that folder via source.root,
    will be accessible through the default route {default} and, must use
    Postgresql and Redis services.
  - Preserve existing source code and configuration, and add the existing
    Symfony demo configuration (--upsun option) to the main .upsun/config.yaml
  - Do not delete opencode.
  - Work only on the new environment.
  - Load the database schema and fixtures during first deploy.
  - You can use /tmp folder to install what you need.
  - Use the Upsun CLI to interact with the platform, do not use the API directly.
  ```
</Accordion>

You can test the new config without affecting your production instance. Merge the branch when satisfied, and Upsun
redeploys production.

## Troubleshooting

### The server does not start / PORT is not set

Upsun automatically injects `$PORT` into the environment of the `start` command. Make sure your start command references `$PORT` and that OpenCode's `serve` command accepts a `--port` flag. Check `opencode serve --help` for the exact flag name, as it may vary across versions.

### Sessions are not persisting across deploys

Verify that your mounts are defined correctly in `.upsun/config.yaml` and that the paths match where OpenCode writes its SQLite database. The database path can be checked with:

```bash theme={null}
upsun ssh -- opencode db:path
```

### API key not recognized

Confirm the variable is set in the correct environment:

```bash theme={null}
upsun variable:list
```

Sensitive variables show as `[hidden]` — that is expected. Make sure the variable name matches exactly what OpenCode expects (e.g., `ANTHROPIC_API_KEY`).

### OpenCode is slow to respond

If OpenCode is slow to respond, or stops in the middle of processing, check the resource usage of your Upsun container.
You may need to scale up CPU/RAM if your agent is handling large contexts or multiple conversations.

## What's next?

For the second episode in this series, see [How to slash OpenCode Token costs by 90% on Upsun](/posts/ai/opencode-token-optimization/) to reduce token usage on the deployment you just created.

You can attach a custom domain with `upsun domain:add yourdomain.com` and adjust CPU/RAM
through `upsun resources:set` if the agent handles large contexts or multiple conversations.

To extend OpenCode with additional [MCP server integrations](https://opencode.ai/docs/mcp-servers/),
configure them in `~/.config/opencode/` on the persistent mount. You can also use OpenCode's
[GitHub Actions integration](https://opencode.ai/docs/github/) to trigger the remote server on PR comments.

## Resources

* [OpenCode documentation](https://opencode.ai/docs/)
* [Upsun documentation](/docs)
* [Upsun Node.js runtime reference](/docs/languages/nodejs)
* [Upsun config.yaml reference](/docs/core-concepts/yaml/yaml-structure#upsun-yaml-structure)
* [OpenCode GitHub repository](https://github.com/anomalyco/opencode)


# How to slash OpenCode Token costs by 90% on Upsun
Source: https://developer.upsun.com/posts/ai/opencode-token-optimization

Cut your OpenCode token usage by up to 90% on Upsun with three community plugins: OpenSlimedit, opencode-dcp, and opencode-snip. Step-by-step guide to install and configure them on your existing deployment, with benchmarks, troubleshooting, and best practices.

<PostMeta />

> This is **Part 2** of the OpenCode on Upsun series. If you haven't deployed your OpenCode server yet,
> start with [How to Host OpenCode on Upsun](/posts/ai/opencode-on-upsun/).

Running an AI coding agent in server mode is powerful — but token costs add up quickly. Every API call sends tool
schemas, conversation history, and file contents to the model. On a busy session with multiple file reads and command
outputs, you can easily burn 3x the tokens you actually need.

This guide walks you through installing three community plugins that significantly reduce token usage on your existing
OpenCode deployment on Upsun, with minimal changes to your configuration.

## Why tokens accumulate

Before diving into the fixes, it helps to understand where the waste comes from:

* **Tool descriptions** — OpenCode ships with many built-in tools. Their full descriptions are sent with every API
  call, even when most tools are unused in a given step. This compounds across multi-step tasks.
* **Bash output floods** — Commands like `pytest`, `npm install`, or `docker build` dump hundreds of lines into the
  context. The model processes all of it, including passing test names, deprecation warnings, and progress bars.
* **Stale context** — In long sessions, the model replays conversation history and re-reads files that are no longer
  relevant, inflating context size over time.

Three plugins address each of these root causes independently.

<Note>
  These plugins are community-maintained and not officially endorsed by OpenCode.

  **Always:**
  Check their GitHub repositories for the latest updates and compatibility with your OpenCode version.
  Test in a staging environment before deploying to production.
</Note>

## The plugins

<Info>
  Token reduction percentages are sourced from each plugin's official documentation and may vary based on session
  length, model, and usage patterns.
</Info>

### `OpenSlimedit` — tool description compression

[`OpenSlimedit`](https://github.com/ASidorenkoCode/openslimedit) aggressively shortens all built-in tool descriptions,
compacts file read output, and adds line-range editing support. Because tool schemas are sent with every API call,
compressing them saves thousands of input tokens per step — and this compounds across multi-step tasks.

Benchmarks show **11-45% token reduction** across tested models, with zero regressions on Claude Opus 4.6. It works
by modifying descriptions of existing tools only, which avoids the model confusion that affects approaches using
custom tool schemas.

### `opencode-dcp` — dynamic context pruning

[`opencode-dcp`](https://github.com/Opencode-DCP/opencode-dynamic-context-pruning) manages the conversation context
between turns. It exposes a `compress` tool to the model that replaces stale, closed content with high-fidelity
technical summaries before sending requests to the LLM — without modifying your actual session history.

Unlike OpenCode's built-in compaction (which triggers statically when the context hits its limit), DCP lets the model
decide when to compress and which specific messages to target. This results in **50-70% token reduction** on long
sessions.

### `opencode-snip` — bash output filtering

[`opencode-snip`](https://github.com/VincentHardouin/opencode-snip) automatically prefixes shell commands with
[`snip`](https://github.com/edouard-claude/snip), a CLI proxy that filters command output before it reaches the LLM
context window. It handles `git`, `go`, `cargo`, `npm`, `docker`, and more — keeping errors and summaries while
dropping noise.

This delivers **60-90% reduction** on bash-heavy sessions.

## Important considerations

While these plugins are widely used and tested, they may:

* **Modify tool behavior**: `OpenSlimedit` alters tool descriptions.
* **Affect session history**: `opencode-dcp` compresses context, which may remove details the model needs.
* **Introduce latency**: `snip` adds a small overhead to shell commands.

<Warning>
  Recommendation: Start with one plugin at a time, monitor token usage and model behavior, and gradually add others.
  Pin plugin versions in `opencode.json` to avoid breaking changes.
</Warning>

## Installation

OpenCode loads `npm` plugins automatically via `Bun` at startup — no manual `npm install` needed for the plugins
themselves. The only exception is `snip`, a standalone Go binary with **no npm package**: declaring `opencode-snip`
only loads the *plugin*, not the binary it relies on. You install that binary once during the build with the
reusable `install-github-asset.sh` script (Step 2).

### Step 1 — Declare the plugins in `opencode.json`

Add the three plugins to the `plugin` array in your `opencode.json`:

```json title="opencode.json" {2-6} theme={null}
{
  "plugin": [
    "openslimedit@latest",
    "@tarquinen/opencode-dcp@latest",
    "opencode-snip@latest"
  ],
  "mcp": {
    "upsun": {
      "type": "remote",
      "url": "https://mcp.upsun.com/mcp",
      "headers": {
        "upsun-api-token": "${UPSUN_CLI_TOKEN}",
        "enable-write": "true"
      },
      "enabled": true
    }
  }
}
```

OpenCode will install and cache these packages automatically via Bun on the next startup.

### Step 2 — Install the `snip` binary during the build

The three npm plugins are fetched automatically by OpenCode at startup. `snip`, however, is a standalone Go binary
and must be installed during the build. The simplest way on Upsun is the reusable
[`install-github-asset.sh`](/posts/hands-on/install-gh-asset-on-upsun/) script, which pulls a binary straight from its
GitHub releases and installs it globally into `/app/.global/bin` (already on your `PATH`).

Add this to your application's `build` hook in `.upsun/config.yaml`:

```yaml title=".upsun/config.yaml" {6-8} theme={null}
applications:
  app:
    # ...
    hooks:
      build: |
        set -e
        # Install the snip binary (opencode-snip backend) from GitHub releases
        curl -fsS https://raw.githubusercontent.com/upsun/snippets/main/src/install-github-asset.sh | bash /dev/stdin "edouard-claude/snip"
      deploy: |
        set -e
        # Confirm snip is available before OpenCode starts
        snip --version
```

The script auto-detects the right asset (it picks the first release asset whose name contains `linux` + your
architecture, i.e. `snip_<version>_linux_amd64.tar.gz`) and installs the latest release. To pin a version or force a
specific asset, pass them explicitly:

```bash title="Terminal" theme={null}
# install-github-asset.sh "<org/repo>" ["<version>"] ["<asset_name>"]
curl -fsS https://raw.githubusercontent.com/upsun/snippets/main/src/install-github-asset.sh \
  | bash /dev/stdin "edouard-claude/snip" "0.18.0" "snip_0.18.0_linux_amd64.tar.gz"
```

<Note>
  `snip` has **no npm package**, so it cannot be installed via `dependencies`. The `opencode-snip` plugin does not bundle
  the binary either — it only loads the plugin glue. Installing the binary in the build hook is what makes
  `snip` available at runtime.
</Note>

### Step 3 — Deploy

Commit and push:

```bash title="Terminal" theme={null}
git add .upsun/config.yaml opencode.json
git commit -m "Add token optimization plugins + snip binary"
upsun push
```

Upsun will rebuild the container, install the `snip` binary during the build hook, and restart OpenCode. The three
npm plugins are fetched and cached by OpenCode on first startup.

## Which plugin for which problem?

| Problem | Plugin | Reduction |
| - | - | - |
| High token cost per step (all sessions) | **OpenSlimedit** | 11-45% |
| Long sessions with growing context | **opencode-dcp** | 50-70% |
| Bash-heavy sessions (`npm`, `pytest`, `docker`) | **opencode-snip** | 60-90% |

All three can run together — they address different layers of token waste and do not conflict with each other.

## Verify the plugins are loaded

Once deployed, connect to your OpenCode instance and press `Ctrl+P` → **View Status** (System category). You should
see all three plugins listed as active.

For opencode-dcp specifically, you can check savings at any point during a session by running:

```bash title="OpenCode prompt" theme={null}
/dcp stats
```

## Troubleshooting

### `snip` binary not found at runtime

If OpenCode logs show `snip: command not found`, the binary was not installed correctly during the build. Check the
build output with:

```bash title="Terminal" theme={null}
upsun activity:log
```

Look for the `install-github-asset.sh` step in the build log. The script auto-selects the asset matching `linux` +
your architecture (`snip_<version>_linux_amd64.tar.gz`). If a new release changes the naming convention, pass the
exact asset name as the third argument:

```bash title=".upsun/config.yaml (build hook)" theme={null}
curl -fsS https://raw.githubusercontent.com/upsun/snippets/main/src/install-github-asset.sh \
  | bash /dev/stdin "edouard-claude/snip" "0.18.0" "snip_0.18.0_linux_amd64.tar.gz"
```

### Check installed plugin

To check installed plugins, connect to your `opencode` container and run the following command:

```bash title="Terminal" theme={null}
upsun ssh -- cat .local/share/opencode/log/2026-05-26T132215.log | grep "loading plugin"

  INFO  2026-05-26T13:25:04 +20ms service=plugin path=openslimedit@latest loading plugin
  INFO  2026-05-26T13:25:04 +19ms service=plugin path=@tarquinen/opencode-dcp@latest loading plugin
  INFO  2026-05-26T13:25:04 +0ms service=plugin path=opencode-snip@latest loading plugin 
```

<Warning>
  Seeing `opencode-snip@latest loading plugin` confirms the **plugin** loaded — it does **not** mean the `snip`
  **binary** is installed. Always confirm the binary separately with `snip --version` (see the deploy hook in Step 2).
</Warning>

### opencode-dcp increases token usage on short sessions

DCP is most effective on sessions longer than 15-20 turns. On short sessions, the overhead of the compress tool
itself can outweigh the savings. Remove it from the `plugin` array if your typical sessions are short:

```json title="opencode.json" theme={null}
{
  "plugin": [
    "openslimedit@latest",
    "opencode-snip@latest"
  ]
}
```

### A plugin causes unexpected tool behavior

Pin to a specific version instead of `@latest` to stabilize your deployment:

```json title="opencode.json" theme={null}
{
  "plugin": [
    "openslimedit@1.2.0",
    "@tarquinen/opencode-dcp@1.2.3",
    "opencode-snip@1.6.1"
  ]
}
```

## What's next?

With token costs under control, you can monitor per-session usage with
[opencode-tokenscope](https://github.com/ramtinJ95/opencode-tokenscope), which provides a breakdown of which tools
and skills consume the most tokens — useful for identifying further optimization opportunities.

## Resources

* [How to Host OpenCode on Upsun](/posts/ai/opencode-on-upsun/) — Part 1
* [OpenSlimedit GitHub repository](https://github.com/ASidorenkoCode/openslimedit)
* [opencode-dcp GitHub repository](https://github.com/Opencode-DCP/opencode-dynamic-context-pruning)
* [opencode-snip GitHub repository](https://github.com/VincentHardouin/opencode-snip)
* [snip GitHub repository](https://github.com/edouard-claude/snip)
* [install-github-asset.sh — install any GitHub release asset on Upsun](/posts/hands-on/install-gh-asset-on-upsun/)
* [OpenCode plugin documentation](https://opencode.ai/docs/plugins/)
* [Upsun documentation](/docs)


# Prompts are the new legacy code
Source: https://developer.upsun.com/posts/ai/prompts-are-the-new-legacy-code

Dispatch's code review agent lost 80% of its prompt and four sub-agents. Same model, same quality, cost more than halved, 25% faster. Here's the method.

<PostMeta />

[Dispatch](https://upsun.com/dispatch)'s code review agent recently lost about 80% of its system prompt, along with all four of the sub-agents that used to run underneath it. The main before-and-after tests ran on Claude Opus 5, with no change in quality. Cost per review more than halved, and reviews came back about 25% faster.

## Deleting a prompt that works

The prompt-cutting experiment started with Thariq Shihipar's post on [the new rules of context engineering for Claude 5 generation models](https://claude.com/blog/the-new-rules-of-context-engineering-for-claude-5-generation-models). Anthropic had removed more than 80% of Claude Code's system prompt for newer models without lowering its coding evaluation scores.

Applying that result to a production agent requires evidence. The existing prompt already works, and the agent runs every day. You need to prove that removing instructions doesn't reduce quality.

## Recipes lose to pointers

"More context is better" is how most people learned to work with these models. That advice is about data, not about prompts.

Data means the diff, the logs, the profile, the file that needs reading. Give the agent as much of that as it needs. The prompt is different: past a certain point, every line you add makes the agent worse at its job.

Upsun Cloud's [performance agent](/docs/get-started/ai/upsun-cloud-performance-agent) went through two versions of its prompt. One read like a runbook: start here, then check this, then decide if that's the problem, then do this. The other version said here's the continuous profiling endpoint, here are the logs, here's how you inspect transactions, go find the regression. The second version performs a lot better.

Every instruction you write is also a restriction. Tell the model to check three things in order, and it may skip another useful check. Sometimes, that missed check is the one that matters. Left alone, the model often picks a better order than the one you wrote.

## Silent bugs

Conflicting rules often appear only after months of edits.

Every rule looks right the day you write it. You know performance, you know what to look at, and the prompt says so. Then a new case shows up, and you add another rule. The rule from three months ago may now conflict with it in a subtle way. The prompt gets longer and vaguer at the same time.

Debugging the performance agent once meant chasing down why it wouldn't report an issue. It had found the issue. It was throwing it away, because of a narrow rule someone added for an unrelated case and never took out.

A prompt gives you no stack trace. The rule fired exactly as written, outside the situation its author had in mind.

The prompt is code. It has behavior, it regresses, and it accumulates rules whose purpose is no longer clear. It gets harder to change as it grows. Treat it like code, and keep it small.

## The model fights you on this

Ask a model to make a chunk of your prompt shorter and more generic, and it mostly won't. It rewrites the section so the one failure in front of it passes, usually by adding another special case.

Models are built to solve the problem in front of them. A narrow fix does that. Making the prompt smaller is your goal, not the model's, so you have to keep asking for it.

## Sub-agents are a context tool

The old setup ran four reviewers with different lenses: one for security, one for correctness, and so on.

The lenses overlapped, producing duplicate findings and repeated costs. Every sub-agent gets its own context. Each one reads the same diff and surrounding files, then spends its own thinking tokens on that reading. Nothing is shared between them. Four lenses over one diff means paying four times to read the same files and waiting for four sets of round trips.

Sub-agents pay off when their contexts don't overlap. Claude Code includes a read-only agent for codebase search called [Explore](https://code.claude.com/docs/en/sub-agents). Several Explore agents can cover independent areas in parallel. Four reviewers covering the same diff repeat the same context instead.

You could reduce the overlap by reading files in the coordinator or assigning specific files to each lens. Both approaches add coordination and weren't necessary here. One reviewer replaced all four. Its prompt tells it to search aggressively for defects and report everything it finds. Today's models know what a code review agent is and what a defect is. A reviewer told to find defects is already looking for security bugs.

A single reviewer still has a trade-off. Push it to catch more real bugs, and it also starts flagging things that aren't bugs. A dedicated security lens may perform better when security is the product. That hasn't happened in these tests.

## Evals are the spec

You need an evaluation set: a fixed batch of test cases scored the same way every time. Deleting 80% of the prompt was only safe because there was one to check against. Without it you're guessing, and those four sub-agents would still be running.

This set is 25 cases, all written by hand. Synthetic cases didn't hold up in these tests. It's small on purpose, and the cases are deliberately different from each other: security, correctness, dependency changes, etc. Cases that all exercise the same behavior cost money to run and tell you nothing new.

The initial evaluation set favored the old prompt. The lean prompt failed cases the old prompt had passed. Five of those failures were false alarms. The old prompt had only passed them because a phrase buried in it matched those cases. The lean prompt no longer had that phrase. That tuning wasn't deliberate. An evaluation fails, you ask the model for a fix, the fix reads generic enough, and you merge it. After a few months, individual test cases start shaping the prompt instead of its purpose.

That's overfitting, same word as in model training and the same meaning. The prompt scores well on the cases you have and does worse than that score suggests on everything else. Your users notice before you do.

Those five failing cases had to come out of the set before its score meant anything. Finding them was most of the work.

Budget for the runs. A full pass over these 25 cases cost roughly \$20 before the changes and \$7 afterward. Landing the final prompt took hundreds of passes. A change that fixes one case can break another.

Treat the eval set as the spec. It's the thing that says what the agent has to do. The prompt is one implementation of it, and a smaller implementation that still passes is a better one.

## A shorter prompt transfers between models

Cost and speed improved right away. The prompt also got easier to move between models.

A prompt with 200 rules in it ends up tuned to the model you wrote it against. Half those rules exist to work around behavior a newer model doesn't have anymore. Switching models means finding out which half, one regression at a time.

A short prompt has few of those workarounds, and the eval set tells you in one run whether the swap is safe. Moving this agent from Opus 4.8 to Opus 5 takes it from catching around 70% of the real bugs in the set to around 90%. Opus 5 catches real bugs that 4.8 was known to walk past, and it does it with fewer false positives.

The refactored prompt also costs less and scores slightly higher on OpenAI's models, although it isn't faster. GPT-5.6-Terra is much cheaper and faster than Opus. It scores slightly below Opus 4.8, making it an option when cost or speed matters. Opus 5 scores higher than both. GPT-5.6-Sol is worth another look now that its price came down.

Those comparisons depend on using the same prompt for each model.

## If you're trying this

Start from nothing. Say what the agent is for, hand it the tools and the references, and let it work out the order. Add a rule only after you've seen the same failure twice. Every rule you add becomes something you have to maintain.

Before you add a sub-agent, ask whether its context overlaps anything else in the run. If it does, you're paying twice to read the same thing.

Write the eval set by hand, keep the cases different from each other, and avoid overfitting.

Then start deleting, and let the eval set tell you when you've gone too far. Without one, don't try any of this.


# Your agents are stuck on localhost. Upsun isn't.
Source: https://developer.upsun.com/posts/ai/stuck-on-localhost

Coding agents made engineers faster, but cycle time hasn't budged. Background agents running on GitHub, GitLab, and Claude Code can break the bottleneck by producing PRs that Upsun deploys and validates automatically. A practical guide to setting it up with real YAML configs, infrastructure-as-code workflows, and preview environments.


<PostMeta />

Every engineering team I talk to right now is running coding agents. Cursor, Windsurf, Claude Code, Copilot. Engineers are faster. PRs are flying in. And yet, when I zoom out and look at cycle time, DORA metrics, or just the size of the backlog at these organizations, nothing has moved.

I keep seeing the same pattern. We automated the typing, but we didn't automate the system.

The fix is to get agents off the laptop. Let them run in the background, triggered by events in your workflow, producing PRs that get deployed and validated automatically. The tooling to do this exists today across GitHub, GitLab, and standalone agents like Claude Code. And if you're deploying to Upsun, you already have the deployment infrastructure these agents need: git-native deployments, preview environments on every PR, and infrastructure defined as code in your repo.

This article walks through how to set it up.

## The localhost ceiling

An engineer fires up a coding agent on their laptop. The agent writes code, runs tests, maybe opens a PR. That engineer is genuinely 2-3x faster on individual tasks.

Now multiply that by a team of twenty. PRs pile up in review queues. CI pipelines back up. Merge conflicts stack. The bottleneck just shifted downstream, and the agent that created the PR can't help with any of it. It's tethered to one developer's machine, running in one session, working on one thing at a time.

```mermaid theme={null}
graph LR
    A["Developer + Agent"] --> B["PR Created"]
    B --> C["Review Queue"]
    C --> D["CI Pipeline"]
    D --> E["Merge Conflicts"]
    E --> F["Backlog Unchanged"]

    style A fill:#7c3aed,stroke:#5b21b6,color:#fff
    style B fill:#7c3aed,stroke:#5b21b6,color:#fff
    style C fill:#374151,stroke:#1f2937,color:#fff
    style D fill:#374151,stroke:#1f2937,color:#fff
    style E fill:#374151,stroke:#1f2937,color:#fff
    style F fill:#ef4444,stroke:#b91c1c,color:#fff
```

> Violet = faster with agents. Dark = downstream bottlenecks untouched. The speed gains never reach the end of the pipeline.

Ona calls this "the false summit." Individual speed gains that never compound into organizational velocity. Teams adopt coding agents, individual output goes up, and DORA metrics stay flat. The backlog grows. It doesn't shrink.

Background agents break this pattern. They run in isolated cloud environments, get triggered by events (an issue labeled, a test failing, a schedule firing), produce pull requests, and let Upsun deploy those PRs into preview environments for validation. The human reviews a running application, not just a diff.

## What a background agent actually is

A coding agent (Cursor, Claude Code in your terminal, etc.) needs your machine and your attention. You're in the loop: watching, steering, intervening.

A background agent needs neither. It runs in its own environment in the cloud, with a full toolchain, test suite, database access. You kick it off and walk away. Check the result from your phone. When it's done, it submits a pull request. Your job is to review and decide whether to merge.

The mental model that sticks: think of it as a junior engineer. Capable, can handle many tasks, but needs guardrails. You'd scope their access, define what good output looks like, and review their work before it ships.

## Setting up background agents on GitHub

GitHub gives you two paths to background agents: Copilot coding agent (built into GitHub) and Claude Code Action (open-source, runs on GitHub Actions).

### GitHub Copilot coding agent

Copilot's coding agent is the simplest entry point. You assign a GitHub issue to Copilot the same way you'd assign it to a teammate, and it goes to work. It plans, writes code, runs tests, self-reviews with Copilot code review, and opens a pull request.

The agent runs in a GitHub Actions-powered environment. To customize that environment (install dependencies, set up databases, configure tooling), you create a `copilot-setup-steps.yml` file in `.github/workflows/`. This file must contain a single job named `copilot-setup-steps`:

```yaml theme={null}
name: Copilot Setup Steps
on: workflow_dispatch

jobs:
  copilot-setup-steps:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: 'npm'

      - run: npm ci

      - name: Install system dependencies
        run: sudo apt-get update && sudo apt-get install -y sqlite3
```

The job name is strict. If it's not called `copilot-setup-steps`, Copilot won't pick it up. If any setup step fails, Copilot skips the rest and starts working with whatever's available.

To trigger the agent, you assign an issue to Copilot. It reads the issue, creates a branch, works through the implementation, runs your test suite, self-reviews, and opens a PR. The PR then triggers your normal CI pipeline and, on Upsun, spins up a preview environment where the changes are deployed and running.

### Claude Code Action

For more control, or if you're not on a Copilot plan, Claude Code Action is an open-source GitHub Action that runs Claude Code in your CI. You can trigger it from issue comments, issue assignments, PR events, or on a schedule.

The fastest setup path: open Claude Code in your terminal and run `/install-github-app`. That walks you through the GitHub app installation and secrets configuration.

For issue-to-PR automation, you'd set up a workflow like this:

```yaml theme={null}
name: Claude Background Agent
on:
  issues:
    types: [assigned]

jobs:
  handle_issue:
    if: github.event.assignee.login == 'claude[bot]'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: anthropics/claude-code-action@v1
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
```

Assign an issue to the Claude bot, and the workflow kicks off. Claude reads the issue, works on the code, and opens a PR.

You can also set up scheduled maintenance agents that run on a cron:

```yaml theme={null}
name: Weekly Dependency Check
on:
  schedule:
    - cron: '0 9 * * MON'

jobs:
  maintenance:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: anthropics/claude-code-action@v1
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          mode: automation
          prompt: |
            Check for outdated dependencies.
            If any have new stable releases, open a PR
            updating each one individually with a clear
            description of what changed.
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
```

Both approaches produce PRs. Both trigger Upsun preview deployments automatically.

## Setting up background agents on GitLab

GitLab's approach is the Duo Agent Platform, which hit general availability in January 2026. The core flow for background agents is "Issue to Merge Request": you point Duo at a well-scoped issue, and it builds a draft MR with the implementation.

### Prerequisites

You need a few things enabled. In your project settings, go to Settings > General > GitLab Duo and enable the "Allow flow execution" toggle. The feature flags `duo_workflow` and `duo_workflow_in_ci` need to be active on your instance. You need Developer permissions or higher on the project.

### Using the Issue to MR flow

Once enabled, the workflow is straightforward. Open an issue with clear requirements and acceptance criteria. Below the issue header, select "Generate MR with Duo." You can monitor progress under Automate > Sessions.

The agent reads the issue, plans an implementation, creates a branch, writes the code, and opens a draft merge request. From there, your normal CI/CD pipeline takes over, and if you're deploying to Upsun, the MR triggers a preview environment deployment.

### Writing good issues for agents

This matters more than most teams realize. The quality of the agent's output maps directly to the quality of the issue description. Break complex tasks into smaller, focused issues. Write specific acceptance criteria. Include enough context about your codebase conventions that the agent can follow them.

A bad issue: "Fix the login bug." A good issue: "The login form on `/auth/login` returns a 500 when the email field contains a `+` character. The validation in `src/auth/validator.ts` doesn't handle RFC 5321 addr-spec encoding. Fix the regex in `validateEmail()` and add a test case for plus-addressing."

The same principle applies to all three agent platforms. The more structured your input, the better the output.

## Deploying agent PRs to Upsun

Here's where Upsun connects to all of the above. Regardless of which agent platform you use (Copilot, Claude Code, GitLab Duo), the output is the same: a pull request or merge request against your repository.

Upsun is fully git-native. Every deployment is a git push. Every preview environment is a git branch. There's no separate control plane to authenticate against, no dashboard-only settings that agents can't reach. When an agent pushes a branch and opens a PR, Upsun sees it and deploys it automatically.

```mermaid theme={null}
graph LR
    T["Trigger (issue, schedule, event)"] --> A["Agent Works (GitHub/GitLab)"]
    A --> PR["PR / MR Opened"]
    PR --> U["Upsun Preview Environment"]
    U --> V["Tests + Live App"]
    V --> H["Human Reviews Running App"]
    H --> M["Merge + Prod Deploy"]

    style T fill:#374151,stroke:#1f2937,color:#fff
    style A fill:#7c3aed,stroke:#5b21b6,color:#fff
    style PR fill:#7c3aed,stroke:#5b21b6,color:#fff
    style U fill:#c6ff00,stroke:#8fb300,color:#000
    style V fill:#22c55e,stroke:#15803d,color:#fff
    style H fill:#374151,stroke:#1f2937,color:#fff
    style M fill:#22c55e,stroke:#15803d,color:#fff
```

> Dark = human steps. Violet = agent steps. Lime = Upsun. Green = verification and delivery.

Each preview environment is an isolated, production-parity deployment with its own services, data, and URL. The agent's PR doesn't just pass tests in CI. It gets deployed, and you can click through the running application before merging. Tests verify logic. Preview environments verify that the thing actually works when deployed.

For background agents, this is a meaningful difference. You're not reviewing a diff and hoping the deployment works. You're reviewing a running application.

## Infrastructure as code: agents can change more than application code

Most background agent discussions focus on code changes. Fix a bug. Address an issue. Patch a CVE. But there's a much bigger surface area that almost nobody is talking about yet.

On Upsun, infrastructure is defined as code. YAML configuration files committed alongside your application code in the same repository. Services, databases, runtimes, routes, cron jobs. All of it version-controlled, all of it deployed through git.

That means an agent can change infrastructure, not just application code.

Think about what that looks like in practice. An agent branches your repository, bumps your PostgreSQL version from 15 to 16 in the config, and opens a PR. Upsun sees that PR, spins up a preview environment with PostgreSQL 16 running, deploys your application against it, and runs your test suite. You're not reading a config diff and hoping it works. You're looking at a running deployment with the upgraded database actually serving requests.

The same applies to adding a Redis cache, swapping a search backend, resizing containers, testing a new PHP or Python runtime version, or splitting a monolith service into two. Because Upsun treats infrastructure configuration as part of the repository, an agent can propose architectural changes the same way it proposes code changes. And because every PR gets a preview environment, those architectural changes get deployed and validated automatically.

```mermaid theme={null}
graph TD
    S["Scheduled Agent (weekly)"] --> C["Check stable releases for stack components"]
    C --> B["Branch + update infra config YAML"]
    B --> PR["Open PR"]
    PR --> U["Upsun deploys preview environment"]
    U --> T{"Tests pass?"}
    T -- Yes --> R["PR ready for human review"]
    T -- No --> F["Agent reads logs, pushes fix"]
    F --> U

    style S fill:#7c3aed,stroke:#5b21b6,color:#fff
    style C fill:#7c3aed,stroke:#5b21b6,color:#fff
    style B fill:#7c3aed,stroke:#5b21b6,color:#fff
    style PR fill:#7c3aed,stroke:#5b21b6,color:#fff
    style U fill:#c6ff00,stroke:#8fb300,color:#000
    style T fill:#374151,stroke:#1f2937,color:#fff
    style R fill:#22c55e,stroke:#15803d,color:#fff
    style F fill:#7c3aed,stroke:#5b21b6,color:#fff
```

> The agent proposes infrastructure changes. Upsun deploys and validates them. The human only sees PRs that are ready, with a running environment to prove it.

Imagine a scheduled agent that runs weekly, checks your stack against current stable releases, and opens PRs to test upgrades. Each PR deploys a full environment. Your CI runs against the upgraded stack. If the tests pass, the PR sits there waiting for a human to review. If they fail, the agent can read the logs, try a fix, and push again.

I haven't seen many teams doing this yet. But the pieces are all there. The constraint was never the agent's ability to edit a YAML file. It was the lack of a platform that would actually deploy the result and let you validate it. That constraint doesn't exist on Upsun.

## Git as the universal interface

There's a reason Upsun maps well to background agents, and it's worth stating plainly: everything runs through git.

Every deployment is a git push. Every preview environment is a git branch. Infrastructure config, application code, routes, services, cron jobs: all committed to the repository. There's no separate control plane, no dashboard-only settings that agents can't reach, no imperative API calls to manage infrastructure state.

```mermaid theme={null}
graph LR
    subgraph Git Repository
        CODE["Application Code"]
        INFRA["Infrastructure Config"]
        ROUTES["Routes + Services"]
        CRON["Cron Jobs"]
    end

    GIT["git push"] --> UPSUN["Upsun"]
    UPSUN --> DEP["Full Deployment (app + infra + services)"]
    CODE --> GIT
    INFRA --> GIT
    ROUTES --> GIT
    CRON --> GIT

    style CODE fill:#374151,stroke:#1f2937,color:#fff
    style INFRA fill:#374151,stroke:#1f2937,color:#fff
    style ROUTES fill:#374151,stroke:#1f2937,color:#fff
    style CRON fill:#374151,stroke:#1f2937,color:#fff
    style GIT fill:#7c3aed,stroke:#5b21b6,color:#fff
    style UPSUN fill:#c6ff00,stroke:#8fb300,color:#000
    style DEP fill:#22c55e,stroke:#15803d,color:#fff
```

> Everything lives in the repo. Everything deploys through git. Agents don't need a separate interface.

For background agents, this is exactly the right interface. Agents already know how to work with git. They clone repos, create branches, make commits, open pull requests. When your entire platform operates through that same mechanism, there's no translation layer. An agent that can open a PR can deploy infrastructure. An agent that can push a branch can spin up an environment.

A lot of the friction in getting background agents into production comes from integration complexity: custom API clients, separate auth flows, imperative provisioning scripts. When the platform's interface is git, most of that goes away. The agent doesn't need special tooling to interact with Upsun. It needs the same git access it already has.

## Governance: don't skip this

Governance is the one teams skip, and it's the one that matters most. It means three things: identity, permissions, and audit trails.

The agent needs a real identity in your systems. Not a shared service account. Permissions need to be scoped to what the agent needs for the task at hand. And you need to trace back what the agent did, when, and on whose authority.

On GitHub, Copilot coding agent runs under its own identity with scoped permissions. Claude Code Action runs on your GitHub Actions runner with whatever secrets and permissions you configure in the workflow file. On GitLab, Duo agents operate within the project's permission model.

The principle of least privilege matters more here than anywhere else. Models hallucinate. Prompts can get injected. Design the governance model assuming the agent will sometimes do the wrong thing, and make sure the blast radius stays small.

Governance enforced by a system prompt ("please don't delete files") is a suggestion. Governance enforced at the execution layer (deny lists, scoped credentials, deterministic command blocking) is actual governance. Without that distinction, your security team will veto autonomous agents. And they'd be right to.

## Where to start

Start with one workflow. Something well-defined, with a clear start and end. When a specific issue gets labeled, create a PR that addresses it. That's a tight closed loop where you can measure whether the agent did the right thing.

Pick your agent platform based on what you already use. On GitHub, try Copilot coding agent by assigning an issue, or set up Claude Code Action for more control. On GitLab, enable Duo Agent Platform and use the Issue to MR flow. Both integrate with Upsun through the same mechanism: git.

Don't skip governance, even for a pilot. The habits you build early define the system you end up with.

And if your agents are still running on localhost, that's the first thing to change. The false summit doesn't clear itself.


# Introducing the Upsun MCP server: bring Upsun into your LLMs
Source: https://developer.upsun.com/posts/ai/upsun-mcp-announcement

Manage your Upsun infrastructure directly through AI assistants with our new Model Context Protocol server - now in beta at mcp.upsun.com

<PostMeta />

Today marks a significant milestone in our evolution from Platform.sh to Upsun. We're launching the **Upsun MCP Server**, a new integration that transforms how you interact with your favorite cloud application platform through AI assistants.

<Note>
  Available now in **beta** at `https://mcp.upsun.com/mcp`, this represents our commitment to bringing real AI improvements directly to your development workflow. As a beta release, we're actively seeking feedback to shape its evolution and its features. Feel free to bring up issues or PR on the [`upsun-mcp-server` GitHub repository](https://github.com/upsun/upsun-mcp-server).
</Note>

## Infrastructure management where you already work

The Upsun MCP server eliminates context switching entirely. Through integration with AI assistants like Claude, you manage your entire Upsun infrastructure using natural language, right where you're already working.

```bash {filename="Claude"} theme={null}
You: "Create a preview environment for my feature branch with PostgreSQL"
Claude: "I'll create that preview environment for you now..."
[Environment created with full production data clone in 2 minutes]
```

No terminal. No console. No documentation hunting. Your AI assistant becomes your infrastructure expert.

<img alt="MCP projects" />

## Why MCP changes everything for infrastructure

### Natural Language Infrastructure-as-Code

Traditional infrastructure management requires memorizing commands and syntax. With MCP, you describe what you want:

* "Show me all active environments in my e-commerce project"
* "Create a backup before I deploy this breaking change"
* "Add Redis caching to my staging environment"

Your AI assistant translates intent into action, handling the complexity behind the scenes.

### Seamless CI/CD integration

MCP servers aren't isolated tools, they integrate directly into your existing workflows. Trigger deployments from your IDE. Monitor builds from your documentation. Manage resources from anywhere you interact with AI.

This integration extends **to your CI/CD pipelines**.

### Automation that thinks

Traditional automation follows rigid rules. AI-powered automation adapts. Need to scale resources based on complex patterns? Your AI assistant analyzes metrics, understands context, and makes intelligent decisions.

Example scenarios MCP enables:

* Intelligent resource allocation based on usage patterns
* Automated troubleshooting with root cause analysis
* Smart backup strategies that adapt to your workflow
* Predictive scaling before traffic spikes

## What you can do today

<Info>
  Every operation respects Upsun's security model. **The beta defaults to read-only operations for safety, with write operations available through explicit configuration.**

  To enable write operations, add the `"enable-write": "true"` header to your MCP configuration. Only enable this if you understand the implications and trust your AI assistant with infrastructure modifications.
</Info>

The Upsun MCP Server exposes our API through task oriented tools like the CLI does:

### Project & Environment Management

* Create and configure projects
* Manage environments and deployments
* Handle branching and merging strategies
* Monitor activities and logs

### Infrastructure Operations

* Configure services and databases
* Manage domains and SSL certificates
* Create and restore backups
* Set up routing and caching

### Security & Access

* Manage SSH keys
* Configure access controls
* Handle certificates

## Part of our broader AI vision

The MCP server launch represents our broader commitment to AI-enhanced development. This is the first of many AI innovations coming to Upsun.

We're not adding AI as a gimmick. We're solving real problems that cost you time and money. Every AI feature we ship must pass one test: Does it make developers' lives genuinely better?

## Upsun MCP Architecture

In order to ensure the best level of service and maintenance, Upsun has deployed its MCP with [Streamable HTTP transport](https://modelcontextprotocol.io/docs/learn/architecture).

It uses HTTP POST for client-to-server messages with optional Server-Sent Events for streaming capabilities. This transport enables remote server communication and supports standard HTTP authentication methods including bearer tokens, API keys, and custom headers.

```mermaid theme={null}
graph TB
    AI["AI Assistant<br/>(MCP Client)"]
    MCP["Upsun MCP Server<br/>mcp.upsun.com/mcp"]
    API["Upsun API"]
    
    PROJECT1["Upsun Project 1"]
    PROJECT2["Upsun Project 2"]
    PROJECT3["Upsun Project 3"]
    
    %% Connections
    AI -->|API Token| MCP
    MCP --> API
    API -->|Action| PROJECT1
    API -->|Action| PROJECT2
    API -->|Action| PROJECT3
    
    %% Styling
    classDef client fill:#D0F302,stroke:#000,stroke-width:2px,color:#000
    classDef server fill:#6046FF,stroke:#000,stroke-width:2px,color:#fff
    classDef api fill:#000,stroke:#D0F302,stroke-width:2px,color:#D0F302
    classDef projects fill:#D0F302,stroke:#000,stroke-width:2px,color:#000
    
    class AI client
    class MCP server
    class API api
    class PROJECT1,PROJECT2,PROJECT3 projects
```

## Installation instructions

Set up the Upsun MCP Server in under a minute:

1. Get your API token from the [Upsun Console](https://console.upsun.com/). Navigate to your account settings and generate a new API token with appropriate permissions for your projects.
2. Configure your MCP client to connect to `https://mcp.upsun.com/mcp`
3. Start managing infrastructure through natural language

The Upsun MCP server works with all major AI development environments. Choose your preferred client below:

<AccordionGroup>
  <Accordion title="Install in Cursor">
    Go to: `Settings` -> `Cursor Settings` -> `MCP` -> `Add new global MCP server`

    Pasting the following configuration into your Cursor `~/.cursor/mcp.json` file is the recommended approach. You may also install in a specific project by creating `.cursor/mcp.json` in your project folder. See [Cursor MCP docs](https://docs.cursor.com/context/model-context-protocol) for more info.

    #### Cursor Remote Server Connection

    ```json theme={null}
    {
      "mcpServers": {
        "upsun": {
          "url": "https://mcp.upsun.com/mcp",
          "headers": {
            "upsun-api-token": "YOUR_API_TOKEN",
            "enable-write": "false"
          }
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Install in Claude Code">
    Run this command. See [Claude Code MCP docs](https://docs.anthropic.com/en/docs/claude-code/mcp) for more info.

    #### Claude Code Remote Server Connection

    ```sh theme={null}
    claude mcp add --transport http upsun https://mcp.upsun.com/mcp --header "upsun-api-token: YOUR_API_TOKEN" --header "enable-write: false"
    ```
  </Accordion>

  <Accordion title="Install in Windsurf">
    Add this to your Windsurf MCP config file. See [Windsurf MCP docs](https://docs.windsurf.com/windsurf/cascade/mcp) for more info.

    #### Windsurf Remote Server Connection

    ```json theme={null}
    {
      "mcpServers": {
        "upsun": {
          "serverUrl": "https://mcp.upsun.com/mcp",
          "headers": {
            "upsun-api-token": "YOUR_API_TOKEN",
            "enable-write": "false"
          }
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Install in VS Code">
    Add this to your VS Code MCP config file. See [VS Code MCP docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more info.

    #### VS Code Remote Server Connection

    ```json theme={null}
    "mcp": {
      "servers": {
        "upsun": {
          "type": "http",
          "url": "https://mcp.upsun.com/mcp",
          "headers": {
            "upsun-api-token": "YOUR_API_TOKEN",
            "enable-write": "false"
          }
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Install in Cline">
    You can easily configure the Upsun MCP server through Cline:

    1. Open **Cline**.
    2. Click the hamburger menu icon (☰) to enter the **MCP Servers** section.
    3. Choose **Remote Servers** tab.
    4. Click the **Edit Configuration** button.
    5. Add upsun to `mcpServers`:

    ```json theme={null}
    {
      "mcpServers": {
        "upsun": {
          "url": "https://mcp.upsun.com/mcp",
          "type": "streamableHttp",
          "headers": {
            "upsun-api-token": "YOUR_API_TOKEN",
            "enable-write": "false"
          }
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Install in Zed">
    Add this to your Zed `settings.json`. See [Zed Context Server docs](https://zed.dev/docs/assistant/context-servers) for more info.

    ```json theme={null}
    {
      "context_servers": {
        "Upsun": {
          "settings": {
            "url": "https://mcp.upsun.com/mcp",
            "headers": {
              "upsun-api-token": "YOUR_API_TOKEN",
              "enable-write": "false"
            }
          }
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Install in Augment Code">
    To configure the Upsun MCP server in Augment Code:

    ### **Manual Configuration**

    1. Press Cmd/Ctrl Shift P or go to the hamburger menu in the Augment panel
    2. Select Edit Settings
    3. Under Advanced, click Edit in settings.json
    4. Add the server configuration to the `mcpServers` array in the `augment.advanced` object

    ```json theme={null}
    "augment.advanced": {
      "mcpServers": [
        {
          "name": "upsun",
          "url": "https://mcp.upsun.com/mcp",
          "headers": {
            "upsun-api-token": "YOUR_API_TOKEN",
            "enable-write": "false"
          }
        }
      ]
    }
    ```

    Once the MCP server is added, restart your editor. If you receive any errors, check the syntax to make sure closing brackets or commas are not missing.
  </Accordion>

  <Accordion title="Install in Roo Code">
    Add this to your Roo Code MCP configuration file. See [Roo Code MCP docs](https://docs.roocode.com/features/mcp/using-mcp-in-roo) for more info.

    #### Roo Code Remote Server Connection

    ```json theme={null}
    {
      "mcpServers": {
        "upsun": {
          "type": "streamable-http",
          "url": "https://mcp.upsun.com/mcp",
          "headers": {
            "upsun-api-token": "YOUR_API_TOKEN",
            "enable-write": "false"
          }
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Install in Gemini CLI">
    See [Gemini CLI Configuration](https://google-gemini.github.io/gemini-cli/docs/tools/mcp-server.html) for details.

    1. Open the Gemini CLI settings file. The location is `~/.gemini/settings.json` (where `~` is your home directory).
    2. Add the following to the `mcpServers` object in your `settings.json` file:

    ```json theme={null}
    {
      "mcpServers": {
        "upsun": {
          "httpUrl": "https://mcp.upsun.com/mcp",
          "headers": {
            "upsun-api-token": "YOUR_API_TOKEN",
            "enable-write": "false",
            "Accept": "application/json, text/event-stream"
          }
        }
      }
    }
    ```

    If the `mcpServers` object does not exist, create it.
  </Accordion>

  <Accordion title="Install in Claude Desktop">
    #### Remote Server Connection

    Open Claude Desktop and navigate to Settings > Connectors > Add Custom Connector. Enter the name as `Upsun` and the remote MCP server URL as `https://mcp.upsun.com/mcp`.

    Add your API token in the headers configuration:

    ```json theme={null}
    {
      "upsun-api-token": "YOUR_API_TOKEN",
      "enable-write": "false"
    }
    ```
  </Accordion>

  <Accordion title="Install in Opencode">
    Add this to your Opencode configuration file. See [Opencode MCP docs](https://opencode.ai/docs/mcp-servers) for more info.

    #### Opencode Remote Server Connection

    ```json theme={null}
    "mcp": {
      "upsun": {
        "type": "remote",
        "url": "https://mcp.upsun.com/mcp",
        "headers": {
          "upsun-api-token": "YOUR_API_TOKEN",
          "enable-write": "false"
        },
        "enabled": true
      }
    }
    ```
  </Accordion>

  <Accordion title="Install in JetBrains AI Assistant">
    See [JetBrains AI Assistant Documentation](https://www.jetbrains.com/help/ai-assistant/configure-an-mcp-server.html) for more details.

    1. In JetBrains IDEs, go to `Settings` -> `Tools` -> `AI Assistant` -> `Model Context Protocol (MCP)`
    2. Click `+ Add`.
    3. Click on `Command` in the top-left corner of the dialog and select the As JSON option from the list
    4. Add this configuration and click `OK`

    ```json theme={null}
    {
      "mcpServers": {
        "upsun": {
          "url": "https://mcp.upsun.com/mcp",
          "headers": {
            "upsun-api-token": "YOUR_API_TOKEN",
            "enable-write": "false"
          }
        }
      }
    }
    ```

    5. Click `Apply` to save changes.
    6. The same way upsun could be added for JetBrains Junie in `Settings` -> `Tools` -> `Junie` -> `MCP Settings`
  </Accordion>

  <Accordion title="Install in Kiro">
    See [Kiro Model Context Protocol Documentation](https://kiro.dev/docs/mcp/configuration/) for details.

    1. Navigate `Kiro` > `MCP Servers`
    2. Add a new MCP server by clicking the `+ Add` button.
    3. Paste the configuration given below:

    ```json theme={null}
    {
      "mcpServers": {
        "Upsun": {
          "url": "https://mcp.upsun.com/mcp",
          "headers": {
            "upsun-api-token": "YOUR_API_TOKEN",
            "enable-write": "false"
          },
          "disabled": false,
          "autoApprove": []
        }
      }
    }
    ```

    4. Click `Save` to apply the changes.
  </Accordion>

  <Accordion title="Install in Trae">
    Use the Add manually feature and fill in the JSON configuration information for that MCP server.
    For more details, visit the [Trae documentation](https://docs.trae.ai/ide/model-context-protocol?_lang=en).

    #### Trae Remote Server Connection

    ```json theme={null}
    {
      "mcpServers": {
        "upsun": {
          "url": "https://mcp.upsun.com/mcp",
          "headers": {
            "upsun-api-token": "YOUR_API_TOKEN",
            "enable-write": "false"
          }
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Install in Amazon Q Developer CLI">
    Add this to your Amazon Q Developer CLI configuration file. See [Amazon Q Developer CLI docs](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line-mcp-configuration.html) for more details.

    ```json theme={null}
    {
      "mcpServers": {
        "upsun": {
          "url": "https://mcp.upsun.com/mcp",
          "headers": {
            "upsun-api-token": "YOUR_API_TOKEN",
            "enable-write": "false"
          }
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Install in Warp">
    See [Warp Model Context Protocol Documentation](https://docs.warp.dev/knowledge-and-collaboration/mcp#adding-an-mcp-server) for details.

    1. Navigate `Settings` > `AI` > `Manage MCP servers`.
    2. Add a new MCP server by clicking the `+ Add` button.
    3. Paste the configuration given below:

    ```json theme={null}
    {
      "Upsun": {
        "url": "https://mcp.upsun.com/mcp",
        "headers": {
          "upsun-api-token": "YOUR_API_TOKEN",
          "enable-write": "false"
        },
        "start_on_launch": true
      }
    }
    ```

    4. Click `Save` to apply the changes.
  </Accordion>

  <Accordion title="Install in Copilot Coding Agent">
    **Using Upsun MCP with Copilot Coding Agent**

    Add the following configuration to the `mcp` section of your Copilot Coding Agent configuration file Repository->Settings->Copilot->Coding agent->MCP configuration:

    ```json theme={null}
    {
      "mcpServers": {
        "upsun": {
          "type": "http",
          "url": "https://mcp.upsun.com/mcp",
          "headers": {
            "upsun-api-token": "YOUR_API_TOKEN",
            "enable-write": "false"
          }
        }
      }
    }
    ```

    For more information, see the [official GitHub documentation](https://docs.github.com/en/enterprise-cloud@latest/copilot/how-tos/agents/copilot-coding-agent/extending-copilot-coding-agent-with-mcp).
  </Accordion>

  <Accordion title="Install in LM Studio">
    See [LM Studio MCP Support](https://lmstudio.ai/blog/lmstudio-v0.3.17) for more information.

    #### Manual set-up:

    1. Navigate to `Program` (right side) > `Install` > `Edit mcp.json`.
    2. Paste the configuration given below:

    ```json theme={null}
    {
      "mcpServers": {
        "Upsun": {
          "url": "https://mcp.upsun.com/mcp",
          "headers": {
            "upsun-api-token": "YOUR_API_TOKEN",
            "enable-write": "false"
          }
        }
      }
    }
    ```

    3. Click `Save` to apply the changes.
    4. Toggle the MCP server on/off from the right hand side, under `Program`, or by clicking the plug icon at the bottom of the chat box.
  </Accordion>

  <Accordion title="Install in Visual Studio 2022">
    You can configure the Upsun MCP server in Visual Studio 2022 by following the [Visual Studio MCP Servers documentation](https://learn.microsoft.com/visualstudio/ide/mcp-servers?view=vs-2022).

    Add this to your Visual Studio MCP config file (see the [Visual Studio docs](https://learn.microsoft.com/visualstudio/ide/mcp-servers?view=vs-2022) for details):

    ```json theme={null}
    {
      "inputs": [],
      "servers": {
        "upsun": {
          "type": "http",
          "url": "https://mcp.upsun.com/mcp",
          "headers": {
            "upsun-api-token": "YOUR_API_TOKEN",
            "enable-write": "false"
          }
        }
      }
    }
    ```

    For more information and troubleshooting, refer to the [Visual Studio MCP Servers documentation](https://learn.microsoft.com/visualstudio/ide/mcp-servers?view=vs-2022).
  </Accordion>

  <Accordion title="Install in Crush">
    Add this to your Crush configuration file. See [Crush MCP docs](https://github.com/charmbracelet/crush#mcps) for more info.

    #### Crush Remote Server Connection (HTTP)

    ```json theme={null}
    {
      "$schema": "https://charm.land/crush.json",
      "mcp": {
        "upsun": {
          "type": "http",
          "url": "https://mcp.upsun.com/mcp",
          "headers": {
            "upsun-api-token": "YOUR_API_TOKEN",
            "enable-write": "false"
          }
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Install in BoltAI">
    Open the "Settings" page of the app, navigate to "Plugins," and configure the Upsun MCP server:

    ```json theme={null}
    {
      "mcpServers": {
        "upsun": {
          "url": "https://mcp.upsun.com/mcp",
          "headers": {
            "upsun-api-token": "YOUR_API_TOKEN",
            "enable-write": "false"
          }
        }
      }
    }
    ```

    More information is available on [BoltAI's Documentation site](https://docs.boltai.com/docs/plugins/mcp-servers). For BoltAI on iOS, [see this guide](https://docs.boltai.com/docs/boltai-mobile/mcp-servers).
  </Accordion>

  <Accordion title="Install in Rovo Dev CLI">
    Edit your Rovo Dev CLI MCP config by running the command below -

    ```bash theme={null}
    acli rovodev mcp
    ```

    Example config -

    #### Remote Server Connection

    ```json theme={null}
    {
      "mcpServers": {
        "upsun": {
          "url": "https://mcp.upsun.com/mcp",
          "headers": {
            "upsun-api-token": "YOUR_API_TOKEN",
            "enable-write": "false"
          }
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Install in Zencoder">
    To configure the Upsun MCP server in Zencoder, follow these steps:

    1. Go to the Zencoder menu (...)
    2. From the dropdown menu, select Agent tools
    3. Click on the Add custom MCP
    4. Add the name and server configuration from below, and make sure to hit the Install button

    ```json theme={null}
    {
      "url": "https://mcp.upsun.com/mcp",
      "headers": {
        "upsun-api-token": "YOUR_API_TOKEN",
        "enable-write": "false"
      }
    }
    ```

    Once the MCP server is added, you can easily continue using it.
  </Accordion>

  <Accordion title="Install in Qodo Gen">
    See [Qodo Gen docs](https://docs.qodo.ai/qodo-documentation/qodo-gen/qodo-gen-chat/agentic-mode/agentic-tools-mcps) for more details.

    1. Open Qodo Gen chat panel in VSCode or IntelliJ.
    2. Click Connect more tools.
    3. Click + Add new MCP.
    4. Add the following configuration:

    #### Qodo Gen Remote Server Connection

    ```json theme={null}
    {
      "mcpServers": {
        "upsun": {
          "url": "https://mcp.upsun.com/mcp",
          "headers": {
            "upsun-api-token": "YOUR_API_TOKEN",
            "enable-write": "false"
          }
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Install in Perplexity Desktop">
    See [Local and Remote MCPs for Perplexity](https://www.perplexity.ai/help-center/en/articles/11502712-local-and-remote-mcps-for-perplexity) for more information.

    1. Navigate `Perplexity` > `Settings`
    2. Select `Connectors`.
    3. Click `Add Connector`.
    4. Select `Advanced`.
    5. Enter Server Name: `Upsun`
    6. Paste the following JSON in the text area:

    ```json theme={null}
    {
      "url": "https://mcp.upsun.com/mcp",
      "headers": {
        "upsun-api-token": "YOUR_API_TOKEN",
        "enable-write": "false"
      }
    }
    ```

    7. Click `Save`.
  </Accordion>
</AccordionGroup>


# Will AI make software companies worthless?
Source: https://developer.upsun.com/posts/ai/will-ai-make-software-companies-worthless

If anyone can build software with AI, do software companies still matter? The answer is more nuanced than you might think.

<PostMeta />

> "If AI gets to the point where anybody can easily create any software, what will happen to all these software companies? Do they just become worthless?"

That question recently sparked a 200+ comment thread on Reddit. And it's not hard to see why people are asking it. Earlier this year at Davos, Anthropic CEO Dario Amodei said something that got a lot of attention: "I have engineers within Anthropic who say, 'I don't write any code anymore. I just let the model write the code. I edit it.'" He went on to predict that AI might handle "most, maybe all" of what software engineers do within six to twelve months.

When the CEO of one of the most advanced AI companies says his own engineers have stopped writing code, it's worth paying attention. So is the software industry headed for collapse?

**The short answer: no. But the long answer is more interesting.**

This question fundamentally misunderstands what a software company actually is.

## The sandwich shop paradox

Think about restaurants for a second. Anyone can make a sandwich. You've got bread, some meat, maybe cheese, whatever sauce you like. Five minutes, done. So why do sandwich shops exist? Why isn't the entire restaurant industry collapsing under the weight of home kitchens?

Because making a sandwich isn't the same as running a sandwich shop.

People pay for convenience. They pay for consistency. They pay for not having to clean up afterward. They pay for the expertise that makes a sandwich better than what they'd throw together at home. And they pay for the entire experience surrounding that sandwich.

Software works the same way. The code is the sandwich. But the business? That's everything else.

## The 1/3 rule

Here's a reality check that often gets lost in these conversations. Take a software company with 300 employees like Upsun. How many of them write code? Maybe 100. A third at best.

<img alt="build" />

The other two-thirds? Sales, marketing, customer success, legal, finance, HR, operations, security, compliance, support. The people who answer the phone when something breaks at 2 AM. The folks who handle enterprise contracts and negotiate SLAs. The team that ensures you're GDPR compliant and won't get sued into oblivion.

AI can help you write code. It can't (yet) replace the entire organizational machinery that turns code into a business. A solo developer with AI can build an app. Building a company that supports thousands of customers across multiple time zones, handles their data securely, maintains uptime guarantees, and evolves the product based on market demands? That's a different beast entirely.

## Creating software is not the same as keeping it running

This is where the "anyone can build software" argument falls apart. Because building is the fun part. It's the honeymoon phase. Everything works in your dev environment, your demo looks slick, and you're feeling pretty good about yourself.

Then reality hits.

<img alt="build" />

Your app needs to handle ten times the traffic you expected. A security vulnerability shows up in one of your dependencies. Users start requesting features you never anticipated. The database schema you designed in week one doesn't scale to week fifty. Some edge case you never considered crashes the whole thing.

Maintenance, security, scalability, updates, patches, monitoring, incident response. This is where software gets expensive. This is where it gets hard. And this is where most vibe-coded projects go to die.

Professional software companies have entire teams dedicated to keeping things running. They have on-call rotations, automated testing pipelines, staging environments, rollback procedures, and years of accumulated knowledge about what can go wrong. A weekend project built with AI prompts doesn't have any of that.

## The vibe coder ceiling

Let's talk about vibe coding for a minute. It's a real phenomenon. Non-technical people are building functional apps by conversing with AI. They're creating personal tools, automating workflows, and prototyping ideas that would have required a developer a few years ago.

This is genuinely impressive. And it's genuinely useful. But it has a ceiling.

Vibe coders hit walls. Weird bugs they can't diagnose. Performance issues they don't understand. Security flaws they can't even see. The AI can get you 80% of the way there, sometimes 90%. But that last 10% often requires understanding what's actually happening under the hood.

Here's a typical scenario: someone builds a personal CRM with AI assistance. Works great for the first 500 contacts. Then the searches start slowing down. The app hangs when loading lists. The AI suggests adding indexes, but the vibe coder doesn't know which ones or why. They copy-paste the solution, and it helps for a while. Then another bottleneck appears. And another. Each fix creates new complexity they don't fully understand.

Eventually, the codebase becomes a house of cards. It works, mostly, but nobody knows why. And when it stops working, nobody knows how to fix it without potentially breaking something else.

And when you're running a business on that software? When customers depend on it? When there's money and reputation on the line? That's when the ceiling becomes a serious problem.

Professional developers aren't going away. What's changing is what they spend their time on. Less boilerplate, more architecture. Less repetitive CRUD, more complex problem-solving. The entry bar for creating something has dropped. The bar for creating something reliable, secure, and scalable hasn't moved much at all.

## Software companies get AI too

Here's something the doomsayers often forget: software companies also have access to AI.

If AI makes individual developers more productive, it makes development teams more productive too. The company that previously needed 50 engineers to build and maintain a product might need 30 now. Or those 50 engineers can build something three times as complex.

<img alt="build" />

Software companies aren't standing still while the world changes around them. They're adopting the same tools, automating their own workflows, and using AI to extend their capabilities. The competitive dynamics shift, but the gap between professional operations and amateur builds doesn't necessarily shrink.

In fact, it might widen. A well-funded company with experienced engineers using AI effectively can produce software at a pace and quality level that a solo vibe coder can't match. The tools are the same, but the expertise in wielding them isn't.

## The real victims: simple SaaS and indie hackers

Alright, so total industry collapse isn't happening. But that doesn't mean everyone survives unscathed.

Simple, single-purpose SaaS apps are in trouble. The habit tracker. The basic CRM. The minimal project management tool. The productivity app that does one thing reasonably well.

These are exactly the kinds of products that motivated individuals can now build for themselves. Why pay \$10 a month for a habit tracker when you can spend a weekend building one that does exactly what you want, customized to your specific workflow, with no subscription fees?

People are doing this. They're canceling subscriptions and building personal tools. Not everyone, but enough to matter. The market for commoditized, undifferentiated software is getting squeezed.

Indie hackers building small products face similar pressure. The barrier to entry has dropped, which means more competition. And when your product is something an AI-assisted weekend project can replicate, your differentiation disappears.

The math used to work like this: spend months building something, charge enough users \$10/month, reach sustainable revenue. Now the equation changes. Potential customers look at your product, think "I could build that," and some of them actually do. Your total addressable market shrinks. Your conversion rates drop. The users who do sign up expect lower prices because they know the alternative.

This doesn't mean all indie products are doomed. Unique value propositions, strong communities, excellent support, and genuine expertise still matter. But "I built a thing that works" isn't enough anymore when anyone can build a thing that works.

## The enterprise moat

On the other end of the spectrum, enterprise software looks pretty safe.

Think Adobe, Microsoft, Salesforce, SAP. These companies aren't selling code. They're selling ecosystems. Integrations with hundreds of other tools. Compliance certifications that took years to obtain. Support contracts with guaranteed response times. Training programs and consultants who know the product inside out. Decades of accumulated features that address every edge case in every industry.

No amount of vibe coding replicates that. You might be able to prompt your way to a basic photo editor or a simple CRM. You're not prompting your way to Photoshop or Salesforce. The complexity is too deep, the ecosystem too interconnected, the trust too hard-earned.

Consider what it actually takes to sell software to a large enterprise. Security audits. SOC 2 compliance. GDPR readiness. Integration with their existing identity provider. Custom SLAs. Dedicated account management. The ability to survive a procurement process that takes six months and involves legal, security, IT, and finance teams.

A solo developer with an AI-built app can't offer any of that. The software itself might be functionally equivalent for a narrow use case. Everything surrounding it isn't even close.

Enterprise buyers aren't looking for the cheapest option. They're looking for the safest option. The vendor who'll still be around in five years. The platform that won't collapse when their business depends on it. AI makes building things easier, but it doesn't make building trust easier.

## The race to the bottom (and what lies beyond)

For simple apps, expect a race to the bottom. Prices will drop. Competition will intensify. Products that don't differentiate will struggle.

But markets have a way of finding equilibrium. When everyone can build basic software, basic software stops being valuable. The premium moves to complexity, reliability, and service. The businesses that survive will be the ones that offer something beyond "it works."

Customer relationships matter more. Support quality matters more. Institutional knowledge matters more. Brand trust matters more. All the things that AI can't easily replicate become the differentiators.

We'll probably see a boom in personal tools. People building exactly what they need, for themselves, maintained as long as they care to maintain it. That's fine. That's even good. It doesn't eliminate the need for professional software any more than home cooking eliminates restaurants.

## The uncomfortable question

Of course, clients are already asking it: "Can't you do this with AI for one-tenth the price?"

The honest answer is: sometimes, yes. For straightforward tasks, AI dramatically reduces the effort required. Pricing models will adjust. Expectations will shift. The market will recalibrate.

But the follow-up question matters more: "And who's going to maintain it? Who's on call when it breaks? Who's liable when something goes wrong? Who's going to update it when requirements change?"

Building software has gotten cheaper. Running a software business hasn't. And as long as that gap exists, software companies have a reason to exist too.

## Where this leaves us

AI isn't making software companies worthless. It's making bad software companies worthless. The ones coasting on complexity that AI can now handle. The ones whose only value proposition was "we can write code and you can't."

The companies that survive and thrive will be the ones that always understood: the code was never the whole product. The business is the product. The reliability is the product. The support is the product. The trust is the product.

If your entire value can be replicated by someone with a laptop and a ChatGPT subscription, you had a problem before AI came along. You were selling a commodity and charging for scarcity.

The scarcity is gone. Time to sell something else.

The software industry has survived paradigm shifts before. The rise of open source didn't kill proprietary software companies. Cloud computing didn't eliminate the need for software vendors. Each wave changed who won and who lost, but the industry adapted.

AI is the next wave. It'll reshape the landscape, not erase it. The winners will be the companies that understand what they're really selling has never been code. It's always been everything around it.


# Artificial Intelligence
Source: https://developer.upsun.com/posts/articles/ai



<ShowMore>
  <a href="/posts/ai/prompts-are-the-new-legacy-code">
    <div>
      <div>
        <span>Thursday, September 10th 2026</span>
      </div>

      <h3>Prompts are the new legacy code</h3>
      <p>Dispatch's code review agent lost 80% of its prompt and four sub-agents. Same model, same quality, cost more than halved, 25% faster. Here's the method.</p>
    </div>
  </a>

  <a href="/posts/ai/how-to-choose-a-code-index-for-your-coding-agent">
    <div>
      <div>
        <span>Tuesday, August 4th 2026</span>
      </div>

      <h3>How to choose a code index for your coding agent</h3>
      <p>Compare Graft and roam-code on a real Go, TypeScript, Swift, and SQL codebase to evaluate context coverage, retrieval quality, and change analysis in practice.</p>
    </div>
  </a>

  <a href="/posts/ai/opencode-token-optimization">
    <div>
      <div>
        <span>Tuesday, June 2nd 2026</span>
      </div>

      <h3>How to slash OpenCode Token costs by 90% on Upsun</h3>
      <p>Cut your OpenCode token usage by up to 90% on Upsun with three community plugins: OpenSlimedit, opencode-dcp, and opencode-snip. Step-by-step guide to install and configure them on your existing deployment, with benchmarks, troubleshooting, and best practices.</p>
    </div>
  </a>

  <a href="/posts/ai/opencode-on-upsun">
    <div>
      <div>
        <span>Tuesday, May 19th 2026</span>
      </div>

      <h3>How to Host OpenCode on Upsun</h3>
      <p>Deploy an OpenCode AI coding agent on Upsun with a single git push. This tutorial covers configuration, persistent storage, LLM API keys, and remote MCP server integration.</p>
    </div>
  </a>

  <a href="/posts/ai/aiweekly-2026-04-27">
    <div>
      <div>
        <span>Monday, April 27th 2026</span>
      </div>

      <h3>AI Weekly Review - Apr. 27th 2026</h3>
      <p>A press, Youtube and Github review of everything AI</p>
    </div>
  </a>

  <a href="/posts/ai/aiweekly-2026-04-13">
    <div>
      <div>
        <span>Monday, April 13th 2026</span>
      </div>

      <h3>AI Weekly Review - Apr. 13th 2026</h3>
      <p>A press, Youtube and Github review of everything AI</p>
    </div>
  </a>

  <a href="/posts/ai/aiweekly-2026-04-07">
    <div>
      <div>
        <span>Tuesday, April 7th 2026</span>
      </div>

      <h3>AI Weekly Review - Apr. 7th 2026</h3>
      <p>A press, Youtube and Github review of everything AI</p>
    </div>
  </a>

  <a href="/posts/discussions/why-ai-agents-need-cloud-sandboxes">
    <div>
      <div>
        <span>Tuesday, March 31st 2026</span>
      </div>

      <h3>Why AI agents need cloud sandboxes</h3>
      <p>AI agents run real commands on real systems. Learn why cloud sandboxes with production data beat local isolation for safe AI agent workflows.</p>
    </div>
  </a>

  <a href="/posts/ai/aiweekly-2026-03-30">
    <div>
      <div>
        <span>Monday, March 30th 2026</span>
      </div>

      <h3>AI Weekly Review - Mar. 30th 2026</h3>
      <p>A press, Youtube and Github review of everything AI</p>
    </div>
  </a>

  <a href="/posts/ai/stuck-on-localhost">
    <div>
      <div>
        <span>Thursday, March 26th 2026</span>
      </div>

      <h3>Your agents are stuck on localhost. Upsun isn't.</h3>
      <p>Coding agents made engineers faster, but cycle time hasn't budged. Background agents running on GitHub, GitLab, and Claude Code can break the bottleneck by producing PRs that Upsun deploys and validates automatically. A practical guide to setting it up with real YAML configs, infrastructure-as-code workflows, and preview environments.</p>
    </div>
  </a>

  <a href="/posts/ai/aiweekly-2026-03-23">
    <div>
      <div>
        <span>Monday, March 23rd 2026</span>
      </div>

      <h3>AI Weekly Review - Mar. 23rd 2026</h3>
      <p>A press, Youtube and Github review of everything AI</p>
    </div>
  </a>

  <a href="/posts/ai/aiweekly-2026-03-16">
    <div>
      <div>
        <span>Monday, March 16th 2026</span>
      </div>

      <h3>AI Weekly Review - Mar. 16th 2026</h3>
      <p>A press, Youtube and Github review of everything AI</p>
    </div>
  </a>

  <a href="/posts/ai/aiweekly-2026-03-09">
    <div>
      <div>
        <span>Monday, March 9th 2026</span>
      </div>

      <h3>AI Weekly Review - Mar. 9th 2026</h3>
      <p>A press, Youtube and Github review of everything AI</p>
    </div>
  </a>

  <a href="/posts/discussions/how-product-managers-use-preview-environments-and-ai-to-prototype">
    <div>
      <div>
        <span>Thursday, March 5th 2026</span>
      </div>

      <h3>How product managers use preview environments and AI to prototype</h3>
      <p>Learn how product managers at Upsun use AI coding assistants and preview environments to prototype feature ideas, validate concepts with real data, and share interactive demos with stakeholders.</p>
    </div>
  </a>

  <a href="/posts/ai/aiweekly-2026-03-02">
    <div>
      <div>
        <span>Monday, March 2nd 2026</span>
      </div>

      <h3>AI Weekly Review - Mar. 2nd 2026</h3>
      <p>A press, Youtube and Github review of everything AI</p>
    </div>
  </a>

  <a href="/posts/discussions/cpu-vs-gpu">
    <div>
      <div>
        <span>Thursday, February 26th 2026</span>
      </div>

      <h3>CPU vs GPU for AI: most AI applications don't need GPUs</h3>
      <p>How to build and deploy an Angular application on Upsun.</p>
    </div>
  </a>

  <a href="/posts/ai/aiweekly-2026-02-23">
    <div>
      <div>
        <span>Monday, February 23rd 2026</span>
      </div>

      <h3>AI Weekly Review - Feb. 23th 2026</h3>
      <p>A press, Youtube and Github review of everything AI</p>
    </div>
  </a>

  <a href="/posts/ai/agents-md-less-is-more">
    <div>
      <div>
        <span>Monday, February 23rd 2026</span>
      </div>

      <h3>The research is in: your AGENTS.md is probably too long</h3>
      <p>Research shows comprehensive AGENTS.md files actually hurt coding agent performance. Learn why less is more and how to build context files that work.</p>
    </div>
  </a>

  <a href="/posts/ai/aiweekly-2026-02-17">
    <div>
      <div>
        <span>Tuesday, February 17th 2026</span>
      </div>

      <h3>AI Weekly Review - Feb. 17th 2026</h3>
      <p>A press, Youtube and Github review of everything AI</p>
    </div>
  </a>

  <a href="/posts/ai/making-coding-agents-reliable">
    <div>
      <div>
        <span>Tuesday, February 17th 2026</span>
      </div>

      <h3>Making coding agents (Claude Code, Codex, etc.) reliable</h3>
      <p>The bottleneck for AI coding agents isn't model capability. It's your verification infrastructure. Here's how to fix that.</p>
    </div>
  </a>

  <a href="/posts/ai/git-worktrees-for-parallel-ai-coding-agents">
    <div>
      <div>
        <span>Wednesday, February 11th 2026</span>
      </div>

      <h3>Git worktrees for parallel AI coding agents</h3>
      <p>Learn how git worktrees enable parallel AI agent workflows, their limitations, and what an ideal orchestration tool needs.</p>
    </div>
  </a>

  <a href="/posts/ai/will-ai-make-software-companies-worthless">
    <div>
      <div>
        <span>Friday, January 30th 2026</span>
      </div>

      <h3>Will AI make software companies worthless?</h3>
      <p>If anyone can build software with AI, do software companies still matter? The answer is more nuanced than you might think.</p>
    </div>
  </a>

  <a href="/posts/discussions/whatsun-efficient-code-analysis">
    <div>
      <div>
        <span>Thursday, December 18th 2025</span>
      </div>

      <h3>Efficient code analysis for LLMs</h3>
      <p>Learn how Whatsun generates concise codebase summaries to improve the performance and accuracy of AI features.</p>
    </div>
  </a>

  <a href="/posts/discussions/building-ai-feature-necessary-evals">
    <div>
      <div>
        <span>Thursday, December 4th 2025</span>
      </div>

      <h3>Building an AI feature: The necessary evals</h3>
      <p>What we learned building an AI feature: evaluations take most of the time, and your existing tools are enough.</p>
    </div>
  </a>

  <a href="/posts/ai/upsun-mcp-announcement">
    <div>
      <div>
        <span>Monday, September 22nd 2025</span>
      </div>

      <h3>Introducing the Upsun MCP server: bring Upsun into your LLMs</h3>
      <p>Manage your Upsun infrastructure directly through AI assistants with our new Model Context Protocol server - now in beta at mcp.upsun.com</p>
    </div>
  </a>

  <a href="/posts/use-cases/n8n-saved-my-life">
    <div>
      <div>
        <span>Thursday, July 3rd 2025</span>
      </div>

      <h3>How n8n saved our Advocacy impact on Social Media!</h3>
      <p>Learn how n8n workflows improve internal communication and amplify our Advocacy social media impact.</p>
    </div>
  </a>

  <a href="/posts/releases/llms-introduction">
    <div>
      <div>
        <span>Friday, February 14th 2025</span>
      </div>

      <h3>Upsun and Platform.sh Docs are now llms.txt compatible!</h3>
      <p>We’re thrilled to announce that both [Upsun Documentation](https://docs.upsun.com) and [Platform.sh Documentation](https://docs.platform.sh) are now fully compatible with [llms.txt proposed standard](https://llmstxt.org/)!</p>
    </div>
  </a>

  <a href="/posts/how-tos/install-pandoc-on-upsun">
    <div>
      <div>
        <span>Wednesday, February 12th 2025</span>
      </div>

      <h3>Up(sun) and ready with Pandoc</h3>
      <p>With the recent growth in enthusiasm for AI assistants, you may be looking for how these assistants can provide technical information about your product.</p>
    </div>
  </a>
</ShowMore>


# Hands-On
Source: https://developer.upsun.com/posts/articles/hands-on



<ShowMore>
  <a href="/posts/tutorials/ai-log-analysis-agent-in-an-upsun-task-container">
    <div>
      <div>
        <span>Tuesday, September 1st 2026</span>
      </div>

      <h3>Run an AI Log-Analysis Agent in an Upsun Task Container</h3>
      <p>Reuse the cron-triggers-a-task pattern to run an OpenCode AI agent inside an Upsun task container. The agent reads your cron and application logs, analyzes them, and writes a Markdown health report to the task logs and a temporary file.</p>
    </div>
  </a>

  <a href="/posts/tutorials/offload-heavy-jobs-to-upsun-task-containers-with-cron">
    <div>
      <div>
        <span>Thursday, August 20th 2026</span>
      </div>

      <h3>Offload Heavy Jobs to Upsun Task Containers, Triggered by Cron</h3>
      <p>Move long, resource-hungry jobs out of your crons and into on-demand Upsun task containers. Learn how to define a task, authorize your app to trigger it, and fire it from a lightweight cron for database imports or search reindexing.</p>
    </div>
  </a>

  <a href="/posts/hands-on/civicrm-with-wordpress-bedrock-on-upsun">
    <div>
      <div>
        <span>Tuesday, June 30th 2026</span>
      </div>

      <h3>CiviCRM with WordPress Bedrock on Upsun</h3>
      <p>A guide to deploying CiviCRM on top of a Bedrock-based WordPress installation on Upsun, utilizing an optimized Composer template and MariaDB schemas.</p>
    </div>
  </a>

  <a href="/posts/use-cases/n8n-upgrade-with-postgresql-and-redis">
    <div>
      <div>
        <span>Wednesday, April 29th 2026</span>
      </div>

      <h3>Scale n8n with PostgreSQL and Redis on Upsun</h3>
      <p>Upgrade your n8n instance from SQLite to PostgreSQL and add Redis caching for better performance, scalability, and reliability. Step-by-step guide for Upsun.</p>
    </div>
  </a>

  <a href="/posts/hands-on/that-cron-should-be-a-worker">
    <div>
      <div>
        <span>Wednesday, March 4th 2026</span>
      </div>

      <h3>That cron should be a worker</h3>
      <p>Long-running crons block your deployments, steal resources from your app container, and create support tickets. Here's when to use workers instead.</p>
    </div>
  </a>

  <a href="/posts/hands-on/the-real-story-of-setting-up-drupal-canvas-with-ai">
    <div>
      <div>
        <span>Friday, February 13th 2026</span>
      </div>

      <h3>From DrupalCon keynote to live Upsun demo: the real story of setting up Drupal Canvas with AI</h3>
      <p>Discover how the Lemberg Solutions team set up Drupal Canvas with an AI assistant: how long it took, the challenges we faced and lessons we learned.</p>
    </div>
  </a>

  <a href="/posts/hands-on/scriberr-on-upsun">
    <div>
      <div>
        <span>Tuesday, February 10th 2026</span>
      </div>

      <h3>Scriberr on Upsun</h3>
      <p>Learn how to deploy Scriberr, an AI-powered transcription tool, on Upsun for self-hosted audio and video transcription.</p>
    </div>
  </a>

  <a href="/posts/hands-on/unstable-website-use-queues">
    <div>
      <div>
        <span>Thursday, February 5th 2026</span>
      </div>

      <h3>Unstable website? Use queues.</h3>
      <p>Your site throws 502 errors when external APIs are slow. The fix isn't more resources. It's offloading that work to background jobs so your responses stay fast.</p>
    </div>
  </a>

  <a href="/posts/hands-on/how-to-use-harlequin-sql-ide-with-upsun">
    <div>
      <div>
        <span>Wednesday, January 14th 2026</span>
      </div>

      <h3>How to Use Harlequin SQL IDE with Upsun</h3>
      <p>Learn two ways to connect Harlequin SQL IDE to your Upsun PostgreSQL database: using local SSH tunnels or deploying Harlequin directly on the platform.</p>
    </div>
  </a>

  <a href="/posts/hands-on/stop-testing-jcr-apps-in-production">
    <div>
      <div>
        <span>Tuesday, January 6th 2026</span>
      </div>

      <h3>Stop testing JCR apps in production</h3>
      <p>Learn why JCR-based applications benefit from fast, production-grade environment cloning. Discover how Upsun removes one of JCR's biggest operational challenges through instant repository duplication.</p>
    </div>
  </a>

  <a href="/posts/hands-on/civicrm-drupal-11-on-upsun">
    <div>
      <div>
        <span>Friday, December 19th 2025</span>
      </div>

      <h3>Installing CiviCRM with Drupal 11 on Upsun</h3>
      <p>Learn how to install CiviCRM with Drupal 11 on Upsun, from config.yml and databases to cron, caching, extensions and Skvare’s best-practice template.</p>
    </div>
  </a>

  <a href="/posts/hands-on/migration-day-executing-your-upsun-cutover">
    <div>
      <div>
        <span>Tuesday, December 16th 2025</span>
      </div>

      <h3>Migration day: executing your Upsun cutover</h3>
      <p>A step-by-step guide to migration day: maintenance windows, cutover sequences, verification, and post-migration monitoring strategies.</p>
    </div>
  </a>

  <a href="/posts/hands-on/zero-downtime-deployments-with-upsun">
    <div>
      <div>
        <span>Wednesday, December 3rd 2025</span>
      </div>

      <h3>Zero-downtime deployments: now in open beta</h3>
      <p>We've launched zero-downtime deployments in open beta. Deploy your applications without service interruption.</p>
    </div>
  </a>

  <a href="/posts/hands-on/ai-use-case-generate-load-test-scenarios">
    <div>
      <div>
        <span>Thursday, November 27th 2025</span>
      </div>

      <h3>AI use-case: Generate load test scenarios with MCPs</h3>
      <p>Automate Locust load testing by combining Chrome MCP and Context7 to generate realistic user behavior patterns with Claude Code.</p>
    </div>
  </a>

  <a href="/posts/hands-on/varnish-104-advanced-traffic-filtering-with-classification-headers-on-upsun">
    <div>
      <div>
        <span>Friday, November 7th 2025</span>
      </div>

      <h3>Varnish 104: Advanced Traffic Filtering with Classification Headers on Upsun</h3>
      <p>Learn how to implement advanced security controls in Varnish on Upsun using classification headers to block malicious traffic, restrict geographic access, filter by ASN, and protect sensitive paths with HTTP Basic Auth.</p>
    </div>
  </a>

  <a href="/posts/hands-on/varnish-103-cache-optimization-with-url-normalization-on-upsun">
    <div>
      <div>
        <span>Friday, October 31st 2025</span>
      </div>

      <h3>Varnish 103: Cache Optimization with URL Normalization on Upsun</h3>
      <p>Learn how to maximize Varnish cache efficiency through URL normalization, query string sorting, and tracking parameter removal to dramatically improve cache hit ratios and reduce backend load.</p>
    </div>
  </a>

  <a href="/posts/hands-on/varnish-102-protecting-your-application-with-rate-limiting-on-upsun">
    <div>
      <div>
        <span>Friday, October 24th 2025</span>
      </div>

      <h3>Varnish 102: Protecting Your Application with Rate Limiting on Upsun</h3>
      <p>Learn how to implement effective rate limiting in Varnish using the vsthrottle VMOD to protect your application from abuse, prevent DDoS attacks, and ensure fair resource allocation.</p>
    </div>
  </a>

  <a href="/posts/hands-on/varnish-101-protecting-paths-with-http-basic-authentication-on-upsun">
    <div>
      <div>
        <span>Friday, October 17th 2025</span>
      </div>

      <h3>Varnish 101: Protecting Paths with HTTP Basic Authentication on Upsun</h3>
      <p>Learn how to implement HTTP Basic Authentication directly in Varnish VCL on Upsun to protect specific paths like admin areas, staging environments, and work-in-progress content without touching your backend.</p>
    </div>
  </a>

  <a href="/posts/hands-on/building-internal-ai-agents-for-our-teams-on-upsun">
    <div>
      <div>
        <span>Tuesday, September 30th 2025</span>
      </div>

      <h3>Building internal AI agents for our teams on Upsun</h3>
      <p>Learn how to build and deploy production-ready AI agents on Upsun using Google's ADK, ChromaDB vector database, and Retrieval-Augmented Generation (RAG) to create context-aware, domain-specific agents for your team.</p>
    </div>
  </a>

  <a href="/posts/hands-on/run-tailscale-on-upsun-secure-vpn-connections">
    <div>
      <div>
        <span>Tuesday, September 16th 2025</span>
      </div>

      <h3>Run Tailscale on Upsun: Create secure VPN connections for your applications</h3>
      <p>Learn how to integrate Tailscale VPN with your Upsun applications to create secure, private network connections between your containers and infrastructure.</p>
    </div>
  </a>

  <a href="/posts/hands-on/store-embeddings-in-chroma-with-persistent-storage-nodejs-and-python-examples">
    <div>
      <div>
        <span>Wednesday, September 3rd 2025</span>
      </div>

      <h3>Store embeddings in chroma with persistent storage (nodejs and python examples)</h3>
      <p>Learn how to implement Chroma with persistent storage on Upsun using both Node.js and Python, including document ingestion and embedding storage.</p>
    </div>
  </a>

  <a href="/posts/hands-on/fastly-maintenance">
    <div>
      <div>
        <span>Monday, August 25th 2025</span>
      </div>

      <h3>How to enable custom maintenance page in Fastly</h3>
      <p>Configure GitLab CI/CD to deploy to Upsun from private air-gapped GitLab instances using push-based workflows and API automation.</p>
    </div>
  </a>

  <a href="/posts/hands-on/connect-multiple-projects-applications-or-services-together">
    <div>
      <div>
        <span>Friday, August 15th 2025</span>
      </div>

      <h3>Connect multiple projects applications or services together</h3>
      <p>Learn how to use Chisel to securely connect applications and services across different Upsun projects, with a practical MariaDB replication example.</p>
    </div>
  </a>

  <a href="/posts/hands-on/gitlab-push-solution">
    <div>
      <div>
        <span>Monday, July 21st 2025</span>
      </div>

      <h3>Synchronize your air-gapped GitLab with Upsun</h3>
      <p>Configure GitLab CI/CD to deploy to Upsun from private air-gapped GitLab instances using push-based workflows and API automation</p>
    </div>
  </a>

  <a href="/posts/hands-on/deploy-mcp-servers-on-upsun">
    <div>
      <div>
        <span>Thursday, June 5th 2025</span>
      </div>

      <h3>Build and deploy AI-Native Applications with MCP Servers on Upsun</h3>
      <p>Learn how Model Context Protocol servers work with different transports and deploy them to Upsun for scalable AI-powered applications</p>
    </div>
  </a>

  <a href="/posts/hands-on/nocode-n8n">
    <div>
      <div>
        <span>Wednesday, May 14th 2025</span>
      </div>

      <h3>NoCode with Upsun: Supercharge Your Automation with Zero Code</h3>
      <p>Learn how to leverage Upsun to deploy powerful NoCode tools like n8n for workflow automation. Fast setup, secure hosting, and real-world use cases — all without writing code.</p>
    </div>
  </a>

  <a href="/posts/hands-on/pytorch-running-on-upsun">
    <div>
      <div>
        <span>Thursday, May 1st 2025</span>
      </div>

      <h3>How to run PyTorch in an Upsun application?</h3>
      <p>Learn how to deploy a sentiment analysis application powered by PyTorch and FastAPI on the Upsun cloud platform</p>
    </div>
  </a>

  <a href="/posts/hands-on/postgres-mcp-on-upsun">
    <div>
      <div>
        <span>Wednesday, April 30th 2025</span>
      </div>

      <h3>Using PostgreSQL MCP with Upsun Remote Database</h3>
      <p>Learn how to set up an MCP server to connect your Upsun PostgreSQL database to language models like Claude or IDE like VSCode GitHub Copilot and Cursor, enabling natural language data queries without writing SQL.</p>
    </div>
  </a>

  <a href="/posts/hands-on/route-ids-env">
    <div>
      <div>
        <span>Monday, April 28th 2025</span>
      </div>

      <h3>How to automatically inject multi-app endpoints as environment variables</h3>
      <p>Learn how to use Upsun route identifiers and the PLATFORM\_ROUTES variable to easily get and use the hostnames of dynamically deployed applications in your project.</p>
    </div>
  </a>

  <a href="/posts/hands-on/install-gh-asset-on-upsun">
    <div>
      <div>
        <span>Thursday, April 10th 2025</span>
      </div>

      <h3>Up(sun) and ready with GitHub release assets installation</h3>
      <p>Discover how to install any GitHub release asset you want in your Upsun project.</p>
    </div>
  </a>

  <a href="/posts/hands-on/deploying-chainlit-with-rag">
    <div>
      <div>
        <span>Tuesday, January 14th 2025</span>
      </div>

      <h3>Experiment with Chainlit AI interface with RAG on Upsun</h3>
      <p>Learn to deploy production-ready RAG applications with Chainlit and Python on Upsun. Tutorial covers OpenAI Assistants integration, llama\_index implementation, and secure authentication.</p>
    </div>
  </a>

  <a href="/posts/hands-on/harnessing-power-embeddings">
    <div>
      <div>
        <span>Monday, May 20th 2024</span>
      </div>

      <h3>Harnessing the power of Embeddings: a real-world example of a watch recommendation app using a vector database.</h3>
      <p>Learn how to build a real-world watch recommendation application using embeddings and a vector database. This tutorial covers using Postgres with pgvector, Laravel, React, OpenAI, and Groq, deployed on Upsun.</p>
    </div>
  </a>

  <a href="/posts/hands-on/guide-to-limit-deployments-to-platformsh-only-with-tags-part-three">
    <div>
      <div>
        <span>Friday, April 12th 2024</span>
      </div>

      <h3>Limit deployments to Platform.sh only with tags: part three</h3>
      <p>In parts [one](/posts/hands-on/guide-to-limit-deployments-to-platformsh-only-with-tags-part-one) and</p>
    </div>
  </a>

  <a href="/posts/hands-on/guide-to-limit-deployments-to-platformsh-only-with-tags-part-one">
    <div>
      <div>
        <span>Thursday, March 14th 2024</span>
      </div>

      <h3>Limit deployments to Platform.sh only with tags: part one</h3>
      <p>Throughout the years, many users have asked us if it’s possible to only deploy to Platform.sh when a tag is pushed using</p>
    </div>
  </a>

  <a href="/posts/hands-on/guide-to-limit-deployments-to-platformsh-only-with-tags-part-two">
    <div>
      <div>
        <span>Thursday, March 14th 2024</span>
      </div>

      <h3>Limit deployments to Platform.sh only when Git tagged: part two</h3>
      <p>In [part one of this series](https://platform.sh/blog/guide-to-limit-deployments-to-platformsh-only-with-tags-part-one/),</p>
    </div>
  </a>

  <a href="/posts/hands-on/powerup-your-local-development-with-ddev">
    <div>
      <div>
        <span>Thursday, January 5th 2023</span>
      </div>

      <h3>Power-up Your Local Development with DDEV</h3>
      <p>Get the best local development experience with the DDEV-Platform.sh add-on. Follow our guide, share your feedback, and optimize your workflow</p>
    </div>
  </a>
</ShowMore>


# How It Works
Source: https://developer.upsun.com/posts/articles/how-it-works



<ShowMore>
  <a href="/posts/how-it-works/airflow-on-a-locked-down-platform">
    <div>
      <div>
        <span>Tuesday, September 22nd 2026</span>
      </div>

      <h3>Airflow on a locked-down platform</h3>
      <p>Running Apache Airflow on Upsun's hardened containers takes 30 lines of C and a decision about how much task isolation you actually want back.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/how-to-host-a-website-that-isnt-publicly-reachable">
    <div>
      <div>
        <span>Thursday, September 3rd 2026</span>
      </div>

      <h3>How to host a website that isn't publicly reachable</h3>
      <p>Some applications should never answer a request from the open internet. Here are the ways to make one unreachable on Upsun, and how to pick between them.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/why-lets-encrypt-certificate-renewals-fail">
    <div>
      <div>
        <span>Tuesday, August 25th 2026</span>
      </div>

      <h3>Why Let's Encrypt certificate renewals fail</h3>
      <p>Certificate renewals fail for a handful of recurring reasons. Here's how the HTTP-01 challenge works and what breaks it, from IPv6 records to CDN rules.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/how-ssh-authentication-works-on-upsun">
    <div>
      <div>
        <span>Tuesday, August 18th 2026</span>
      </div>

      <h3>How SSH authentication works on Upsun Cloud</h3>
      <p>Decode the SSH certificate the Upsun CLI provisions for you, then follow it through the SSH proxy: CA trust, revocation, access documents, and MFA.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/backup-consistency-why-it-matters-and-how-upsun-handles-it">
    <div>
      <div>
        <span>Tuesday, July 21st 2026</span>
      </div>

      <h3>Backup consistency: why it matters and how Upsun handles it</h3>
      <p>Learn what backup consistency means at the filesystem and service levels, and how Upsun balances consistent backups with zero-disruption live backups.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/can-you-trust-the-x-client-ip-header">
    <div>
      <div>
        <span>Tuesday, July 14th 2026</span>
      </div>

      <h3>Can you trust the X-Client-IP header?</h3>
      <p>Why the X-Client-IP header on Upsun holds the real visitor IP behind Fastly, Cloudflare, and CloudFront, and how to log real client IPs behind any other CDN.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/write-a-git-server-with-per-branch-permissions-in-five-minutes">
    <div>
      <div>
        <span>Tuesday, July 7th 2026</span>
      </div>

      <h3>Write a Git server with per-branch permissions in five minutes</h3>
      <p>Upsun's most basic API is a Git server. Build one in Python with Dulwich and Paramiko, and add per-branch read permissions in a single method.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/cloning-a-terabyte-in-a-minute-and-the-limit-hiding-behind-it">
    <div>
      <div>
        <span>Tuesday, June 23rd 2026</span>
      </div>

      <h3>Cloning a terabyte in a minute, and the limit hiding behind it</h3>
      <p>Upsun clones a terabyte production environment in under a minute using Ceph copy-on-write. Here is the 16-level clone-depth limit behind it, why flattening is the price you pay, and what it says about engineering trade-offs.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/how-redundancy-and-failover-work-on-upsun">
    <div>
      <div>
        <span>Tuesday, June 16th 2026</span>
      </div>

      <h3>How redundancy and failover work on Upsun</h3>
      <p>Upsun handles redundancy and failover inside your region, at the compute, storage, and network layers. Here's where it happens, how fast it is, and the trade-offs behind it.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/upsun-deployment-hooks-and-commands-which-one-to-use-and-when">
    <div>
      <div>
        <span>Thursday, June 4th 2026</span>
      </div>

      <h3>Upsun deployment hooks and commands: which one to use, and when</h3>
      <p>Build hooks, deploy hooks, pre\_start, start, and post\_start all shape how Upsun deploys your app. Learn what each one does and when to reach for it.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/building-observability-from-scratch-three-times-over">
    <div>
      <div>
        <span>Tuesday, April 21st 2026</span>
      </div>

      <h3>Building observability from scratch, three times over</h3>
      <p>A look back at how Platform.sh / Upsun's observability evolved from Nagios on a single box to a unified stack across thousands of VMs, and the migration patterns that made each transition smooth.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/how-we-caught-a-silent-io-storm-before-it-hit-production">
    <div>
      <div>
        <span>Tuesday, April 14th 2026</span>
      </div>

      <h3>How we caught a silent IO storm before it hit production</h3>
      <p>A sysctl setting that worked fine for years caused over 500 MB/s of disk writes after migrating to Debian 12. MariaDB stalled on pending IO, Redis complained about slow fsync, and RBD-backed storage ground to a halt. The culprit: cgroup v2 changes how the kernel divides dirty page budgets across containers.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/how-upsun-provisions-tls-certificates-at-scale">
    <div>
      <div>
        <span>Thursday, April 9th 2026</span>
      </div>

      <h3>How Upsun provisions TLS certificates at scale</h3>
      <p>Every Upsun environment gets HTTPS automatically. Here's how the certificate system works, from wildcards to Let's Encrypt automation.</p>
    </div>
  </a>

  <a href="/posts/core-concepts/meta-upsun-validation-schema-dx-improvement">
    <div>
      <div>
        <span>Tuesday, April 7th 2026</span>
      </div>

      <h3>How Meta-Upsun improved Validation Schema and Developer eXperience</h3>
      <p>The introduction of Meta-Upsun enabled dynamic validation schemas and version enumeration for Upsun services and runtimes, significantly improving developer experience.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/why-upsun-moved-from-lvm-to-ceph">
    <div>
      <div>
        <span>Thursday, April 2nd 2026</span>
      </div>

      <h3>Why we moved from LVM to Ceph for container storage</h3>
      <p>Upsun migrated from LVM to Ceph for container storage to separate compute from storage, enable instant volume migration, and make VMs disposable again.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/meta-reference-source-introduction">
    <div>
      <div>
        <span>Wednesday, March 25th 2026</span>
      </div>

      <h3>Centralising Upsun Technical References with Meta-Upsun</h3>
      <p>How Upsun centralised runtime, service, region, and PHP reference data into a single public API to improve consistency, automation, and documentation accuracy.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/rpm-repo-s3">
    <div>
      <div>
        <span>Tuesday, March 17th 2026</span>
      </div>

      <h3>How we host an RPM repository on AWS S3</h3>
      <p>Learn how to host an RPM repository entirely on AWS S3 with no active components, minimal cost, and authenticated access using IAM.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/natural-scaling-for-multi-country-ecommerce">
    <div>
      <div>
        <span>Thursday, March 12th 2026</span>
      </div>

      <h3>Natural scaling for multi-country ecommerce</h3>
      <p>Multi-country ecommerce is a textbook case for natural scaling. Instead of cramming every country into one store, give each its own. Here's why.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/your-waf-is-buffering-ours-is-streaming">
    <div>
      <div>
        <span>Wednesday, February 18th 2026</span>
      </div>

      <h3>Your WAF is buffering. Ours is streaming.</h3>
      <p>Most WAFs buffer your entire request before validating it. That's slow. Upsun's technical WAF validates requests while streaming them to your backend, so you don't pay a latency tax for security.</p>
    </div>
  </a>

  <a href="/posts/core-concepts/eliminating-database-pwd-risk-with-network-isolation">
    <div>
      <div>
        <span>Wednesday, February 4th 2026</span>
      </div>

      <h3>Eliminating Database Password Risk with Network Isolation</h3>
      <p>By removing default database passwords, Upsun reduces common credential risks (leaks, reuse, hardcoding) and relies on stronger security controls like SSH keys and private networking.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/spf-dkim-dmarc-what-are-those-for-anyway">
    <div>
      <div>
        <span>Thursday, January 29th 2026</span>
      </div>

      <h3>SPF, DKIM, DMARC, what are those for anyway?</h3>
      <p>Finally understand what SPF, DKIM, and DMARC actually do, why email needs them, and how to set them up without wanting to flip a table.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/how-weve-been-hardening-containers-since-before-docker-made-it-cool">
    <div>
      <div>
        <span>Tuesday, January 13th 2026</span>
      </div>

      <h3>How we've been hardening containers since before Docker made it cool</h3>
      <p>Docker's hardened images are great, but we've been doing this for years. Here's the automated pipeline that's been securing hundreds of container images behind the scenes at Upsun.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/keeping-the-peace-how-zookeeper-stops-database-nodes-from-fighting">
    <div>
      <div>
        <span>Tuesday, December 9th 2025</span>
      </div>

      <h3>Keeping the peace: how ZooKeeper stops database nodes from fighting</h3>
      <p>Learn how Upsun uses Zookeeper's sequences, watchers, and ephemeral nodes to coordinate MariaDB clusters and workers across distributed systems without breaking your application.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/when-php-fpm-runs-out-of-workers-a-502-error-field-guide">
    <div>
      <div>
        <span>Monday, November 24th 2025</span>
      </div>

      <h3>When php-fpm runs out of workers: a 502 error field guide</h3>
      <p>Your PHP site keeps throwing 502 errors. Your CDN shows 503s. Learn why PHP-FPM workers get exhausted and how to diagnose and fix the real problems.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/we-switched-from-lvm-to-sparse-files">
    <div>
      <div>
        <span>Friday, November 14th 2025</span>
      </div>

      <h3>We switched from LVM to... sparse files?!</h3>
      <p>How we eliminated 90% of VM evacuation time by replacing LVM with sparse files for temporary storage. A tale of inertia, performance bottlenecks, and surprisingly effective solutions.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/we-made-our-infrastructure-read-only-and-never-looked-back">
    <div>
      <div>
        <span>Monday, November 3rd 2025</span>
      </div>

      <h3>We made our infrastructure read-only and never looked back</h3>
      <p>Learn why read-only infrastructure eliminates entire classes of security attacks, improves reproducibility, and simplifies compliance while enabling predictable deployments.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/event-loop-monitoring-in-nextjs-performance-guide">
    <div>
      <div>
        <span>Friday, October 24th 2025</span>
      </div>

      <h3>Event Loop Monitoring in Next.js: Performance Guide</h3>
      <p>Learn to implement event loop monitoring in Next.js applications to identify blocking operations, optimize performance, and scale confidently with production-ready code.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/autoscaling-deep-dive">
    <div>
      <div>
        <span>Monday, October 20th 2025</span>
      </div>

      <h3>Auto-scaling on Upsun Flex. A deep dive.</h3>
      <p>Learn how Upsun's autoscaling dynamically adjusts application instances based on CPU usage, ensuring performance during traffic spikes while optimizing costs.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/fake-ip-till-you-make-ip">
    <div>
      <div>
        <span>Tuesday, October 14th 2025</span>
      </div>

      <h3>Fake IP till you make IP</h3>
      <p>How Upsun uses virtual IPs and NAT to keep your database connections stable even when containers move between VMs. A look at the networking tricks behind relationship stability.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/explore-plan-execute-methodology">
    <div>
      <div>
        <span>Friday, October 3rd 2025</span>
      </div>

      <h3>Mastering the Explore, Plan, Execute methodology for AI-assisted development</h3>
      <p>Learn how to transform AI coding assistants from eager juniors into rockstar developers using proven context strategies, quality assurance, and the three-phase workflow</p>
    </div>
  </a>

  <a href="/posts/how-it-works/cut-aws-bandwidth-costs-95-with-dm-cache">
    <div>
      <div>
        <span>Tuesday, September 9th 2025</span>
      </div>

      <h3>How we cut AWS bandwidth costs 95% with dm-cache: fast local SSD caching for network storage</h3>
      <p>Learn how Upsun solved costly inter-AZ bandwidth billing by implementing dm-cache with local SSDs, achieving 95% read traffic reduction and 30x performance improvement.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/how-do-we-do-incremental-but-really-full-backups-on-top-of-ceph">
    <div>
      <div>
        <span>Monday, August 25th 2025</span>
      </div>

      <h3>High-performance backups: How Ceph snapshots enable incremental full backups</h3>
      <p>Learn how Upsun leverages Ceph's RBD export-diff feature to implement high-performance incremental backups that maintain full restore capabilities for large-scale container storage.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/how-upsun-built-stateless-mesh-networking-for-high-density-containers">
    <div>
      <div>
        <span>Wednesday, August 6th 2025</span>
      </div>

      <h3>How Upsun built stateless mesh networking for high-density containers</h3>
      <p>Discover how Upsun's innovative stateless mesh networking architecture handles thousands of containers without databases or bottlenecks.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/mcp-interaction-types-article">
    <div>
      <div>
        <span>Saturday, June 7th 2025</span>
      </div>

      <h3>Beyond Tool Calling: Understanding MCP's Three Core Interaction Types</h3>
      <p>Discover how prompts, resources, and tools work together in the Model Context Protocol to create richer AI application experiences beyond simple tool calling.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/debian-repo-s3">
    <div>
      <div>
        <span>Wednesday, January 29th 2025</span>
      </div>

      <h3>How we host a Debian repository on AWS S3</h3>
      <p>Pretty cool fact about our internal Debian repositories: they’re hosted entirely on AWS S3. Why is that cool? For 2</p>
    </div>
  </a>

  <a href="/posts/how-it-works/using-the-upsun-api">
    <div>
      <div>
        <span>Thursday, September 19th 2024</span>
      </div>

      <h3>Using the Upsun API</h3>
      <p>> Anything you can do, API can do better!</p>
    </div>
  </a>

  <a href="/posts/how-it-works/how-platformsh-stays-ahead-of-emerging-cybersecurity-threats">
    <div>
      <div>
        <span>Friday, October 13th 2023</span>
      </div>

      <h3>Semper vigilans: how Platform.sh stays ahead of emerging cybersecurity threats (so you don’t have to)</h3>
      <p>Always vigilant is more than a motto. Find out how the Platform.sh Security team monitors vulnerabilities 24x7 to protect customers from cybersecurity threats.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/how-do-you-manage-ssh-keys-in-your-organization">
    <div>
      <div>
        <span>Wednesday, October 21st 2020</span>
      </div>

      <h3>SSH certificates with Platform.sh</h3>
      <p>Learn how Platform.sh simplifies provisioning SSH certificates for secure and keyless SSH authentication, enhancing security and making compliance easier.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/installers-that-dont-suck">
    <div>
      <div>
        <span>Wednesday, August 5th 2020</span>
      </div>

      <h3>Installers that don't suck</h3>
      <p>Learn how to create cloud-friendly web application installers that account for cloud-based environments and optimize the user experience.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/the-platformsh-build-and-deploy-pipeline">
    <div>
      <div>
        <span>Tuesday, October 3rd 2017</span>
      </div>

      <h3>The Platform.sh build-and-deploy pipeline</h3>
      <p>Learn how Platform.sh simplifies the build and deploy pipeline for web applications, ensuring consistency and repeatability with Git-based semantics.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/repeatable-deployments">
    <div>
      <div>
        <span>Tuesday, December 13th 2016</span>
      </div>

      <h3>How repeatable deployments work</h3>
      <p>Platform.sh ensures predictable, repeatable deployments by controlling the key inputs to your application and guaranteeing code consistency.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/how-platform-paas-works">
    <div>
      <div>
        <span>Tuesday, March 3rd 2015</span>
      </div>

      <h3>How the Platform.sh PaaS works</h3>
      <p>Discover how Platform.sh simplifies PaaS. Focus on your code; we manage the rest. Explore our second-generation PaaS for seamless application development.</p>
    </div>
  </a>
</ShowMore>


# How-Tos
Source: https://developer.upsun.com/posts/articles/how-tos



<ShowMore>
  <a href="/posts/how-tos/supply-chain-attacks-in-the-ai-era-and-what-to-do-about-them">
    <div>
      <div>
        <span>Thursday, April 30th 2026</span>
      </div>

      <h3>Supply chain attacks in the AI era, and what to do about them</h3>
      <p>AI agents are reading code at scale, including your dependencies. Why supply chain risk just changed, plus a build-time fix to add on Upsun.</p>
    </div>
  </a>

  <a href="/posts/how-tos/meta-version-updater-introduction">
    <div>
      <div>
        <span>Wednesday, April 1st 2026</span>
      </div>

      <h3>Automating Runtime and Service Tracking with Meta Version Updater</h3>
      <p>Meta is Upsun’s shared reference layer for runtimes, services, regions, and extensions. Learn why we built it, how it works, and how it powers the next generation of Upsun documentation and tooling.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/meta-reference-source-introduction">
    <div>
      <div>
        <span>Wednesday, March 25th 2026</span>
      </div>

      <h3>Centralising Upsun Technical References with Meta-Upsun</h3>
      <p>How Upsun centralised runtime, service, region, and PHP reference data into a single public API to improve consistency, automation, and documentation accuracy.</p>
    </div>
  </a>

  <a href="/posts/how-tos/replicate-your-production-outage-on-staging">
    <div>
      <div>
        <span>Tuesday, March 10th 2026</span>
      </div>

      <h3>Replicate your production outage on staging</h3>
      <p>After fixing a production outage, you need to prove the fix works under the same traffic. Here's how to replicate real production traffic on an Upsun staging environment using the observability API and k6.</p>
    </div>
  </a>

  <a href="/posts/how-tos/fastly-cdn-and-waf">
    <div>
      <div>
        <span>Tuesday, March 3rd 2026</span>
      </div>

      <h3>Speed vs. Security? Why not both: The Fastly CDN and WAF on Upsun</h3>
      <p>Learn how to pair Fastly’s CDN for speed with its Next-Gen WAF for security on Upsun. Optimize global performance while protecting your infrastructure from threats.</p>
    </div>
  </a>

  <a href="/posts/how-tos/automated-encrypt-backups-amazon-s3">
    <div>
      <div>
        <span>Monday, January 12th 2026</span>
      </div>

      <h3>Automated encrypted backups to Amazon S3 | Upsun</h3>
      <p>Learn how to configure Duplicity, GPG keys, and cron on Upsun to send incremental, encrypted backups of your application to AWS S3 for reliable restores</p>
    </div>
  </a>

  <a href="/posts/how-tos/planning-your-upsun-migration-the-6-9-week-roadmap">
    <div>
      <div>
        <span>Tuesday, December 2nd 2025</span>
      </div>

      <h3>Planning your Upsun migration: the 6-9 week roadmap</h3>
      <p>Learn why 6-9 weeks is the ideal timeline for Upsun migrations, with expert insights on planning, testing, and avoiding common pitfalls.</p>
    </div>
  </a>

  <a href="/posts/how-tos/creating-custom-reports-using-cli">
    <div>
      <div>
        <span>Wednesday, November 12th 2025</span>
      </div>

      <h3>Creating Custom Reports using the Upsun Cloud CLI</h3>
      <p>Someone recently asked me</p>
    </div>
  </a>

  <a href="/posts/how-tos/fastlycdn-pluginapp-activation">
    <div>
      <div>
        <span>Tuesday, October 7th 2025</span>
      </div>

      <h3>Streamline Your CDN Management with Fastly CDN Plugin App \[BETA]</h3>
      <p>Managing Content Delivery Network (CDN) configurations alongside your application deployments can be a complex task, often requiring developers to switch between multiple interfaces and tools. The Fastly CDN plugin app bridges this gap by bringing Fastly CDN management directly into your Upsun console, creating a seamless workflow for developers who want to manage their CDN configurations without leaving their primary development environment.</p>
    </div>
  </a>

  <a href="/posts/how-tos/composer1-rip">
    <div>
      <div>
        <span>Tuesday, September 9th 2025</span>
      </div>

      <h3>Composer 1 is dead – Upgrade to Composer 2 now</h3>
      <p>Composer 1 has reached end of life and is no longer available on Upsun and Platform.sh. Learn why it’s no longer possible to rely on Composer 1, what errors you’ll see, and how to safely upgrade your project to Composer 2.</p>
    </div>
  </a>

  <a href="/posts/how-tos/handling-well-known-directory">
    <div>
      <div>
        <span>Monday, May 26th 2025</span>
      </div>

      <h3>How to manage the `.well-known` directory on Upsun and Platform.sh</h3>
      <p>If you have ever tried to enable</p>
    </div>
  </a>

  <a href="/posts/how-tos/validate-yaml-config">
    <div>
      <div>
        <span>Tuesday, May 6th 2025</span>
      </div>

      <h3>Making .upsun/config.yaml easier to edit with IDE autocomplete and validation</h3>
      <p>Boost your productivity and eliminate configuration errors with real-time autocompletion and validation for your .upsun/config.yaml — discover how to enhance your IDE experience in just a few simple steps!</p>
    </div>
  </a>

  <a href="/posts/how-tos/context7-mcp">
    <div>
      <div>
        <span>Thursday, May 1st 2025</span>
      </div>

      <h3>Upsun documentation is now available via the Context7 MCP</h3>
      <p>Access Upsun documentation directly from your AI workflows using Context7's Model Context Protocol integration</p>
    </div>
  </a>

  <a href="/posts/how-tos/install-pandoc-on-upsun">
    <div>
      <div>
        <span>Wednesday, February 12th 2025</span>
      </div>

      <h3>Up(sun) and ready with Pandoc</h3>
      <p>With the recent growth in enthusiasm for AI assistants, you may be looking for how these assistants can provide technical information about your product.</p>
    </div>
  </a>

  <a href="/posts/how-tos/no-downtime-postgres-updates">
    <div>
      <div>
        <span>Thursday, January 9th 2025</span>
      </div>

      <h3>How to update your PostgreSQL database without downtime</h3>
      <p>On paper, releasing a new version of your application that requires upgrading the schema of the database is straightforward. But, changes of code and schema can not be updated in an atomic way, you only need to take care that old code is not performing a query against new schema, and reciprocally.</p>
    </div>
  </a>

  <a href="/posts/how-tos/blackfire-google-alert-markers-interfaces">
    <div>
      <div>
        <span>Tuesday, November 5th 2024</span>
      </div>

      <h3>Import multiple RSS Feeds on your Blackfire timeline + extra interfaces</h3>
      <p>We saw in the [previous episode](/posts/how-tos/blackfire-google-alert-markers) how to automatically add context on your Blackfire timeline from an RSS Feed (Google Alert),</p>
    </div>
  </a>

  <a href="/posts/how-tos/schedule-resource-availability">
    <div>
      <div>
        <span>Thursday, October 24th 2024</span>
      </div>

      <h3>Scheduling resources</h3>
      <p>As Upsun does purely usage-driven billing,</p>
    </div>
  </a>

  <a href="/posts/how-tos/configuring-an-autoscaler">
    <div>
      <div>
        <span>Saturday, October 19th 2024</span>
      </div>

      <h3>Adding an autoscaler to Upsun projects</h3>
      <p>In this post we will describe a small configuration that will</p>
    </div>
  </a>

  <a href="/posts/how-tos/blackfire-google-alert-markers">
    <div>
      <div>
        <span>Monday, October 7th 2024</span>
      </div>

      <h3>Add context on your Blackfire timeline from a Google Alerts RSS Feed</h3>
      <p>Observing your application is essential to be able to find what needs (and what does not need) to be optimized.</p>
    </div>
  </a>

  <a href="/posts/how-tos/automate-with-gatling-1">
    <div>
      <div>
        <span>Friday, September 20th 2024</span>
      </div>

      <h3>How to automate load tests with Gatling</h3>
      <p>When I was on your side of the keyboard, developing cool and funny applications (more or less :D), load tests were (most of the time) executed a few days before going live.</p>
    </div>
  </a>

  <a href="/posts/how-tos/help-reduce-resource-consumption-put-your-preview-environments-on-pause">
    <div>
      <div>
        <span>Friday, August 18th 2023</span>
      </div>

      <h3>Help reduce resource consumption: Put your preview environments on pause</h3>
      <p>You can now manually pause your idle preview environments or have them automatically paused after 14 days of being idle to minimize your resource usage.</p>
    </div>
  </a>

  <a href="/posts/how-tos/measuring-the-success-of-a-deployment-with-githubactions">
    <div>
      <div>
        <span>Thursday, December 23rd 2021</span>
      </div>

      <h3>Measuring Deployment Success with GitHub Actions</h3>
      <p>Learn how GitHub actions can streamline your Platform.sh deployments for faster and more efficient development workflows</p>
    </div>
  </a>

  <a href="/posts/how-tos/get-more-control-over-your-environments-with-build-variables">
    <div>
      <div>
        <span>Tuesday, August 10th 2021</span>
      </div>

      <h3>Get more control over your environments with build variables</h3>
      <p>Discover the visible-build flag on Platform.sh, enabling environment-specific build variables for more control over your development process.</p>
    </div>
  </a>
</ShowMore>


# All Articles
Source: https://developer.upsun.com/posts/articles/index



<div>
  <a href="https://developer.upsun.com/posts/articles/blog-rss/rss.xml" title="RSS Feed">
    <svg>
      <path />
    </svg>

    RSS
  </a>
</div>

<ShowMore>
  <a href="/posts/insights/session-storage-gets-complicated-faster-than-you-think">
    <div>
      <div>
        <span>Wednesday, September 30th 2026</span>
      </div>

      <h3>Session storage gets complicated faster than you think</h3>
      <p>Explore session storage tradeoffs across files, PostgreSQL, Redis, and Valkey, from expiration and cleanup to memory limits. Test your options on Upsun Cloud.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/airflow-on-a-locked-down-platform">
    <div>
      <div>
        <span>Tuesday, September 22nd 2026</span>
      </div>

      <h3>Airflow on a locked-down platform</h3>
      <p>Running Apache Airflow on Upsun's hardened containers takes 30 lines of C and a decision about how much task isolation you actually want back.</p>
    </div>
  </a>

  <a href="/posts/ai/prompts-are-the-new-legacy-code">
    <div>
      <div>
        <span>Thursday, September 10th 2026</span>
      </div>

      <h3>Prompts are the new legacy code</h3>
      <p>Dispatch's code review agent lost 80% of its prompt and four sub-agents. Same model, same quality, cost more than halved, 25% faster. Here's the method.</p>
    </div>
  </a>

  <a href="/posts/discussions/give-your-ai-agent-a-system-that-is-safe-to-break">
    <div>
      <div>
        <span>Tuesday, September 8th 2026</span>
      </div>

      <h3>Give your AI agent a system that is safe to break</h3>
      <p>Handing an agent credentials narrows what it can do, not where its mistakes land. Run it inside a branched environment instead, and the worst outcome is a broken copy of your stack.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/how-to-host-a-website-that-isnt-publicly-reachable">
    <div>
      <div>
        <span>Thursday, September 3rd 2026</span>
      </div>

      <h3>How to host a website that isn't publicly reachable</h3>
      <p>Some applications should never answer a request from the open internet. Here are the ways to make one unreachable on Upsun, and how to pick between them.</p>
    </div>
  </a>

  <a href="/posts/tutorials/ai-log-analysis-agent-in-an-upsun-task-container">
    <div>
      <div>
        <span>Tuesday, September 1st 2026</span>
      </div>

      <h3>Run an AI Log-Analysis Agent in an Upsun Task Container</h3>
      <p>Reuse the cron-triggers-a-task pattern to run an OpenCode AI agent inside an Upsun task container. The agent reads your cron and application logs, analyzes them, and writes a Markdown health report to the task logs and a temporary file.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/why-lets-encrypt-certificate-renewals-fail">
    <div>
      <div>
        <span>Tuesday, August 25th 2026</span>
      </div>

      <h3>Why Let's Encrypt certificate renewals fail</h3>
      <p>Certificate renewals fail for a handful of recurring reasons. Here's how the HTTP-01 challenge works and what breaks it, from IPv6 records to CDN rules.</p>
    </div>
  </a>

  <a href="/posts/tutorials/offload-heavy-jobs-to-upsun-task-containers-with-cron">
    <div>
      <div>
        <span>Thursday, August 20th 2026</span>
      </div>

      <h3>Offload Heavy Jobs to Upsun Task Containers, Triggered by Cron</h3>
      <p>Move long, resource-hungry jobs out of your crons and into on-demand Upsun task containers. Learn how to define a task, authorize your app to trigger it, and fire it from a lightweight cron for database imports or search reindexing.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/how-ssh-authentication-works-on-upsun">
    <div>
      <div>
        <span>Tuesday, August 18th 2026</span>
      </div>

      <h3>How SSH authentication works on Upsun Cloud</h3>
      <p>Decode the SSH certificate the Upsun CLI provisions for you, then follow it through the SSH proxy: CA trust, revocation, access documents, and MFA.</p>
    </div>
  </a>

  <a href="/posts/ai/how-to-choose-a-code-index-for-your-coding-agent">
    <div>
      <div>
        <span>Tuesday, August 4th 2026</span>
      </div>

      <h3>How to choose a code index for your coding agent</h3>
      <p>Compare Graft and roam-code on a real Go, TypeScript, Swift, and SQL codebase to evaluate context coverage, retrieval quality, and change analysis in practice.</p>
    </div>
  </a>

  <a href="/posts/insights/which-stack-would-you-pick-for-an-interactive-ai-app-today">
    <div>
      <div>
        <span>Friday, July 31st 2026</span>
      </div>

      <h3>Which stack would you pick for an interactive AI app today?</h3>
      <p>Coding agents changed how new teams pick a tech stack. A tour of 8 ecosystems for interactive AI apps, and why "can we run it" beats "can we write it".</p>
    </div>
  </a>

  <a href="/posts/how-it-works/backup-consistency-why-it-matters-and-how-upsun-handles-it">
    <div>
      <div>
        <span>Tuesday, July 21st 2026</span>
      </div>

      <h3>Backup consistency: why it matters and how Upsun handles it</h3>
      <p>Learn what backup consistency means at the filesystem and service levels, and how Upsun balances consistent backups with zero-disruption live backups.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/can-you-trust-the-x-client-ip-header">
    <div>
      <div>
        <span>Tuesday, July 14th 2026</span>
      </div>

      <h3>Can you trust the X-Client-IP header?</h3>
      <p>Why the X-Client-IP header on Upsun holds the real visitor IP behind Fastly, Cloudflare, and CloudFront, and how to log real client IPs behind any other CDN.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/write-a-git-server-with-per-branch-permissions-in-five-minutes">
    <div>
      <div>
        <span>Tuesday, July 7th 2026</span>
      </div>

      <h3>Write a Git server with per-branch permissions in five minutes</h3>
      <p>Upsun's most basic API is a Git server. Build one in Python with Dulwich and Paramiko, and add per-branch read permissions in a single method.</p>
    </div>
  </a>

  <a href="/posts/insights/why-emacs-is-still-my-interface-to-my-computer">
    <div>
      <div>
        <span>Tuesday, June 30th 2026</span>
      </div>

      <h3>Why Emacs is still my interface to my computer</h3>
      <p>Why I still use Emacs every day: one consistent interface for editing, Git with Magit, terminals, a Claude Code agent per project, and the rest of my computer.</p>
    </div>
  </a>

  <a href="/posts/hands-on/civicrm-with-wordpress-bedrock-on-upsun">
    <div>
      <div>
        <span>Tuesday, June 30th 2026</span>
      </div>

      <h3>CiviCRM with WordPress Bedrock on Upsun</h3>
      <p>A guide to deploying CiviCRM on top of a Bedrock-based WordPress installation on Upsun, utilizing an optimized Composer template and MariaDB schemas.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/cloning-a-terabyte-in-a-minute-and-the-limit-hiding-behind-it">
    <div>
      <div>
        <span>Tuesday, June 23rd 2026</span>
      </div>

      <h3>Cloning a terabyte in a minute, and the limit hiding behind it</h3>
      <p>Upsun clones a terabyte production environment in under a minute using Ceph copy-on-write. Here is the 16-level clone-depth limit behind it, why flattening is the price you pay, and what it says about engineering trade-offs.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/how-redundancy-and-failover-work-on-upsun">
    <div>
      <div>
        <span>Tuesday, June 16th 2026</span>
      </div>

      <h3>How redundancy and failover work on Upsun</h3>
      <p>Upsun handles redundancy and failover inside your region, at the compute, storage, and network layers. Here's where it happens, how fast it is, and the trade-offs behind it.</p>
    </div>
  </a>

  <a href="/posts/insights/code-matters-less-than-ever-and-more-than-ever">
    <div>
      <div>
        <span>Tuesday, June 9th 2026</span>
      </div>

      <h3>Code matters less than ever, and more than ever</h3>
      <p>AI made code cheap to write and cheap to throw away, so it matters less than ever. It also matters more, because debugging, reviews, and velocity all depend on it.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/upsun-deployment-hooks-and-commands-which-one-to-use-and-when">
    <div>
      <div>
        <span>Thursday, June 4th 2026</span>
      </div>

      <h3>Upsun deployment hooks and commands: which one to use, and when</h3>
      <p>Build hooks, deploy hooks, pre\_start, start, and post\_start all shape how Upsun deploys your app. Learn what each one does and when to reach for it.</p>
    </div>
  </a>

  <a href="/posts/ai/opencode-token-optimization">
    <div>
      <div>
        <span>Tuesday, June 2nd 2026</span>
      </div>

      <h3>How to slash OpenCode Token costs by 90% on Upsun</h3>
      <p>Cut your OpenCode token usage by up to 90% on Upsun with three community plugins: OpenSlimedit, opencode-dcp, and opencode-snip. Step-by-step guide to install and configure them on your existing deployment, with benchmarks, troubleshooting, and best practices.</p>
    </div>
  </a>

  <a href="/posts/tutorials/deploying-laravel-reverb-on-upsun">
    <div>
      <div>
        <span>Thursday, May 21st 2026</span>
      </div>

      <h3>Deploying Laravel Reverb on Upsun</h3>
      <p>Build a real-time voting app with Laravel and Reverb, deploy it to Upsun, then scale the WebSocket layer horizontally with Redis pub/sub.</p>
    </div>
  </a>

  <a href="/posts/insights/ddev-is-in-good-hands">
    <div>
      <div>
        <span>Thursday, May 21st 2026</span>
      </div>

      <h3>DDEV is in good hands</h3>
      <p>DDEV is alive, actively maintained, and back with its foundation. A look at our chapter in the project, why we got involved, and why we are happy to step out of the way.</p>
    </div>
  </a>

  <a href="/posts/ai/opencode-on-upsun">
    <div>
      <div>
        <span>Tuesday, May 19th 2026</span>
      </div>

      <h3>How to Host OpenCode on Upsun</h3>
      <p>Deploy an OpenCode AI coding agent on Upsun with a single git push. This tutorial covers configuration, persistent storage, LLM API keys, and remote MCP server integration.</p>
    </div>
  </a>

  <a href="/posts/insights/rate-limiting-rails-apps-when-you-cant-put-varnish-in-front">
    <div>
      <div>
        <span>Tuesday, May 12th 2026</span>
      </div>

      <h3>Rate limiting Rails apps when you can't put Varnish in front</h3>
      <p>When the edge isn't yours, rate limit from inside the application. How rack-attack works, why limits are about quality of service, and what Rails 8 changed.</p>
    </div>
  </a>

  <a href="/posts/insights/the-not-so-hidden-cost-of-ai-scrapers">
    <div>
      <div>
        <span>Tuesday, May 5th 2026</span>
      </div>

      <h3>The (not so) hidden cost of AI scrapers</h3>
      <p>AI scrapers drive up your hosting cost while real users wait. Use robots.txt, cache normalization, and sane application limits to take the pressure off.</p>
    </div>
  </a>

  <a href="/posts/how-tos/supply-chain-attacks-in-the-ai-era-and-what-to-do-about-them">
    <div>
      <div>
        <span>Thursday, April 30th 2026</span>
      </div>

      <h3>Supply chain attacks in the AI era, and what to do about them</h3>
      <p>AI agents are reading code at scale, including your dependencies. Why supply chain risk just changed, plus a build-time fix to add on Upsun.</p>
    </div>
  </a>

  <a href="/posts/use-cases/n8n-upgrade-with-postgresql-and-redis">
    <div>
      <div>
        <span>Wednesday, April 29th 2026</span>
      </div>

      <h3>Scale n8n with PostgreSQL and Redis on Upsun</h3>
      <p>Upgrade your n8n instance from SQLite to PostgreSQL and add Redis caching for better performance, scalability, and reliability. Step-by-step guide for Upsun.</p>
    </div>
  </a>

  <a href="/posts/ai/aiweekly-2026-04-27">
    <div>
      <div>
        <span>Monday, April 27th 2026</span>
      </div>

      <h3>AI Weekly Review - Apr. 27th 2026</h3>
      <p>A press, Youtube and Github review of everything AI</p>
    </div>
  </a>

  <a href="/posts/how-it-works/building-observability-from-scratch-three-times-over">
    <div>
      <div>
        <span>Tuesday, April 21st 2026</span>
      </div>

      <h3>Building observability from scratch, three times over</h3>
      <p>A look back at how Platform.sh / Upsun's observability evolved from Nagios on a single box to a unified stack across thousands of VMs, and the migration patterns that made each transition smooth.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/how-we-caught-a-silent-io-storm-before-it-hit-production">
    <div>
      <div>
        <span>Tuesday, April 14th 2026</span>
      </div>

      <h3>How we caught a silent IO storm before it hit production</h3>
      <p>A sysctl setting that worked fine for years caused over 500 MB/s of disk writes after migrating to Debian 12. MariaDB stalled on pending IO, Redis complained about slow fsync, and RBD-backed storage ground to a halt. The culprit: cgroup v2 changes how the kernel divides dirty page budgets across containers.</p>
    </div>
  </a>

  <a href="/posts/ai/aiweekly-2026-04-13">
    <div>
      <div>
        <span>Monday, April 13th 2026</span>
      </div>

      <h3>AI Weekly Review - Apr. 13th 2026</h3>
      <p>A press, Youtube and Github review of everything AI</p>
    </div>
  </a>

  <a href="/posts/how-it-works/how-upsun-provisions-tls-certificates-at-scale">
    <div>
      <div>
        <span>Thursday, April 9th 2026</span>
      </div>

      <h3>How Upsun provisions TLS certificates at scale</h3>
      <p>Every Upsun environment gets HTTPS automatically. Here's how the certificate system works, from wildcards to Let's Encrypt automation.</p>
    </div>
  </a>

  <a href="/posts/tutorials/sandboxing-ai-agents-on-upsun">
    <div>
      <div>
        <span>Wednesday, April 8th 2026</span>
      </div>

      <h3>Sandboxing AI agents on Upsun</h3>
      <p>Sandbox AI agents in Upsun containers to protect secrets from prompt injection. Covers Linux primitives, Claude Code, and Codex.</p>
    </div>
  </a>

  <a href="/posts/core-concepts/meta-upsun-validation-schema-dx-improvement">
    <div>
      <div>
        <span>Tuesday, April 7th 2026</span>
      </div>

      <h3>How Meta-Upsun improved Validation Schema and Developer eXperience</h3>
      <p>The introduction of Meta-Upsun enabled dynamic validation schemas and version enumeration for Upsun services and runtimes, significantly improving developer experience.</p>
    </div>
  </a>

  <a href="/posts/ai/aiweekly-2026-04-07">
    <div>
      <div>
        <span>Tuesday, April 7th 2026</span>
      </div>

      <h3>AI Weekly Review - Apr. 7th 2026</h3>
      <p>A press, Youtube and Github review of everything AI</p>
    </div>
  </a>

  <a href="/posts/how-it-works/why-upsun-moved-from-lvm-to-ceph">
    <div>
      <div>
        <span>Thursday, April 2nd 2026</span>
      </div>

      <h3>Why we moved from LVM to Ceph for container storage</h3>
      <p>Upsun migrated from LVM to Ceph for container storage to separate compute from storage, enable instant volume migration, and make VMs disposable again.</p>
    </div>
  </a>

  <a href="/posts/how-tos/meta-version-updater-introduction">
    <div>
      <div>
        <span>Wednesday, April 1st 2026</span>
      </div>

      <h3>Automating Runtime and Service Tracking with Meta Version Updater</h3>
      <p>Meta is Upsun’s shared reference layer for runtimes, services, regions, and extensions. Learn why we built it, how it works, and how it powers the next generation of Upsun documentation and tooling.</p>
    </div>
  </a>

  <a href="/posts/discussions/why-ai-agents-need-cloud-sandboxes">
    <div>
      <div>
        <span>Tuesday, March 31st 2026</span>
      </div>

      <h3>Why AI agents need cloud sandboxes</h3>
      <p>AI agents run real commands on real systems. Learn why cloud sandboxes with production data beat local isolation for safe AI agent workflows.</p>
    </div>
  </a>

  <a href="/posts/ai/aiweekly-2026-03-30">
    <div>
      <div>
        <span>Monday, March 30th 2026</span>
      </div>

      <h3>AI Weekly Review - Mar. 30th 2026</h3>
      <p>A press, Youtube and Github review of everything AI</p>
    </div>
  </a>

  <a href="/posts/ai/stuck-on-localhost">
    <div>
      <div>
        <span>Thursday, March 26th 2026</span>
      </div>

      <h3>Your agents are stuck on localhost. Upsun isn't.</h3>
      <p>Coding agents made engineers faster, but cycle time hasn't budged. Background agents running on GitHub, GitLab, and Claude Code can break the bottleneck by producing PRs that Upsun deploys and validates automatically. A practical guide to setting it up with real YAML configs, infrastructure-as-code workflows, and preview environments.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/meta-reference-source-introduction">
    <div>
      <div>
        <span>Wednesday, March 25th 2026</span>
      </div>

      <h3>Centralising Upsun Technical References with Meta-Upsun</h3>
      <p>How Upsun centralised runtime, service, region, and PHP reference data into a single public API to improve consistency, automation, and documentation accuracy.</p>
    </div>
  </a>

  <a href="/posts/discussions/governance-is-a-contract-chain-and-youre-in-it">
    <div>
      <div>
        <span>Tuesday, March 24th 2026</span>
      </div>

      <h3>Governance is a contract chain, and you're in it</h3>
      <p>Governance is a chain of contracts from certification bodies to you. AI didn't change the chain, but it produces code faster than humans can review it.</p>
    </div>
  </a>

  <a href="/posts/ai/aiweekly-2026-03-23">
    <div>
      <div>
        <span>Monday, March 23rd 2026</span>
      </div>

      <h3>AI Weekly Review - Mar. 23rd 2026</h3>
      <p>A press, Youtube and Github review of everything AI</p>
    </div>
  </a>

  <a href="/posts/how-it-works/rpm-repo-s3">
    <div>
      <div>
        <span>Tuesday, March 17th 2026</span>
      </div>

      <h3>How we host an RPM repository on AWS S3</h3>
      <p>Learn how to host an RPM repository entirely on AWS S3 with no active components, minimal cost, and authenticated access using IAM.</p>
    </div>
  </a>

  <a href="/posts/releases/introducing-developer-upsun-com">
    <div>
      <div>
        <span>Monday, March 16th 2026</span>
      </div>

      <h3>Introducing developer.upsun.com: Upsun docs, rebuilt for developers and AI agents</h3>
      <p>The Upsun documentation has moved to developer.upsun.com with a complete infrastructure rebuild focused on agent-readiness. 244+ pages of structured, machine-readable content with llms.txt support and built-in AI assistance.</p>
    </div>
  </a>

  <a href="/posts/ai/aiweekly-2026-03-16">
    <div>
      <div>
        <span>Monday, March 16th 2026</span>
      </div>

      <h3>AI Weekly Review - Mar. 16th 2026</h3>
      <p>A press, Youtube and Github review of everything AI</p>
    </div>
  </a>

  <a href="/posts/how-it-works/natural-scaling-for-multi-country-ecommerce">
    <div>
      <div>
        <span>Thursday, March 12th 2026</span>
      </div>

      <h3>Natural scaling for multi-country ecommerce</h3>
      <p>Multi-country ecommerce is a textbook case for natural scaling. Instead of cramming every country into one store, give each its own. Here's why.</p>
    </div>
  </a>

  <a href="/posts/how-tos/replicate-your-production-outage-on-staging">
    <div>
      <div>
        <span>Tuesday, March 10th 2026</span>
      </div>

      <h3>Replicate your production outage on staging</h3>
      <p>After fixing a production outage, you need to prove the fix works under the same traffic. Here's how to replicate real production traffic on an Upsun staging environment using the observability API and k6.</p>
    </div>
  </a>

  <a href="/posts/ai/aiweekly-2026-03-09">
    <div>
      <div>
        <span>Monday, March 9th 2026</span>
      </div>

      <h3>AI Weekly Review - Mar. 9th 2026</h3>
      <p>A press, Youtube and Github review of everything AI</p>
    </div>
  </a>

  <a href="/posts/discussions/how-product-managers-use-preview-environments-and-ai-to-prototype">
    <div>
      <div>
        <span>Thursday, March 5th 2026</span>
      </div>

      <h3>How product managers use preview environments and AI to prototype</h3>
      <p>Learn how product managers at Upsun use AI coding assistants and preview environments to prototype feature ideas, validate concepts with real data, and share interactive demos with stakeholders.</p>
    </div>
  </a>

  <a href="/posts/hands-on/that-cron-should-be-a-worker">
    <div>
      <div>
        <span>Wednesday, March 4th 2026</span>
      </div>

      <h3>That cron should be a worker</h3>
      <p>Long-running crons block your deployments, steal resources from your app container, and create support tickets. Here's when to use workers instead.</p>
    </div>
  </a>

  <a href="/posts/how-tos/fastly-cdn-and-waf">
    <div>
      <div>
        <span>Tuesday, March 3rd 2026</span>
      </div>

      <h3>Speed vs. Security? Why not both: The Fastly CDN and WAF on Upsun</h3>
      <p>Learn how to pair Fastly’s CDN for speed with its Next-Gen WAF for security on Upsun. Optimize global performance while protecting your infrastructure from threats.</p>
    </div>
  </a>

  <a href="/posts/ai/aiweekly-2026-03-02">
    <div>
      <div>
        <span>Monday, March 2nd 2026</span>
      </div>

      <h3>AI Weekly Review - Mar. 2nd 2026</h3>
      <p>A press, Youtube and Github review of everything AI</p>
    </div>
  </a>

  <a href="/posts/tutorials/deploy-mattermost-on-upsun">
    <div>
      <div>
        <span>Friday, February 27th 2026</span>
      </div>

      <h3>Deploy Mattermost Team Edition on Upsun</h3>
      <p>Learn how to deploy a self-hosted Mattermost Team Edition server on Upsun, with PostgreSQL 16 and OpenSearch 2 configured automatically through a single infrastructure-as-code file.</p>
    </div>
  </a>

  <a href="/posts/discussions/cpu-vs-gpu">
    <div>
      <div>
        <span>Thursday, February 26th 2026</span>
      </div>

      <h3>CPU vs GPU for AI: most AI applications don't need GPUs</h3>
      <p>How to build and deploy an Angular application on Upsun.</p>
    </div>
  </a>

  <a href="/posts/releases/upsun-node-sdk-announcement">
    <div>
      <div>
        <span>Wednesday, February 25th 2026</span>
      </div>

      <h3>Announcing the Official Upsun Node.js SDK</h3>
      <p>Discover how the Upsun Node SDK simplifies API access and speeds up integrations, with clear documentation and modern tooling.</p>
    </div>
  </a>

  <a href="/posts/discussions/instant-data-cloning-was-a-bet-ai-agents-are-the-payoff">
    <div>
      <div>
        <span>Tuesday, February 24th 2026</span>
      </div>

      <h3>Instant data cloning was a bet. AI agents are the payoff.</h3>
      <p>How Upsun's data-first architecture, built a decade ago for CMS and e-commerce needs, turns out to be the exact infrastructure AI agents need: instant, isolated, production-identical environments with real data.</p>
    </div>
  </a>

  <a href="/posts/ai/aiweekly-2026-02-23">
    <div>
      <div>
        <span>Monday, February 23rd 2026</span>
      </div>

      <h3>AI Weekly Review - Feb. 23th 2026</h3>
      <p>A press, Youtube and Github review of everything AI</p>
    </div>
  </a>

  <a href="/posts/ai/agents-md-less-is-more">
    <div>
      <div>
        <span>Monday, February 23rd 2026</span>
      </div>

      <h3>The research is in: your AGENTS.md is probably too long</h3>
      <p>Research shows comprehensive AGENTS.md files actually hurt coding agent performance. Learn why less is more and how to build context files that work.</p>
    </div>
  </a>

  <a href="/posts/discussions/building-an-ai-code-review-agent-for-gitlab">
    <div>
      <div>
        <span>Thursday, February 19th 2026</span>
      </div>

      <h3>Building an AI code review agent for our self-hosted GitLab</h3>
      <p>I vibe-coded a GitLab code review agent last month - 40K lines of Python written by Claude - and it has reviewed 1000 merge requests.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/your-waf-is-buffering-ours-is-streaming">
    <div>
      <div>
        <span>Wednesday, February 18th 2026</span>
      </div>

      <h3>Your WAF is buffering. Ours is streaming.</h3>
      <p>Most WAFs buffer your entire request before validating it. That's slow. Upsun's technical WAF validates requests while streaming them to your backend, so you don't pay a latency tax for security.</p>
    </div>
  </a>

  <a href="/posts/ai/aiweekly-2026-02-17">
    <div>
      <div>
        <span>Tuesday, February 17th 2026</span>
      </div>

      <h3>AI Weekly Review - Feb. 17th 2026</h3>
      <p>A press, Youtube and Github review of everything AI</p>
    </div>
  </a>

  <a href="/posts/ai/making-coding-agents-reliable">
    <div>
      <div>
        <span>Tuesday, February 17th 2026</span>
      </div>

      <h3>Making coding agents (Claude Code, Codex, etc.) reliable</h3>
      <p>The bottleneck for AI coding agents isn't model capability. It's your verification infrastructure. Here's how to fix that.</p>
    </div>
  </a>

  <a href="/posts/hands-on/the-real-story-of-setting-up-drupal-canvas-with-ai">
    <div>
      <div>
        <span>Friday, February 13th 2026</span>
      </div>

      <h3>From DrupalCon keynote to live Upsun demo: the real story of setting up Drupal Canvas with AI</h3>
      <p>Discover how the Lemberg Solutions team set up Drupal Canvas with an AI assistant: how long it took, the challenges we faced and lessons we learned.</p>
    </div>
  </a>

  <a href="/posts/ai/git-worktrees-for-parallel-ai-coding-agents">
    <div>
      <div>
        <span>Wednesday, February 11th 2026</span>
      </div>

      <h3>Git worktrees for parallel AI coding agents</h3>
      <p>Learn how git worktrees enable parallel AI agent workflows, their limitations, and what an ideal orchestration tool needs.</p>
    </div>
  </a>

  <a href="/posts/hands-on/scriberr-on-upsun">
    <div>
      <div>
        <span>Tuesday, February 10th 2026</span>
      </div>

      <h3>Scriberr on Upsun</h3>
      <p>Learn how to deploy Scriberr, an AI-powered transcription tool, on Upsun for self-hosted audio and video transcription.</p>
    </div>
  </a>

  <a href="/posts/hands-on/unstable-website-use-queues">
    <div>
      <div>
        <span>Thursday, February 5th 2026</span>
      </div>

      <h3>Unstable website? Use queues.</h3>
      <p>Your site throws 502 errors when external APIs are slow. The fix isn't more resources. It's offloading that work to background jobs so your responses stay fast.</p>
    </div>
  </a>

  <a href="/posts/core-concepts/eliminating-database-pwd-risk-with-network-isolation">
    <div>
      <div>
        <span>Wednesday, February 4th 2026</span>
      </div>

      <h3>Eliminating Database Password Risk with Network Isolation</h3>
      <p>By removing default database passwords, Upsun reduces common credential risks (leaks, reuse, hardcoding) and relies on stronger security controls like SSH keys and private networking.</p>
    </div>
  </a>

  <a href="/posts/insights/the-only-correct-way-to-git-pull-and-merge">
    <div>
      <div>
        <span>Tuesday, February 3rd 2026</span>
      </div>

      <h3>The only correct way to git pull and merge</h3>
      <p>A strongly opinionated guide to git pull and merge strategies that will make your commit history actually useful. Learn when to rebase, when to merge, and why the defaults are lying to you.</p>
    </div>
  </a>

  <a href="/posts/ai/will-ai-make-software-companies-worthless">
    <div>
      <div>
        <span>Friday, January 30th 2026</span>
      </div>

      <h3>Will AI make software companies worthless?</h3>
      <p>If anyone can build software with AI, do software companies still matter? The answer is more nuanced than you might think.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/spf-dkim-dmarc-what-are-those-for-anyway">
    <div>
      <div>
        <span>Thursday, January 29th 2026</span>
      </div>

      <h3>SPF, DKIM, DMARC, what are those for anyway?</h3>
      <p>Finally understand what SPF, DKIM, and DMARC actually do, why email needs them, and how to set them up without wanting to flip a table.</p>
    </div>
  </a>

  <a href="/posts/insights/the-third-way-to-scale-that-nobody-talks-about">
    <div>
      <div>
        <span>Tuesday, January 20th 2026</span>
      </div>

      <h3>The third way to scale that nobody talks about</h3>
      <p>Beyond vertical and horizontal scaling lies a third approach that most scaling discussions ignore. Learn about natural scaling, where you sidestep the problem entirely.</p>
    </div>
  </a>

  <a href="/posts/hands-on/how-to-use-harlequin-sql-ide-with-upsun">
    <div>
      <div>
        <span>Wednesday, January 14th 2026</span>
      </div>

      <h3>How to Use Harlequin SQL IDE with Upsun</h3>
      <p>Learn two ways to connect Harlequin SQL IDE to your Upsun PostgreSQL database: using local SSH tunnels or deploying Harlequin directly on the platform.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/how-weve-been-hardening-containers-since-before-docker-made-it-cool">
    <div>
      <div>
        <span>Tuesday, January 13th 2026</span>
      </div>

      <h3>How we've been hardening containers since before Docker made it cool</h3>
      <p>Docker's hardened images are great, but we've been doing this for years. Here's the automated pipeline that's been securing hundreds of container images behind the scenes at Upsun.</p>
    </div>
  </a>

  <a href="/posts/how-tos/automated-encrypt-backups-amazon-s3">
    <div>
      <div>
        <span>Monday, January 12th 2026</span>
      </div>

      <h3>Automated encrypted backups to Amazon S3 | Upsun</h3>
      <p>Learn how to configure Duplicity, GPG keys, and cron on Upsun to send incremental, encrypted backups of your application to AWS S3 for reliable restores</p>
    </div>
  </a>

  <a href="/posts/discussions/the-universal-commerce-protocol-and-the-inevitable-rise-of-agentic-commerce">
    <div>
      <div>
        <span>Monday, January 12th 2026</span>
      </div>

      <h3>The universal commerce protocol and the inevitable rise of agentic commerce</h3>
      <p>Fifteen years ago, I believed the trajectory of digital commerce was destined for a singular, consolidated fate. To me, the technological landscape was fracturing rapidly; the desktop monopoly had shattered, giving way to the mobile web, native applications, and the nascent experiments of Google Glass and early IoT devices. In my view, for independent brands and retailers, this multiplication of channels represented a terrifying escalation in technical complexity. To sell effectively, I thought a merchant needed not just a website, but a mobile-responsive design, an iOS app, an Android app, and integrations with a growing roster of marketplaces.</p>
    </div>
  </a>

  <a href="/posts/hands-on/stop-testing-jcr-apps-in-production">
    <div>
      <div>
        <span>Tuesday, January 6th 2026</span>
      </div>

      <h3>Stop testing JCR apps in production</h3>
      <p>Learn why JCR-based applications benefit from fast, production-grade environment cloning. Discover how Upsun removes one of JCR's biggest operational challenges through instant repository duplication.</p>
    </div>
  </a>

  <a href="/posts/releases/composer-2.9">
    <div>
      <div>
        <span>Thursday, December 25th 2025</span>
      </div>

      <h3>Composer 2.9 lands on Upsun PHP Images: Here’s what you need to know</h3>
      <p>Remote code execution vulnerability in Next.js 15.x and 16.x App Router requires immediate patching. Learn how to secure your applications.</p>
    </div>
  </a>

  <a href="/posts/hands-on/civicrm-drupal-11-on-upsun">
    <div>
      <div>
        <span>Friday, December 19th 2025</span>
      </div>

      <h3>Installing CiviCRM with Drupal 11 on Upsun</h3>
      <p>Learn how to install CiviCRM with Drupal 11 on Upsun, from config.yml and databases to cron, caching, extensions and Skvare’s best-practice template.</p>
    </div>
  </a>

  <a href="/posts/discussions/whatsun-efficient-code-analysis">
    <div>
      <div>
        <span>Thursday, December 18th 2025</span>
      </div>

      <h3>Efficient code analysis for LLMs</h3>
      <p>Learn how Whatsun generates concise codebase summaries to improve the performance and accuracy of AI features.</p>
    </div>
  </a>

  <a href="/posts/unknown/how-we-scaled-live-connections-for-1200-developers-at-symfonycon">
    <div>
      <div>
        <span>Wednesday, December 17th 2025</span>
      </div>

      <h3>How we scaled live connections for 1200 developers at SymfonyCon</h3>
      <p>A Symfony core contributor's journey from FrankenPHP 502 errors to a stable multi-app architecture that handled hundreds of live connections at SymfonyCon 2025.</p>
    </div>
  </a>

  <a href="/posts/hands-on/migration-day-executing-your-upsun-cutover">
    <div>
      <div>
        <span>Tuesday, December 16th 2025</span>
      </div>

      <h3>Migration day: executing your Upsun cutover</h3>
      <p>A step-by-step guide to migration day: maintenance windows, cutover sequences, verification, and post-migration monitoring strategies.</p>
    </div>
  </a>

  <a href="/posts/releases/composable-image-embraces-real-world-diversity">
    <div>
      <div>
        <span>Thursday, December 11th 2025</span>
      </div>

      <h3>One project, many needs: How Composable Image embraces real-world diversity</h3>
      <p>Applications rarely fit inside a single tidy runtime box. They evolve through experiments, architectural shifts, quick MVP spikes that outlast their intended lifespan, and the continuous layering of new business needs.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/keeping-the-peace-how-zookeeper-stops-database-nodes-from-fighting">
    <div>
      <div>
        <span>Tuesday, December 9th 2025</span>
      </div>

      <h3>Keeping the peace: how ZooKeeper stops database nodes from fighting</h3>
      <p>Learn how Upsun uses Zookeeper's sequences, watchers, and ephemeral nodes to coordinate MariaDB clusters and workers across distributed systems without breaking your application.</p>
    </div>
  </a>

  <a href="/posts/insights/why-you-cant-just-add-infinite-php-fpm-workers">
    <div>
      <div>
        <span>Monday, December 8th 2025</span>
      </div>

      <h3>Why you can't just add infinite PHP-FPM workers</h3>
      <p>Workers need memory. Learn how PHP-FPM sizing hints work, why you can't just add infinite workers, and how to tune your worker count based on actual memory usage.</p>
    </div>
  </a>

  <a href="/posts/discussions/building-ai-feature-necessary-evals">
    <div>
      <div>
        <span>Thursday, December 4th 2025</span>
      </div>

      <h3>Building an AI feature: The necessary evals</h3>
      <p>What we learned building an AI feature: evaluations take most of the time, and your existing tools are enough.</p>
    </div>
  </a>

  <a href="/posts/discussions/nextjs-cve-2025-66478">
    <div>
      <div>
        <span>Thursday, December 4th 2025</span>
      </div>

      <h3>Critical Next.js Security Update: CVE-2025-66478 Affects RSC</h3>
      <p>Remote code execution vulnerability in Next.js 15.x and 16.x App Router requires immediate patching. Learn how to secure your applications.</p>
    </div>
  </a>

  <a href="/posts/hands-on/zero-downtime-deployments-with-upsun">
    <div>
      <div>
        <span>Wednesday, December 3rd 2025</span>
      </div>

      <h3>Zero-downtime deployments: now in open beta</h3>
      <p>We've launched zero-downtime deployments in open beta. Deploy your applications without service interruption.</p>
    </div>
  </a>

  <a href="/posts/tutorials/angular-and-upsun">
    <div>
      <div>
        <span>Wednesday, December 3rd 2025</span>
      </div>

      <h3>Building and Deploying Angular Apps on Upsun</h3>
      <p>How to build and deploy an Angular application on Upsun.</p>
    </div>
  </a>

  <a href="/posts/how-tos/planning-your-upsun-migration-the-6-9-week-roadmap">
    <div>
      <div>
        <span>Tuesday, December 2nd 2025</span>
      </div>

      <h3>Planning your Upsun migration: the 6-9 week roadmap</h3>
      <p>Learn why 6-9 weeks is the ideal timeline for Upsun migrations, with expert insights on planning, testing, and avoiding common pitfalls.</p>
    </div>
  </a>

  <a href="/posts/insights/why-setting-your-php-memory-limit-to-60gb-wont-help">
    <div>
      <div>
        <span>Monday, December 1st 2025</span>
      </div>

      <h3>Why setting your PHP memory limit to 60GB won't help</h3>
      <p>When you see a PHP memory limit error, your instinct shouldn't be to just increase the limit. Learn what PHP memory\_limit actually does and why blindly increasing it can hurt your site's uptime.</p>
    </div>
  </a>

  <a href="/posts/hands-on/ai-use-case-generate-load-test-scenarios">
    <div>
      <div>
        <span>Thursday, November 27th 2025</span>
      </div>

      <h3>AI use-case: Generate load test scenarios with MCPs</h3>
      <p>Automate Locust load testing by combining Chrome MCP and Context7 to generate realistic user behavior patterns with Claude Code.</p>
    </div>
  </a>

  <a href="/posts/insights/my-terminal-setup-mac-linux">
    <div>
      <div>
        <span>Wednesday, November 26th 2025</span>
      </div>

      <h3>My terminal setup (Mac & Linux)</h3>
      <p>A no-nonsense guide to transforming your terminal from painful to powerful with GhostTTY, NeoVim, and Claude Code</p>
    </div>
  </a>

  <a href="/posts/how-it-works/when-php-fpm-runs-out-of-workers-a-502-error-field-guide">
    <div>
      <div>
        <span>Monday, November 24th 2025</span>
      </div>

      <h3>When php-fpm runs out of workers: a 502 error field guide</h3>
      <p>Your PHP site keeps throwing 502 errors. Your CDN shows 503s. Learn why PHP-FPM workers get exhausted and how to diagnose and fix the real problems.</p>
    </div>
  </a>

  <a href="/posts/releases/php-85-release">
    <div>
      <div>
        <span>Thursday, November 20th 2025</span>
      </div>

      <h3>PHP 8.5 is here!</h3>
      <p>What if the next PHP revolution made no noise but completely transformed your developer daily life?</p>
    </div>
  </a>

  <a href="/posts/how-it-works/we-switched-from-lvm-to-sparse-files">
    <div>
      <div>
        <span>Friday, November 14th 2025</span>
      </div>

      <h3>We switched from LVM to... sparse files?!</h3>
      <p>How we eliminated 90% of VM evacuation time by replacing LVM with sparse files for temporary storage. A tale of inertia, performance bottlenecks, and surprisingly effective solutions.</p>
    </div>
  </a>

  <a href="/posts/how-tos/creating-custom-reports-using-cli">
    <div>
      <div>
        <span>Wednesday, November 12th 2025</span>
      </div>

      <h3>Creating Custom Reports using the Upsun Cloud CLI</h3>
      <p>Someone recently asked me</p>
    </div>
  </a>

  <a href="/posts/insights/the-mystery-of-the-shrinking-database-dump">
    <div>
      <div>
        <span>Monday, November 10th 2025</span>
      </div>

      <h3>The mystery of the shrinking database dump</h3>
      <p>Your database uses 10GB but dumps to 100MB. Discover why database dumps shrink, how InnoDB fragmentation works, and how to reclaim that missing storage space.</p>
    </div>
  </a>

  <a href="/posts/hands-on/varnish-104-advanced-traffic-filtering-with-classification-headers-on-upsun">
    <div>
      <div>
        <span>Friday, November 7th 2025</span>
      </div>

      <h3>Varnish 104: Advanced Traffic Filtering with Classification Headers on Upsun</h3>
      <p>Learn how to implement advanced security controls in Varnish on Upsun using classification headers to block malicious traffic, restrict geographic access, filter by ASN, and protect sensitive paths with HTTP Basic Auth.</p>
    </div>
  </a>

  <a href="/posts/releases/upsun-php-sdk-announcement">
    <div>
      <div>
        <span>Tuesday, November 4th 2025</span>
      </div>

      <h3>Introducing the Upsun PHP SDK</h3>
      <p>Discover how the Upsun PHP SDK simplifies API access and speeds up integrations, with clear documentation and modern tooling.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/we-made-our-infrastructure-read-only-and-never-looked-back">
    <div>
      <div>
        <span>Monday, November 3rd 2025</span>
      </div>

      <h3>We made our infrastructure read-only and never looked back</h3>
      <p>Learn why read-only infrastructure eliminates entire classes of security attacks, improves reproducibility, and simplifies compliance while enabling predictable deployments.</p>
    </div>
  </a>

  <a href="/posts/hands-on/varnish-103-cache-optimization-with-url-normalization-on-upsun">
    <div>
      <div>
        <span>Friday, October 31st 2025</span>
      </div>

      <h3>Varnish 103: Cache Optimization with URL Normalization on Upsun</h3>
      <p>Learn how to maximize Varnish cache efficiency through URL normalization, query string sorting, and tracking parameter removal to dramatically improve cache hit ratios and reduce backend load.</p>
    </div>
  </a>

  <a href="/posts/hands-on/varnish-102-protecting-your-application-with-rate-limiting-on-upsun">
    <div>
      <div>
        <span>Friday, October 24th 2025</span>
      </div>

      <h3>Varnish 102: Protecting Your Application with Rate Limiting on Upsun</h3>
      <p>Learn how to implement effective rate limiting in Varnish using the vsthrottle VMOD to protect your application from abuse, prevent DDoS attacks, and ensure fair resource allocation.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/event-loop-monitoring-in-nextjs-performance-guide">
    <div>
      <div>
        <span>Friday, October 24th 2025</span>
      </div>

      <h3>Event Loop Monitoring in Next.js: Performance Guide</h3>
      <p>Learn to implement event loop monitoring in Next.js applications to identify blocking operations, optimize performance, and scale confidently with production-ready code.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/autoscaling-deep-dive">
    <div>
      <div>
        <span>Monday, October 20th 2025</span>
      </div>

      <h3>Auto-scaling on Upsun Flex. A deep dive.</h3>
      <p>Learn how Upsun's autoscaling dynamically adjusts application instances based on CPU usage, ensuring performance during traffic spikes while optimizing costs.</p>
    </div>
  </a>

  <a href="/posts/hands-on/varnish-101-protecting-paths-with-http-basic-authentication-on-upsun">
    <div>
      <div>
        <span>Friday, October 17th 2025</span>
      </div>

      <h3>Varnish 101: Protecting Paths with HTTP Basic Authentication on Upsun</h3>
      <p>Learn how to implement HTTP Basic Authentication directly in Varnish VCL on Upsun to protect specific paths like admin areas, staging environments, and work-in-progress content without touching your backend.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/fake-ip-till-you-make-ip">
    <div>
      <div>
        <span>Tuesday, October 14th 2025</span>
      </div>

      <h3>Fake IP till you make IP</h3>
      <p>How Upsun uses virtual IPs and NAT to keep your database connections stable even when containers move between VMs. A look at the networking tricks behind relationship stability.</p>
    </div>
  </a>

  <a href="/posts/how-tos/fastlycdn-pluginapp-activation">
    <div>
      <div>
        <span>Tuesday, October 7th 2025</span>
      </div>

      <h3>Streamline Your CDN Management with Fastly CDN Plugin App \[BETA]</h3>
      <p>Managing Content Delivery Network (CDN) configurations alongside your application deployments can be a complex task, often requiring developers to switch between multiple interfaces and tools. The Fastly CDN plugin app bridges this gap by bringing Fastly CDN management directly into your Upsun console, creating a seamless workflow for developers who want to manage their CDN configurations without leaving their primary development environment.</p>
    </div>
  </a>

  <a href="/posts/tutorials/deploying-open-source-on-upsun">
    <div>
      <div>
        <span>Tuesday, October 7th 2025</span>
      </div>

      <h3>Deploying open-source projects on Upsun: Snipe-IT as an example</h3>
      <p>Learn how to deploy any GitHub-hosted open-source project on Upsun by forking repositories, configuring for deployment, and keeping your fork synchronized with upstream updates.</p>
    </div>
  </a>

  <a href="/posts/insights/build-time-environment-variables-considered-harmful">
    <div>
      <div>
        <span>Monday, October 6th 2025</span>
      </div>

      <h3>Build-time environment variables considered harmful</h3>
      <p>Build-time environment variables break deployment caching, compromise security, and force unnecessary rebuilds. Learn why runtime configuration is the better alternative.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/explore-plan-execute-methodology">
    <div>
      <div>
        <span>Friday, October 3rd 2025</span>
      </div>

      <h3>Mastering the Explore, Plan, Execute methodology for AI-assisted development</h3>
      <p>Learn how to transform AI coding assistants from eager juniors into rockstar developers using proven context strategies, quality assurance, and the three-phase workflow</p>
    </div>
  </a>

  <a href="/posts/tutorials/building-async-processing-pipelines-with-fastapi-and-celery-on-upsun">
    <div>
      <div>
        <span>Friday, October 3rd 2025</span>
      </div>

      <h3>Building async processing pipelines with FastAPI and Celery on Upsun</h3>
      <p>Learn how to build production-ready async processing pipelines using FastAPI and Celery on Upsun. From architecture design to deployment, discover how to handle long-running tasks without blocking your API responses.</p>
    </div>
  </a>

  <a href="/posts/hands-on/building-internal-ai-agents-for-our-teams-on-upsun">
    <div>
      <div>
        <span>Tuesday, September 30th 2025</span>
      </div>

      <h3>Building internal AI agents for our teams on Upsun</h3>
      <p>Learn how to build and deploy production-ready AI agents on Upsun using Google's ADK, ChromaDB vector database, and Retrieval-Augmented Generation (RAG) to create context-aware, domain-specific agents for your team.</p>
    </div>
  </a>

  <a href="/posts/ai/upsun-mcp-announcement">
    <div>
      <div>
        <span>Monday, September 22nd 2025</span>
      </div>

      <h3>Introducing the Upsun MCP server: bring Upsun into your LLMs</h3>
      <p>Manage your Upsun infrastructure directly through AI assistants with our new Model Context Protocol server - now in beta at mcp.upsun.com</p>
    </div>
  </a>

  <a href="/posts/insights/why-you-should-replace-postgresql-with-git-for-your-next-project">
    <div>
      <div>
        <span>Friday, September 19th 2025</span>
      </div>

      <h3>Why you should replace PostgreSQL with Git for your next project</h3>
      <p>Explore how Git's internal architecture makes it a surprisingly capable database alternative. Learn Git's data structures through a practical todo app implementation that might make you reconsider your database choices.</p>
    </div>
  </a>

  <a href="/posts/hands-on/run-tailscale-on-upsun-secure-vpn-connections">
    <div>
      <div>
        <span>Tuesday, September 16th 2025</span>
      </div>

      <h3>Run Tailscale on Upsun: Create secure VPN connections for your applications</h3>
      <p>Learn how to integrate Tailscale VPN with your Upsun applications to create secure, private network connections between your containers and infrastructure.</p>
    </div>
  </a>

  <a href="/posts/how-tos/composer1-rip">
    <div>
      <div>
        <span>Tuesday, September 9th 2025</span>
      </div>

      <h3>Composer 1 is dead – Upgrade to Composer 2 now</h3>
      <p>Composer 1 has reached end of life and is no longer available on Upsun and Platform.sh. Learn why it’s no longer possible to rely on Composer 1, what errors you’ll see, and how to safely upgrade your project to Composer 2.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/cut-aws-bandwidth-costs-95-with-dm-cache">
    <div>
      <div>
        <span>Tuesday, September 9th 2025</span>
      </div>

      <h3>How we cut AWS bandwidth costs 95% with dm-cache: fast local SSD caching for network storage</h3>
      <p>Learn how Upsun solved costly inter-AZ bandwidth billing by implementing dm-cache with local SSDs, achieving 95% read traffic reduction and 30x performance improvement.</p>
    </div>
  </a>

  <a href="/posts/hands-on/store-embeddings-in-chroma-with-persistent-storage-nodejs-and-python-examples">
    <div>
      <div>
        <span>Wednesday, September 3rd 2025</span>
      </div>

      <h3>Store embeddings in chroma with persistent storage (nodejs and python examples)</h3>
      <p>Learn how to implement Chroma with persistent storage on Upsun using both Node.js and Python, including document ingestion and embedding storage.</p>
    </div>
  </a>

  <a href="/posts/hands-on/fastly-maintenance">
    <div>
      <div>
        <span>Monday, August 25th 2025</span>
      </div>

      <h3>How to enable custom maintenance page in Fastly</h3>
      <p>Configure GitLab CI/CD to deploy to Upsun from private air-gapped GitLab instances using push-based workflows and API automation.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/how-do-we-do-incremental-but-really-full-backups-on-top-of-ceph">
    <div>
      <div>
        <span>Monday, August 25th 2025</span>
      </div>

      <h3>High-performance backups: How Ceph snapshots enable incremental full backups</h3>
      <p>Learn how Upsun leverages Ceph's RBD export-diff feature to implement high-performance incremental backups that maintain full restore capabilities for large-scale container storage.</p>
    </div>
  </a>

  <a href="/posts/hands-on/connect-multiple-projects-applications-or-services-together">
    <div>
      <div>
        <span>Friday, August 15th 2025</span>
      </div>

      <h3>Connect multiple projects applications or services together</h3>
      <p>Learn how to use Chisel to securely connect applications and services across different Upsun projects, with a practical MariaDB replication example.</p>
    </div>
  </a>

  <a href="/posts/insights/why-your-readme-matters-more-than-ai-configuration-files">
    <div>
      <div>
        <span>Tuesday, August 12th 2025</span>
      </div>

      <h3>AGENTS.md: Why your README matters more than AI configuration files</h3>
      <p>AGENTS.md promises to standardize AI coding assistant configuration, but the real solution is writing better READMEs that serve both humans and AI agents</p>
    </div>
  </a>

  <a href="/posts/insights/why-python-developers-should-switch-to-uv">
    <div>
      <div>
        <span>Thursday, August 7th 2025</span>
      </div>

      <h3>Why Python developers should switch to uv</h3>
      <p>Learn how uv, the revolutionary Python package manager, delivers 100x faster installations and streamlines project management with automatic virtual environments and dependency tracking.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/how-upsun-built-stateless-mesh-networking-for-high-density-containers">
    <div>
      <div>
        <span>Wednesday, August 6th 2025</span>
      </div>

      <h3>How Upsun built stateless mesh networking for high-density containers</h3>
      <p>Discover how Upsun's innovative stateless mesh networking architecture handles thousands of containers without databases or bottlenecks.</p>
    </div>
  </a>

  <a href="/posts/unknown/platformsh-un-global-compact-sdgs-2025">
    <div>
      <div>
        <span>Wednesday, July 30th 2025</span>
      </div>

      <h3>Platform.sh reaffirms commitment to the UN Global Compact and the SDGs</h3>
      <p>We’re pleased to confirm that Platform.</p>
    </div>
  </a>

  <a href="/posts/hands-on/gitlab-push-solution">
    <div>
      <div>
        <span>Monday, July 21st 2025</span>
      </div>

      <h3>Synchronize your air-gapped GitLab with Upsun</h3>
      <p>Configure GitLab CI/CD to deploy to Upsun from private air-gapped GitLab instances using push-based workflows and API automation</p>
    </div>
  </a>

  <a href="/posts/unknown/new-improvement-global-settings-in-console">
    <div>
      <div>
        <span>Wednesday, July 9th 2025</span>
      </div>

      <h3>New improvement: global settings in console</h3>
      <p>Discover the new global settings page in the Console. Easily configure project and environment settings in one location for a smoother experience.</p>
    </div>
  </a>

  <a href="/posts/use-cases/n8n-saved-my-life">
    <div>
      <div>
        <span>Thursday, July 3rd 2025</span>
      </div>

      <h3>How n8n saved our Advocacy impact on Social Media!</h3>
      <p>Learn how n8n workflows improve internal communication and amplify our Advocacy social media impact.</p>
    </div>
  </a>

  <a href="/posts/insights/why-configuration-as-code-beats-click-and-deploy">
    <div>
      <div>
        <span>Thursday, June 12th 2025</span>
      </div>

      <h3>Git-Driven Infrastructure: Why Configuration as Code Beats Click-and-Deploy</h3>
      <p>Discover why YAML-driven infrastructure outperforms point-and-click deployment for scalable, maintainable applications. Learn best practices for configuration as code.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/mcp-interaction-types-article">
    <div>
      <div>
        <span>Saturday, June 7th 2025</span>
      </div>

      <h3>Beyond Tool Calling: Understanding MCP's Three Core Interaction Types</h3>
      <p>Discover how prompts, resources, and tools work together in the Model Context Protocol to create richer AI application experiences beyond simple tool calling.</p>
    </div>
  </a>

  <a href="/posts/hands-on/deploy-mcp-servers-on-upsun">
    <div>
      <div>
        <span>Thursday, June 5th 2025</span>
      </div>

      <h3>Build and deploy AI-Native Applications with MCP Servers on Upsun</h3>
      <p>Learn how Model Context Protocol servers work with different transports and deploy them to Upsun for scalable AI-powered applications</p>
    </div>
  </a>

  <a href="/posts/releases/redis-release">
    <div>
      <div>
        <span>Wednesday, June 4th 2025</span>
      </div>

      <h3>Redis 8.0 is here</h3>
      <p>We are excited to announce that **Redis 8.0** is now available for all customers.</p>
    </div>
  </a>

  <a href="/posts/how-tos/handling-well-known-directory">
    <div>
      <div>
        <span>Monday, May 26th 2025</span>
      </div>

      <h3>How to manage the `.well-known` directory on Upsun and Platform.sh</h3>
      <p>If you have ever tried to enable</p>
    </div>
  </a>

  <a href="/posts/hands-on/nocode-n8n">
    <div>
      <div>
        <span>Wednesday, May 14th 2025</span>
      </div>

      <h3>NoCode with Upsun: Supercharge Your Automation with Zero Code</h3>
      <p>Learn how to leverage Upsun to deploy powerful NoCode tools like n8n for workflow automation. Fast setup, secure hosting, and real-world use cases — all without writing code.</p>
    </div>
  </a>

  <a href="/posts/insights/advanced-prompting-techniques-for-coding">
    <div>
      <div>
        <span>Thursday, May 8th 2025</span>
      </div>

      <h3>Advanced prompting techniques for complex coding tasks</h3>
      <p>This articles will give you an overview of prompting strategies that help coding assistants reason through difficult problems and produce higher-quality solutions.</p>
    </div>
  </a>

  <a href="/posts/releases/file_size_limit">
    <div>
      <div>
        <span>Wednesday, May 7th 2025</span>
      </div>

      <h3>New file size limits explained</h3>
      <p>To ensure the optimal performance, stability, and reliability of our Git infrastructure, we are introducing a limit on the size of individual files that can be pushed to your project repositories.</p>
    </div>
  </a>

  <a href="/posts/releases/vscode-extension">
    <div>
      <div>
        <span>Tuesday, May 6th 2025</span>
      </div>

      <h3>Supercharge your workflow with the Upsun VSCode Extension</h3>
      <p>If you're working on Upsun projects with VSCode, the **Upsun VSCode extension** is an essential tool to enhance your development experience. Learn more...</p>
    </div>
  </a>

  <a href="/posts/how-tos/validate-yaml-config">
    <div>
      <div>
        <span>Tuesday, May 6th 2025</span>
      </div>

      <h3>Making .upsun/config.yaml easier to edit with IDE autocomplete and validation</h3>
      <p>Boost your productivity and eliminate configuration errors with real-time autocompletion and validation for your .upsun/config.yaml — discover how to enhance your IDE experience in just a few simple steps!</p>
    </div>
  </a>

  <a href="/posts/hands-on/pytorch-running-on-upsun">
    <div>
      <div>
        <span>Thursday, May 1st 2025</span>
      </div>

      <h3>How to run PyTorch in an Upsun application?</h3>
      <p>Learn how to deploy a sentiment analysis application powered by PyTorch and FastAPI on the Upsun cloud platform</p>
    </div>
  </a>

  <a href="/posts/how-tos/context7-mcp">
    <div>
      <div>
        <span>Thursday, May 1st 2025</span>
      </div>

      <h3>Upsun documentation is now available via the Context7 MCP</h3>
      <p>Access Upsun documentation directly from your AI workflows using Context7's Model Context Protocol integration</p>
    </div>
  </a>

  <a href="/posts/hands-on/postgres-mcp-on-upsun">
    <div>
      <div>
        <span>Wednesday, April 30th 2025</span>
      </div>

      <h3>Using PostgreSQL MCP with Upsun Remote Database</h3>
      <p>Learn how to set up an MCP server to connect your Upsun PostgreSQL database to language models like Claude or IDE like VSCode GitHub Copilot and Cursor, enabling natural language data queries without writing SQL.</p>
    </div>
  </a>

  <a href="/posts/hands-on/route-ids-env">
    <div>
      <div>
        <span>Monday, April 28th 2025</span>
      </div>

      <h3>How to automatically inject multi-app endpoints as environment variables</h3>
      <p>Learn how to use Upsun route identifiers and the PLATFORM\_ROUTES variable to easily get and use the hostnames of dynamically deployed applications in your project.</p>
    </div>
  </a>

  <a href="/posts/tutorials/oauth-nextjs-laravel">
    <div>
      <div>
        <span>Monday, April 28th 2025</span>
      </div>

      <h3>OAuth authentication between Next.js and Laravel Passport</h3>
      <p>Learn how to implement secure OAuth authentication between a Next.js frontend and Laravel backend using Passport with the Authorization Code Flow and PKCE.</p>
    </div>
  </a>

  <a href="/posts/tutorials/deploying-clamav-service">
    <div>
      <div>
        <span>Thursday, April 24th 2025</span>
      </div>

      <h3>Deploy ClamAV on Upsun, on service mode.</h3>
      <p>Learn how to deploy ClamAV service on Upsun. This tutorial covers ClamAV integration on service scan mode.</p>
    </div>
  </a>

  <a href="/posts/releases/valkey-release">
    <div>
      <div>
        <span>Wednesday, April 16th 2025</span>
      </div>

      <h3>Valkey is now available</h3>
      <p>We're excited to announce the availability of [Valkey](https://valkey.io/), a high-performance, open-source key/value database, now offered as a managed service on Upsun. Valkey serves as a drop-in alternative to Redis, particularly relevant following recent licensing changes to the Redis project.</p>
    </div>
  </a>

  <a href="/posts/hands-on/install-gh-asset-on-upsun">
    <div>
      <div>
        <span>Thursday, April 10th 2025</span>
      </div>

      <h3>Up(sun) and ready with GitHub release assets installation</h3>
      <p>Discover how to install any GitHub release asset you want in your Upsun project.</p>
    </div>
  </a>

  <a href="/posts/unknown/nextjs-cve-2025-2997">
    <div>
      <div>
        <span>Tuesday, March 25th 2025</span>
      </div>

      <h3>Next.js Security Vulnerability (CVE-2025-29927): What Upsun Users Need to Know</h3>
      <p>A comprehensive guide to understanding and addressing the recent Next.js security vulnerability CVE-2025-29927 for applications deployed on Upsun.</p>
    </div>
  </a>

  <a href="/posts/tutorials/sfcon2024-decouple-frontend">
    <div>
      <div>
        <span>Monday, March 24th 2025</span>
      </div>

      <h3>Decouple your Symfony frontend using Next.js</h3>
      <p>How to decouple your frontend from your backend, using a Symfony project as backend and adding a Next.js application for frontend.</p>
    </div>
  </a>

  <a href="/posts/tutorials/deploying-with-lisp">
    <div>
      <div>
        <span>Monday, March 17th 2025</span>
      </div>

      <h3>Up(sun) and running with Lisp</h3>
      <p>Lisp support was discontinued in March 2025. If you really want to power a Lisp project, feel free to reach out on the [Upsun Community Forum](https://community.upsun.com/).</p>
    </div>
  </a>

  <a href="/posts/tutorials/deploying-twill-on-upsun">
    <div>
      <div>
        <span>Wednesday, March 12th 2025</span>
      </div>

      <h3>Up(sun) and Running with Twill</h3>
      <p>This guide provides instructions for deploying and working with [Twill](https://twillcms.com/), an "open-source</p>
    </div>
  </a>

  <a href="/posts/releases/elixir-118-release-available">
    <div>
      <div>
        <span>Wednesday, February 26th 2025</span>
      </div>

      <h3>Apologies to the Elixir community: 1.18 release now available</h3>
      <p>Elixir 1.18 is now available on Upsun and Platform.sh with type checking, LSP improvements, and built-in JSON support.</p>
    </div>
  </a>

  <a href="/posts/tutorials/deploying-clamav-onetime">
    <div>
      <div>
        <span>Friday, February 14th 2025</span>
      </div>

      <h3>Deploy ClamAV on Upsun, on one-time scan</h3>
      <p>Learn how to deploy ClamAV service on Upsun. This tutorial covers ClamAV integration on one-time scan mode.</p>
    </div>
  </a>

  <a href="/posts/releases/llms-introduction">
    <div>
      <div>
        <span>Friday, February 14th 2025</span>
      </div>

      <h3>Upsun and Platform.sh Docs are now llms.txt compatible!</h3>
      <p>We’re thrilled to announce that both [Upsun Documentation](https://docs.upsun.com) and [Platform.sh Documentation](https://docs.platform.sh) are now fully compatible with [llms.txt proposed standard](https://llmstxt.org/)!</p>
    </div>
  </a>

  <a href="/posts/how-tos/install-pandoc-on-upsun">
    <div>
      <div>
        <span>Wednesday, February 12th 2025</span>
      </div>

      <h3>Up(sun) and ready with Pandoc</h3>
      <p>With the recent growth in enthusiasm for AI assistants, you may be looking for how these assistants can provide technical information about your product.</p>
    </div>
  </a>

  <a href="/posts/unknown/magento-performance-optimization">
    <div>
      <div>
        <span>Tuesday, February 4th 2025</span>
      </div>

      <h3>Magento performance optimization–Actionable tips and strategies</h3>
      <p>Is your ecommerce store traffic resulting in enough conversions.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/debian-repo-s3">
    <div>
      <div>
        <span>Wednesday, January 29th 2025</span>
      </div>

      <h3>How we host a Debian repository on AWS S3</h3>
      <p>Pretty cool fact about our internal Debian repositories: they’re hosted entirely on AWS S3. Why is that cool? For 2</p>
    </div>
  </a>

  <a href="/posts/tutorials/upsun-and-running-forem">
    <div>
      <div>
        <span>Friday, January 24th 2025</span>
      </div>

      <h3>Up(sun) and Running with Forem</h3>
      <p>This guide provides instructions for deploying and working with [Forem](https://www.forem.com/), an "open-source</p>
    </div>
  </a>

  <a href="/posts/tutorials/drupal-and-upsun">
    <div>
      <div>
        <span>Thursday, January 16th 2025</span>
      </div>

      <h3>Drupal and Upsun</h3>
      <p>[Drupal CMS](https://www.drupal.org/project/cms), born of [DrupalCon 2024 initiative](https://www.drupal.org/about/in-the-news/blog/drupal-cms-groundbreaking-new-version-of-drupal-detailed-at-drupalcon-singapore-2024) "Starshot", has been [released today](https://www.drupal.org/blog/drupal-cms-1-0).</p>
    </div>
  </a>

  <a href="/posts/hands-on/deploying-chainlit-with-rag">
    <div>
      <div>
        <span>Tuesday, January 14th 2025</span>
      </div>

      <h3>Experiment with Chainlit AI interface with RAG on Upsun</h3>
      <p>Learn to deploy production-ready RAG applications with Chainlit and Python on Upsun. Tutorial covers OpenAI Assistants integration, llama\_index implementation, and secure authentication.</p>
    </div>
  </a>

  <a href="/posts/how-tos/no-downtime-postgres-updates">
    <div>
      <div>
        <span>Thursday, January 9th 2025</span>
      </div>

      <h3>How to update your PostgreSQL database without downtime</h3>
      <p>On paper, releasing a new version of your application that requires upgrading the schema of the database is straightforward. But, changes of code and schema can not be updated in an atomic way, you only need to take care that old code is not performing a query against new schema, and reciprocally.</p>
    </div>
  </a>

  <a href="/posts/discussions/triage-bot">
    <div>
      <div>
        <span>Wednesday, December 18th 2024</span>
      </div>

      <h3>How did we migrate issues from GitLab to Linear?</h3>
      <p>We migrated our issues from GitLab to Linear due to GitLab's limited issue-tracking features. To handle thousands of issues and tight timelines, we developed a migration tool using GitLab Triage Bot and Linear's GraphQL API. The tool mapped issue states, assignees, labels, and comments, and transformed GitLab epics into Linear issues with sub-issues. It was successful overall and enabled team-by-team migration for flexibility. Now, [we’re open-sourcing the migrator](https://github.com/upsun/gitlab-triage-linear-migrator) to help others facing similar challenges.</p>
    </div>
  </a>

  <a href="/posts/discussions/go-124">
    <div>
      <div>
        <span>Sunday, December 15th 2024</span>
      </div>

      <h3>Golang 1.24 is looking seriously awesome</h3>
      <p>The Golang team just released the [first release candidate of Golang 1.24](https://tip.golang.org/doc/go1.24). At Upsun, we use Golang extensively for everything in our hot path, especially for the routing of HTTP requests throughout our infrastructure. Here is what we are looking forward to the most.</p>
    </div>
  </a>

  <a href="/posts/discussions/cve-2024-45337">
    <div>
      <div>
        <span>Friday, December 13th 2024</span>
      </div>

      <h3>CVE-2024-45337</h3>
      <p>This article was originally published on the [Platform.sh blog](https://platform.sh/blog/uncovered-and-patched-golang-vunerability/).</p>
    </div>
  </a>

  <a href="/posts/unknown/uncovered-and-patched-golang-vunerability">
    <div>
      <div>
        <span>Friday, December 13th 2024</span>
      </div>

      <h3>Security vulnerability uncovered and patched in the golang.org/x/crypto /ssh package</h3>
      <p>Misimplementation of PublicKeyCallback leads to authorization bypass in Go's x/crypto/sshPlatform.</p>
    </div>
  </a>

  <a href="/posts/releases/php-84-release">
    <div>
      <div>
        <span>Tuesday, November 26th 2024</span>
      </div>

      <h3>PHP 8.4 is here!</h3>
      <p>PHP 8.4 was [officially released](https://www.php.net/archive/2024.php#2024-11-21-4) on November 21st, and with it comes a number of improvements and new features that you can - as of today - begin working with on your Upsun and Platform.sh projects.</p>
    </div>
  </a>

  <a href="/posts/tutorials/laravel-rest-api-on-upsun">
    <div>
      <div>
        <span>Friday, November 15th 2024</span>
      </div>

      <h3>Creating and deploying a Laravel REST API on Upsun in 10 minutes</h3>
      <p>Follow this comprehensive guide to build and deploy a modern Laravel REST API on Upsun's cloud platform. We'll walk through setting up your local development environment, creating API endpoints, and deploying to production with a custom domain. This tutorial is perfect for developers looking to quickly ship production-ready Laravel applications without dealing with complex infrastructure management.</p>
    </div>
  </a>

  <a href="/posts/how-tos/blackfire-google-alert-markers-interfaces">
    <div>
      <div>
        <span>Tuesday, November 5th 2024</span>
      </div>

      <h3>Import multiple RSS Feeds on your Blackfire timeline + extra interfaces</h3>
      <p>We saw in the [previous episode](/posts/how-tos/blackfire-google-alert-markers) how to automatically add context on your Blackfire timeline from an RSS Feed (Google Alert),</p>
    </div>
  </a>

  <a href="/posts/unknown/human-impact-of-adopting-platformsh">
    <div>
      <div>
        <span>Tuesday, October 29th 2024</span>
      </div>

      <h3>A tale of people: the human impact of adopting Platform.sh</h3>
      <p>I have a complicated relationship with people.</p>
    </div>
  </a>

  <a href="/posts/how-tos/schedule-resource-availability">
    <div>
      <div>
        <span>Thursday, October 24th 2024</span>
      </div>

      <h3>Scheduling resources</h3>
      <p>As Upsun does purely usage-driven billing,</p>
    </div>
  </a>

  <a href="/posts/releases/continuous-profiling-comparisons">
    <div>
      <div>
        <span>Wednesday, October 23rd 2024</span>
      </div>

      <h3>Continuous profiling comparisons</h3>
      <p>Upsun’s new continuous profiling comparisons feature provides deeper insights into application performance, enabling you to easily contrast performance metrics over time or between code versions.</p>
    </div>
  </a>

  <a href="/posts/tutorials/rails8-upsun-tutorial">
    <div>
      <div>
        <span>Wednesday, October 23rd 2024</span>
      </div>

      <h3>Deploy your first Rails 8 application on Upsun</h3>
      <p>Learn how to build and deploy a modern Rails 8 blog application on Upsun's cloud platform. This hands-on tutorial walks you through local development setup, creating a feature-rich blog application, and deploying it to production with proper monitoring and scaling. Discover why Platform-as-a-Service remains relevant even with Rails 8's new deployment features, and learn best practices for cloud deployment. Perfect for developers wanting to quickly ship production-ready Rails applications without managing complex infrastructure.</p>
    </div>
  </a>

  <a href="/posts/how-tos/configuring-an-autoscaler">
    <div>
      <div>
        <span>Saturday, October 19th 2024</span>
      </div>

      <h3>Adding an autoscaler to Upsun projects</h3>
      <p>In this post we will describe a small configuration that will</p>
    </div>
  </a>

  <a href="/posts/how-tos/blackfire-google-alert-markers">
    <div>
      <div>
        <span>Monday, October 7th 2024</span>
      </div>

      <h3>Add context on your Blackfire timeline from a Google Alerts RSS Feed</h3>
      <p>Observing your application is essential to be able to find what needs (and what does not need) to be optimized.</p>
    </div>
  </a>

  <a href="/posts/releases/context-driven-navigation">
    <div>
      <div>
        <span>Thursday, October 3rd 2024</span>
      </div>

      <h3>Context driven navigation</h3>
      <p>You may have noticed some changes to navigation and user settings on your Platform.sh dashboard.</p>
    </div>
  </a>

  <a href="/posts/discussions/understanding-cors">
    <div>
      <div>
        <span>Monday, September 30th 2024</span>
      </div>

      <h3>Understanding Cross-Origin Resource Sharing (CORS)</h3>
      <p>Learn about Cross-Origin Resource Sharing (CORS), a crucial web security mechanism. Understand its importance, key concepts, and implementation in Symfony, Next.js, and Laravel. Includes practical examples and tips for testing with curl and Postman, plus Platform.sh configuration guidance.</p>
    </div>
  </a>

  <a href="/posts/unknown/evolve-partner-summit-awards">
    <div>
      <div>
        <span>Monday, September 23rd 2024</span>
      </div>

      <h3>It's almost time…Platform.sh’s Evolve Partner Summit Awards</h3>
      <p>We’d love for you to join us in Paris to celebrate the incredible work you’ve done.</p>
    </div>
  </a>

  <a href="/posts/how-tos/automate-with-gatling-1">
    <div>
      <div>
        <span>Friday, September 20th 2024</span>
      </div>

      <h3>How to automate load tests with Gatling</h3>
      <p>When I was on your side of the keyboard, developing cool and funny applications (more or less :D), load tests were (most of the time) executed a few days before going live.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/using-the-upsun-api">
    <div>
      <div>
        <span>Thursday, September 19th 2024</span>
      </div>

      <h3>Using the Upsun API</h3>
      <p>> Anything you can do, API can do better!</p>
    </div>
  </a>

  <a href="/posts/discussions/preview-environments-a-developers-secret-weapon">
    <div>
      <div>
        <span>Thursday, September 19th 2024</span>
      </div>

      <h3>Preview Environments</h3>
      <p>Discover how preview environments transform software deployment, reducing stress and improving code quality. Learn about the six essential components for implementing preview environments, including Git, infrastructure as code, and automated DNS management. Find out why preview environments are crucial for catching bugs, testing performance, and enhancing collaboration between technical and non-technical team members. Explore how Upsun's platform leverages preview environments to streamline the development process and deliver higher-quality software products.</p>
    </div>
  </a>

  <a href="/posts/releases/introducing-dev-center">
    <div>
      <div>
        <span>Wednesday, September 18th 2024</span>
      </div>

      <h3>Introducing the Upsun Developer Center</h3>
      <p>This month our Developer Relations and Advocacy teams are excited to share with you our latest resource: the Upsun Developer Center.</p>
    </div>
  </a>

  <a href="/posts/tutorials/how-to-host-multiple-applications">
    <div>
      <div>
        <span>Friday, August 16th 2024</span>
      </div>

      <h3>How to host a multiple-application project on Platform.sh</h3>
      <p>Learn how to host and configure multiple-application projects on Platform.sh with this step-by-step guide.</p>
    </div>
  </a>

  <a href="/posts/hands-on/harnessing-power-embeddings">
    <div>
      <div>
        <span>Monday, May 20th 2024</span>
      </div>

      <h3>Harnessing the power of Embeddings: a real-world example of a watch recommendation app using a vector database.</h3>
      <p>Learn how to build a real-world watch recommendation application using embeddings and a vector database. This tutorial covers using Postgres with pgvector, Laravel, React, OpenAI, and Groq, deployed on Upsun.</p>
    </div>
  </a>

  <a href="/posts/use-cases/wordpress-performance-optimization-with-blackfire">
    <div>
      <div>
        <span>Tuesday, April 16th 2024</span>
      </div>

      <h3>Meeting Jonny Harris: WordPress performance optimization with Blackfire</h3>
      <p>Jonny Harris is a WordPress core contributor and committer based in the UK and a member of the WordPress Performance</p>
    </div>
  </a>

  <a href="/posts/hands-on/guide-to-limit-deployments-to-platformsh-only-with-tags-part-three">
    <div>
      <div>
        <span>Friday, April 12th 2024</span>
      </div>

      <h3>Limit deployments to Platform.sh only with tags: part three</h3>
      <p>In parts [one](/posts/hands-on/guide-to-limit-deployments-to-platformsh-only-with-tags-part-one) and</p>
    </div>
  </a>

  <a href="/posts/unknown/drupal-camp-florida-2024">
    <div>
      <div>
        <span>Monday, March 25th 2024</span>
      </div>

      <h3>DrupalCamp Florida 2024: sharing takeaways from the experts</h3>
      <p>I had the pleasure of returning to DrupalCamp FL (DCFL) again this year and even now in its sixteenth year, DCFL 2024 was as lively and energetic as ever.</p>
    </div>
  </a>

  <a href="/posts/hands-on/guide-to-limit-deployments-to-platformsh-only-with-tags-part-one">
    <div>
      <div>
        <span>Thursday, March 14th 2024</span>
      </div>

      <h3>Limit deployments to Platform.sh only with tags: part one</h3>
      <p>Throughout the years, many users have asked us if it’s possible to only deploy to Platform.sh when a tag is pushed using</p>
    </div>
  </a>

  <a href="/posts/hands-on/guide-to-limit-deployments-to-platformsh-only-with-tags-part-two">
    <div>
      <div>
        <span>Thursday, March 14th 2024</span>
      </div>

      <h3>Limit deployments to Platform.sh only when Git tagged: part two</h3>
      <p>In [part one of this series](https://platform.sh/blog/guide-to-limit-deployments-to-platformsh-only-with-tags-part-one/),</p>
    </div>
  </a>

  <a href="/posts/tutorials/deploying-remixjs-app-on-upsun">
    <div>
      <div>
        <span>Friday, March 1st 2024</span>
      </div>

      <h3>Deploying a Remix JS app on Upsun in 5 minutes</h3>
      <p>Learn how to deploy a Remix JS application on Upsun in just 5 minutes. This tutorial covers creating a project, setting up the Node.js server, and deploying your app.</p>
    </div>
  </a>

  <a href="/posts/tutorials/deploying-laravel-with-horizon-on-upsun">
    <div>
      <div>
        <span>Wednesday, February 28th 2024</span>
      </div>

      <h3>Deploying Laravel with Horizon on Upsun</h3>
      <p>Learn how to deploy a Laravel application with Redis queues and Horizon on Upsun, including PostgreSQL database setup, environment configuration, and domain management.</p>
    </div>
  </a>

  <a href="/posts/unknown/whats-the-deal-with-eu-headquartered-iaas-providers">
    <div>
      <div>
        <span>Monday, November 13th 2023</span>
      </div>

      <h3>International data protection with EU-entities of US-headquartered IaaS providers</h3>
      <p>Learn why we use EU-headquartered IaaS providers for maximum data protection and the additional measures we have in place with our providers for GDPR.</p>
    </div>
  </a>

  <a href="/posts/unknown/building-a-trust-centric-culture-for-success">
    <div>
      <div>
        <span>Wednesday, November 8th 2023</span>
      </div>

      <h3>Building a trust-centric culture for success</h3>
      <p>Trust is more than compliance. It drives employee and customer retention, positive word of mouth, and builds your brand reputation. Find out how to build it.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/how-platformsh-stays-ahead-of-emerging-cybersecurity-threats">
    <div>
      <div>
        <span>Friday, October 13th 2023</span>
      </div>

      <h3>Semper vigilans: how Platform.sh stays ahead of emerging cybersecurity threats (so you don’t have to)</h3>
      <p>Always vigilant is more than a motto. Find out how the Platform.sh Security team monitors vulnerabilities 24x7 to protect customers from cybersecurity threats.</p>
    </div>
  </a>

  <a href="/posts/releases/bun-support-is-here">
    <div>
      <div>
        <span>Friday, September 8th 2023</span>
      </div>

      <h3>It's out of the Oven: Bun 1.0 support on Platform.sh</h3>
      <p>Bun 1.0 support is now available on Platform.sh. Discover our comparison results against Yarn and how to test Bun 1.0 out for yourself in this article.</p>
    </div>
  </a>

  <a href="/posts/how-tos/help-reduce-resource-consumption-put-your-preview-environments-on-pause">
    <div>
      <div>
        <span>Friday, August 18th 2023</span>
      </div>

      <h3>Help reduce resource consumption: Put your preview environments on pause</h3>
      <p>You can now manually pause your idle preview environments or have them automatically paused after 14 days of being idle to minimize your resource usage.</p>
    </div>
  </a>

  <a href="/posts/unknown/an-update-to-our-events-privacy-policy">
    <div>
      <div>
        <span>Wednesday, May 31st 2023</span>
      </div>

      <h3>An update to our events privacy policy</h3>
      <p>To ensure the best experience at Platform.sh conferences and events, we've updated our privacy policy detailing how we'll use and care for your personal data.</p>
    </div>
  </a>

  <a href="/posts/unknown/greater-organization-insights-through-weekly-activity-reports-emails">
    <div>
      <div>
        <span>Monday, April 10th 2023</span>
      </div>

      <h3>Greater organization insights through weekly activity reports emails</h3>
      <p>For our Elite/Enterprise customers, we now will be sending weekly activity reports to provide visibility on the key stats and metrics on all projects.</p>
    </div>
  </a>

  <a href="/posts/unknown/infrastructure-metrics-expanded-to-longer-time-frames">
    <div>
      <div>
        <span>Wednesday, February 1st 2023</span>
      </div>

      <h3>Infrastructure Monitoring Metrics with Longer Time Frames</h3>
      <p>Unlock valuable insights with longer time frames in infrastructure metrics on Platform.sh. Make informed decisions for better capacity planning.</p>
    </div>
  </a>

  <a href="/posts/unknown/its-time-for-version--all-new-upgrades-for-our-api-server">
    <div>
      <div>
        <span>Thursday, January 26th 2023</span>
      </div>

      <h3>Introducing version 19: New upgrades for our API server</h3>
      <p>Unlock the power of Version 19 upgrades, boosting API server performance. Upgrade with Platform.sh for a seamless experience and enhanced capabilities.</p>
    </div>
  </a>

  <a href="/posts/releases/platformsh-is-always-one-step-ahead-announcing-postgresql--python--and-ruby--for-our-users">
    <div>
      <div>
        <span>Monday, January 16th 2023</span>
      </div>

      <h3>Platform.sh is always one step ahead: Announcing PostgreSQL 15, Python 3.11, and Ruby 3.2 for our users</h3>
      <p>Explore the new features and performance improvements in Python 3.11, PostgreSQL 15, and Ruby 3.2. Stay up-to-date with the latest programming languages.</p>
    </div>
  </a>

  <a href="/posts/hands-on/powerup-your-local-development-with-ddev">
    <div>
      <div>
        <span>Thursday, January 5th 2023</span>
      </div>

      <h3>Power-up Your Local Development with DDEV</h3>
      <p>Get the best local development experience with the DDEV-Platform.sh add-on. Follow our guide, share your feedback, and optimize your workflow</p>
    </div>
  </a>

  <a href="/posts/unknown/introducing-our-new-api-and-metrics-servers-upgrades">
    <div>
      <div>
        <span>Thursday, December 15th 2022</span>
      </div>

      <h3>Introducing our new API and Metrics servers upgrades</h3>
      <p>Updates: Jenkins 'H' pattern for cron jobs, result filters for activity scripts, cancellable build and source operations, and the clear build cache activity.</p>
    </div>
  </a>

  <a href="/posts/unknown/dont-be-held-to-ransom-security-awareness-with-platformsh">
    <div>
      <div>
        <span>Friday, December 2nd 2022</span>
      </div>

      <h3>Don’t be held to ransom: Security awareness with Platform.sh</h3>
      <p>Learn how to safeguard your organization against ransomware attacks. Explore security measures and proactive steps to protect your company's data.</p>
    </div>
  </a>

  <a href="/posts/unknown/are-your-websites-ready-to-handle-traffic-peaks-this-holiday-season">
    <div>
      <div>
        <span>Monday, November 28th 2022</span>
      </div>

      <h3>Are your websites ready to handle traffic peaks this holiday season?</h3>
      <p>Discover how to optimize your website for increased holiday traffic. Learn best practices for performance and customer experience during the busy sales season.</p>
    </div>
  </a>

  <a href="/posts/unknown/the-platformsh-cli-is-ready-to-golang">
    <div>
      <div>
        <span>Thursday, November 17th 2022</span>
      </div>

      <h3>The Platform.sh CLI is ready to Go(lang)</h3>
      <p>New Universal Platform.sh CLI, designed to help developers manage projects efficiently, supporting multiple languages and eliminating PHP dependency.</p>
    </div>
  </a>

  <a href="/posts/releases/introducing-a-more-complete-logs-forwarding-experience">
    <div>
      <div>
        <span>Friday, November 4th 2022</span>
      </div>

      <h3>Introducing a more complete logs forwarding experience</h3>
      <p>Streamline monitoring with centralized log forwarding. Platform.sh now supports log forwarding to Sumologic, New Relic Logs, Splunk, and more. Discover how!</p>
    </div>
  </a>

  <a href="/posts/unknown/platformsh-partners-with-mongodb-to-help-customers-build-modern-applications-faster">
    <div>
      <div>
        <span>Thursday, October 6th 2022</span>
      </div>

      <h3>Platform.sh partners with MongoDB to help customers build modern applications faster</h3>
      <p>Announcing MongoDB 5.0 for Enterprise and Elite customers. Enjoy improved security, support, and features. Upgrade now for seamless MongoDB integration.</p>
    </div>
  </a>

  <a href="/posts/unknown/mohammed-ajmal-siddiqui">
    <div>
      <div>
        <span>Friday, September 16th 2022</span>
      </div>

      <h3>Platform.sh | Journeys Mohammed Ajmal Siddiqui</h3>
      <p>Follow Ajmal's journey from India to Paris as he navigates programming, internships, and lockdowns. Join Platform.sh's success story today!</p>
    </div>
  </a>

  <a href="/posts/unknown/weve-made-changes-to-our-dpa-to-clarify-platformsh-role-under-the-gdpr">
    <div>
      <div>
        <span>Thursday, September 1st 2022</span>
      </div>

      <h3>We’ve made changes to our DPA to clarify Platform.sh role under the GDPR</h3>
      <p>Discover how Platform.sh complies with GDPR, acting as both a data controller and data processor under the European Union's General Data Protection Regulation.</p>
    </div>
  </a>

  <a href="/posts/unknown/were-updating-our-privacy-policy-to-include-event-accommodations">
    <div>
      <div>
        <span>Friday, August 19th 2022</span>
      </div>

      <h3>We’re updating our privacy policy to include event accommodations</h3>
      <p>Learn about our privacy policy update regarding dietary restrictions and disability accommodations at Platform.sh events.</p>
    </div>
  </a>

  <a href="/posts/unknown/pandemic-caused-spike-in-cybercrime">
    <div>
      <div>
        <span>Thursday, May 26th 2022</span>
      </div>

      <h3>The pandemic has indeed caused a massive spike in cybercrime</h3>
      <p>Insights from Joey Stanford, VP of Privacy & Security at Platform.sh, on cybersecurity trends, challenges, and the future of security for modern businesses.</p>
    </div>
  </a>

  <a href="/posts/unknown/infrastructure-metrics-for-all-professional-projects">
    <div>
      <div>
        <span>Tuesday, May 3rd 2022</span>
      </div>

      <h3>Infrastructure Metrics available for all Professional projects</h3>
      <p>Gain insight into your application's behavior with observability and metrics on Platform.sh. Monitor CPU, RAM, disk space, and more for informed decisions.</p>
    </div>
  </a>

  <a href="/posts/unknown/greener-hosting-starts-with-transparency">
    <div>
      <div>
        <span>Friday, April 22nd 2022</span>
      </div>

      <h3>Greener hosting starts with transparency</h3>
      <p>Platform.sh enhances transparency about its carbon footprint. Make informed choices on where to deploy your projects with data on environmental impact.</p>
    </div>
  </a>

  <a href="/posts/unknown/automated-code-updates">
    <div>
      <div>
        <span>Friday, April 15th 2022</span>
      </div>

      <h3>Automated code updates</h3>
      <p>Simplify updates and security for critical apps. Platform.sh offers automated source operations to keep your apps up to date.</p>
    </div>
  </a>

  <a href="/posts/unknown/split-projects-and-users-across-organizations">
    <div>
      <div>
        <span>Friday, April 15th 2022</span>
      </div>

      <h3>Split projects and users across multiple organizations</h3>
      <p>Platform.sh now allows creating multiple organizations to suit your project, billing, and contributor management needs.</p>
    </div>
  </a>

  <a href="/posts/unknown/go-1-18-released-on-platformsh">
    <div>
      <div>
        <span>Wednesday, March 16th 2022</span>
      </div>

      <h3>Go 1.18 released on Platform.sh</h3>
      <p>Discover the new features in Go 1.18, including support for generics, and learn how to upgrade your Go projects on Platform.sh for enhanced functionality.</p>
    </div>
  </a>

  <a href="/posts/unknown/privacy-policy-updates">
    <div>
      <div>
        <span>Wednesday, February 16th 2022</span>
      </div>

      <h3>Privacy Policy updates and subprocessors list change</h3>
      <p>Discover the latest changes in Privacy Policy version 6.0, including UTMs and Law Enforcement Requests guidelines. Learn more at Platform.sh.</p>
    </div>
  </a>

  <a href="/posts/unknown/platformsh-announces-microsoft-azure-support-australian-market">
    <div>
      <div>
        <span>Friday, January 28th 2022</span>
      </div>

      <h3>Announcing Microsoft Azure Support for Australia</h3>
      <p>Extending services to the Australian market, offering more choice and local support for web platform development on Microsoft Azure and other cloud providers.</p>
    </div>
  </a>

  <a href="/posts/unknown/managing-multiple-website">
    <div>
      <div>
        <span>Thursday, January 27th 2022</span>
      </div>

      <h3>The secret to managing multiple websites</h3>
      <p>Learn how a unified DevOps strategy can help manage a diverse website portfolio at scale while controlling costs and driving predictability with Platform.sh.</p>
    </div>
  </a>

  <a href="/posts/how-tos/measuring-the-success-of-a-deployment-with-githubactions">
    <div>
      <div>
        <span>Thursday, December 23rd 2021</span>
      </div>

      <h3>Measuring Deployment Success with GitHub Actions</h3>
      <p>Learn how GitHub actions can streamline your Platform.sh deployments for faster and more efficient development workflows</p>
    </div>
  </a>

  <a href="/posts/unknown/share-your-activities-with-robots-surfacing-activities-with-github-actions">
    <div>
      <div>
        <span>Wednesday, December 22nd 2021</span>
      </div>

      <h3>Surfacing activities with GitHub actions</h3>
      <p>Learn how to leverage the predictable link in your workflow by integrating Platform.sh with GitHub Actions. Streamline your deployments and error handling.</p>
    </div>
  </a>

  <a href="/posts/unknown/share-your-failures-fix-them-faster">
    <div>
      <div>
        <span>Wednesday, December 8th 2021</span>
      </div>

      <h3>Share and fix failures faster with shareable activities</h3>
      <p>Troubleshoot failures efficiently with shareable activity logs. Collaborate with your team and Platform.sh support to streamline Continuous Delivery workflow.</p>
    </div>
  </a>

  <a href="/posts/unknown/overview-video">
    <div>
      <div>
        <span>Monday, November 15th 2021</span>
      </div>

      <h3>New Platform.sh overview video: a proven, 5-step approach helps explain a complex concept</h3>
      <p>Discover what Platform.sh does in this 5-step overview video. Clear explanations, no technical jargon. Learn how it can benefit your business. Watch now!</p>
    </div>
  </a>

  <a href="/posts/unknown/creating-problem-solving-partnerships-through-open-innovation">
    <div>
      <div>
        <span>Wednesday, September 8th 2021</span>
      </div>

      <h3>Creating problem-solving partnerships with open innovation</h3>
      <p>Learn about open innovation, its challenges, and benefits. Discover how companies collaborate for creative problem-solving and innovation.</p>
    </div>
  </a>

  <a href="/posts/unknown/keeping-afloat-during-flood-of-worker-turnover">
    <div>
      <div>
        <span>Thursday, August 19th 2021</span>
      </div>

      <h3>Keeping afloat during the flood of worker turnover</h3>
      <p>Discover insights on the talent turnover tsunami, burnout, and remote work strategies. Learn how to win the talent war in today's job market.</p>
    </div>
  </a>

  <a href="/posts/unknown/beginners-guide-to-platformsh">
    <div>
      <div>
        <span>Tuesday, August 17th 2021</span>
      </div>

      <h3>A beginner’s guide to Platform.sh</h3>
      <p>Beginner's guide to Platform.sh: a complete end-to-end cloud Platform-as-a-Service for development teams. Discover the features and developer experience.</p>
    </div>
  </a>

  <a href="/posts/how-tos/get-more-control-over-your-environments-with-build-variables">
    <div>
      <div>
        <span>Tuesday, August 10th 2021</span>
      </div>

      <h3>Get more control over your environments with build variables</h3>
      <p>Discover the visible-build flag on Platform.sh, enabling environment-specific build variables for more control over your development process.</p>
    </div>
  </a>

  <a href="/posts/unknown/building-better-mousetrap-barebones-budget">
    <div>
      <div>
        <span>Thursday, July 1st 2021</span>
      </div>

      <h3>Building a better mousetrap on a barebones budget</h3>
      <p>Learn from Dan Kildahl's insights on innovating wisely with limited resources in the latest Fleet Club session. Join the conversation at Fleet Club.</p>
    </div>
  </a>

  <a href="/posts/unknown/best-practices-for-engaging-digital-agency">
    <div>
      <div>
        <span>Monday, April 26th 2021</span>
      </div>

      <h3>Best practices for engaging a digital agency</h3>
      <p>Build a strong digital agency partnership with open communication and trust. Learn top tips from Carl Smith, Bureau of Digital principal.</p>
    </div>
  </a>

  <a href="/posts/unknown/four-reasons-to-build-ecommerce-site-with-modern-paas">
    <div>
      <div>
        <span>Thursday, April 22nd 2021</span>
      </div>

      <h3>Four reasons to build your ecommerce site with a modern PaaS</h3>
      <p>Discover why SportRx and FREITAG chose Platform.sh for their ecommerce businesses. Higher performance, scalability, stability, and redundancy.</p>
    </div>
  </a>

  <a href="/posts/unknown/plan-monitor-operate-more-knowledgeably-with-metrics">
    <div>
      <div>
        <span>Wednesday, March 17th 2021</span>
      </div>

      <h3>Plan, monitor, and operate more knowledgeably with metrics</h3>
      <p>Introducing metrics and observability on Dedicated infrastructure projects, allowing you to easily monitor CPU, RAM, and disk usage across your hosts.</p>
    </div>
  </a>

  <a href="/posts/unknown/time-to-breakup-three-reasons-to-decouple-your-application">
    <div>
      <div>
        <span>Wednesday, February 10th 2021</span>
      </div>

      <h3>Time to breakup? Three reasons to decouple your application</h3>
      <p>Reasons to consider decoupling your website on Platform.sh. Specialized frameworks, focused teams, and create once, publish everywhere benefits.</p>
    </div>
  </a>

  <a href="/posts/core-concepts/https-and-tls-certificates-always-served-fresh">
    <div>
      <div>
        <span>Tuesday, February 9th 2021</span>
      </div>

      <h3>HTTPS and TLS certificates: Always served fresh</h3>
      <p>Goodbye to expired certificates! We now auto-renew TLS certificates for your websites, ensuring end-to-end encryption without interruptions.</p>
    </div>
  </a>

  <a href="/posts/unknown/how-digital-agency-adapt-innovates-without-heavy-lifting">
    <div>
      <div>
        <span>Wednesday, February 3rd 2021</span>
      </div>

      <h3>How digital agency Adapt innovates—without heavy-lifting</h3>
      <p>Discover how to optimize websites using Statamic on Laravel with Platform.sh. Flexible, secure, and editor-friendly solutions for developers and editors.</p>
    </div>
  </a>

  <a href="/posts/unknown/lazard-names-platformsh-to-their-t100-index">
    <div>
      <div>
        <span>Monday, February 1st 2021</span>
      </div>

      <h3>Lazard names Platform.sh to their T100 Index</h3>
      <p>Lazard recognizes Platform.sh as a top European company with disruptive potential. Learn how we enable innovation and flexibility for businesses.</p>
    </div>
  </a>

  <a href="/posts/unknown/renaming-your-projects-default-branch">
    <div>
      <div>
        <span>Wednesday, January 20th 2021</span>
      </div>

      <h3>Renaming your project’s default branch</h3>
      <p>Update your Project's default branch in Git repositories. Rename your master branch to support a more inclusive default naming convention.</p>
    </div>
  </a>

  <a href="/posts/unknown/frederic-potvin-and-yann-deshayes">
    <div>
      <div>
        <span>Tuesday, January 19th 2021</span>
      </div>

      <h3>Platform.sh | Journeys Frederic Potvin and Yann Deshayes</h3>
      <p>Stories of two Platform.sh engineers who left and returned, highlighting the company's flexibility, employee support, and commitment to a healthy work culture</p>
    </div>
  </a>

  <a href="/posts/unknown/free-your-developers-the-simple-way-to-rebalance-your-devops-resources">
    <div>
      <div>
        <span>Thursday, January 14th 2021</span>
      </div>

      <h3>Free your developers! The simple way to rebalance your DevOps resources</h3>
      <p>Discover how Platform-as-a-Service (PaaS) can shift the balance of power from Ops to Dev, giving organizations more time, money, and tools for development.</p>
    </div>
  </a>

  <a href="/posts/unknown/what-the-heck-is-a-decoupled-website">
    <div>
      <div>
        <span>Monday, January 11th 2021</span>
      </div>

      <h3>CMS architecture: What the heck is . . . a decoupled website?</h3>
      <p>A decoupled CMS architecture splits website tasks into smaller apps while maintaining specific functions. Learn how Platform.sh improves the process.</p>
    </div>
  </a>

  <a href="/posts/unknown/platformsh-joins-gaia-x">
    <div>
      <div>
        <span>Monday, December 7th 2020</span>
      </div>

      <h3>Platform.sh joins the Gaia-X data infrastructure initiative</h3>
      <p>Platform.sh partners with Gaia-X, boosting EU data security and processing. Trusted by leading European institutions, we're committed to a secure data future.</p>
    </div>
  </a>

  <a href="/posts/unknown/record-breaking-2020-black-friday-cyber-monday-volumes">
    <div>
      <div>
        <span>Monday, December 7th 2020</span>
      </div>

      <h3>Record-breaking 2020 Black Friday volumes</h3>
      <p>Platform.sh helped retailers thrive during the 2020 holiday season with record traffic and order volumes. Learn more about our high-performance architecture.</p>
    </div>
  </a>

  <a href="/posts/unknown/what-the-heck-is-a-cdn">
    <div>
      <div>
        <span>Friday, November 27th 2020</span>
      </div>

      <h3>What the heck is . . . a CDN?</h3>
      <p>Ask a non-technical professional what the most challenging part of their job is and you’ll often hear, “Understanding what the heck our developers are talking about.</p>
    </div>
  </a>

  <a href="/posts/unknown/php-80-brings-it-all-together-on-platformsh">
    <div>
      <div>
        <span>Thursday, November 26th 2020</span>
      </div>

      <h3>PHP 8.0 brings it all together on Platform.sh</h3>
      <p>Discover the new features in PHP 8.0 and learn how to upgrade your Platform.sh projects. Constructor Property Promotion, Attributes, Named Arguments, and more!</p>
    </div>
  </a>

  <a href="/posts/core-concepts/getting-gitops-right">
    <div>
      <div>
        <span>Tuesday, November 10th 2020</span>
      </div>

      <h3>Getting GitOps right</h3>
      <p>Source code management has never been simpler with GitOps from Platform.sh. We'll help you get started with automating your deployments.</p>
    </div>
  </a>

  <a href="/posts/releases/php-80-feature-focus-constructor-property-promotion">
    <div>
      <div>
        <span>Thursday, November 5th 2020</span>
      </div>

      <h3>PHP 8.0 feature focus: Class constructor property promotion</h3>
      <p>Discover how PHP 8.0's Constructor Property Promotion feature can streamline your code, reduce verbosity, and make coding faster. Try it on Platform.sh today!</p>
    </div>
  </a>

  <a href="/posts/unknown/php-80-feature-focus-language-tightening">
    <div>
      <div>
        <span>Thursday, October 22nd 2020</span>
      </div>

      <h3>PHP 8.0 feature focus: Language tightenings</h3>
      <p>Explore PHP 8.0's language changes for safer code. Discover stable sorting, numeric string handling, stricter magic methods, and more on Platform.sh!</p>
    </div>
  </a>

  <a href="/posts/how-it-works/how-do-you-manage-ssh-keys-in-your-organization">
    <div>
      <div>
        <span>Wednesday, October 21st 2020</span>
      </div>

      <h3>SSH certificates with Platform.sh</h3>
      <p>Learn how Platform.sh simplifies provisioning SSH certificates for secure and keyless SSH authentication, enhancing security and making compliance easier.</p>
    </div>
  </a>

  <a href="/posts/unknown/ks-chan">
    <div>
      <div>
        <span>Wednesday, October 21st 2020</span>
      </div>

      <h3>Platform.sh | Journeys KS Chan</h3>
      <p>Discover how a Platform.sh engineer found work-life balance while shaping the company's largest department, all while spending time with his family.</p>
    </div>
  </a>

  <a href="/posts/unknown/php-80-feature-focus-quality-of-life-improvements">
    <div>
      <div>
        <span>Wednesday, October 14th 2020</span>
      </div>

      <h3>PHP 8.0 feature focus: quality of life improvements</h3>
      <p>Explore PHP 8.0's new string functions, throw expression, and other improvements. Try PHP 8.0 on Platform.sh today!</p>
    </div>
  </a>

  <a href="/posts/unknown/what-the-heck-is-a-container">
    <div>
      <div>
        <span>Monday, October 5th 2020</span>
      </div>

      <h3>CMS architecture: What the heck is . . . containerization?</h3>
      <p>Want to better understand containerization? Let Platform.sh walk you through it. Our no-hassle container platform will keep your applications running smoothly.</p>
    </div>
  </a>

  <a href="/posts/releases/php-80-feature-focus-weak-maps">
    <div>
      <div>
        <span>Thursday, October 1st 2020</span>
      </div>

      <h3>PHP 8.0 feature focus: Weak maps</h3>
      <p>Learn how PHP 8.0's Weak Maps simplify memory management by efficiently handling cached objects. Try PHP 8.0 on Platform.sh today!</p>
    </div>
  </a>

  <a href="/posts/unknown/mahdi-mokhtariirani">
    <div>
      <div>
        <span>Wednesday, September 16th 2020</span>
      </div>

      <h3>Platform.sh | Journeys Mahdi Mokhtariirani</h3>
      <p>Follow Mahdi's journey from Iran to Europe, his experiences at Platform.sh, and how he continues to learn and grow in unfamiliar surroundings.</p>
    </div>
  </a>

  <a href="/posts/unknown/microsoft-azure-west-datacenter">
    <div>
      <div>
        <span>Tuesday, September 8th 2020</span>
      </div>

      <h3>Expansion of Microsoft Azure Data Center services</h3>
      <p>Platform.sh expands to Microsoft Azure West US 2, offering agile teams in the West faster access. Learn more about our end-to-end web platform.</p>
    </div>
  </a>

  <a href="/posts/unknown/pre-release-php-8-0-images-now-available">
    <div>
      <div>
        <span>Thursday, September 3rd 2020</span>
      </div>

      <h3>Pre-release PHP 8.0 images now available</h3>
      <p>Explore PHP 8.0's new features and performance improvements. Try it out early on Platform.sh with a simple configuration change.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/installers-that-dont-suck">
    <div>
      <div>
        <span>Wednesday, August 5th 2020</span>
      </div>

      <h3>Installers that don't suck</h3>
      <p>Learn how to create cloud-friendly web application installers that account for cloud-based environments and optimize the user experience.</p>
    </div>
  </a>

  <a href="/posts/engineering/save-your-drupal-team-hours-and-effort-with-source-operations-and-activity-scripts">
    <div>
      <div>
        <span>Tuesday, July 28th 2020</span>
      </div>

      <h3>Source Operations and Activity Scripts for Drupal teams</h3>
      <p>Learn how to automate Drupal updates on Platform.sh using Source Operations and Activity Scripts, saving your development team time and effort.</p>
    </div>
  </a>

  <a href="/posts/unknown/headless-but-this-time-live-decoupled-drupal-with-gatsby">
    <div>
      <div>
        <span>Tuesday, July 28th 2020</span>
      </div>

      <h3>Headless, but this time live! Decoupled Drupal with Gatsby</h3>
      <p>Learn to decouple Drupal and Gatsby on Platform.sh for parallel work and efficient content management. Follow our tutorial and deploy your project today!</p>
    </div>
  </a>

  <a href="/posts/unknown/connecting-with-the-community-at-drupalcon-global">
    <div>
      <div>
        <span>Friday, July 24th 2020</span>
      </div>

      <h3>Connecting with the community at DrupalCon Global</h3>
      <p>Discover our highlights from DrupalCon Global, including our partnership with Lando and booth demos. Stay updated on our Drupal community involvement.</p>
    </div>
  </a>

  <a href="/posts/unknown/sso-for-platformsh-now-available-for-openid-connect-and-google">
    <div>
      <div>
        <span>Thursday, June 25th 2020</span>
      </div>

      <h3>SSO available for OpenID Connect and Google</h3>
      <p>Enhance security with Single Sign-On for OpenID Connect and Google. Protect your projects with two-factor authentication and password rotation.</p>
    </div>
  </a>

  <a href="/posts/unknown/platformsh-partner-eZ-Systems-announces-name-change-to-ibexa">
    <div>
      <div>
        <span>Tuesday, June 23rd 2020</span>
      </div>

      <h3>Platform.sh partner eZ Systems announces name change to Ibexa</h3>
      <p>After twenty years as a successful Web Content Management vendor, eZ Systems last month announced the launch of its new corporate brand identity and name: Ibexa</p>
    </div>
  </a>

  <a href="/posts/unknown/integrations-management-through-platform-sh-console">
    <div>
      <div>
        <span>Thursday, June 18th 2020</span>
      </div>

      <h3>View your external integrations through the console</h3>
      <p>View, create, update, and debug your Platform.sh project's external integrations directly from the console for increased control.</p>
    </div>
  </a>

  <a href="/posts/unknown/headless-strapi-and-wordpress-content-with-gatsby-builds">
    <div>
      <div>
        <span>Wednesday, May 13th 2020</span>
      </div>

      <h3>Going headless during your Gatsby builds</h3>
      <p>Recently, Platform.</p>
    </div>
  </a>

  <a href="/posts/unknown/improve-visibility-over-your-external-integrations">
    <div>
      <div>
        <span>Tuesday, May 12th 2020</span>
      </div>

      <h3>Improve visibility over your external integrations</h3>
      <p>Stay updated with activities from your integrations in the API or CLI. Easily validate, test, and troubleshoot external integrations with Platform.sh.</p>
    </div>
  </a>

  <a href="/posts/unknown/improving-access-and-security-for-your-projects">
    <div>
      <div>
        <span>Monday, April 20th 2020</span>
      </div>

      <h3>Improving access and security for your projects</h3>
      <p>Improved user security measures, including strong password policies and Single Sign-On (SSO) capabilities for enhanced authentication and mitigation control.</p>
    </div>
  </a>

  <a href="/posts/unknown/supporting-drupal-covid-19">
    <div>
      <div>
        <span>Friday, April 17th 2020</span>
      </div>

      <h3>Supporting the Drupal Association through COVID-19</h3>
      <p>Platform.sh remains committed to DrupalCon, Drupal Association, and COVID-19 response initiatives during these challenging times.</p>
    </div>
  </a>

  <a href="/posts/unknown/taking-your-application-to-saas-a-business-decision">
    <div>
      <div>
        <span>Friday, April 17th 2020</span>
      </div>

      <h3>High-performance for cloud application development</h3>
      <p>Learn why some applications make it to a \$2 billion SaaS acquisition while others don't. Explore the path to SaaS success with Platform.sh.</p>
    </div>
  </a>

  <a href="/posts/unknown/new-enterprise-pricing-tiers-fleetops">
    <div>
      <div>
        <span>Wednesday, April 15th 2020</span>
      </div>

      <h3>New pricing tiers make FleetOps accessible</h3>
      <p>New product tiers offering features for managing multiple websites. Explore Platform.sh's Elite tier with Technical Account Management, higher SLAs, and more.</p>
    </div>
  </a>

  <a href="/posts/unknown/the-monolith-myth-why-tech-suites-are-not-solution">
    <div>
      <div>
        <span>Monday, April 13th 2020</span>
      </div>

      <h3>A monolith myth: All-in-one tech suites aren't the solution</h3>
      <p>Explore the reality behind all-in-one tech suites and why they often fail to meet the diverse needs of businesses</p>
    </div>
  </a>

  <a href="/posts/unknown/a-10x-increase-in-enterprise-valuation-over-two-years-a-saas-case-study">
    <div>
      <div>
        <span>Tuesday, April 7th 2020</span>
      </div>

      <h3>SaaS case study: 10x increase in enterprise valuation</h3>
      <p>Learn how an ecommerce company increased valuation via a Platform.sh cloud transition. Explore SaaS benefits, business value, and insights for your model.</p>
    </div>
  </a>

  <a href="/posts/unknown/the-suddenly-online-conference">
    <div>
      <div>
        <span>Thursday, April 2nd 2020</span>
      </div>

      <h3>The suddenly online conference: an Indy Cloud Conf case study</h3>
      <p>Explore the challenges and successes of transitioning from in-person conferences to remote events during the COVID-19 pandemic.</p>
    </div>
  </a>

  <a href="/posts/unknown/platformsh-covid-19-response">
    <div>
      <div>
        <span>Tuesday, March 17th 2020</span>
      </div>

      <h3>A note to Platform.sh customers about COVID-19 preparedness</h3>
      <p>Platform.sh remains fully operational during the COVID-19 pandemic. Learn about our measures to ensure business continuity and employee safety.</p>
    </div>
  </a>

  <a href="/posts/unknown/survival-guide-for-efficient-remote-work">
    <div>
      <div>
        <span>Friday, March 13th 2020</span>
      </div>

      <h3>Voilà! You’re now a distributed workforce</h3>
      <p>A Survival Guide for managers who need to drive a company that became remote overnight due to COVID-19</p>
    </div>
  </a>

  <a href="/posts/releases/deploy-strapi-on-platformsh">
    <div>
      <div>
        <span>Tuesday, March 3rd 2020</span>
      </div>

      <h3>Platform.sh–deploying the future of content with one click</h3>
      <p>Platform.sh and Strapi empower developers with a headless CMS solution for streamlined digital experiences. Deploy Strapi instantly. Learn more</p>
    </div>
  </a>

  <a href="/posts/unknown/out-of-the-lab-Node.js-12-features-graduate-from-experimental-status">
    <div>
      <div>
        <span>Tuesday, January 14th 2020</span>
      </div>

      <h3>Node.js 12 features graduate from experimental status</h3>
      <p>Discover the latest Node.js 12 LTS release with performance optimizations and new features. Upgrade your applications seamlessly with Platform.sh. Learn more!</p>
    </div>
  </a>

  <a href="/posts/unknown/what-is-new-with-jakarta-nosql-part-II">
    <div>
      <div>
        <span>Wednesday, January 8th 2020</span>
      </div>

      <h3>What’s new with Jakarta NoSQL? (Part II)</h3>
      <p>Discover cloud-native with Jakarta EE, best practices, and deploying applications with Jakarta EE NoSQL. Move to the cloud with Platform.sh.</p>
    </div>
  </a>

  <a href="/posts/unknown/sharpen-your-tusks-it-is-time-for-python-3.8">
    <div>
      <div>
        <span>Wednesday, December 18th 2019</span>
      </div>

      <h3>Sharpen your tusks: it's time for Python 3.8</h3>
      <p>Discover the latest features in Python 3.8, including the walrus operator, self-documenting f-strings, and more. Upgrade your Python applications</p>
    </div>
  </a>

  <a href="/posts/unknown/php-7.4-is-just-a-git-push-away">
    <div>
      <div>
        <span>Thursday, November 28th 2019</span>
      </div>

      <h3>PHP 7.4 is just a git push away</h3>
      <p>The latest features in PHP 7.4. Learn about typed properties, short-lambda syntax, null coalesce assignment, and opcache preloading.</p>
    </div>
  </a>

  <a href="/posts/unknown/new-services-page">
    <div>
      <div>
        <span>Tuesday, October 15th 2019</span>
      </div>

      <h3>New Services Page: more shininess, as promised</h3>
      <p>Discover the brand new Services page in our management console. Get detailed insights into your services, routes, and applications right from the console.</p>
    </div>
  </a>

  <a href="/posts/business/website-fleet">
    <div>
      <div>
        <span>Friday, October 11th 2019</span>
      </div>

      <h3>Website fleet management: challenges and opportunities</h3>
      <p>A solution to manage website fleets, automate code updates, and streamline operations for organizations with numerous websites and applications.</p>
    </div>
  </a>

  <a href="/posts/engineering/three-ways-to-manage-a-fleet">
    <div>
      <div>
        <span>Friday, October 11th 2019</span>
      </div>

      <h3>Three ways to manage a website fleet</h3>
      <p>Efficient multi-website management using Source Operations on Platform.sh. Automate updates, builds, and deployments for a large number of websites with ease.</p>
    </div>
  </a>

  <a href="/posts/unknown/strong-customer-authentication">
    <div>
      <div>
        <span>Thursday, September 26th 2019</span>
      </div>

      <h3>Strong Customer Authentication will be required for European credit and bank card payments</h3>
      <p>Get ready for Strong Customer Authentication (SCA) in Europe. Ensure your Platform.sh account complies with new credit card payment security regulations.</p>
    </div>
  </a>

  <a href="/posts/unknown/security-updates-for-php-rolling-out-now">
    <div>
      <div>
        <span>Wednesday, September 11th 2019</span>
      </div>

      <h3>Security updates for PHP: rolling out now</h3>
      <p>Stay secure with the latest PHP updates. Learn how Platform.sh ensures your protection with automatic upgrades. No action needed on your part.</p>
    </div>
  </a>

  <a href="/posts/unknown/go-release-1.13-on-Platform.sh">
    <div>
      <div>
        <span>Wednesday, September 4th 2019</span>
      </div>

      <h3>New: Go release 1.13 on Platform.sh</h3>
      <p>Upgrade your Go projects on Platform.sh to version 1.13, featuring improvements like Go Modules, enhanced number literal support, and more. Try it now!</p>
    </div>
  </a>

  <a href="/posts/unknown/try-out-the-future-of-php-on-platform.sh-today">
    <div>
      <div>
        <span>Tuesday, August 27th 2019</span>
      </div>

      <h3>PHP 7.4 is here: Try out the future of PHP on Platform.sh today!</h3>
      <p>Explore the new features in PHP 7.4 and learn how to deploy pre-release versions on Platform.sh to test and prepare your project for the official release.</p>
    </div>
  </a>

  <a href="/posts/unknown/microservices-in-the-cloud-part-two">
    <div>
      <div>
        <span>Friday, August 23rd 2019</span>
      </div>

      <h3>Microservices in the cloud, part two</h3>
      <p>Discover microservices, clean code, SOLID principles, and more. Explore Speaker, Session, Conference services with Eclipse MicroProfile.</p>
    </div>
  </a>

  <a href="/posts/unknown/microservices-in-the-cloud-part-one">
    <div>
      <div>
        <span>Tuesday, August 13th 2019</span>
      </div>

      <h3>Microservices in the cloud, part one</h3>
      <p>Microservices are a software architecture, where the systems are a collection of several independent services. Each service has a specific b</p>
    </div>
  </a>

  <a href="/posts/unknown/lisp">
    <div>
      <div>
        <span>Thursday, August 8th 2019</span>
      </div>

      <h3>We are happy, relieved and somewhat amused to announce the availability of Common Lisp on Platform.sh</h3>
      <p>Discover the history and uniqueness of Lisp, a programming language often called 'the path not taken,' and learn how to deploy a Lisp web applications.</p>
    </div>
  </a>

  <a href="/posts/unknown/platform.sh-documentation-new-guides-new-look">
    <div>
      <div>
        <span>Thursday, August 1st 2019</span>
      </div>

      <h3>Platform.sh documentation: new guides, new look</h3>
      <p>Explore the comprehensive Platform.sh documentation. Find step-by-step guides, tutorials, and resources to simplify web app development with Platform.sh.</p>
    </div>
  </a>

  <a href="/posts/unknown/jakarta-ee-generation-iv-a-new-hope">
    <div>
      <div>
        <span>Tuesday, July 30th 2019</span>
      </div>

      <h3>Jakarta EE: Generation IV - a new hope</h3>
      <p>Explore Jakarta EE & MongoDB on Platform.sh. Build enterprise apps with Java & NoSQL. Easy deployment with our tutorial.</p>
    </div>
  </a>

  <a href="/posts/unknown/version-will-be-required-in-type-what-it-means-for-your-projects">
    <div>
      <div>
        <span>Monday, July 22nd 2019</span>
      </div>

      <h3>Version will be required in type: what it means for your projects</h3>
      <p>Important changes to Platform.sh configuration requirements. Learn how including versions in your configurations impacts your projects.</p>
    </div>
  </a>

  <a href="/posts/unknown/eclipse-microprofiles-gain-agility-release-faster">
    <div>
      <div>
        <span>Monday, July 15th 2019</span>
      </div>

      <h3>Eclipse MicroProfiles: gain agility, release faster</h3>
      <p>Explore how Eclipse MicroProfile optimizes Enterprise Java for microservices architecture. Learn about Java frameworks and Platform.sh for cloud deployment.</p>
    </div>
  </a>

  <a href="/posts/unknown/web-dev-plus-IT-unique-roles-equal-partners-in-application-success">
    <div>
      <div>
        <span>Monday, June 24th 2019</span>
      </div>

      <h3>Web dev + IT: unique roles, equal partners in app success</h3>
      <p>Platform.sh enables web development teams to work autonomously without the need for IT assistance, with a focus on governance, security, and compliance.</p>
    </div>
  </a>

  <a href="/posts/unknown/Spring-MVC-and-MongoDB-a-match-made-in-Platform.sh-heaven">
    <div>
      <div>
        <span>Wednesday, June 19th 2019</span>
      </div>

      <h3>Spring MVC and MongoDB: a match made in Platform.sh heaven</h3>
      <p>Learn how to effortlessly integrate Spring MVC with MongoDB on Platform.sh. Create stand-alone, production-grade applications with ease.</p>
    </div>
  </a>

  <a href="/posts/unknown/off-with-its-head-headless-Chrome-as-a-service">
    <div>
      <div>
        <span>Wednesday, June 12th 2019</span>
      </div>

      <h3>Off with its Head! Headless Chrome as a Service decoded</h3>
      <p>Headless Chrome is a headless browser configurable on Platform.sh. Compare screenshots and generate PDFs hassle-free today</p>
    </div>
  </a>

  <a href="/posts/unknown/java-hello-world-at-platform.sh">
    <div>
      <div>
        <span>Thursday, June 6th 2019</span>
      </div>

      <h3>Java: Hello, World! at Platform.sh</h3>
      <p>Discover how to deploy Java applications on Platform.sh. Learn about Spring Boot, MySQL integration, and continuous deployment for Java apps.</p>
    </div>
  </a>

  <a href="/posts/unknown/apache-kafka-support">
    <div>
      <div>
        <span>Wednesday, June 5th 2019</span>
      </div>

      <h3>Apache Kafka now available</h3>
      <p>Discover the power of Apache Kafka for real-time streaming applications and data pipelines. Get started with Kafka on Platform.sh. No servers to configure.</p>
    </div>
  </a>

  <a href="/posts/unknown/new-german-region">
    <div>
      <div>
        <span>Wednesday, May 22nd 2019</span>
      </div>

      <h3>New Germany region: more speed, more capability, lower cost</h3>
      <p>Discover Platform.sh Enterprise in Germany. Get more speed, capability, and compliance for your applications with strict data control.</p>
    </div>
  </a>

  <a href="/posts/unknown/it-worked-in-staging">
    <div>
      <div>
        <span>Thursday, April 25th 2019</span>
      </div>

      <h3>Learning to trust the machines and the process in DevOps</h3>
      <p>Platform.sh enables seamless collaboration between development and operations teams, leading to predictable and reliable deployments for your applications.</p>
    </div>
  </a>

  <a href="/posts/unknown/shiny-new-platformsh-web-management-console">
    <div>
      <div>
        <span>Thursday, April 11th 2019</span>
      </div>

      <h3>Shiny, new Platform.sh management console</h3>
      <p>Explore the new and improved Platform.sh management console, built for better usability and visualization. Try it now and share your feedback!</p>
    </div>
  </a>

  <a href="/posts/unknown/adobe-summit-2019">
    <div>
      <div>
        <span>Monday, April 1st 2019</span>
      </div>

      <h3>Adobe Summit 2019: take-aways</h3>
      <p>Discover key announcements from the Adobe Summit 2019, including Magento integration and Adobe Experience Cloud.</p>
    </div>
  </a>

  <a href="/posts/unknown/four-days-four-languages-four-frameworks-day-3-gatsbyjs-the-reactbased-static-site-generator">
    <div>
      <div>
        <span>Thursday, February 28th 2019</span>
      </div>

      <h3>4 days, 4 languages, 4 frameworks, Day 3: GatsbyJS</h3>
      <p>Explore how to run GatsbyJS, a Progressive Web App (PWA), on Platform.sh. Learn about JAMstack architecture and deploy your Gatsby site easily.</p>
    </div>
  </a>

  <a href="/posts/unknown/four-days-four-languages-four-frameworks-day-2-running-hugo">
    <div>
      <div>
        <span>Wednesday, February 27th 2019</span>
      </div>

      <h3>4 days, 4 languages, 4 frameworks, Day 2: Running Hugo</h3>
      <p>Learn how to build a static site with Hugo on Platform.sh. Hugo is a fast and light static site generator that's easy to use with Platform.sh.</p>
    </div>
  </a>

  <a href="/posts/unknown/four-days-four-languages-four-frameworks-on-platformsh">
    <div>
      <div>
        <span>Tuesday, February 26th 2019</span>
      </div>

      <h3>Four days, four languages, four frameworks on Platform.sh</h3>
      <p>Learn how to run Brightspot CMS, a Java-based content management system, on Platform.sh with Apache Tomcat, MySQL, and Solr. Deploy with ease</p>
    </div>
  </a>

  <a href="/posts/unknown/platformsh-full-speed-ahead-into-2019">
    <div>
      <div>
        <span>Tuesday, January 29th 2019</span>
      </div>

      <h3>Platform.sh full speed ahead into 2019</h3>
      <p>Discover Platform.sh's achievements in 2018 and its goals for 2019. From customer success to robust products, see what's in store for the future.</p>
    </div>
  </a>

  <a href="/posts/unknown/open-source-software-roi-for-your-organization">
    <div>
      <div>
        <span>Wednesday, January 2nd 2019</span>
      </div>

      <h3>Open source software ROI for your organization</h3>
      <p>The benefits of contributing to open-source software and how it can enhance your organization, attract top developers, and improve your software quality.</p>
    </div>
  </a>

  <a href="/posts/unknown/give-the-gift-of-ruby-this-season">
    <div>
      <div>
        <span>Tuesday, December 18th 2018</span>
      </div>

      <h3>Give the gift of Ruby this season</h3>
      <p>Discover the new features in Ruby 2.5 and how to easily upgrade your Ruby apps to the latest version with Platform.sh. Enjoy improved performance and syntax.</p>
    </div>
  </a>

  <a href="/posts/releases/deploy-with-php-73-this-friday-er-thursday">
    <div>
      <div>
        <span>Thursday, December 6th 2018</span>
      </div>

      <h3>Deploy with PHP 7.3 this Friday, er, Thursday</h3>
      <p>Platform.sh welcomes PHP 7.3! Explore the latest features and performance improvements. Upgrade your application with a simple YAML tweak.</p>
    </div>
  </a>

  <a href="/posts/unknown/update-to-our-privacy-policy">
    <div>
      <div>
        <span>Monday, November 19th 2018</span>
      </div>

      <h3>Update to our Privacy Policy</h3>
      <p>The latest updates to our Privacy Policy, version 2.1, including grammar fixes, GDPR compliance, and a toll-free contact number for California citizens.</p>
    </div>
  </a>

  <a href="/posts/unknown/our-black-friday-gift-10000-cpus-overnight-without-downtime">
    <div>
      <div>
        <span>Friday, November 16th 2018</span>
      </div>

      <h3>Our Black Friday gift: 10,000 CPUs without downtime</h3>
      <p>Prepare your ecommerce site for Black Friday seamlessly with Platform.sh. Add capacity, handle high traffic, and ensure performance without downtime.</p>
    </div>
  </a>

  <a href="/posts/unknown/good-morning-australia-were-back-in-business">
    <div>
      <div>
        <span>Thursday, November 15th 2018</span>
      </div>

      <h3>Good morning, Australia: we’re back in business</h3>
      <p>Reflecting on Platform.sh's first year in Australia. Improved uptime, support, pricing, and plans for a better experience. Learn how we can help you.</p>
    </div>
  </a>

  <a href="/posts/unknown/why-you-should-care-about-wechat-before-its-too-late">
    <div>
      <div>
        <span>Wednesday, October 31st 2018</span>
      </div>

      <h3>Why you should care about WeChat before it's too late!</h3>
      <p>Learn about WeChat, China's super-app, and discover strategies for reaching its vast user base. WeChat's influence on mobile commerce and marketing.</p>
    </div>
  </a>

  <a href="/posts/releases/golang-forth-and-deploy">
    <div>
      <div>
        <span>Monday, October 29th 2018</span>
      </div>

      <h3>Go\[lang] forth and deploy</h3>
      <p>Discover the full support for Go 1.11 on Platform.sh. No more GOPATH required. Easy setup and deployment for Go applications with Go modules and Platform.sh.</p>
    </div>
  </a>

  <a href="/posts/unknown/were-improving-our-communications-tools-at-platformsh">
    <div>
      <div>
        <span>Friday, October 26th 2018</span>
      </div>

      <h3>We're improving our communications tools at Platform.sh</h3>
      <p>We value your privacy. Learn about our email management system, Marketo, and how to change your opt-in status.</p>
    </div>
  </a>

  <a href="/posts/releases/deploy-your-python-37-code-to-the-moon">
    <div>
      <div>
        <span>Wednesday, September 5th 2018</span>
      </div>

      <h3>Deploy your Python 3.7 code to the Moon</h3>
      <p>Platform.sh now supports Python 3.7. Explore the latest features and enhancements. Update your .platform.app.yaml file and enjoy Python 3.7!</p>
    </div>
  </a>

  <a href="/posts/unknown/platformsh-wins-2018-stratus-award-for-cloud-computing">
    <div>
      <div>
        <span>Thursday, August 30th 2018</span>
      </div>

      <h3>Platform.sh Wins 2018 Stratus Award for Cloud Computing</h3>
      <p>Platform.sh wins 2018 Stratus Award for Cloud Computing in the Platform-as-a-Service category by Business Intelligence Group.</p>
    </div>
  </a>

  <a href="/posts/unknown/of-cicadas-and-cron-jobs">
    <div>
      <div>
        <span>Tuesday, August 21st 2018</span>
      </div>

      <h3>Of Cicadas and cron jobs</h3>
      <p>Discover how cicadas and prime numbers can teach us about optimizing web development tasks and avoiding conflicts in cron jobs for smoother website performance.</p>
    </div>
  </a>

  <a href="/posts/unknown/its-july-2018-do-you-know-what-your-php-is">
    <div>
      <div>
        <span>Tuesday, July 3rd 2018</span>
      </div>

      <h3>It's July 2018, do you know what your PHP is?</h3>
      <p>Discover the benefits of upgrading to PHP 7, including better performance, enhanced security, and new functionality.</p>
    </div>
  </a>

  <a href="/posts/unknown/some-gifts-for-the-json-fans">
    <div>
      <div>
        <span>Thursday, June 28th 2018</span>
      </div>

      <h3>Some gifts for the JSON fans</h3>
      <p>Platform.sh now supports the latest MongoDB versions and Node.js version 10. Upgrade seamlessly to enjoy new features and stability for your applications.</p>
    </div>
  </a>

  <a href="/posts/unknown/your-guide-to-gdpr-compliance-training-your-employees">
    <div>
      <div>
        <span>Friday, June 8th 2018</span>
      </div>

      <h3>Your Guide to GDPR Compliance: Training your employees</h3>
      <p>Discover the importance of GDPR staff training for data protection and how it can safeguard your organization. Ensure GDPR compliance with informed employees.</p>
    </div>
  </a>

  <a href="/posts/unknown/the-github-acquisition-its-all-about-cloud-for-microsoft">
    <div>
      <div>
        <span>Tuesday, June 5th 2018</span>
      </div>

      <h3>The Github acquisition: it's all about cloud for Microsoft</h3>
      <p>Explore how Microsoft's acquisition of GitHub aligns with its cloud strategy and the emerging paradigm of GitOps for application deployment to the cloud.</p>
    </div>
  </a>

  <a href="/posts/unknown/your-guide-to-gdpr-compliance-transfers-of-personal-data-to-third-countries">
    <div>
      <div>
        <span>Wednesday, May 30th 2018</span>
      </div>

      <h3>Your Guide to GDPR Compliance: Transfers of personal data to third countries</h3>
      <p>International personal data transfers under GDPR and the conditions for such transfers. Ensure your organization complies with data protection rules.</p>
    </div>
  </a>

  <a href="/posts/unknown/your-guide-to-gdpr-compliance-data-protection-impact-assessment-and-security-measures-for-processing-data">
    <div>
      <div>
        <span>Friday, May 25th 2018</span>
      </div>

      <h3>Your Guide to GDPR Compliance: Data protection impact assessment and security measures for processing data</h3>
      <p>Discover how the GDPR's Data Protection Impact Assessment (DPIA) can help you identify and minimize privacy risks, build trust, and achieve compliance.</p>
    </div>
  </a>

  <a href="/posts/unknown/platformsh-raises-34m-to-bring-speed-and-confidence-to-enterprise-cloud-deployments">
    <div>
      <div>
        <span>Wednesday, May 23rd 2018</span>
      </div>

      <h3>Platform.sh raises \$34M in series C funding</h3>
      <p>Platform.sh secures \$34M in Series C funding to accelerate growth and support customers in North America. Simplify cloud infrastructures with Platform.sh.</p>
    </div>
  </a>

  <a href="/posts/unknown/your-guide-to-gdpr-compliance-data-subject-rights">
    <div>
      <div>
        <span>Wednesday, May 23rd 2018</span>
      </div>

      <h3>Your Guide to GDPR Compliance: Data subject rights</h3>
      <p>Explore GDPR data rights: be informed, access, rectify, erase, restrict processing, data portability, object, and automated decision-making.</p>
    </div>
  </a>

  <a href="/posts/unknown/data-protection-by-design-and-default">
    <div>
      <div>
        <span>Monday, May 7th 2018</span>
      </div>

      <h3>Data protection by design and by default</h3>
      <p>Explore protection by design in our GDPR blog series. Platform.sh ensures data security through privacy by design principles in this insightful article</p>
    </div>
  </a>

  <a href="/posts/unknown/platformsh-confirms-that-it-is-ready-for-the-gdpr">
    <div>
      <div>
        <span>Wednesday, May 2nd 2018</span>
      </div>

      <h3>Platform.sh confirms that it is ready for the GDPR</h3>
      <p>Discover what GDPR (General Data Protection Regulation) is and how it impacts your organization's data privacy. Learn about our GDPR measures and guidelines.</p>
    </div>
  </a>

  <a href="/posts/unknown/your-guide-to-gdpr-compliance-the-six-principles-of-processing-personal-data">
    <div>
      <div>
        <span>Friday, April 20th 2018</span>
      </div>

      <h3>Your Guide to GDPR Compliance: The Six Principles of Processing Personal Data</h3>
      <p>Discover the six key data protection principles of GDPR and why they are vital for compliance. Learn how to prioritize your GDPR efforts.</p>
    </div>
  </a>

  <a href="/posts/insights/what-will-you-do-after-you-deploy">
    <div>
      <div>
        <span>Tuesday, April 17th 2018</span>
      </div>

      <h3>What will you do after you deploy?</h3>
      <p>Learn how Platform.sh's post\_deploy hook can keep your site responsive during deploy tasks, making your deploys faster and more efficient.</p>
    </div>
  </a>

  <a href="/posts/unknown/your-guide-to-gdpr-compliance-roles-and-responsibilities">
    <div>
      <div>
        <span>Monday, April 9th 2018</span>
      </div>

      <h3>Your Guide to GDPR Compliance: Roles and Responsibilities</h3>
      <p>Learn the roles and responsibilities under GDPR - data subject, data controller, data processor. Get ready for GDPR compliance today!</p>
    </div>
  </a>

  <a href="/posts/unknown/your-guide-to-gdpr-compliance-introduction">
    <div>
      <div>
        <span>Wednesday, April 4th 2018</span>
      </div>

      <h3>Your Guide to GDPR Compliance (Introduction)</h3>
      <p>Get ready for GDPR with our comprehensive guide. Understand its impact, your responsibilities, and how to protect personal data and privacy.</p>
    </div>
  </a>

  <a href="/posts/unknown/drupal-critical-core-vulnerability-announced">
    <div>
      <div>
        <span>Wednesday, March 28th 2018</span>
      </div>

      <h3>Drupal critical core vulnerability announced</h3>
      <p>Urgent security update for Drupal users. Update to 8.5.1 / 8.4.9 / 8.3.8 / 7.58 immediately. Platform.sh is working on a platform-level fix.</p>
    </div>
  </a>

  <a href="/posts/unknown/using-platformsh-with-scrum">
    <div>
      <div>
        <span>Tuesday, February 13th 2018</span>
      </div>

      <h3>Using Platform.sh with Scrum</h3>
      <p>Learn how Platform.sh's Git-based environment workflow unblocks Scrum projects, allowing for efficient testing, parallel development, and feature isolation.</p>
    </div>
  </a>

  <a href="/posts/releases/hhvm-deploys-off-into-the-sunset">
    <div>
      <div>
        <span>Tuesday, January 30th 2018</span>
      </div>

      <h3>HHVM deploys off into the sunset</h3>
      <p>Platform.sh will no longer support HHVM runtime after 1 March 2018. Learn about this change and the evolution of PHP alternatives.</p>
    </div>
  </a>

  <a href="/posts/unknown/platformsh-is-ready-to-make-an-impact-in-china">
    <div>
      <div>
        <span>Wednesday, January 24th 2018</span>
      </div>

      <h3>Platform.sh is ready to make an Impact in China</h3>
      <p>Platform.sh is partnering with Impact China 2018 to help China ready startups expand their operations in China and offer cloud hosting services in the region.</p>
    </div>
  </a>

  <a href="/posts/unknown/spectremeltdown-security-update-notice">
    <div>
      <div>
        <span>Friday, January 5th 2018</span>
      </div>

      <h3>Spectre/Meltdown Security Update Notice</h3>
      <p>Platform.sh addresses the Spectre and Meltdown vulnerabilities with scheduled maintenance. Learn more about the updates and potential downtime.</p>
    </div>
  </a>

  <a href="/posts/unknown/backup-and-forget">
    <div>
      <div>
        <span>Wednesday, January 3rd 2018</span>
      </div>

      <h3>Backup and Forget</h3>
      <p>Learn how to automate disaster recovery backups using Platform.sh. A simple 3-step process for routine snapshots of your production environment.</p>
    </div>
  </a>

  <a href="/posts/unknown/a-look-back-on-2017">
    <div>
      <div>
        <span>Friday, December 29th 2017</span>
      </div>

      <h3>A look back on 2017</h3>
      <p>Explore a year of enhancements at Platform.sh, from HTTP/2 support to expanded services. Preview what's coming in 2018 for our PaaS.</p>
    </div>
  </a>

  <a href="/posts/unknown/tighten-up-your-tls">
    <div>
      <div>
        <span>Thursday, December 28th 2017</span>
      </div>

      <h3>Tighten up your TLS</h3>
      <p>Discover new TLS-related features for increased website security on Platform.sh. Restrict TLS versions, enable HSTS, and implement client-authenticated TLS.</p>
    </div>
  </a>

  <a href="/posts/unknown/route-all-the-things">
    <div>
      <div>
        <span>Wednesday, December 20th 2017</span>
      </div>

      <h3>Route all the things</h3>
      <p>Learn how the routing system works on Platform.sh, including its flexibility, multi-domain support, and routing configurations.</p>
    </div>
  </a>

  <a href="/posts/unknown/gitlab-integration-is-here">
    <div>
      <div>
        <span>Tuesday, December 12th 2017</span>
      </div>

      <h3>GitLab Integration is here!</h3>
      <p>Easily integrate GitLab with Platform.sh for streamlined code management, deployment, and collaboration. Create environments for every branch and pull request.</p>
    </div>
  </a>

  <a href="/posts/unknown/living-on-the-edge-with-ruby-25-preview">
    <div>
      <div>
        <span>Tuesday, December 12th 2017</span>
      </div>

      <h3>Living on the edge with Ruby 2.5 (preview)</h3>
      <p>Discover how to effortlessly migrate your Ruby and Rails applications to Ruby 2.5 on Platform.sh, with enhanced performance and new features.</p>
    </div>
  </a>

  <a href="/posts/unknown/platformsh-joins-the-prestigious-french-tech-tour-china-2017">
    <div>
      <div>
        <span>Sunday, December 3rd 2017</span>
      </div>

      <h3>Platform.sh joins the prestigious French Tech Tour China 2017</h3>
      <p>Join our CEO and team in Singapore, Hong Kong, Shenzhen, Shanghai, and Beijing for the French Tech Tour China 2017. Learn more about Platform.sh's journey.</p>
    </div>
  </a>

  <a href="/posts/unknown/welcome-to-the-world-php-72">
    <div>
      <div>
        <span>Thursday, November 30th 2017</span>
      </div>

      <h3>Welcome to the world, PHP 7.2!</h3>
      <p>Learn about the new features and improvements in PHP 7.2.0, including better performance and security enhancements. Try PHP 7.2.0 on Platform.sh with ease.</p>
    </div>
  </a>

  <a href="/posts/unknown/deploy-api-platform-on-platformsh">
    <div>
      <div>
        <span>Wednesday, November 29th 2017</span>
      </div>

      <h3>Simplifying API Platform Deployment on Platform.sh</h3>
      <p>Optimize API development with Platform.sh. Deploy API Platform effortlessly and unlock robust backend capabilities for your APIs</p>
    </div>
  </a>

  <a href="/posts/unknown/wordpress-security-updates-the-quick-way">
    <div>
      <div>
        <span>Wednesday, November 1st 2017</span>
      </div>

      <h3>WordPress security updates, the quick way</h3>
      <p>Learn how to update your WordPress version to 4.8.3 to fix a security vulnerability.</p>
    </div>
  </a>

  <a href="/posts/unknown/going-local-with-lando">
    <div>
      <div>
        <span>Wednesday, October 18th 2017</span>
      </div>

      <h3>Going Local with Lando</h3>
      <p>Lando, a Docker-based local development tool recommended by Platform.sh. Easily set up your local environment and sync data from for seamless web development.</p>
    </div>
  </a>

  <a href="/posts/unknown/wildcard-support-for-cookies-in-the-http-cache">
    <div>
      <div>
        <span>Tuesday, October 17th 2017</span>
      </div>

      <h3>Wildcard support for cookies in the HTTP cache</h3>
      <p>Learn how to use regular expressions for wildcard cookie matching at the cache layer on Platform.sh, improving caching rules and caching performance.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/the-platformsh-build-and-deploy-pipeline">
    <div>
      <div>
        <span>Tuesday, October 3rd 2017</span>
      </div>

      <h3>The Platform.sh build-and-deploy pipeline</h3>
      <p>Learn how Platform.sh simplifies the build and deploy pipeline for web applications, ensuring consistency and repeatability with Git-based semantics.</p>
    </div>
  </a>

  <a href="/posts/unknown/taking-care-of-your-health">
    <div>
      <div>
        <span>Monday, October 2nd 2017</span>
      </div>

      <h3>Taking care of your health</h3>
      <p>Easily monitor your project's health with built-in notification checks for disk space, sent via email, Slack, or Pager Duty on Platform Professional projects.</p>
    </div>
  </a>

  <a href="/posts/unknown/platformsh-joins-orange-cloud-for-business-at-huawei-connect-2017-shanghai">
    <div>
      <div>
        <span>Monday, September 4th 2017</span>
      </div>

      <h3>Platform.sh & Orange Cloud at Huawei Connect 2017, Shanghai</h3>
      <p>Join Platform.sh and Orange Cloud for Business at Huawei Connect in Shanghai. Discover Continuous Deployment cloud hosting for agile development.</p>
    </div>
  </a>

  <a href="/posts/unknown/6-things-to-do-to-make-your-application-cloud-friendly">
    <div>
      <div>
        <span>Monday, August 7th 2017</span>
      </div>

      <h3>7 things to do to make your application cloud-friendly</h3>
      <p>Make your app cloud-friendly with 7 steps. Test it on Platform.sh for free to ensure compatibility in a real-world environment.</p>
    </div>
  </a>

  <a href="/posts/unknown/deploy-down-under-platformsh-is-now-available-in-australia">
    <div>
      <div>
        <span>Monday, July 3rd 2017</span>
      </div>

      <h3>Deploy Down Under: Platform.sh is now available in Australia</h3>
      <p>Experience unmatched Australian cloud hosting. Deploy PHP, NodeJS, Ruby & Python projects with Platform.sh's Continuous Deployment. Try it now!</p>
    </div>
  </a>

  <a href="/posts/unknown/containers-old-containers-new-memcached-support-and-php-72">
    <div>
      <div>
        <span>Monday, June 26th 2017</span>
      </div>

      <h3>Containers, memcached support, and PHP 7.2</h3>
      <p>Stay updated with Platform.sh's latest features, including MariaDB and Memcached support. Try PHP 7.2-alpha and explore new languages</p>
    </div>
  </a>

  <a href="/posts/unknown/now-available-sovereign-hosting-solution-in-microsoft-cloud-germany">
    <div>
      <div>
        <span>Thursday, June 22nd 2017</span>
      </div>

      <h3>Sovereign Hosting Solution in Microsoft Cloud Germany</h3>
      <p>A sovereign, end-to-end development and production hosting solution in Microsoft Cloud Germany. Ensure compliance, data security, and efficiency gains.</p>
    </div>
  </a>

  <a href="/posts/unknown/getting-to-5050-women-men-participation-polyconf-a-very-diverse-conference">
    <div>
      <div>
        <span>Thursday, June 8th 2017</span>
      </div>

      <h3>Getting to 50/50: Polyconf, a very diverse conference</h3>
      <p>Learn about PolyConf 2023, a conference promoting diversity in tech. Discover how Platform.sh supports gender diversity and inclusion in the tech community.</p>
    </div>
  </a>

  <a href="/posts/unknown/the-ultimate-third-party-resources-list-on-using-platformsh">
    <div>
      <div>
        <span>Tuesday, May 16th 2017</span>
      </div>

      <h3>The Ultimate Third Party Resources List on Using Platform.sh</h3>
      <p>Resources and guides from the Platform.sh community. Get tips on migrations, debugging, workflows, and more for your projects. Contribute to this growing list.</p>
    </div>
  </a>

  <a href="/posts/unknown/devops-gives-you-wings">
    <div>
      <div>
        <span>Tuesday, May 9th 2017</span>
      </div>

      <h3>DevOps gives you wings</h3>
      <p>Discover the importance of DevOps and automation for your organization. Learn how Platform.sh can help you achieve better DevOps for competitive success.</p>
    </div>
  </a>

  <a href="/posts/unknown/screencast-composer-and-continuous-integration">
    <div>
      <div>
        <span>Tuesday, May 9th 2017</span>
      </div>

      <h3>Screencast - Composer and Continuous Integration</h3>
      <p>Discover how Platform.sh simplifies Composer usage and streamlines continuous integration. Learn about managing PHP applications effectively.</p>
    </div>
  </a>

  <a href="/posts/unknown/sponsoring-predotscale-and-election-drinks">
    <div>
      <div>
        <span>Friday, April 21st 2017</span>
      </div>

      <h3>Sponsoring pre-dotScale and election drinks !</h3>
      <p>Platform.sh invites you to enjoy free drinks at Café Delaville in Paris before the dotSecurity and dotScale conferences. A perfect opportunity to mingle!</p>
    </div>
  </a>

  <a href="/posts/unknown/free-ssl-certificates-for-every-project-every-environment">
    <div>
      <div>
        <span>Thursday, April 20th 2017</span>
      </div>

      <h3>Free SSL certificates for every project & every environment</h3>
      <p>We now offer free automatic Let's Encrypt SSL certificates, making your site secure, fast, and feature-rich. Say hello to secure, fast, and easy web hosting!</p>
    </div>
  </a>

  <a href="/posts/unknown/imagine-2017-the-new-magento-ecosystem">
    <div>
      <div>
        <span>Thursday, April 13th 2017</span>
      </div>

      <h3>Imagine 2017: The New Magento Ecosystem</h3>
      <p>Dive into the excitement of Magento Imagine 2017. Discover how Magento's revitalized spirit and innovative approach are shaping the future of e-commerce.</p>
    </div>
  </a>

  <a href="/posts/unknown/global-app-cache-our-managed-tiered-cdn-feature-for-global-page-and-asset-cache-coverage">
    <div>
      <div>
        <span>Wednesday, April 5th 2017</span>
      </div>

      <h3>Global App Cache: Managed CDNs for optimal performance</h3>
      <p>CDN caching boosts website speed and reliability. Learn how our Global App Cache combines multiple CDNs for optimal delivery and 99.99% uptime.</p>
    </div>
  </a>

  <a href="/posts/unknown/influxdb">
    <div>
      <div>
        <span>Monday, March 27th 2017</span>
      </div>

      <h3>Now you can save time in a database</h3>
      <p>Introducing Influx DB 1.2, perfect for high-volume logging, data collection, and metrics. Easily add it to your services.yaml file for improved data handling.</p>
    </div>
  </a>

  <a href="/posts/unknown/oliver-sweeney-website-revamp-with-magento-cloud-powered-by-platformsh-oozes-sophistication-and-luxury">
    <div>
      <div>
        <span>Friday, March 17th 2017</span>
      </div>

      <h3>Oliver Sweeney website revamp with Magento Cloud</h3>
      <p>When your company sells luxury items, you want your website to offer that same exclusive, stunning digital experience for your customers too.</p>
    </div>
  </a>

  <a href="/posts/unknown/expands-usa-operations-meet-growing-demand-north-america">
    <div>
      <div>
        <span>Tuesday, February 14th 2017</span>
      </div>

      <h3>Platform.sh expands its US operations</h3>
      <p>Platform.sh opens its US headquarters in San Francisco, forms a US Advisory board, and launches strong North America recruitment to meet growing demand.</p>
    </div>
  </a>

  <a href="/posts/unknown/multi-mysql">
    <div>
      <div>
        <span>Friday, February 10th 2017</span>
      </div>

      <h3>Multiple MySQLs Make Platform.sh a Multisite Machine</h3>
      <p>Learn how Platform.sh now supports multiple databases in MySQL and restricted user access. Optimize your projects with flexible database configurations.</p>
    </div>
  </a>

  <a href="/posts/unknown/platformsh-at-the-oop-conference">
    <div>
      <div>
        <span>Thursday, January 26th 2017</span>
      </div>

      <h3>Platform.sh is down wit' OOP</h3>
      <p>Join us at OOP Conference 2017 in Munich from Jan 30 to Feb 3. Live demos, answers to your PaaS questions, and more at booth 3.14. Don't miss it!</p>
    </div>
  </a>

  <a href="/posts/unknown/persistent-redis">
    <div>
      <div>
        <span>Wednesday, January 25th 2017</span>
      </div>

      <h3>Redis, now for long-term keys and values</h3>
      <p>Discover Platform.sh's Redis Persistent Service, a super-fast key-value database that allows you to store data permanently. Learn how to configure and use it.</p>
    </div>
  </a>

  <a href="/posts/unknown/solr-63">
    <div>
      <div>
        <span>Tuesday, January 17th 2017</span>
      </div>

      <h3>New year, new Solr, new features</h3>
      <p>Platform.sh launches the new Apache Solr version 6.3 with multi-core support, providing better search capabilities for your applications.</p>
    </div>
  </a>

  <a href="/posts/unknown/mongodb_apocalypse">
    <div>
      <div>
        <span>Tuesday, January 10th 2017</span>
      </div>

      <h3>Your instances safe from MongoDB Apocalypse on the Platform.sh PaaS</h3>
      <p>Discover why your MongoDB instances are safe on Platform.sh. Our secure architecture keeps your data protected. Join us for peace of mind!</p>
    </div>
  </a>

  <a href="/posts/unknown/the-year-we-won-php">
    <div>
      <div>
        <span>Monday, January 9th 2017</span>
      </div>

      <h3>2016, The Year We Won PHP</h3>
      <p>Why Platform.sh is the preferred choice for hosting PHP applications. From Drupal and Symfony to Magento and more, we're here to make it run seamlessly.</p>
    </div>
  </a>

  <a href="/posts/unknown/http2">
    <div>
      <div>
        <span>Sunday, January 8th 2017</span>
      </div>

      <h3>Announcing HTTP/2 support!</h3>
      <p>Experience blazing-fast website loading times in 2017 with HTTP/2 support on all Platform.sh regions. No setup required; it's already active!</p>
    </div>
  </a>

  <a href="/posts/unknown/php-71">
    <div>
      <div>
        <span>Thursday, December 29th 2016</span>
      </div>

      <h3>Next Wave PHP now supported</h3>
      <p>Discover the latest PHP 7.1 features, async support, and PThreads support on Platform.sh. Upgrade your PHP version for improved speed and new features.</p>
    </div>
  </a>

  <a href="/posts/unknown/what-is-your-timezone">
    <div>
      <div>
        <span>Tuesday, December 27th 2016</span>
      </div>

      <h3>What's your timezone?</h3>
      <p>Discover how Platform.sh, a fully distributed company, manages its global team and communication using Node.js and self-hosted timezone.io.</p>
    </div>
  </a>

  <a href="/posts/unknown/production-artifact">
    <div>
      <div>
        <span>Friday, December 23rd 2016</span>
      </div>

      <h3>Production is an artifact of development</h3>
      <p>Explore the concept that production is an artifact of development and how Platform.sh revolutionizes web hosting for modern web applications.</p>
    </div>
  </a>

  <a href="/posts/unknown/project-variables">
    <div>
      <div>
        <span>Tuesday, December 20th 2016</span>
      </div>

      <h3>This week in new features - Build-time variables</h3>
      <p>Discover the benefits of project-level variables available at build time on Platform.sh and explore their use cases, including private composer repositories.</p>
    </div>
  </a>

  <a href="/posts/unknown/screencast-yaml">
    <div>
      <div>
        <span>Monday, December 19th 2016</span>
      </div>

      <h3>Screencast - Configuring your Platform.sh Project</h3>
      <p>Learn to set up your project on Platform.sh, manage dependencies with infrastructure as code, and gain independence in this quick technical screencast.</p>
    </div>
  </a>

  <a href="/posts/unknown/leader-php-hosting-multiple-partnerships">
    <div>
      <div>
        <span>Thursday, December 15th 2016</span>
      </div>

      <h3>Platform.sh at the forefront of PHP hosting in 2016</h3>
      <p>Platform.sh is the go-to PaaS for major PHP vendors like Magento, eZ Systems, TYPO3, and Sensio Labs. Get maximum scalability, stability, and performance.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/repeatable-deployments">
    <div>
      <div>
        <span>Tuesday, December 13th 2016</span>
      </div>

      <h3>How repeatable deployments work</h3>
      <p>Platform.sh ensures predictable, repeatable deployments by controlling the key inputs to your application and guaranteeing code consistency.</p>
    </div>
  </a>

  <a href="/posts/unknown/app-updates-php">
    <div>
      <div>
        <span>Friday, December 9th 2016</span>
      </div>

      <h3>Application updates for PHP containers</h3>
      <p>Discover the latest improvements for PHP containers on Platform.sh. Learn about environment configuration, starting processes, and log file changes.</p>
    </div>
  </a>

  <a href="/posts/unknown/screencast-basic-platformsh-workflow">
    <div>
      <div>
        <span>Monday, December 5th 2016</span>
      </div>

      <h3>Screencast - Basic Platform.sh Workflow</h3>
      <p>Discover how Platform.sh makes Git branching and merging easier. Streamline your development process in this Platform.sh from Scratch series.</p>
    </div>
  </a>

  <a href="/posts/unknown/a-cloud-for-symfony">
    <div>
      <div>
        <span>Friday, December 2nd 2016</span>
      </div>

      <h3>A Cloud for Symfony</h3>
      <p>Discover SensioCloud, the new comprehensive cloud offering for Symfony applications. Managed services, optimized runtimes, and scalability.</p>
    </div>
  </a>

  <a href="/posts/unknown/typo3-8-starting-platformsh-cloud">
    <div>
      <div>
        <span>Thursday, October 27th 2016</span>
      </div>

      <h3>TYPO3 CMS 8 starting today with Platform.sh in the cloud</h3>
      <p>Try TYPO3 CMS 8 on Platform.sh with Microsoft Azure in Germany. Scale your projects, enjoy developer-friendly features, and ensure data protection.</p>
    </div>
  </a>

  <a href="/posts/unknown/do-more-with-less">
    <div>
      <div>
        <span>Monday, October 17th 2016</span>
      </div>

      <h3>Cut your digital budget by 30% by doing less work</h3>
      <p>Discover how Platform.sh can help you simplify digital, reduce costs, and increase efficiency with faster development and deployment processes.</p>
    </div>
  </a>

  <a href="/posts/unknown/typo3-platformsh-cloud-integration">
    <div>
      <div>
        <span>Thursday, October 13th 2016</span>
      </div>

      <h3>TYPO3 and Platform.sh announce cloud readiness and tech preview of strategic integration</h3>
      <p>Test TYPO3 on Platform.sh cloud hosting. Discover the benefits of this partnership with continuous delivery hosting. Ideal for Composer-based applications.</p>
    </div>
  </a>

  <a href="/posts/unknown/vc-ready-funding-survey">
    <div>
      <div>
        <span>Tuesday, October 4th 2016</span>
      </div>

      <h3>Three trends that make successful tech startups attractive to VCs</h3>
      <p>Explore best practices for software development and team management in today's startup landscape. Learn how to build attractive software for VC funding.</p>
    </div>
  </a>

  <a href="/posts/releases/python-ruby-support">
    <div>
      <div>
        <span>Friday, September 23rd 2016</span>
      </div>

      <h3>Continuous Deployment - Now with Python and Ruby support!</h3>
      <p>Platform.sh now offers continuous deployment for Ruby and Python developers. Explore the benefits of continuous deployment for your projects in these languages.</p>
    </div>
  </a>

  <a href="/posts/unknown/documentation-tng">
    <div>
      <div>
        <span>Wednesday, September 21st 2016</span>
      </div>

      <h3>Platform.sh Documentation - The Next Generation</h3>
      <p>Explore our redesigned documentation to discover the full potential of Platform.sh for your development needs.</p>
    </div>
  </a>

  <a href="/posts/unknown/ez-systems-partnership">
    <div>
      <div>
        <span>Monday, September 19th 2016</span>
      </div>

      <h3>We partnered with eZ Systems to accelerate development</h3>
      <p>eZ Systems and Platform.sh partner to accelerate development with eZ Platform, offering an accelerated path to build content-rich websites and applications.</p>
    </div>
  </a>

  <a href="/posts/releases/github-blackfire-platformsh">
    <div>
      <div>
        <span>Tuesday, August 30th 2016</span>
      </div>

      <h3>Develop on GitHub, Deploy on Platform.sh, Test on Blackfire.io</h3>
      <p>Learn how to easily integrate GitHub, Blackfire, and Platform.sh for streamlined code management, deployment, and performance testing.</p>
    </div>
  </a>

  <a href="/posts/unknown/gitflow-is-now-supported">
    <div>
      <div>
        <span>Wednesday, August 24th 2016</span>
      </div>

      <h3>GitFlow is now supported on Platform.sh!</h3>
      <p>Learn about our recent infrastructure update with bug fixes and GitFlow branch name support. Enjoy the new features on Platform.sh!</p>
    </div>
  </a>

  <a href="/posts/unknown/release-ui-2-13">
    <div>
      <div>
        <span>Tuesday, August 23rd 2016</span>
      </div>

      <h3>UI version 2.13 released</h3>
      <p>Announcing Platform.sh UI version 2.13 with new enhancements, error notifications, SSH key alerts, and better environment handling. Stay informed and organized. Try it now!</p>
    </div>
  </a>

  <a href="/posts/unknown/httpoxy">
    <div>
      <div>
        <span>Wednesday, July 20th 2016</span>
      </div>

      <h3>Httpoxy or how Platform.sh keeps your applications safe</h3>
      <p>Ensure your applications' security! We've fixed the Httpoxy vulnerability in every Platform.sh region, so you're safe without any redeployments.</p>
    </div>
  </a>

  <a href="/posts/unknown/release-ui-2-12">
    <div>
      <div>
        <span>Monday, July 18th 2016</span>
      </div>

      <h3>UI version 2.12 released</h3>
      <p>Announcing Platform.sh UI version 2.12 with enhancements for easier setup, domain validation, SSH keys, environment management, and user administration. Explore now!</p>
    </div>
  </a>

  <a href="/posts/unknown/release-ui-2-11">
    <div>
      <div>
        <span>Tuesday, July 5th 2016</span>
      </div>

      <h3>UI version 2.11 released</h3>
      <p>Announcing Platform.sh UI version 2.11 with new warning notifications, environment grouping, autofocus on text inputs, and improved display of environment variables.</p>
    </div>
  </a>

  <a href="/posts/unknown/new-features-june">
    <div>
      <div>
        <span>Thursday, June 30th 2016</span>
      </div>

      <h3>June Features Update</h3>
      <p>The latest updates and improvements from Platform.sh. From web interface enhancements to CLI improvements and Drupal 8 with Composer updates.</p>
    </div>
  </a>

  <a href="/posts/unknown/is-thecloud-really-someone-elses-computer">
    <div>
      <div>
        <span>Monday, June 27th 2016</span>
      </div>

      <h3>Is the Cloud really someone else's computer?</h3>
      <p>Difference between "the Cloud" and cloud computing. The benefits and drawbacks of both concepts, and how Platform.sh offers a unique approach to hosting.</p>
    </div>
  </a>

  <a href="/posts/unknown/cloud-adoption-europe-data-privacy">
    <div>
      <div>
        <span>Tuesday, June 21st 2016</span>
      </div>

      <h3>Cloud adoption in Europe: Addressing data privacy concerns</h3>
      <p>Discover the advantages of cloud services and data privacy considerations for European enterprises, including Platform.sh's partnership with Microsoft Azure.</p>
    </div>
  </a>

  <a href="/posts/unknown/marketing-manager-paris">
    <div>
      <div>
        <span>Friday, June 10th 2016</span>
      </div>

      <h3>Looking for our new marketing manager! Are you the one?</h3>
      <p>Exciting opportunity to join the award-winning Platform.sh marketing team. Grow your career with a groundbreaking hosting and development tool.</p>
    </div>
  </a>

  <a href="/posts/unknown/drupal-8-starter-kit-now-with-php-7-and-composer">
    <div>
      <div>
        <span>Tuesday, June 7th 2016</span>
      </div>

      <h3>Drupal 8 starter kit now with PHP 7 and Composer!</h3>
      <p>Discover how Drupal 8.1 embraces Composer and PHP 7 on Platform.sh. Learn what changes and how it benefits your Drupal projects.</p>
    </div>
  </a>

  <a href="/posts/unknown/release-ui-2-10">
    <div>
      <div>
        <span>Tuesday, June 7th 2016</span>
      </div>

      <h3>UI version 2.10 released</h3>
      <p>Announcing Platform.sh UI version 2.10 with accessibility improvements, better messages, and enhanced log display in the activity stream.</p>
    </div>
  </a>

  <a href="/posts/unknown/microsoft-joint-paas-offering">
    <div>
      <div>
        <span>Thursday, June 2nd 2016</span>
      </div>

      <h3>Microsoft and Platform.sh announce joint PaaS offering for High Availability (HA) hosting</h3>
      <p>Platform.sh announces plans for scalable web apps in German datacenters, offering 99.99% uptime, and Azure integration. Learn more today!</p>
    </div>
  </a>

  <a href="/posts/unknown/isv-saas-iaas-providers">
    <div>
      <div>
        <span>Wednesday, May 25th 2016</span>
      </div>

      <h3>Software vendor, SaaS or IaaS - doesn’t matter which. Platform.sh really is the killer app for you!</h3>
      <p>Discover how Platform.sh is revolutionizing SaaS, software vendors, and hosting providers by offering innovative solutions in the cloud computing space.</p>
    </div>
  </a>

  <a href="/posts/unknown/drupalcon-nola-survival-guide">
    <div>
      <div>
        <span>Thursday, May 5th 2016</span>
      </div>

      <h3>DrupalCon New Orleans Survival Guide</h3>
      <p>Attending DrupalCon New Orleans? Learn tips for making the most of your experience, from networking to sessions and sprints, with Platform.sh.</p>
    </div>
  </a>

  <a href="/posts/unknown/larry-garfield-joins-platformsh">
    <div>
      <div>
        <span>Monday, May 2nd 2016</span>
      </div>

      <h3>The one and only Director of Runtimes and Integrations</h3>
      <p>Meet Larry Garfield, our new Director of Runtimes, Integrations, and Services. Discover why he's a perfect fit for Platform.sh and connect with him on Twitter.</p>
    </div>
  </a>

  <a href="/posts/unknown/magento-enterprise-cloud-edition-powered-by-platform-sh">
    <div>
      <div>
        <span>Tuesday, April 12th 2016</span>
      </div>

      <h3>Platform.sh Provides PaaS Technology to Magento Commerce</h3>
      <p>Discover how Magento Commerce benefits from Platform.sh's second-generation PaaS for its Enterprise Cloud Edition, enhancing development and release management.</p>
    </div>
  </a>

  <a href="/posts/unknown/deploy-to-the-moon">
    <div>
      <div>
        <span>Friday, April 1st 2016</span>
      </div>

      <h3>Platform.sh announces world’s first LDN for web applications</h3>
      <p>Platform.sh achieves the extraordinary by deploying PHP apps on the lunar surface. Experience the world's first Lunar Delivery Network (LDN).</p>
    </div>
  </a>

  <a href="/posts/unknown/release-cli-3-0">
    <div>
      <div>
        <span>Tuesday, March 22nd 2016</span>
      </div>

      <h3>CLI version 3.0 released</h3>
      <p>Announcing Platform.sh CLI version 3.0 with major changes: new file structure, web root location, and PHP requirement. Upgrade now!</p>
    </div>
  </a>

  <a href="/posts/unknown/platform.sh-independent-company">
    <div>
      <div>
        <span>Tuesday, February 9th 2016</span>
      </div>

      <h3>Platform.sh becomes an independent company</h3>
      <p>Exciting news from Platform.sh! We're now an independent company, with a renewed focus on our cloud hosting solution. Read about our journey and plans.</p>
    </div>
  </a>

  <a href="/posts/unknown/php-session-bug">
    <div>
      <div>
        <span>Thursday, December 17th 2015</span>
      </div>

      <h3>All Platform.sh clients kept automatically safe from serious PHP bug</h3>
      <p>PHP session extension bug and how Platform.sh has automatically updated sites to prevent vulnerability. No action required for our customers.</p>
    </div>
  </a>

  <a href="/posts/unknown/drupal-8-release-party">
    <div>
      <div>
        <span>Thursday, November 19th 2015</span>
      </div>

      <h3>Drupal 8.0 has been released... Party time!</h3>
      <p>Join the global Drupal 8 release celebration! Learn more about Drupal 8 parties and deploy it today on Platform.sh for a free trial.</p>
    </div>
  </a>

  <a href="/posts/unknown/safe-harbour-safe">
    <div>
      <div>
        <span>Tuesday, November 3rd 2015</span>
      </div>

      <h3>Concerned about the recent European Court ruling on Safe Harbor?</h3>
      <p>Discover the consequences of the EU-US Safe Harbor agreement invalidation and how Platform.sh offers flexibility to protect your data as needed.</p>
    </div>
  </a>

  <a href="/posts/unknown/badcamp">
    <div>
      <div>
        <span>Tuesday, October 20th 2015</span>
      </div>

      <h3>Platform.sh to exhibit at BADCamp 2015</h3>
      <p>Platform.sh, a Contrib Level sponsor, will be at BADCamp 2015. Visit our booth for demos and learn about web application hosting.</p>
    </div>
  </a>

  <a href="/posts/unknown/best-horizontal-cloud-solution-for-2015-in-europe">
    <div>
      <div>
        <span>Friday, October 9th 2015</span>
      </div>

      <h3>Platform.sh Best Horizontal Cloud Solution for 2015 in Europe</h3>
      <p>Platform.sh awarded Best Horizontal Cloud Solution in Europe by Eurocloud. Find out more.</p>
    </div>
  </a>

  <a href="/posts/unknown/release-hhvm">
    <div>
      <div>
        <span>Wednesday, September 23rd 2015</span>
      </div>

      <h3>HHVM versions 3.9 and 3.12 supported</h3>
      <p>Announcing HHVM support on Platform.sh. HHVM offers improved PHP performance and scalability. Learn how to use and configure it in our documentation.</p>
    </div>
  </a>

  <a href="/posts/unknown/symfony-documentation-pull-requests">
    <div>
      <div>
        <span>Thursday, September 10th 2015</span>
      </div>

      <h3>Platform.sh hosts Symfony documentation GitHub pull requests</h3>
      <p>Symfony's documentation now uses Platform.sh for automatic code deployment into isolated environments, simplifying review and testing.</p>
    </div>
  </a>

  <a href="/posts/unknown/featured-on-bitbucket">
    <div>
      <div>
        <span>Monday, August 17th 2015</span>
      </div>

      <h3>Platform.sh / Bitbucket Integration, featured on the Bitbucket Blog</h3>
      <p>Discover the Bitbucket integration with Platform.sh. Learn how it works in this short screencast. Get the details on the Bitbucket Blog.</p>
    </div>
  </a>

  <a href="/posts/unknown/platform-sh-hiring-interns">
    <div>
      <div>
        <span>Monday, August 10th 2015</span>
      </div>

      <h3>Hiring interns</h3>
      <p>Explore cloud engineering internships at Platform.sh. Gain hands-on experience with high availability cloud infrastructure and cutting-edge technologies.</p>
    </div>
  </a>

  <a href="/posts/unknown/work-with-distribution">
    <div>
      <div>
        <span>Tuesday, July 28th 2015</span>
      </div>

      <h3>The correct way to work with Drupal distributions</h3>
      <p>Learn how to easily build and maintain your Drupal site on top of distributions using Platform.sh's support for Drush Make files.</p>
    </div>
  </a>

  <a href="/posts/unknown/release-docs-3-0">
    <div>
      <div>
        <span>Saturday, July 25th 2015</span>
      </div>

      <h3>Documentation version 3.0 released</h3>
      <p>Announcing Platform.sh documentation version 3.0 with improved guides and easier contributions. Explore the new documentation now!</p>
    </div>
  </a>

  <a href="/posts/unknown/five-platform-sh-the-paas-for-drupal-8">
    <div>
      <div>
        <span>Thursday, July 16th 2015</span>
      </div>

      <h3>Five reasons why Platform.sh is the PaaS you need for Drupal 8</h3>
      <p>Discover why Drupal 8 on Platform.sh is making waves. From Swiss publishers to usability testing, explore the Drupal 8 hype. Get ready for the future!</p>
    </div>
  </a>

  <a href="/posts/unknown/best-horizontal-cloud-platform-eurocloud">
    <div>
      <div>
        <span>Friday, July 10th 2015</span>
      </div>

      <h3>Platform.sh elected Best Horizontal Cloud Platform of the year</h3>
      <p>Platform.sh wins Best Cloud Services for horizontal markets at CLOUD WEEK Paris. Discover how Platform.sh empowers marketing teams for agile web development.</p>
    </div>
  </a>

  <a href="/posts/unknown/ceo-interviewed-on-bfm-business">
    <div>
      <div>
        <span>Wednesday, July 8th 2015</span>
      </div>

      <h3>CEO of Commerce Guys is interviewed by the main French Business TV Channel about Platform.sh</h3>
      <p>Fred Plais, Platform.sh CEO, discusses Platform.sh's innovation and European Grant on French business TV channel interview.</p>
    </div>
  </a>

  <a href="/posts/unknown/european-horizon-2020-grant">
    <div>
      <div>
        <span>Thursday, June 25th 2015</span>
      </div>

      <h3>Platform.sh awarded a €1.95M grant</h3>
      <p>PaaS leader Platform.sh receives EU innovation grant. Explore their ambitious roadmap for multi-cloud, distributed storage, and more.</p>
    </div>
  </a>

  <a href="/posts/unknown/2015-06-european-cloud-leadership-born-in-france">
    <div>
      <div>
        <span>Tuesday, June 23rd 2015</span>
      </div>

      <h3>European cloud leadership is being born before our very own eyes in France</h3>
      <p>Discover how Platform.sh achieved success following Commerce Guys with 250+ customers worldwide.</p>
    </div>
  </a>

  <a href="/posts/unknown/release-ui-2-0">
    <div>
      <div>
        <span>Wednesday, May 27th 2015</span>
      </div>

      <h3>UI version 2.0 released</h3>
      <p>Announcing Platform.sh UI version 2.0 with new features: environment status, access control, SSH key upload, SSL certificate management, and more.</p>
    </div>
  </a>

  <a href="/posts/unknown/groundbreaking-drupal-8-news-portal-goes-live-platformsh">
    <div>
      <div>
        <span>Wednesday, May 13th 2015</span>
      </div>

      <h3>Groundbreaking Drupal 8 news portal goes live on Platform.sh</h3>
      <p>Platform.sh, PaaS leader, is hosting one of the first Enterprise production sites on Drupal 8. Platform.sh enhances development workflows.</p>
    </div>
  </a>

  <a href="/posts/unknown/platformsh-cli-developments-1-10">
    <div>
      <div>
        <span>Monday, March 16th 2015</span>
      </div>

      <h3>Platform.sh CLI developments</h3>
      <p>Explore the latest updates and features in the Platform.sh CLI, the powerful tool for web developers. Manage your projects with ease. Install or upgrade now!</p>
    </div>
  </a>

  <a href="/posts/how-it-works/how-platform-paas-works">
    <div>
      <div>
        <span>Tuesday, March 3rd 2015</span>
      </div>

      <h3>How the Platform.sh PaaS works</h3>
      <p>Discover how Platform.sh simplifies PaaS. Focus on your code; we manage the rest. Explore our second-generation PaaS for seamless application development.</p>
    </div>
  </a>

  <a href="/posts/discussions/containers-are-the-new-static-binaries">
    <div>
      <div>
        <span>Thursday, February 26th 2015</span>
      </div>

      <h3>Containers are the new static binaries</h3>
      <p>Platform.sh updates: new languages, MariaDB, and PHP 7.2-alpha support. Stay informed and enjoy your containers.</p>
    </div>
  </a>

  <a href="/posts/unknown/blackfire-integration">
    <div>
      <div>
        <span>Monday, February 2nd 2015</span>
      </div>

      <h3>Support for Blackfire Profiler</h3>
      <p>Optimize performance with Blackfire Profiler on Platform.sh. Monitor server resources, identify bottlenecks, and compare codebases for better performance.</p>
    </div>
  </a>

  <a href="/posts/unknown/release-ui-1-10">
    <div>
      <div>
        <span>Monday, January 26th 2015</span>
      </div>

      <h3>UI version 1.10 released</h3>
      <p>Announcing Platform.sh UI version 1.10 with easy SSH key upload and snapshot restoration. Enhance your Platform.sh experience. Explore the new features now!</p>
    </div>
  </a>

  <a href="/posts/unknown/release-cli-1-7">
    <div>
      <div>
        <span>Tuesday, January 20th 2015</span>
      </div>

      <h3>CLI version 1.7 released</h3>
      <p>Announcing Platform.sh CLI version 1.7.1 with new features, improved commands, and enhanced HTTP access control. Install or upgrade using Composer!</p>
    </div>
  </a>

  <a href="/posts/unknown/git-clients-vulnerable">
    <div>
      <div>
        <span>Friday, December 19th 2014</span>
      </div>

      <h3>Git clients vulnerable</h3>
      <p>Learn about the Git vulnerability affecting Mac OS X and Windows users. Find out how Platform.sh customers can protect their Git clients.</p>
    </div>
  </a>

  <a href="/posts/unknown/release-ui-1-9">
    <div>
      <div>
        <span>Wednesday, December 3rd 2014</span>
      </div>

      <h3>UI version 1.9 released</h3>
      <p>Announcing Platform.sh UI version 1.9 with quick environment access, easy Git and SSH command copying, and unified configuration screens.</p>
    </div>
  </a>

  <a href="/posts/unknown/us-platform-adoption">
    <div>
      <div>
        <span>Wednesday, November 5th 2014</span>
      </div>

      <h3>Leading digital agencies adopt Platform.sh to support Continuous Delivery</h3>
      <p>Discover the benefits of Platform.sh for hosting Drupal and Symfony web applications. Streamline development, reduce costs, and improve deployment.</p>
    </div>
  </a>

  <a href="/posts/unknown/release-cli-1-2">
    <div>
      <div>
        <span>Wednesday, October 29th 2014</span>
      </div>

      <h3>CLI version 1.2 released</h3>
      <p>Announcing Platform.sh CLI version 1.2.2 with new features, colorful interface, safer commands, and more. Install or upgrade using Composer now!</p>
    </div>
  </a>

  <a href="/posts/unknown/1000-tickets-strong">
    <div>
      <div>
        <span>Wednesday, October 22nd 2014</span>
      </div>

      <h3>1000 tickets strong</h3>
      <p>Join us in recognizing the milestone of 1,000 support tickets, showcasing rapid responses, high satisfaction, and efficient issue resolution.</p>
    </div>
  </a>

  <a href="/posts/unknown/protecting-your-apps">
    <div>
      <div>
        <span>Tuesday, October 21st 2014</span>
      </div>

      <h3>Protecting your apps</h3>
      <p>Platform.sh launched automated blocking for critical vulnerabilities (incl. Drupal SQL Injection) and seeks collaborators for an open-source signature database</p>
    </div>
  </a>

  <a href="/posts/unknown/sa-core-2014-005">
    <div>
      <div>
        <span>Wednesday, October 15th 2014</span>
      </div>

      <h3>Platform.sh and Drupal 7.32 Core SQL Injection</h3>
      <p>Learn about the Drupal 7.32 security update and the steps taken by Platform.sh to protect your Drupal website from a severe SQL injection vulnerability.</p>
    </div>
  </a>

  <a href="/posts/unknown/wunderkraut-chooses-platform">
    <div>
      <div>
        <span>Tuesday, September 30th 2014</span>
      </div>

      <h3>Wunderkraut adopts Platform.sh for all of its 14 international offices</h3>
      <p>Wunderkraut announces their partnership for adopting Platform.sh in all 14 international offices, enhancing cloud hosting and development.</p>
    </div>
  </a>

  <a href="/posts/unknown/platform-removes-developer-overhead-6">
    <div>
      <div>
        <span>Tuesday, September 23rd 2014</span>
      </div>

      <h3>FlixBus launches new eCommerce Service on Platform.sh Enterprise</h3>
      <p>sh is a one-stop solution offering a new paradigm in collaborative web development and live hosting London, U.</p>
    </div>
  </a>

  <a href="/posts/unknown/release-cli-1-1">
    <div>
      <div>
        <span>Tuesday, September 9th 2014</span>
      </div>

      <h3>CLI version 1.1 released</h3>
      <p>Platform.sh CLI version 1.1.0 is out with new features and commands. Upgrade now! Learn more on GitHub.</p>
    </div>
  </a>

  <a href="/posts/unknown/platform-removes-developer-overhead">
    <div>
      <div>
        <span>Thursday, July 31st 2014</span>
      </div>

      <h3>How the Platform.sh PaaS removes developer overhead</h3>
      <p>Platform.sh is a PaaS designed to bring continuous delivery to Drupal. Explore its features and CLI for agile Drupal development.</p>
    </div>
  </a>

  <a href="/posts/unknown/commerce-guys-launches-platform">
    <div>
      <div>
        <span>Tuesday, May 13th 2014</span>
      </div>

      <h3>Commerce Guys Launches Platform.sh, Continuous Delivery Cloud on Amazon Web Services</h3>
      <p>Discover Platform.sh, a revolutionary cloud hosting solution for Drupal, Symfony, and PHP-based applications. Achieve up to 25% savings on developer effort.</p>
    </div>
  </a>
</ShowMore>


# Insights
Source: https://developer.upsun.com/posts/articles/insights



<ShowMore>
  <a href="/posts/insights/session-storage-gets-complicated-faster-than-you-think">
    <div>
      <div>
        <span>Wednesday, September 30th 2026</span>
      </div>

      <h3>Session storage gets complicated faster than you think</h3>
      <p>Explore session storage tradeoffs across files, PostgreSQL, Redis, and Valkey, from expiration and cleanup to memory limits. Test your options on Upsun Cloud.</p>
    </div>
  </a>

  <a href="/posts/ai/prompts-are-the-new-legacy-code">
    <div>
      <div>
        <span>Thursday, September 10th 2026</span>
      </div>

      <h3>Prompts are the new legacy code</h3>
      <p>Dispatch's code review agent lost 80% of its prompt and four sub-agents. Same model, same quality, cost more than halved, 25% faster. Here's the method.</p>
    </div>
  </a>

  <a href="/posts/insights/which-stack-would-you-pick-for-an-interactive-ai-app-today">
    <div>
      <div>
        <span>Friday, July 31st 2026</span>
      </div>

      <h3>Which stack would you pick for an interactive AI app today?</h3>
      <p>Coding agents changed how new teams pick a tech stack. A tour of 8 ecosystems for interactive AI apps, and why "can we run it" beats "can we write it".</p>
    </div>
  </a>

  <a href="/posts/insights/why-emacs-is-still-my-interface-to-my-computer">
    <div>
      <div>
        <span>Tuesday, June 30th 2026</span>
      </div>

      <h3>Why Emacs is still my interface to my computer</h3>
      <p>Why I still use Emacs every day: one consistent interface for editing, Git with Magit, terminals, a Claude Code agent per project, and the rest of my computer.</p>
    </div>
  </a>

  <a href="/posts/insights/code-matters-less-than-ever-and-more-than-ever">
    <div>
      <div>
        <span>Tuesday, June 9th 2026</span>
      </div>

      <h3>Code matters less than ever, and more than ever</h3>
      <p>AI made code cheap to write and cheap to throw away, so it matters less than ever. It also matters more, because debugging, reviews, and velocity all depend on it.</p>
    </div>
  </a>

  <a href="/posts/insights/ddev-is-in-good-hands">
    <div>
      <div>
        <span>Thursday, May 21st 2026</span>
      </div>

      <h3>DDEV is in good hands</h3>
      <p>DDEV is alive, actively maintained, and back with its foundation. A look at our chapter in the project, why we got involved, and why we are happy to step out of the way.</p>
    </div>
  </a>

  <a href="/posts/insights/rate-limiting-rails-apps-when-you-cant-put-varnish-in-front">
    <div>
      <div>
        <span>Tuesday, May 12th 2026</span>
      </div>

      <h3>Rate limiting Rails apps when you can't put Varnish in front</h3>
      <p>When the edge isn't yours, rate limit from inside the application. How rack-attack works, why limits are about quality of service, and what Rails 8 changed.</p>
    </div>
  </a>

  <a href="/posts/insights/the-not-so-hidden-cost-of-ai-scrapers">
    <div>
      <div>
        <span>Tuesday, May 5th 2026</span>
      </div>

      <h3>The (not so) hidden cost of AI scrapers</h3>
      <p>AI scrapers drive up your hosting cost while real users wait. Use robots.txt, cache normalization, and sane application limits to take the pressure off.</p>
    </div>
  </a>

  <a href="/posts/insights/the-only-correct-way-to-git-pull-and-merge">
    <div>
      <div>
        <span>Tuesday, February 3rd 2026</span>
      </div>

      <h3>The only correct way to git pull and merge</h3>
      <p>A strongly opinionated guide to git pull and merge strategies that will make your commit history actually useful. Learn when to rebase, when to merge, and why the defaults are lying to you.</p>
    </div>
  </a>

  <a href="/posts/insights/the-third-way-to-scale-that-nobody-talks-about">
    <div>
      <div>
        <span>Tuesday, January 20th 2026</span>
      </div>

      <h3>The third way to scale that nobody talks about</h3>
      <p>Beyond vertical and horizontal scaling lies a third approach that most scaling discussions ignore. Learn about natural scaling, where you sidestep the problem entirely.</p>
    </div>
  </a>

  <a href="/posts/insights/why-you-cant-just-add-infinite-php-fpm-workers">
    <div>
      <div>
        <span>Monday, December 8th 2025</span>
      </div>

      <h3>Why you can't just add infinite PHP-FPM workers</h3>
      <p>Workers need memory. Learn how PHP-FPM sizing hints work, why you can't just add infinite workers, and how to tune your worker count based on actual memory usage.</p>
    </div>
  </a>

  <a href="/posts/insights/why-setting-your-php-memory-limit-to-60gb-wont-help">
    <div>
      <div>
        <span>Monday, December 1st 2025</span>
      </div>

      <h3>Why setting your PHP memory limit to 60GB won't help</h3>
      <p>When you see a PHP memory limit error, your instinct shouldn't be to just increase the limit. Learn what PHP memory\_limit actually does and why blindly increasing it can hurt your site's uptime.</p>
    </div>
  </a>

  <a href="/posts/insights/my-terminal-setup-mac-linux">
    <div>
      <div>
        <span>Wednesday, November 26th 2025</span>
      </div>

      <h3>My terminal setup (Mac & Linux)</h3>
      <p>A no-nonsense guide to transforming your terminal from painful to powerful with GhostTTY, NeoVim, and Claude Code</p>
    </div>
  </a>

  <a href="/posts/insights/the-mystery-of-the-shrinking-database-dump">
    <div>
      <div>
        <span>Monday, November 10th 2025</span>
      </div>

      <h3>The mystery of the shrinking database dump</h3>
      <p>Your database uses 10GB but dumps to 100MB. Discover why database dumps shrink, how InnoDB fragmentation works, and how to reclaim that missing storage space.</p>
    </div>
  </a>

  <a href="/posts/insights/build-time-environment-variables-considered-harmful">
    <div>
      <div>
        <span>Monday, October 6th 2025</span>
      </div>

      <h3>Build-time environment variables considered harmful</h3>
      <p>Build-time environment variables break deployment caching, compromise security, and force unnecessary rebuilds. Learn why runtime configuration is the better alternative.</p>
    </div>
  </a>

  <a href="/posts/insights/why-you-should-replace-postgresql-with-git-for-your-next-project">
    <div>
      <div>
        <span>Friday, September 19th 2025</span>
      </div>

      <h3>Why you should replace PostgreSQL with Git for your next project</h3>
      <p>Explore how Git's internal architecture makes it a surprisingly capable database alternative. Learn Git's data structures through a practical todo app implementation that might make you reconsider your database choices.</p>
    </div>
  </a>

  <a href="/posts/insights/why-your-readme-matters-more-than-ai-configuration-files">
    <div>
      <div>
        <span>Tuesday, August 12th 2025</span>
      </div>

      <h3>AGENTS.md: Why your README matters more than AI configuration files</h3>
      <p>AGENTS.md promises to standardize AI coding assistant configuration, but the real solution is writing better READMEs that serve both humans and AI agents</p>
    </div>
  </a>

  <a href="/posts/insights/why-python-developers-should-switch-to-uv">
    <div>
      <div>
        <span>Thursday, August 7th 2025</span>
      </div>

      <h3>Why Python developers should switch to uv</h3>
      <p>Learn how uv, the revolutionary Python package manager, delivers 100x faster installations and streamlines project management with automatic virtual environments and dependency tracking.</p>
    </div>
  </a>

  <a href="/posts/insights/why-configuration-as-code-beats-click-and-deploy">
    <div>
      <div>
        <span>Thursday, June 12th 2025</span>
      </div>

      <h3>Git-Driven Infrastructure: Why Configuration as Code Beats Click-and-Deploy</h3>
      <p>Discover why YAML-driven infrastructure outperforms point-and-click deployment for scalable, maintainable applications. Learn best practices for configuration as code.</p>
    </div>
  </a>

  <a href="/posts/insights/advanced-prompting-techniques-for-coding">
    <div>
      <div>
        <span>Thursday, May 8th 2025</span>
      </div>

      <h3>Advanced prompting techniques for complex coding tasks</h3>
      <p>This articles will give you an overview of prompting strategies that help coding assistants reason through difficult problems and produce higher-quality solutions.</p>
    </div>
  </a>

  <a href="/posts/insights/what-will-you-do-after-you-deploy">
    <div>
      <div>
        <span>Tuesday, April 17th 2018</span>
      </div>

      <h3>What will you do after you deploy?</h3>
      <p>Learn how Platform.sh's post\_deploy hook can keep your site responsive during deploy tasks, making your deploys faster and more efficient.</p>
    </div>
  </a>
</ShowMore>


# Releases
Source: https://developer.upsun.com/posts/articles/releases



<ShowMore>
  <a href="/posts/releases/introducing-developer-upsun-com">
    <div>
      <div>
        <span>Monday, March 16th 2026</span>
      </div>

      <h3>Introducing developer.upsun.com: Upsun docs, rebuilt for developers and AI agents</h3>
      <p>The Upsun documentation has moved to developer.upsun.com with a complete infrastructure rebuild focused on agent-readiness. 244+ pages of structured, machine-readable content with llms.txt support and built-in AI assistance.</p>
    </div>
  </a>

  <a href="/posts/releases/upsun-node-sdk-announcement">
    <div>
      <div>
        <span>Wednesday, February 25th 2026</span>
      </div>

      <h3>Announcing the Official Upsun Node.js SDK</h3>
      <p>Discover how the Upsun Node SDK simplifies API access and speeds up integrations, with clear documentation and modern tooling.</p>
    </div>
  </a>

  <a href="/posts/releases/composer-2.9">
    <div>
      <div>
        <span>Thursday, December 25th 2025</span>
      </div>

      <h3>Composer 2.9 lands on Upsun PHP Images: Here’s what you need to know</h3>
      <p>Remote code execution vulnerability in Next.js 15.x and 16.x App Router requires immediate patching. Learn how to secure your applications.</p>
    </div>
  </a>

  <a href="/posts/releases/composable-image-embraces-real-world-diversity">
    <div>
      <div>
        <span>Thursday, December 11th 2025</span>
      </div>

      <h3>One project, many needs: How Composable Image embraces real-world diversity</h3>
      <p>Applications rarely fit inside a single tidy runtime box. They evolve through experiments, architectural shifts, quick MVP spikes that outlast their intended lifespan, and the continuous layering of new business needs.</p>
    </div>
  </a>

  <a href="/posts/releases/php-85-release">
    <div>
      <div>
        <span>Thursday, November 20th 2025</span>
      </div>

      <h3>PHP 8.5 is here!</h3>
      <p>What if the next PHP revolution made no noise but completely transformed your developer daily life?</p>
    </div>
  </a>

  <a href="/posts/releases/upsun-php-sdk-announcement">
    <div>
      <div>
        <span>Tuesday, November 4th 2025</span>
      </div>

      <h3>Introducing the Upsun PHP SDK</h3>
      <p>Discover how the Upsun PHP SDK simplifies API access and speeds up integrations, with clear documentation and modern tooling.</p>
    </div>
  </a>

  <a href="/posts/releases/redis-release">
    <div>
      <div>
        <span>Wednesday, June 4th 2025</span>
      </div>

      <h3>Redis 8.0 is here</h3>
      <p>We are excited to announce that **Redis 8.0** is now available for all customers.</p>
    </div>
  </a>

  <a href="/posts/releases/file_size_limit">
    <div>
      <div>
        <span>Wednesday, May 7th 2025</span>
      </div>

      <h3>New file size limits explained</h3>
      <p>To ensure the optimal performance, stability, and reliability of our Git infrastructure, we are introducing a limit on the size of individual files that can be pushed to your project repositories.</p>
    </div>
  </a>

  <a href="/posts/releases/vscode-extension">
    <div>
      <div>
        <span>Tuesday, May 6th 2025</span>
      </div>

      <h3>Supercharge your workflow with the Upsun VSCode Extension</h3>
      <p>If you're working on Upsun projects with VSCode, the **Upsun VSCode extension** is an essential tool to enhance your development experience. Learn more...</p>
    </div>
  </a>

  <a href="/posts/releases/valkey-release">
    <div>
      <div>
        <span>Wednesday, April 16th 2025</span>
      </div>

      <h3>Valkey is now available</h3>
      <p>We're excited to announce the availability of [Valkey](https://valkey.io/), a high-performance, open-source key/value database, now offered as a managed service on Upsun. Valkey serves as a drop-in alternative to Redis, particularly relevant following recent licensing changes to the Redis project.</p>
    </div>
  </a>

  <a href="/posts/releases/elixir-118-release-available">
    <div>
      <div>
        <span>Wednesday, February 26th 2025</span>
      </div>

      <h3>Apologies to the Elixir community: 1.18 release now available</h3>
      <p>Elixir 1.18 is now available on Upsun and Platform.sh with type checking, LSP improvements, and built-in JSON support.</p>
    </div>
  </a>

  <a href="/posts/releases/llms-introduction">
    <div>
      <div>
        <span>Friday, February 14th 2025</span>
      </div>

      <h3>Upsun and Platform.sh Docs are now llms.txt compatible!</h3>
      <p>We’re thrilled to announce that both [Upsun Documentation](https://docs.upsun.com) and [Platform.sh Documentation](https://docs.platform.sh) are now fully compatible with [llms.txt proposed standard](https://llmstxt.org/)!</p>
    </div>
  </a>

  <a href="/posts/releases/php-84-release">
    <div>
      <div>
        <span>Tuesday, November 26th 2024</span>
      </div>

      <h3>PHP 8.4 is here!</h3>
      <p>PHP 8.4 was [officially released](https://www.php.net/archive/2024.php#2024-11-21-4) on November 21st, and with it comes a number of improvements and new features that you can - as of today - begin working with on your Upsun and Platform.sh projects.</p>
    </div>
  </a>

  <a href="/posts/releases/continuous-profiling-comparisons">
    <div>
      <div>
        <span>Wednesday, October 23rd 2024</span>
      </div>

      <h3>Continuous profiling comparisons</h3>
      <p>Upsun’s new continuous profiling comparisons feature provides deeper insights into application performance, enabling you to easily contrast performance metrics over time or between code versions.</p>
    </div>
  </a>

  <a href="/posts/releases/context-driven-navigation">
    <div>
      <div>
        <span>Thursday, October 3rd 2024</span>
      </div>

      <h3>Context driven navigation</h3>
      <p>You may have noticed some changes to navigation and user settings on your Platform.sh dashboard.</p>
    </div>
  </a>

  <a href="/posts/releases/introducing-dev-center">
    <div>
      <div>
        <span>Wednesday, September 18th 2024</span>
      </div>

      <h3>Introducing the Upsun Developer Center</h3>
      <p>This month our Developer Relations and Advocacy teams are excited to share with you our latest resource: the Upsun Developer Center.</p>
    </div>
  </a>

  <a href="/posts/releases/bun-support-is-here">
    <div>
      <div>
        <span>Friday, September 8th 2023</span>
      </div>

      <h3>It's out of the Oven: Bun 1.0 support on Platform.sh</h3>
      <p>Bun 1.0 support is now available on Platform.sh. Discover our comparison results against Yarn and how to test Bun 1.0 out for yourself in this article.</p>
    </div>
  </a>

  <a href="/posts/releases/platformsh-is-always-one-step-ahead-announcing-postgresql--python--and-ruby--for-our-users">
    <div>
      <div>
        <span>Monday, January 16th 2023</span>
      </div>

      <h3>Platform.sh is always one step ahead: Announcing PostgreSQL 15, Python 3.11, and Ruby 3.2 for our users</h3>
      <p>Explore the new features and performance improvements in Python 3.11, PostgreSQL 15, and Ruby 3.2. Stay up-to-date with the latest programming languages.</p>
    </div>
  </a>

  <a href="/posts/releases/introducing-a-more-complete-logs-forwarding-experience">
    <div>
      <div>
        <span>Friday, November 4th 2022</span>
      </div>

      <h3>Introducing a more complete logs forwarding experience</h3>
      <p>Streamline monitoring with centralized log forwarding. Platform.sh now supports log forwarding to Sumologic, New Relic Logs, Splunk, and more. Discover how!</p>
    </div>
  </a>

  <a href="/posts/releases/php-80-feature-focus-constructor-property-promotion">
    <div>
      <div>
        <span>Thursday, November 5th 2020</span>
      </div>

      <h3>PHP 8.0 feature focus: Class constructor property promotion</h3>
      <p>Discover how PHP 8.0's Constructor Property Promotion feature can streamline your code, reduce verbosity, and make coding faster. Try it on Platform.sh today!</p>
    </div>
  </a>

  <a href="/posts/releases/php-80-feature-focus-weak-maps">
    <div>
      <div>
        <span>Thursday, October 1st 2020</span>
      </div>

      <h3>PHP 8.0 feature focus: Weak maps</h3>
      <p>Learn how PHP 8.0's Weak Maps simplify memory management by efficiently handling cached objects. Try PHP 8.0 on Platform.sh today!</p>
    </div>
  </a>

  <a href="/posts/releases/deploy-strapi-on-platformsh">
    <div>
      <div>
        <span>Tuesday, March 3rd 2020</span>
      </div>

      <h3>Platform.sh–deploying the future of content with one click</h3>
      <p>Platform.sh and Strapi empower developers with a headless CMS solution for streamlined digital experiences. Deploy Strapi instantly. Learn more</p>
    </div>
  </a>

  <a href="/posts/releases/deploy-with-php-73-this-friday-er-thursday">
    <div>
      <div>
        <span>Thursday, December 6th 2018</span>
      </div>

      <h3>Deploy with PHP 7.3 this Friday, er, Thursday</h3>
      <p>Platform.sh welcomes PHP 7.3! Explore the latest features and performance improvements. Upgrade your application with a simple YAML tweak.</p>
    </div>
  </a>

  <a href="/posts/releases/golang-forth-and-deploy">
    <div>
      <div>
        <span>Monday, October 29th 2018</span>
      </div>

      <h3>Go\[lang] forth and deploy</h3>
      <p>Discover the full support for Go 1.11 on Platform.sh. No more GOPATH required. Easy setup and deployment for Go applications with Go modules and Platform.sh.</p>
    </div>
  </a>

  <a href="/posts/releases/deploy-your-python-37-code-to-the-moon">
    <div>
      <div>
        <span>Wednesday, September 5th 2018</span>
      </div>

      <h3>Deploy your Python 3.7 code to the Moon</h3>
      <p>Platform.sh now supports Python 3.7. Explore the latest features and enhancements. Update your .platform.app.yaml file and enjoy Python 3.7!</p>
    </div>
  </a>

  <a href="/posts/releases/hhvm-deploys-off-into-the-sunset">
    <div>
      <div>
        <span>Tuesday, January 30th 2018</span>
      </div>

      <h3>HHVM deploys off into the sunset</h3>
      <p>Platform.sh will no longer support HHVM runtime after 1 March 2018. Learn about this change and the evolution of PHP alternatives.</p>
    </div>
  </a>

  <a href="/posts/releases/python-ruby-support">
    <div>
      <div>
        <span>Friday, September 23rd 2016</span>
      </div>

      <h3>Continuous Deployment - Now with Python and Ruby support!</h3>
      <p>Platform.sh now offers continuous deployment for Ruby and Python developers. Explore the benefits of continuous deployment for your projects in these languages.</p>
    </div>
  </a>

  <a href="/posts/releases/github-blackfire-platformsh">
    <div>
      <div>
        <span>Tuesday, August 30th 2016</span>
      </div>

      <h3>Develop on GitHub, Deploy on Platform.sh, Test on Blackfire.io</h3>
      <p>Learn how to easily integrate GitHub, Blackfire, and Platform.sh for streamlined code management, deployment, and performance testing.</p>
    </div>
  </a>
</ShowMore>


# Aaron Collier
Source: https://developer.upsun.com/posts/authors/aaron-collier

Articles written by Aaron Collier.

<div>
  <a href="/posts/unknown/go-1-18-released-on-platformsh">
    <div>
      <div>
        <span>Wednesday, March 16th 2022</span>
      </div>

      <h3>Go 1.18 released on Platform.sh</h3>
      <p>Discover the new features in Go 1.18, including support for generics, and learn how to upgrade your Go projects on Platform.sh for enhanced functionality.</p>
    </div>
  </a>
</div>


# Aaron Dudenhofer
Source: https://developer.upsun.com/posts/authors/aaron-dudenhofer

Articles written by Aaron Dudenhofer.

<div>
  <a href="/posts/unknown/release-ui-2-10">
    <div>
      <div>
        <span>Tuesday, June 7th 2016</span>
      </div>

      <h3>UI version 2.10 released</h3>
      <p>Announcing Platform.sh UI version 2.10 with accessibility improvements, better messages, and enhanced log display in the activity stream.</p>
    </div>
  </a>

  <a href="/posts/unknown/release-ui-2-0">
    <div>
      <div>
        <span>Wednesday, May 27th 2015</span>
      </div>

      <h3>UI version 2.0 released</h3>
      <p>Announcing Platform.sh UI version 2.0 with new features: environment status, access control, SSH key upload, SSL certificate management, and more.</p>
    </div>
  </a>
</div>


# Ana Cidre
Source: https://developer.upsun.com/posts/authors/anacidre

Articles written by Ana Cidre.

<div>
  <div>
    <a href="https://www.linkedin.com/in/ana-cidre">LinkedIn</a>
  </div>
</div>

<div>
  <a href="/posts/releases/introducing-developer-upsun-com">
    <div>
      <div>
        <span>Monday, March 16th 2026</span>
      </div>

      <h3>Introducing developer.upsun.com: Upsun docs, rebuilt for developers and AI agents</h3>
      <p>The Upsun documentation has moved to developer.upsun.com with a complete infrastructure rebuild focused on agent-readiness. 244+ pages of structured, machine-readable content with llms.txt support and built-in AI assistance.</p>
    </div>
  </a>

  <a href="/posts/discussions/cpu-vs-gpu">
    <div>
      <div>
        <span>Thursday, February 26th 2026</span>
      </div>

      <h3>CPU vs GPU for AI: most AI applications don't need GPUs</h3>
      <p>How to build and deploy an Angular application on Upsun.</p>
    </div>
  </a>

  <a href="/posts/tutorials/angular-and-upsun">
    <div>
      <div>
        <span>Wednesday, December 3rd 2025</span>
      </div>

      <h3>Building and Deploying Angular Apps on Upsun</h3>
      <p>How to build and deploy an Angular application on Upsun.</p>
    </div>
  </a>
</div>


# Andoni Auzmendi
Source: https://developer.upsun.com/posts/authors/andoni

Articles written by Andoni Auzmendi.

<div>
  <a href="/posts/hands-on/fastly-maintenance">
    <div>
      <div>
        <span>Monday, August 25th 2025</span>
      </div>

      <h3>How to enable custom maintenance page in Fastly</h3>
      <p>Configure GitLab CI/CD to deploy to Upsun from private air-gapped GitLab instances using push-based workflows and API automation.</p>
    </div>
  </a>
</div>


# Andrei (Alex) Taranu
Source: https://developer.upsun.com/posts/authors/andrei-taranu

Articles written by Andrei (Alex) Taranu.

<div>
  <div>
    <a href="https://www.linkedin.com/in/andrei-alex-taranu/">LinkedIn</a>
  </div>
</div>

<div>
  <a href="/posts/how-tos/supply-chain-attacks-in-the-ai-era-and-what-to-do-about-them">
    <div>
      <div>
        <span>Thursday, April 30th 2026</span>
      </div>

      <h3>Supply chain attacks in the AI era, and what to do about them</h3>
      <p>AI agents are reading code at scale, including your dependencies. Why supply chain risk just changed, plus a build-time fix to add on Upsun.</p>
    </div>
  </a>
</div>


# Andrew Melck
Source: https://developer.upsun.com/posts/authors/andrew-melck

Articles written by Andrew Melck.

<div>
  <a href="/posts/unknown/new-german-region">
    <div>
      <div>
        <span>Wednesday, May 22nd 2019</span>
      </div>

      <h3>New Germany region: more speed, more capability, lower cost</h3>
      <p>Discover Platform.sh Enterprise in Germany. Get more speed, capability, and compliance for your applications with strict data control.</p>
    </div>
  </a>

  <a href="/posts/unknown/now-available-sovereign-hosting-solution-in-microsoft-cloud-germany">
    <div>
      <div>
        <span>Thursday, June 22nd 2017</span>
      </div>

      <h3>Sovereign Hosting Solution in Microsoft Cloud Germany</h3>
      <p>A sovereign, end-to-end development and production hosting solution in Microsoft Cloud Germany. Ensure compliance, data security, and efficiency gains.</p>
    </div>
  </a>

  <a href="/posts/unknown/platformsh-at-the-oop-conference">
    <div>
      <div>
        <span>Thursday, January 26th 2017</span>
      </div>

      <h3>Platform.sh is down wit' OOP</h3>
      <p>Join us at OOP Conference 2017 in Munich from Jan 30 to Feb 3. Live demos, answers to your PaaS questions, and more at booth 3.14. Don't miss it!</p>
    </div>
  </a>
</div>


# Augustin Delaporte
Source: https://developer.upsun.com/posts/authors/augustin-delaporte

Articles written by Augustin Delaporte.

<div>
  <div>
    <a href="https://www.linkedin.com/in/augustindelaporte/">LinkedIn</a>
  </div>
</div>

<div>
  <a href="/posts/discussions/instant-data-cloning-was-a-bet-ai-agents-are-the-payoff">
    <div>
      <div>
        <span>Tuesday, February 24th 2026</span>
      </div>

      <h3>Instant data cloning was a bet. AI agents are the payoff.</h3>
      <p>How Upsun's data-first architecture, built a decade ago for CMS and e-commerce needs, turns out to be the exact infrastructure AI agents need: instant, isolated, production-identical environments with real data.</p>
    </div>
  </a>
</div>


# Carl Smith
Source: https://developer.upsun.com/posts/authors/carl-smith

Articles written by Carl Smith.

<div>
  <a href="/posts/unknown/best-practices-for-engaging-digital-agency">
    <div>
      <div>
        <span>Monday, April 26th 2021</span>
      </div>

      <h3>Best practices for engaging a digital agency</h3>
      <p>Build a strong digital agency partnership with open communication and trust. Learn top tips from Carl Smith, Bureau of Digital principal.</p>
    </div>
  </a>
</div>


# Cati Mayer
Source: https://developer.upsun.com/posts/authors/cati-mayer

Articles written by Cati Mayer.

<div>
  <a href="/posts/unknown/mohammed-ajmal-siddiqui">
    <div>
      <div>
        <span>Friday, September 16th 2022</span>
      </div>

      <h3>Platform.sh | Journeys Mohammed Ajmal Siddiqui</h3>
      <p>Follow Ajmal's journey from India to Paris as he navigates programming, internships, and lockdowns. Join Platform.sh's success story today!</p>
    </div>
  </a>

  <a href="/posts/unknown/frederic-potvin-and-yann-deshayes">
    <div>
      <div>
        <span>Tuesday, January 19th 2021</span>
      </div>

      <h3>Platform.sh | Journeys Frederic Potvin and Yann Deshayes</h3>
      <p>Stories of two Platform.sh engineers who left and returned, highlighting the company's flexibility, employee support, and commitment to a healthy work culture</p>
    </div>
  </a>

  <a href="/posts/unknown/ks-chan">
    <div>
      <div>
        <span>Wednesday, October 21st 2020</span>
      </div>

      <h3>Platform.sh | Journeys KS Chan</h3>
      <p>Discover how a Platform.sh engineer found work-life balance while shaping the company's largest department, all while spending time with his family.</p>
    </div>
  </a>

  <a href="/posts/unknown/mahdi-mokhtariirani">
    <div>
      <div>
        <span>Wednesday, September 16th 2020</span>
      </div>

      <h3>Platform.sh | Journeys Mahdi Mokhtariirani</h3>
      <p>Follow Mahdi's journey from Iran to Europe, his experiences at Platform.sh, and how he continues to learn and grow in unfamiliar surroundings.</p>
    </div>
  </a>
</div>


# C Trinkwon
Source: https://developer.upsun.com/posts/authors/catplat

Articles written by C Trinkwon.

<div>
  <a href="/posts/how-tos/fastly-cdn-and-waf">
    <div>
      <div>
        <span>Tuesday, March 3rd 2026</span>
      </div>

      <h3>Speed vs. Security? Why not both: The Fastly CDN and WAF on Upsun</h3>
      <p>Learn how to pair Fastly’s CDN for speed with its Next-Gen WAF for security on Upsun. Optimize global performance while protecting your infrastructure from threats.</p>
    </div>
  </a>
</div>


# chadcarlson
Source: https://developer.upsun.com/posts/authors/chadcarlson

Articles written by chadcarlson.

<div>
  <a href="/posts/engineering/save-your-drupal-team-hours-and-effort-with-source-operations-and-activity-scripts">
    <div>
      <div>
        <span>Tuesday, July 28th 2020</span>
      </div>

      <h3>Source Operations and Activity Scripts for Drupal teams</h3>
      <p>Learn how to automate Drupal updates on Platform.sh using Source Operations and Activity Scripts, saving your development team time and effort.</p>
    </div>
  </a>
</div>


# Chad Carlson
Source: https://developer.upsun.com/posts/authors/chadwcarlson

Articles written by Chad Carlson.

<div>
  <img alt="Chad Carlson" />

  <div>
    <a href="https://github.com/chadwcarlson">GitHub</a>
    <a href="https://www.linkedin.com/in/chadwcarlson">LinkedIn</a>
  </div>
</div>

<ShowMore>
  <a href="/posts/unknown/new-improvement-global-settings-in-console">
    <div>
      <div>
        <span>Wednesday, July 9th 2025</span>
      </div>

      <h3>New improvement: global settings in console</h3>
      <p>Discover the new global settings page in the Console. Easily configure project and environment settings in one location for a smoother experience.</p>
    </div>
  </a>

  <a href="/posts/tutorials/drupal-and-upsun">
    <div>
      <div>
        <span>Thursday, January 16th 2025</span>
      </div>

      <h3>Drupal and Upsun</h3>
      <p>[Drupal CMS](https://www.drupal.org/project/cms), born of [DrupalCon 2024 initiative](https://www.drupal.org/about/in-the-news/blog/drupal-cms-groundbreaking-new-version-of-drupal-detailed-at-drupalcon-singapore-2024) "Starshot", has been [released today](https://www.drupal.org/blog/drupal-cms-1-0).</p>
    </div>
  </a>

  <a href="/posts/releases/php-84-release">
    <div>
      <div>
        <span>Tuesday, November 26th 2024</span>
      </div>

      <h3>PHP 8.4 is here!</h3>
      <p>PHP 8.4 was [officially released](https://www.php.net/archive/2024.php#2024-11-21-4) on November 21st, and with it comes a number of improvements and new features that you can - as of today - begin working with on your Upsun and Platform.sh projects.</p>
    </div>
  </a>

  <a href="/posts/releases/introducing-dev-center">
    <div>
      <div>
        <span>Wednesday, September 18th 2024</span>
      </div>

      <h3>Introducing the Upsun Developer Center</h3>
      <p>This month our Developer Relations and Advocacy teams are excited to share with you our latest resource: the Upsun Developer Center.</p>
    </div>
  </a>

  <a href="/posts/how-tos/measuring-the-success-of-a-deployment-with-githubactions">
    <div>
      <div>
        <span>Thursday, December 23rd 2021</span>
      </div>

      <h3>Measuring Deployment Success with GitHub Actions</h3>
      <p>Learn how GitHub actions can streamline your Platform.sh deployments for faster and more efficient development workflows</p>
    </div>
  </a>

  <a href="/posts/unknown/share-your-activities-with-robots-surfacing-activities-with-github-actions">
    <div>
      <div>
        <span>Wednesday, December 22nd 2021</span>
      </div>

      <h3>Surfacing activities with GitHub actions</h3>
      <p>Learn how to leverage the predictable link in your workflow by integrating Platform.sh with GitHub Actions. Streamline your deployments and error handling.</p>
    </div>
  </a>

  <a href="/posts/unknown/share-your-failures-fix-them-faster">
    <div>
      <div>
        <span>Wednesday, December 8th 2021</span>
      </div>

      <h3>Share and fix failures faster with shareable activities</h3>
      <p>Troubleshoot failures efficiently with shareable activity logs. Collaborate with your team and Platform.sh support to streamline Continuous Delivery workflow.</p>
    </div>
  </a>

  <a href="/posts/how-tos/get-more-control-over-your-environments-with-build-variables">
    <div>
      <div>
        <span>Tuesday, August 10th 2021</span>
      </div>

      <h3>Get more control over your environments with build variables</h3>
      <p>Discover the visible-build flag on Platform.sh, enabling environment-specific build variables for more control over your development process.</p>
    </div>
  </a>

  <a href="/posts/unknown/plan-monitor-operate-more-knowledgeably-with-metrics">
    <div>
      <div>
        <span>Wednesday, March 17th 2021</span>
      </div>

      <h3>Plan, monitor, and operate more knowledgeably with metrics</h3>
      <p>Introducing metrics and observability on Dedicated infrastructure projects, allowing you to easily monitor CPU, RAM, and disk usage across your hosts.</p>
    </div>
  </a>

  <a href="/posts/unknown/time-to-breakup-three-reasons-to-decouple-your-application">
    <div>
      <div>
        <span>Wednesday, February 10th 2021</span>
      </div>

      <h3>Time to breakup? Three reasons to decouple your application</h3>
      <p>Reasons to consider decoupling your website on Platform.sh. Specialized frameworks, focused teams, and create once, publish everywhere benefits.</p>
    </div>
  </a>

  <a href="/posts/unknown/renaming-your-projects-default-branch">
    <div>
      <div>
        <span>Wednesday, January 20th 2021</span>
      </div>

      <h3>Renaming your project’s default branch</h3>
      <p>Update your Project's default branch in Git repositories. Rename your master branch to support a more inclusive default naming convention.</p>
    </div>
  </a>

  <a href="/posts/unknown/what-the-heck-is-a-decoupled-website">
    <div>
      <div>
        <span>Monday, January 11th 2021</span>
      </div>

      <h3>CMS architecture: What the heck is . . . a decoupled website?</h3>
      <p>A decoupled CMS architecture splits website tasks into smaller apps while maintaining specific functions. Learn how Platform.sh improves the process.</p>
    </div>
  </a>

  <a href="/posts/unknown/headless-but-this-time-live-decoupled-drupal-with-gatsby">
    <div>
      <div>
        <span>Tuesday, July 28th 2020</span>
      </div>

      <h3>Headless, but this time live! Decoupled Drupal with Gatsby</h3>
      <p>Learn to decouple Drupal and Gatsby on Platform.sh for parallel work and efficient content management. Follow our tutorial and deploy your project today!</p>
    </div>
  </a>

  <a href="/posts/unknown/headless-strapi-and-wordpress-content-with-gatsby-builds">
    <div>
      <div>
        <span>Wednesday, May 13th 2020</span>
      </div>

      <h3>Going headless during your Gatsby builds</h3>
      <p>Recently, Platform.</p>
    </div>
  </a>

  <a href="/posts/unknown/new-services-page">
    <div>
      <div>
        <span>Tuesday, October 15th 2019</span>
      </div>

      <h3>New Services Page: more shininess, as promised</h3>
      <p>Discover the brand new Services page in our management console. Get detailed insights into your services, routes, and applications right from the console.</p>
    </div>
  </a>

  <a href="/posts/unknown/platform.sh-documentation-new-guides-new-look">
    <div>
      <div>
        <span>Thursday, August 1st 2019</span>
      </div>

      <h3>Platform.sh documentation: new guides, new look</h3>
      <p>Explore the comprehensive Platform.sh documentation. Find step-by-step guides, tutorials, and resources to simplify web app development with Platform.sh.</p>
    </div>
  </a>

  <a href="/posts/unknown/off-with-its-head-headless-Chrome-as-a-service">
    <div>
      <div>
        <span>Wednesday, June 12th 2019</span>
      </div>

      <h3>Off with its Head! Headless Chrome as a Service decoded</h3>
      <p>Headless Chrome is a headless browser configurable on Platform.sh. Compare screenshots and generate PDFs hassle-free today</p>
    </div>
  </a>
</ShowMore>


# Chris Yates
Source: https://developer.upsun.com/posts/authors/chris-yates

Articles written by Chris Yates.

<div>
  <a href="/posts/unknown/record-breaking-2020-black-friday-cyber-monday-volumes">
    <div>
      <div>
        <span>Monday, December 7th 2020</span>
      </div>

      <h3>Record-breaking 2020 Black Friday volumes</h3>
      <p>Platform.sh helped retailers thrive during the 2020 holiday season with record traffic and order volumes. Learn more about our high-performance architecture.</p>
    </div>
  </a>

  <a href="/posts/unknown/platformsh-partner-eZ-Systems-announces-name-change-to-ibexa">
    <div>
      <div>
        <span>Tuesday, June 23rd 2020</span>
      </div>

      <h3>Platform.sh partner eZ Systems announces name change to Ibexa</h3>
      <p>After twenty years as a successful Web Content Management vendor, eZ Systems last month announced the launch of its new corporate brand identity and name: Ibexa</p>
    </div>
  </a>

  <a href="/posts/unknown/the-monolith-myth-why-tech-suites-are-not-solution">
    <div>
      <div>
        <span>Monday, April 13th 2020</span>
      </div>

      <h3>A monolith myth: All-in-one tech suites aren't the solution</h3>
      <p>Explore the reality behind all-in-one tech suites and why they often fail to meet the diverse needs of businesses</p>
    </div>
  </a>

  <a href="/posts/unknown/apache-kafka-support">
    <div>
      <div>
        <span>Wednesday, June 5th 2019</span>
      </div>

      <h3>Apache Kafka now available</h3>
      <p>Discover the power of Apache Kafka for real-time streaming applications and data pipelines. Get started with Kafka on Platform.sh. No servers to configure.</p>
    </div>
  </a>

  <a href="/posts/unknown/it-worked-in-staging">
    <div>
      <div>
        <span>Thursday, April 25th 2019</span>
      </div>

      <h3>Learning to trust the machines and the process in DevOps</h3>
      <p>Platform.sh enables seamless collaboration between development and operations teams, leading to predictable and reliable deployments for your applications.</p>
    </div>
  </a>

  <a href="/posts/unknown/open-source-software-roi-for-your-organization">
    <div>
      <div>
        <span>Wednesday, January 2nd 2019</span>
      </div>

      <h3>Open source software ROI for your organization</h3>
      <p>The benefits of contributing to open-source software and how it can enhance your organization, attract top developers, and improve your software quality.</p>
    </div>
  </a>

  <a href="/posts/unknown/our-black-friday-gift-10000-cpus-overnight-without-downtime">
    <div>
      <div>
        <span>Friday, November 16th 2018</span>
      </div>

      <h3>Our Black Friday gift: 10,000 CPUs without downtime</h3>
      <p>Prepare your ecommerce site for Black Friday seamlessly with Platform.sh. Add capacity, handle high traffic, and ensure performance without downtime.</p>
    </div>
  </a>
</div>


# Christian Sieber
Source: https://developer.upsun.com/posts/authors/christian-sieber

Articles written by Christian Sieber.

<div>
  <a href="/posts/unknown/release-hhvm">
    <div>
      <div>
        <span>Wednesday, September 23rd 2015</span>
      </div>

      <h3>HHVM versions 3.9 and 3.12 supported</h3>
      <p>Announcing HHVM support on Platform.sh. HHVM offers improved PHP performance and scalability. Learn how to use and configure it in our documentation.</p>
    </div>
  </a>
</div>


# Christopher Lockheardt
Source: https://developer.upsun.com/posts/authors/christopher-lockheardt

Articles written by Christopher Lockheardt.

<div>
  <a href="/posts/unknown/creating-problem-solving-partnerships-through-open-innovation">
    <div>
      <div>
        <span>Wednesday, September 8th 2021</span>
      </div>

      <h3>Creating problem-solving partnerships with open innovation</h3>
      <p>Learn about open innovation, its challenges, and benefits. Discover how companies collaborate for creative problem-solving and innovation.</p>
    </div>
  </a>

  <a href="/posts/unknown/keeping-afloat-during-flood-of-worker-turnover">
    <div>
      <div>
        <span>Thursday, August 19th 2021</span>
      </div>

      <h3>Keeping afloat during the flood of worker turnover</h3>
      <p>Discover insights on the talent turnover tsunami, burnout, and remote work strategies. Learn how to win the talent war in today's job market.</p>
    </div>
  </a>

  <a href="/posts/unknown/building-better-mousetrap-barebones-budget">
    <div>
      <div>
        <span>Thursday, July 1st 2021</span>
      </div>

      <h3>Building a better mousetrap on a barebones budget</h3>
      <p>Learn from Dan Kildahl's insights on innovating wisely with limited resources in the latest Fleet Club session. Join the conversation at Fleet Club.</p>
    </div>
  </a>

  <a href="/posts/unknown/four-reasons-to-build-ecommerce-site-with-modern-paas">
    <div>
      <div>
        <span>Thursday, April 22nd 2021</span>
      </div>

      <h3>Four reasons to build your ecommerce site with a modern PaaS</h3>
      <p>Discover why SportRx and FREITAG chose Platform.sh for their ecommerce businesses. Higher performance, scalability, stability, and redundancy.</p>
    </div>
  </a>

  <a href="/posts/unknown/free-your-developers-the-simple-way-to-rebalance-your-devops-resources">
    <div>
      <div>
        <span>Thursday, January 14th 2021</span>
      </div>

      <h3>Free your developers! The simple way to rebalance your DevOps resources</h3>
      <p>Discover how Platform-as-a-Service (PaaS) can shift the balance of power from Ops to Dev, giving organizations more time, money, and tools for development.</p>
    </div>
  </a>
</div>


# Christopher Skene
Source: https://developer.upsun.com/posts/authors/christopher-skene

Articles written by Christopher Skene.

<div>
  <a href="/posts/unknown/good-morning-australia-were-back-in-business">
    <div>
      <div>
        <span>Thursday, November 15th 2018</span>
      </div>

      <h3>Good morning, Australia: we’re back in business</h3>
      <p>Reflecting on Platform.sh's first year in Australia. Improved uptime, support, pricing, and plans for a better experience. Learn how we can help you.</p>
    </div>
  </a>

  <a href="/posts/unknown/using-platformsh-with-scrum">
    <div>
      <div>
        <span>Tuesday, February 13th 2018</span>
      </div>

      <h3>Using Platform.sh with Scrum</h3>
      <p>Learn how Platform.sh's Git-based environment workflow unblocks Scrum projects, allowing for efficient testing, parallel development, and feature isolation.</p>
    </div>
  </a>

  <a href="/posts/unknown/wildcard-support-for-cookies-in-the-http-cache">
    <div>
      <div>
        <span>Tuesday, October 17th 2017</span>
      </div>

      <h3>Wildcard support for cookies in the HTTP cache</h3>
      <p>Learn how to use regular expressions for wildcard cookie matching at the cache layer on Platform.sh, improving caching rules and caching performance.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/the-platformsh-build-and-deploy-pipeline">
    <div>
      <div>
        <span>Tuesday, October 3rd 2017</span>
      </div>

      <h3>The Platform.sh build-and-deploy pipeline</h3>
      <p>Learn how Platform.sh simplifies the build and deploy pipeline for web applications, ensuring consistency and repeatability with Git-based semantics.</p>
    </div>
  </a>

  <a href="/posts/unknown/platformsh-joins-orange-cloud-for-business-at-huawei-connect-2017-shanghai">
    <div>
      <div>
        <span>Monday, September 4th 2017</span>
      </div>

      <h3>Platform.sh & Orange Cloud at Huawei Connect 2017, Shanghai</h3>
      <p>Join Platform.sh and Orange Cloud for Business at Huawei Connect in Shanghai. Discover Continuous Deployment cloud hosting for agile development.</p>
    </div>
  </a>

  <a href="/posts/unknown/deploy-down-under-platformsh-is-now-available-in-australia">
    <div>
      <div>
        <span>Monday, July 3rd 2017</span>
      </div>

      <h3>Deploy Down Under: Platform.sh is now available in Australia</h3>
      <p>Experience unmatched Australian cloud hosting. Deploy PHP, NodeJS, Ruby & Python projects with Platform.sh's Continuous Deployment. Try it now!</p>
    </div>
  </a>

  <a href="/posts/unknown/the-ultimate-third-party-resources-list-on-using-platformsh">
    <div>
      <div>
        <span>Tuesday, May 16th 2017</span>
      </div>

      <h3>The Ultimate Third Party Resources List on Using Platform.sh</h3>
      <p>Resources and guides from the Platform.sh community. Get tips on migrations, debugging, workflows, and more for your projects. Contribute to this growing list.</p>
    </div>
  </a>

  <a href="/posts/unknown/do-more-with-less">
    <div>
      <div>
        <span>Monday, October 17th 2016</span>
      </div>

      <h3>Cut your digital budget by 30% by doing less work</h3>
      <p>Discover how Platform.sh can help you simplify digital, reduce costs, and increase efficiency with faster development and deployment processes.</p>
    </div>
  </a>
</div>


# chrisyates
Source: https://developer.upsun.com/posts/authors/chrisyates

Articles written by chrisyates.

<div>
  <a href="/posts/business/website-fleet">
    <div>
      <div>
        <span>Friday, October 11th 2019</span>
      </div>

      <h3>Website fleet management: challenges and opportunities</h3>
      <p>A solution to manage website fleets, automate code updates, and streamline operations for organizations with numerous websites and applications.</p>
    </div>
  </a>
</div>


# Chuck Morgan
Source: https://developer.upsun.com/posts/authors/chuck-morgan

Articles written by Chuck Morgan.

<div>
  <a href="/posts/unknown/an-update-to-our-events-privacy-policy">
    <div>
      <div>
        <span>Wednesday, May 31st 2023</span>
      </div>

      <h3>An update to our events privacy policy</h3>
      <p>To ensure the best experience at Platform.sh conferences and events, we've updated our privacy policy detailing how we'll use and care for your personal data.</p>
    </div>
  </a>

  <a href="/posts/unknown/were-updating-our-privacy-policy-to-include-event-accommodations">
    <div>
      <div>
        <span>Friday, August 19th 2022</span>
      </div>

      <h3>We’re updating our privacy policy to include event accommodations</h3>
      <p>Learn about our privacy policy update regarding dietary restrictions and disability accommodations at Platform.sh events.</p>
    </div>
  </a>
</div>


# Crell
Source: https://developer.upsun.com/posts/authors/crell

Articles written by Crell.

<ShowMore>
  <a href="/posts/core-concepts/https-and-tls-certificates-always-served-fresh">
    <div>
      <div>
        <span>Tuesday, February 9th 2021</span>
      </div>

      <h3>HTTPS and TLS certificates: Always served fresh</h3>
      <p>Goodbye to expired certificates! We now auto-renew TLS certificates for your websites, ensuring end-to-end encryption without interruptions.</p>
    </div>
  </a>

  <a href="/posts/unknown/php-80-brings-it-all-together-on-platformsh">
    <div>
      <div>
        <span>Thursday, November 26th 2020</span>
      </div>

      <h3>PHP 8.0 brings it all together on Platform.sh</h3>
      <p>Discover the new features in PHP 8.0 and learn how to upgrade your Platform.sh projects. Constructor Property Promotion, Attributes, Named Arguments, and more!</p>
    </div>
  </a>

  <a href="/posts/core-concepts/getting-gitops-right">
    <div>
      <div>
        <span>Tuesday, November 10th 2020</span>
      </div>

      <h3>Getting GitOps right</h3>
      <p>Source code management has never been simpler with GitOps from Platform.sh. We'll help you get started with automating your deployments.</p>
    </div>
  </a>

  <a href="/posts/releases/php-80-feature-focus-constructor-property-promotion">
    <div>
      <div>
        <span>Thursday, November 5th 2020</span>
      </div>

      <h3>PHP 8.0 feature focus: Class constructor property promotion</h3>
      <p>Discover how PHP 8.0's Constructor Property Promotion feature can streamline your code, reduce verbosity, and make coding faster. Try it on Platform.sh today!</p>
    </div>
  </a>

  <a href="/posts/unknown/php-80-feature-focus-language-tightening">
    <div>
      <div>
        <span>Thursday, October 22nd 2020</span>
      </div>

      <h3>PHP 8.0 feature focus: Language tightenings</h3>
      <p>Explore PHP 8.0's language changes for safer code. Discover stable sorting, numeric string handling, stricter magic methods, and more on Platform.sh!</p>
    </div>
  </a>

  <a href="/posts/unknown/php-80-feature-focus-quality-of-life-improvements">
    <div>
      <div>
        <span>Wednesday, October 14th 2020</span>
      </div>

      <h3>PHP 8.0 feature focus: quality of life improvements</h3>
      <p>Explore PHP 8.0's new string functions, throw expression, and other improvements. Try PHP 8.0 on Platform.sh today!</p>
    </div>
  </a>

  <a href="/posts/unknown/what-the-heck-is-a-container">
    <div>
      <div>
        <span>Monday, October 5th 2020</span>
      </div>

      <h3>CMS architecture: What the heck is . . . containerization?</h3>
      <p>Want to better understand containerization? Let Platform.sh walk you through it. Our no-hassle container platform will keep your applications running smoothly.</p>
    </div>
  </a>

  <a href="/posts/releases/php-80-feature-focus-weak-maps">
    <div>
      <div>
        <span>Thursday, October 1st 2020</span>
      </div>

      <h3>PHP 8.0 feature focus: Weak maps</h3>
      <p>Learn how PHP 8.0's Weak Maps simplify memory management by efficiently handling cached objects. Try PHP 8.0 on Platform.sh today!</p>
    </div>
  </a>

  <a href="/posts/unknown/pre-release-php-8-0-images-now-available">
    <div>
      <div>
        <span>Thursday, September 3rd 2020</span>
      </div>

      <h3>Pre-release PHP 8.0 images now available</h3>
      <p>Explore PHP 8.0's new features and performance improvements. Try it out early on Platform.sh with a simple configuration change.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/installers-that-dont-suck">
    <div>
      <div>
        <span>Wednesday, August 5th 2020</span>
      </div>

      <h3>Installers that don't suck</h3>
      <p>Learn how to create cloud-friendly web application installers that account for cloud-based environments and optimize the user experience.</p>
    </div>
  </a>

  <a href="/posts/unknown/the-suddenly-online-conference">
    <div>
      <div>
        <span>Thursday, April 2nd 2020</span>
      </div>

      <h3>The suddenly online conference: an Indy Cloud Conf case study</h3>
      <p>Explore the challenges and successes of transitioning from in-person conferences to remote events during the COVID-19 pandemic.</p>
    </div>
  </a>

  <a href="/posts/unknown/php-7.4-is-just-a-git-push-away">
    <div>
      <div>
        <span>Thursday, November 28th 2019</span>
      </div>

      <h3>PHP 7.4 is just a git push away</h3>
      <p>The latest features in PHP 7.4. Learn about typed properties, short-lambda syntax, null coalesce assignment, and opcache preloading.</p>
    </div>
  </a>

  <a href="/posts/engineering/three-ways-to-manage-a-fleet">
    <div>
      <div>
        <span>Friday, October 11th 2019</span>
      </div>

      <h3>Three ways to manage a website fleet</h3>
      <p>Efficient multi-website management using Source Operations on Platform.sh. Automate updates, builds, and deployments for a large number of websites with ease.</p>
    </div>
  </a>

  <a href="/posts/unknown/go-release-1.13-on-Platform.sh">
    <div>
      <div>
        <span>Wednesday, September 4th 2019</span>
      </div>

      <h3>New: Go release 1.13 on Platform.sh</h3>
      <p>Upgrade your Go projects on Platform.sh to version 1.13, featuring improvements like Go Modules, enhanced number literal support, and more. Try it now!</p>
    </div>
  </a>

  <a href="/posts/unknown/try-out-the-future-of-php-on-platform.sh-today">
    <div>
      <div>
        <span>Tuesday, August 27th 2019</span>
      </div>

      <h3>PHP 7.4 is here: Try out the future of PHP on Platform.sh today!</h3>
      <p>Explore the new features in PHP 7.4 and learn how to deploy pre-release versions on Platform.sh to test and prepare your project for the official release.</p>
    </div>
  </a>

  <a href="/posts/releases/deploy-with-php-73-this-friday-er-thursday">
    <div>
      <div>
        <span>Thursday, December 6th 2018</span>
      </div>

      <h3>Deploy with PHP 7.3 this Friday, er, Thursday</h3>
      <p>Platform.sh welcomes PHP 7.3! Explore the latest features and performance improvements. Upgrade your application with a simple YAML tweak.</p>
    </div>
  </a>

  <a href="/posts/releases/golang-forth-and-deploy">
    <div>
      <div>
        <span>Monday, October 29th 2018</span>
      </div>

      <h3>Go\[lang] forth and deploy</h3>
      <p>Discover the full support for Go 1.11 on Platform.sh. No more GOPATH required. Easy setup and deployment for Go applications with Go modules and Platform.sh.</p>
    </div>
  </a>

  <a href="/posts/unknown/of-cicadas-and-cron-jobs">
    <div>
      <div>
        <span>Tuesday, August 21st 2018</span>
      </div>

      <h3>Of Cicadas and cron jobs</h3>
      <p>Discover how cicadas and prime numbers can teach us about optimizing web development tasks and avoiding conflicts in cron jobs for smoother website performance.</p>
    </div>
  </a>

  <a href="/posts/unknown/its-july-2018-do-you-know-what-your-php-is">
    <div>
      <div>
        <span>Tuesday, July 3rd 2018</span>
      </div>

      <h3>It's July 2018, do you know what your PHP is?</h3>
      <p>Discover the benefits of upgrading to PHP 7, including better performance, enhanced security, and new functionality.</p>
    </div>
  </a>

  <a href="/posts/unknown/some-gifts-for-the-json-fans">
    <div>
      <div>
        <span>Thursday, June 28th 2018</span>
      </div>

      <h3>Some gifts for the JSON fans</h3>
      <p>Platform.sh now supports the latest MongoDB versions and Node.js version 10. Upgrade seamlessly to enjoy new features and stability for your applications.</p>
    </div>
  </a>

  <a href="/posts/insights/what-will-you-do-after-you-deploy">
    <div>
      <div>
        <span>Tuesday, April 17th 2018</span>
      </div>

      <h3>What will you do after you deploy?</h3>
      <p>Learn how Platform.sh's post\_deploy hook can keep your site responsive during deploy tasks, making your deploys faster and more efficient.</p>
    </div>
  </a>

  <a href="/posts/releases/hhvm-deploys-off-into-the-sunset">
    <div>
      <div>
        <span>Tuesday, January 30th 2018</span>
      </div>

      <h3>HHVM deploys off into the sunset</h3>
      <p>Platform.sh will no longer support HHVM runtime after 1 March 2018. Learn about this change and the evolution of PHP alternatives.</p>
    </div>
  </a>

  <a href="/posts/unknown/backup-and-forget">
    <div>
      <div>
        <span>Wednesday, January 3rd 2018</span>
      </div>

      <h3>Backup and Forget</h3>
      <p>Learn how to automate disaster recovery backups using Platform.sh. A simple 3-step process for routine snapshots of your production environment.</p>
    </div>
  </a>

  <a href="/posts/unknown/a-look-back-on-2017">
    <div>
      <div>
        <span>Friday, December 29th 2017</span>
      </div>

      <h3>A look back on 2017</h3>
      <p>Explore a year of enhancements at Platform.sh, from HTTP/2 support to expanded services. Preview what's coming in 2018 for our PaaS.</p>
    </div>
  </a>

  <a href="/posts/unknown/tighten-up-your-tls">
    <div>
      <div>
        <span>Thursday, December 28th 2017</span>
      </div>

      <h3>Tighten up your TLS</h3>
      <p>Discover new TLS-related features for increased website security on Platform.sh. Restrict TLS versions, enable HSTS, and implement client-authenticated TLS.</p>
    </div>
  </a>

  <a href="/posts/unknown/route-all-the-things">
    <div>
      <div>
        <span>Wednesday, December 20th 2017</span>
      </div>

      <h3>Route all the things</h3>
      <p>Learn how the routing system works on Platform.sh, including its flexibility, multi-domain support, and routing configurations.</p>
    </div>
  </a>

  <a href="/posts/unknown/welcome-to-the-world-php-72">
    <div>
      <div>
        <span>Thursday, November 30th 2017</span>
      </div>

      <h3>Welcome to the world, PHP 7.2!</h3>
      <p>Learn about the new features and improvements in PHP 7.2.0, including better performance and security enhancements. Try PHP 7.2.0 on Platform.sh with ease.</p>
    </div>
  </a>

  <a href="/posts/unknown/wordpress-security-updates-the-quick-way">
    <div>
      <div>
        <span>Wednesday, November 1st 2017</span>
      </div>

      <h3>WordPress security updates, the quick way</h3>
      <p>Learn how to update your WordPress version to 4.8.3 to fix a security vulnerability.</p>
    </div>
  </a>

  <a href="/posts/unknown/going-local-with-lando">
    <div>
      <div>
        <span>Wednesday, October 18th 2017</span>
      </div>

      <h3>Going Local with Lando</h3>
      <p>Lando, a Docker-based local development tool recommended by Platform.sh. Easily set up your local environment and sync data from for seamless web development.</p>
    </div>
  </a>

  <a href="/posts/unknown/taking-care-of-your-health">
    <div>
      <div>
        <span>Monday, October 2nd 2017</span>
      </div>

      <h3>Taking care of your health</h3>
      <p>Easily monitor your project's health with built-in notification checks for disk space, sent via email, Slack, or Pager Duty on Platform Professional projects.</p>
    </div>
  </a>

  <a href="/posts/unknown/6-things-to-do-to-make-your-application-cloud-friendly">
    <div>
      <div>
        <span>Monday, August 7th 2017</span>
      </div>

      <h3>7 things to do to make your application cloud-friendly</h3>
      <p>Make your app cloud-friendly with 7 steps. Test it on Platform.sh for free to ensure compatibility in a real-world environment.</p>
    </div>
  </a>

  <a href="/posts/unknown/containers-old-containers-new-memcached-support-and-php-72">
    <div>
      <div>
        <span>Monday, June 26th 2017</span>
      </div>

      <h3>Containers, memcached support, and PHP 7.2</h3>
      <p>Stay updated with Platform.sh's latest features, including MariaDB and Memcached support. Try PHP 7.2-alpha and explore new languages</p>
    </div>
  </a>

  <a href="/posts/unknown/free-ssl-certificates-for-every-project-every-environment">
    <div>
      <div>
        <span>Thursday, April 20th 2017</span>
      </div>

      <h3>Free SSL certificates for every project & every environment</h3>
      <p>We now offer free automatic Let's Encrypt SSL certificates, making your site secure, fast, and feature-rich. Say hello to secure, fast, and easy web hosting!</p>
    </div>
  </a>

  <a href="/posts/unknown/influxdb">
    <div>
      <div>
        <span>Monday, March 27th 2017</span>
      </div>

      <h3>Now you can save time in a database</h3>
      <p>Introducing Influx DB 1.2, perfect for high-volume logging, data collection, and metrics. Easily add it to your services.yaml file for improved data handling.</p>
    </div>
  </a>

  <a href="/posts/unknown/multi-mysql">
    <div>
      <div>
        <span>Friday, February 10th 2017</span>
      </div>

      <h3>Multiple MySQLs Make Platform.sh a Multisite Machine</h3>
      <p>Learn how Platform.sh now supports multiple databases in MySQL and restricted user access. Optimize your projects with flexible database configurations.</p>
    </div>
  </a>

  <a href="/posts/unknown/persistent-redis">
    <div>
      <div>
        <span>Wednesday, January 25th 2017</span>
      </div>

      <h3>Redis, now for long-term keys and values</h3>
      <p>Discover Platform.sh's Redis Persistent Service, a super-fast key-value database that allows you to store data permanently. Learn how to configure and use it.</p>
    </div>
  </a>

  <a href="/posts/unknown/solr-63">
    <div>
      <div>
        <span>Tuesday, January 17th 2017</span>
      </div>

      <h3>New year, new Solr, new features</h3>
      <p>Platform.sh launches the new Apache Solr version 6.3 with multi-core support, providing better search capabilities for your applications.</p>
    </div>
  </a>

  <a href="/posts/unknown/php-71">
    <div>
      <div>
        <span>Thursday, December 29th 2016</span>
      </div>

      <h3>Next Wave PHP now supported</h3>
      <p>Discover the latest PHP 7.1 features, async support, and PThreads support on Platform.sh. Upgrade your PHP version for improved speed and new features.</p>
    </div>
  </a>

  <a href="/posts/unknown/production-artifact">
    <div>
      <div>
        <span>Friday, December 23rd 2016</span>
      </div>

      <h3>Production is an artifact of development</h3>
      <p>Explore the concept that production is an artifact of development and how Platform.sh revolutionizes web hosting for modern web applications.</p>
    </div>
  </a>

  <a href="/posts/unknown/project-variables">
    <div>
      <div>
        <span>Tuesday, December 20th 2016</span>
      </div>

      <h3>This week in new features - Build-time variables</h3>
      <p>Discover the benefits of project-level variables available at build time on Platform.sh and explore their use cases, including private composer repositories.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/repeatable-deployments">
    <div>
      <div>
        <span>Tuesday, December 13th 2016</span>
      </div>

      <h3>How repeatable deployments work</h3>
      <p>Platform.sh ensures predictable, repeatable deployments by controlling the key inputs to your application and guaranteeing code consistency.</p>
    </div>
  </a>

  <a href="/posts/unknown/app-updates-php">
    <div>
      <div>
        <span>Friday, December 9th 2016</span>
      </div>

      <h3>Application updates for PHP containers</h3>
      <p>Discover the latest improvements for PHP containers on Platform.sh. Learn about environment configuration, starting processes, and log file changes.</p>
    </div>
  </a>

  <a href="/posts/releases/python-ruby-support">
    <div>
      <div>
        <span>Friday, September 23rd 2016</span>
      </div>

      <h3>Continuous Deployment - Now with Python and Ruby support!</h3>
      <p>Platform.sh now offers continuous deployment for Ruby and Python developers. Explore the benefits of continuous deployment for your projects in these languages.</p>
    </div>
  </a>

  <a href="/posts/unknown/documentation-tng">
    <div>
      <div>
        <span>Wednesday, September 21st 2016</span>
      </div>

      <h3>Platform.sh Documentation - The Next Generation</h3>
      <p>Explore our redesigned documentation to discover the full potential of Platform.sh for your development needs.</p>
    </div>
  </a>

  <a href="/posts/unknown/is-thecloud-really-someone-elses-computer">
    <div>
      <div>
        <span>Monday, June 27th 2016</span>
      </div>

      <h3>Is the Cloud really someone else's computer?</h3>
      <p>Difference between "the Cloud" and cloud computing. The benefits and drawbacks of both concepts, and how Platform.sh offers a unique approach to hosting.</p>
    </div>
  </a>

  <a href="/posts/unknown/drupal-8-starter-kit-now-with-php-7-and-composer">
    <div>
      <div>
        <span>Tuesday, June 7th 2016</span>
      </div>

      <h3>Drupal 8 starter kit now with PHP 7 and Composer!</h3>
      <p>Discover how Drupal 8.1 embraces Composer and PHP 7 on Platform.sh. Learn what changes and how it benefits your Drupal projects.</p>
    </div>
  </a>

  <a href="/posts/unknown/drupalcon-nola-survival-guide">
    <div>
      <div>
        <span>Thursday, May 5th 2016</span>
      </div>

      <h3>DrupalCon New Orleans Survival Guide</h3>
      <p>Attending DrupalCon New Orleans? Learn tips for making the most of your experience, from networking to sessions and sprints, with Platform.sh.</p>
    </div>
  </a>
</ShowMore>


# Damz
Source: https://developer.upsun.com/posts/authors/damz

Articles written by Damz.

<div>
  <a href="/posts/discussions/go-124">
    <div>
      <div>
        <span>Sunday, December 15th 2024</span>
      </div>

      <h3>Golang 1.24 is looking seriously awesome</h3>
      <p>The Golang team just released the [first release candidate of Golang 1.24](https://tip.golang.org/doc/go1.24). At Upsun, we use Golang extensively for everything in our hot path, especially for the routing of HTTP requests throughout our infrastructure. Here is what we are looking forward to the most.</p>
    </div>
  </a>

  <a href="/posts/unknown/git-clients-vulnerable">
    <div>
      <div>
        <span>Friday, December 19th 2014</span>
      </div>

      <h3>Git clients vulnerable</h3>
      <p>Learn about the Git vulnerability affecting Mac OS X and Windows users. Find out how Platform.sh customers can protect their Git clients.</p>
    </div>
  </a>

  <a href="/posts/unknown/protecting-your-apps">
    <div>
      <div>
        <span>Tuesday, October 21st 2014</span>
      </div>

      <h3>Protecting your apps</h3>
      <p>Platform.sh launched automated blocking for critical vulnerabilities (incl. Drupal SQL Injection) and seeks collaborators for an open-source signature database</p>
    </div>
  </a>
</div>


# David Bonachera
Source: https://developer.upsun.com/posts/authors/davidbonachera

Articles written by David Bonachera.

<div>
  <img alt="David Bonachera" />

  <div>
    <a href="https://github.com/davidbonachera">GitHub</a>
    <a href="https://www.linkedin.com/in/davidbonachera">LinkedIn</a>
  </div>
</div>

<div>
  <a href="/posts/hands-on/zero-downtime-deployments-with-upsun">
    <div>
      <div>
        <span>Wednesday, December 3rd 2025</span>
      </div>

      <h3>Zero-downtime deployments: now in open beta</h3>
      <p>We've launched zero-downtime deployments in open beta. Deploy your applications without service interruption.</p>
    </div>
  </a>
</div>


# Ahmet Faruk Dereli
Source: https://developer.upsun.com/posts/authors/dereliahmet1

Articles written by Ahmet Faruk Dereli.

<div>
  <a href="/posts/how-tos/automated-encrypt-backups-amazon-s3">
    <div>
      <div>
        <span>Monday, January 12th 2026</span>
      </div>

      <h3>Automated encrypted backups to Amazon S3 | Upsun</h3>
      <p>Learn how to configure Duplicity, GPG keys, and cron on Upsun to send incremental, encrypted backups of your application to AWS S3 for reliable restores</p>
    </div>
  </a>
</div>


# Jonas Kröger
Source: https://developer.upsun.com/posts/authors/devicezero

Articles written by Jonas Kröger.

<div>
  <img alt="Jonas Kröger" />

  <div>
    <a href="https://github.com/devicezero">GitHub</a>
    <a href="https://www.linkedin.com/in/jonaskroeger/">LinkedIn</a>
  </div>
</div>

<div>
  <a href="/posts/core-concepts/eliminating-database-pwd-risk-with-network-isolation">
    <div>
      <div>
        <span>Wednesday, February 4th 2026</span>
      </div>

      <h3>Eliminating Database Password Risk with Network Isolation</h3>
      <p>By removing default database passwords, Upsun reduces common credential risks (leaks, reuse, hardcoding) and relies on stronger security controls like SSH keys and private networking.</p>
    </div>
  </a>
</div>


# diogo-sousa
Source: https://developer.upsun.com/posts/authors/diogo-sousa

Articles written by diogo-sousa.

<div>
  <a href="/posts/how-it-works/how-platformsh-stays-ahead-of-emerging-cybersecurity-threats">
    <div>
      <div>
        <span>Friday, October 13th 2023</span>
      </div>

      <h3>Semper vigilans: how Platform.sh stays ahead of emerging cybersecurity threats (so you don’t have to)</h3>
      <p>Always vigilant is more than a motto. Find out how the Platform.sh Security team monitors vulnerabilities 24x7 to protect customers from cybersecurity threats.</p>
    </div>
  </a>
</div>


# dman
Source: https://developer.upsun.com/posts/authors/dman

Articles written by dman.

<div>
  <a href="/posts/how-tos/schedule-resource-availability">
    <div>
      <div>
        <span>Thursday, October 24th 2024</span>
      </div>

      <h3>Scheduling resources</h3>
      <p>As Upsun does purely usage-driven billing,</p>
    </div>
  </a>

  <a href="/posts/how-tos/configuring-an-autoscaler">
    <div>
      <div>
        <span>Saturday, October 19th 2024</span>
      </div>

      <h3>Adding an autoscaler to Upsun projects</h3>
      <p>In this post we will describe a small configuration that will</p>
    </div>
  </a>

  <a href="/posts/how-it-works/using-the-upsun-api">
    <div>
      <div>
        <span>Thursday, September 19th 2024</span>
      </div>

      <h3>Using the Upsun API</h3>
      <p>> Anything you can do, API can do better!</p>
    </div>
  </a>
</div>


# Doug Goldberg
Source: https://developer.upsun.com/posts/authors/doug-goldberg

Articles written by Doug Goldberg.

<div>
  <a href="/posts/unknown/adobe-summit-2019">
    <div>
      <div>
        <span>Monday, April 1st 2019</span>
      </div>

      <h3>Adobe Summit 2019: take-aways</h3>
      <p>Discover key announcements from the Adobe Summit 2019, including Magento integration and Adobe Experience Cloud.</p>
    </div>
  </a>

  <a href="/posts/unknown/imagine-2017-the-new-magento-ecosystem">
    <div>
      <div>
        <span>Thursday, April 13th 2017</span>
      </div>

      <h3>Imagine 2017: The New Magento Ecosystem</h3>
      <p>Dive into the excitement of Magento Imagine 2017. Discover how Magento's revitalized spirit and innovative approach are shaping the future of e-commerce.</p>
    </div>
  </a>

  <a href="/posts/unknown/badcamp">
    <div>
      <div>
        <span>Tuesday, October 20th 2015</span>
      </div>

      <h3>Platform.sh to exhibit at BADCamp 2015</h3>
      <p>Platform.sh, a Contrib Level sponsor, will be at BADCamp 2015. Visit our booth for demos and learn about web application hosting.</p>
    </div>
  </a>
</div>


# Duncan Naves
Source: https://developer.upsun.com/posts/authors/duncan-naves

Articles written by Duncan Naves.

<div>
  <img alt="Duncan Naves" />

  <div>
    <a href="https://github.com/duncannaves">GitHub</a>
    <a href="https://www.linkedin.com/in/duncan-naves-a94423aa">LinkedIn</a>
  </div>
</div>

<div>
  <a href="/posts/how-tos/fastlycdn-pluginapp-activation">
    <div>
      <div>
        <span>Tuesday, October 7th 2025</span>
      </div>

      <h3>Streamline Your CDN Management with Fastly CDN Plugin App \[BETA]</h3>
      <p>Managing Content Delivery Network (CDN) configurations alongside your application deployments can be a complex task, often requiring developers to switch between multiple interfaces and tools. The Fastly CDN plugin app bridges this gap by bringing Fastly CDN management directly into your Upsun console, creating a seamless workflow for developers who want to manage their CDN configurations without leaving their primary development environment.</p>
    </div>
  </a>
</div>


# Erika Bustamante
Source: https://developer.upsun.com/posts/authors/erika-bustamante

Articles written by Erika Bustamante.

<div>
  <a href="/posts/unknown/weve-made-changes-to-our-dpa-to-clarify-platformsh-role-under-the-gdpr">
    <div>
      <div>
        <span>Thursday, September 1st 2022</span>
      </div>

      <h3>We’ve made changes to our DPA to clarify Platform.sh role under the GDPR</h3>
      <p>Discover how Platform.sh complies with GDPR, acting as both a data controller and data processor under the European Union's General Data Protection Regulation.</p>
    </div>
  </a>
</div>


# Florent Huck
Source: https://developer.upsun.com/posts/authors/flovntp

Articles written by Florent Huck.

<div>
  <img alt="Florent Huck" />

  <div>
    <a href="https://github.com/flovntp">GitHub</a>
    <a href="https://www.linkedin.com/in/florenthuck">LinkedIn</a>
  </div>
</div>

<ShowMore>
  <a href="/posts/tutorials/ai-log-analysis-agent-in-an-upsun-task-container">
    <div>
      <div>
        <span>Tuesday, September 1st 2026</span>
      </div>

      <h3>Run an AI Log-Analysis Agent in an Upsun Task Container</h3>
      <p>Reuse the cron-triggers-a-task pattern to run an OpenCode AI agent inside an Upsun task container. The agent reads your cron and application logs, analyzes them, and writes a Markdown health report to the task logs and a temporary file.</p>
    </div>
  </a>

  <a href="/posts/tutorials/offload-heavy-jobs-to-upsun-task-containers-with-cron">
    <div>
      <div>
        <span>Thursday, August 20th 2026</span>
      </div>

      <h3>Offload Heavy Jobs to Upsun Task Containers, Triggered by Cron</h3>
      <p>Move long, resource-hungry jobs out of your crons and into on-demand Upsun task containers. Learn how to define a task, authorize your app to trigger it, and fire it from a lightweight cron for database imports or search reindexing.</p>
    </div>
  </a>

  <a href="/posts/ai/opencode-token-optimization">
    <div>
      <div>
        <span>Tuesday, June 2nd 2026</span>
      </div>

      <h3>How to slash OpenCode Token costs by 90% on Upsun</h3>
      <p>Cut your OpenCode token usage by up to 90% on Upsun with three community plugins: OpenSlimedit, opencode-dcp, and opencode-snip. Step-by-step guide to install and configure them on your existing deployment, with benchmarks, troubleshooting, and best practices.</p>
    </div>
  </a>

  <a href="/posts/ai/opencode-on-upsun">
    <div>
      <div>
        <span>Tuesday, May 19th 2026</span>
      </div>

      <h3>How to Host OpenCode on Upsun</h3>
      <p>Deploy an OpenCode AI coding agent on Upsun with a single git push. This tutorial covers configuration, persistent storage, LLM API keys, and remote MCP server integration.</p>
    </div>
  </a>

  <a href="/posts/use-cases/n8n-upgrade-with-postgresql-and-redis">
    <div>
      <div>
        <span>Wednesday, April 29th 2026</span>
      </div>

      <h3>Scale n8n with PostgreSQL and Redis on Upsun</h3>
      <p>Upgrade your n8n instance from SQLite to PostgreSQL and add Redis caching for better performance, scalability, and reliability. Step-by-step guide for Upsun.</p>
    </div>
  </a>

  <a href="/posts/core-concepts/meta-upsun-validation-schema-dx-improvement">
    <div>
      <div>
        <span>Tuesday, April 7th 2026</span>
      </div>

      <h3>How Meta-Upsun improved Validation Schema and Developer eXperience</h3>
      <p>The introduction of Meta-Upsun enabled dynamic validation schemas and version enumeration for Upsun services and runtimes, significantly improving developer experience.</p>
    </div>
  </a>

  <a href="/posts/how-tos/meta-version-updater-introduction">
    <div>
      <div>
        <span>Wednesday, April 1st 2026</span>
      </div>

      <h3>Automating Runtime and Service Tracking with Meta Version Updater</h3>
      <p>Meta is Upsun’s shared reference layer for runtimes, services, regions, and extensions. Learn why we built it, how it works, and how it powers the next generation of Upsun documentation and tooling.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/meta-reference-source-introduction">
    <div>
      <div>
        <span>Wednesday, March 25th 2026</span>
      </div>

      <h3>Centralising Upsun Technical References with Meta-Upsun</h3>
      <p>How Upsun centralised runtime, service, region, and PHP reference data into a single public API to improve consistency, automation, and documentation accuracy.</p>
    </div>
  </a>

  <a href="/posts/releases/upsun-node-sdk-announcement">
    <div>
      <div>
        <span>Wednesday, February 25th 2026</span>
      </div>

      <h3>Announcing the Official Upsun Node.js SDK</h3>
      <p>Discover how the Upsun Node SDK simplifies API access and speeds up integrations, with clear documentation and modern tooling.</p>
    </div>
  </a>

  <a href="/posts/releases/php-85-release">
    <div>
      <div>
        <span>Thursday, November 20th 2025</span>
      </div>

      <h3>PHP 8.5 is here!</h3>
      <p>What if the next PHP revolution made no noise but completely transformed your developer daily life?</p>
    </div>
  </a>

  <a href="/posts/releases/upsun-php-sdk-announcement">
    <div>
      <div>
        <span>Tuesday, November 4th 2025</span>
      </div>

      <h3>Introducing the Upsun PHP SDK</h3>
      <p>Discover how the Upsun PHP SDK simplifies API access and speeds up integrations, with clear documentation and modern tooling.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/autoscaling-deep-dive">
    <div>
      <div>
        <span>Monday, October 20th 2025</span>
      </div>

      <h3>Auto-scaling on Upsun Flex. A deep dive.</h3>
      <p>Learn how Upsun's autoscaling dynamically adjusts application instances based on CPU usage, ensuring performance during traffic spikes while optimizing costs.</p>
    </div>
  </a>

  <a href="/posts/how-tos/composer1-rip">
    <div>
      <div>
        <span>Tuesday, September 9th 2025</span>
      </div>

      <h3>Composer 1 is dead – Upgrade to Composer 2 now</h3>
      <p>Composer 1 has reached end of life and is no longer available on Upsun and Platform.sh. Learn why it’s no longer possible to rely on Composer 1, what errors you’ll see, and how to safely upgrade your project to Composer 2.</p>
    </div>
  </a>

  <a href="/posts/use-cases/n8n-saved-my-life">
    <div>
      <div>
        <span>Thursday, July 3rd 2025</span>
      </div>

      <h3>How n8n saved our Advocacy impact on Social Media!</h3>
      <p>Learn how n8n workflows improve internal communication and amplify our Advocacy social media impact.</p>
    </div>
  </a>

  <a href="/posts/hands-on/nocode-n8n">
    <div>
      <div>
        <span>Wednesday, May 14th 2025</span>
      </div>

      <h3>NoCode with Upsun: Supercharge Your Automation with Zero Code</h3>
      <p>Learn how to leverage Upsun to deploy powerful NoCode tools like n8n for workflow automation. Fast setup, secure hosting, and real-world use cases — all without writing code.</p>
    </div>
  </a>

  <a href="/posts/releases/vscode-extension">
    <div>
      <div>
        <span>Tuesday, May 6th 2025</span>
      </div>

      <h3>Supercharge your workflow with the Upsun VSCode Extension</h3>
      <p>If you're working on Upsun projects with VSCode, the **Upsun VSCode extension** is an essential tool to enhance your development experience. Learn more...</p>
    </div>
  </a>

  <a href="/posts/how-tos/validate-yaml-config">
    <div>
      <div>
        <span>Tuesday, May 6th 2025</span>
      </div>

      <h3>Making .upsun/config.yaml easier to edit with IDE autocomplete and validation</h3>
      <p>Boost your productivity and eliminate configuration errors with real-time autocompletion and validation for your .upsun/config.yaml — discover how to enhance your IDE experience in just a few simple steps!</p>
    </div>
  </a>

  <a href="/posts/tutorials/deploying-clamav-service">
    <div>
      <div>
        <span>Thursday, April 24th 2025</span>
      </div>

      <h3>Deploy ClamAV on Upsun, on service mode.</h3>
      <p>Learn how to deploy ClamAV service on Upsun. This tutorial covers ClamAV integration on service scan mode.</p>
    </div>
  </a>

  <a href="/posts/hands-on/install-gh-asset-on-upsun">
    <div>
      <div>
        <span>Thursday, April 10th 2025</span>
      </div>

      <h3>Up(sun) and ready with GitHub release assets installation</h3>
      <p>Discover how to install any GitHub release asset you want in your Upsun project.</p>
    </div>
  </a>

  <a href="/posts/tutorials/sfcon2024-decouple-frontend">
    <div>
      <div>
        <span>Monday, March 24th 2025</span>
      </div>

      <h3>Decouple your Symfony frontend using Next.js</h3>
      <p>How to decouple your frontend from your backend, using a Symfony project as backend and adding a Next.js application for frontend.</p>
    </div>
  </a>

  <a href="/posts/releases/llms-introduction">
    <div>
      <div>
        <span>Friday, February 14th 2025</span>
      </div>

      <h3>Upsun and Platform.sh Docs are now llms.txt compatible!</h3>
      <p>We’re thrilled to announce that both [Upsun Documentation](https://docs.upsun.com) and [Platform.sh Documentation](https://docs.platform.sh) are now fully compatible with [llms.txt proposed standard](https://llmstxt.org/)!</p>
    </div>
  </a>

  <a href="/posts/how-tos/install-pandoc-on-upsun">
    <div>
      <div>
        <span>Wednesday, February 12th 2025</span>
      </div>

      <h3>Up(sun) and ready with Pandoc</h3>
      <p>With the recent growth in enthusiasm for AI assistants, you may be looking for how these assistants can provide technical information about your product.</p>
    </div>
  </a>

  <a href="/posts/how-tos/blackfire-google-alert-markers-interfaces">
    <div>
      <div>
        <span>Tuesday, November 5th 2024</span>
      </div>

      <h3>Import multiple RSS Feeds on your Blackfire timeline + extra interfaces</h3>
      <p>We saw in the [previous episode](/posts/how-tos/blackfire-google-alert-markers) how to automatically add context on your Blackfire timeline from an RSS Feed (Google Alert),</p>
    </div>
  </a>

  <a href="/posts/how-tos/blackfire-google-alert-markers">
    <div>
      <div>
        <span>Monday, October 7th 2024</span>
      </div>

      <h3>Add context on your Blackfire timeline from a Google Alerts RSS Feed</h3>
      <p>Observing your application is essential to be able to find what needs (and what does not need) to be optimized.</p>
    </div>
  </a>

  <a href="/posts/how-tos/automate-with-gatling-1">
    <div>
      <div>
        <span>Friday, September 20th 2024</span>
      </div>

      <h3>How to automate load tests with Gatling</h3>
      <p>When I was on your side of the keyboard, developing cool and funny applications (more or less :D), load tests were (most of the time) executed a few days before going live.</p>
    </div>
  </a>

  <a href="/posts/tutorials/how-to-host-multiple-applications">
    <div>
      <div>
        <span>Friday, August 16th 2024</span>
      </div>

      <h3>How to host a multiple-application project on Platform.sh</h3>
      <p>Learn how to host and configure multiple-application projects on Platform.sh with this step-by-step guide.</p>
    </div>
  </a>
</ShowMore>


# Fred Plais
Source: https://developer.upsun.com/posts/authors/fred-plais

Articles written by Fred Plais.

<div>
  <a href="/posts/unknown/supporting-drupal-covid-19">
    <div>
      <div>
        <span>Friday, April 17th 2020</span>
      </div>

      <h3>Supporting the Drupal Association through COVID-19</h3>
      <p>Platform.sh remains committed to DrupalCon, Drupal Association, and COVID-19 response initiatives during these challenging times.</p>
    </div>
  </a>

  <a href="/posts/unknown/survival-guide-for-efficient-remote-work">
    <div>
      <div>
        <span>Friday, March 13th 2020</span>
      </div>

      <h3>Voilà! You’re now a distributed workforce</h3>
      <p>A Survival Guide for managers who need to drive a company that became remote overnight due to COVID-19</p>
    </div>
  </a>

  <a href="/posts/unknown/web-dev-plus-IT-unique-roles-equal-partners-in-application-success">
    <div>
      <div>
        <span>Monday, June 24th 2019</span>
      </div>

      <h3>Web dev + IT: unique roles, equal partners in app success</h3>
      <p>Platform.sh enables web development teams to work autonomously without the need for IT assistance, with a focus on governance, security, and compliance.</p>
    </div>
  </a>

  <a href="/posts/unknown/platformsh-full-speed-ahead-into-2019">
    <div>
      <div>
        <span>Tuesday, January 29th 2019</span>
      </div>

      <h3>Platform.sh full speed ahead into 2019</h3>
      <p>Discover Platform.sh's achievements in 2018 and its goals for 2019. From customer success to robust products, see what's in store for the future.</p>
    </div>
  </a>

  <a href="/posts/unknown/the-github-acquisition-its-all-about-cloud-for-microsoft">
    <div>
      <div>
        <span>Tuesday, June 5th 2018</span>
      </div>

      <h3>The Github acquisition: it's all about cloud for Microsoft</h3>
      <p>Explore how Microsoft's acquisition of GitHub aligns with its cloud strategy and the emerging paradigm of GitOps for application deployment to the cloud.</p>
    </div>
  </a>

  <a href="/posts/unknown/expands-usa-operations-meet-growing-demand-north-america">
    <div>
      <div>
        <span>Tuesday, February 14th 2017</span>
      </div>

      <h3>Platform.sh expands its US operations</h3>
      <p>Platform.sh opens its US headquarters in San Francisco, forms a US Advisory board, and launches strong North America recruitment to meet growing demand.</p>
    </div>
  </a>

  <a href="/posts/unknown/vc-ready-funding-survey">
    <div>
      <div>
        <span>Tuesday, October 4th 2016</span>
      </div>

      <h3>Three trends that make successful tech startups attractive to VCs</h3>
      <p>Explore best practices for software development and team management in today's startup landscape. Learn how to build attractive software for VC funding.</p>
    </div>
  </a>

  <a href="/posts/unknown/platform.sh-independent-company">
    <div>
      <div>
        <span>Tuesday, February 9th 2016</span>
      </div>

      <h3>Platform.sh becomes an independent company</h3>
      <p>Exciting news from Platform.sh! We're now an independent company, with a renewed focus on our cloud hosting solution. Read about our journey and plans.</p>
    </div>
  </a>
</div>


# Paul Gilzow
Source: https://developer.upsun.com/posts/authors/gilzow

Articles written by Paul Gilzow.

<div>
  <a href="/posts/how-tos/creating-custom-reports-using-cli">
    <div>
      <div>
        <span>Wednesday, November 12th 2025</span>
      </div>

      <h3>Creating Custom Reports using the Upsun Cloud CLI</h3>
      <p>Someone recently asked me</p>
    </div>
  </a>

  <a href="/posts/how-tos/handling-well-known-directory">
    <div>
      <div>
        <span>Monday, May 26th 2025</span>
      </div>

      <h3>How to manage the `.well-known` directory on Upsun and Platform.sh</h3>
      <p>If you have ever tried to enable</p>
    </div>
  </a>

  <a href="/posts/tutorials/deploying-twill-on-upsun">
    <div>
      <div>
        <span>Wednesday, March 12th 2025</span>
      </div>

      <h3>Up(sun) and Running with Twill</h3>
      <p>This guide provides instructions for deploying and working with [Twill](https://twillcms.com/), an "open-source</p>
    </div>
  </a>

  <a href="/posts/tutorials/upsun-and-running-forem">
    <div>
      <div>
        <span>Friday, January 24th 2025</span>
      </div>

      <h3>Up(sun) and Running with Forem</h3>
      <p>This guide provides instructions for deploying and working with [Forem](https://www.forem.com/), an "open-source</p>
    </div>
  </a>

  <a href="/posts/hands-on/guide-to-limit-deployments-to-platformsh-only-with-tags-part-three">
    <div>
      <div>
        <span>Friday, April 12th 2024</span>
      </div>

      <h3>Limit deployments to Platform.sh only with tags: part three</h3>
      <p>In parts [one](/posts/hands-on/guide-to-limit-deployments-to-platformsh-only-with-tags-part-one) and</p>
    </div>
  </a>

  <a href="/posts/unknown/drupal-camp-florida-2024">
    <div>
      <div>
        <span>Monday, March 25th 2024</span>
      </div>

      <h3>DrupalCamp Florida 2024: sharing takeaways from the experts</h3>
      <p>I had the pleasure of returning to DrupalCamp FL (DCFL) again this year and even now in its sixteenth year, DCFL 2024 was as lively and energetic as ever.</p>
    </div>
  </a>

  <a href="/posts/hands-on/guide-to-limit-deployments-to-platformsh-only-with-tags-part-one">
    <div>
      <div>
        <span>Thursday, March 14th 2024</span>
      </div>

      <h3>Limit deployments to Platform.sh only with tags: part one</h3>
      <p>Throughout the years, many users have asked us if it’s possible to only deploy to Platform.sh when a tag is pushed using</p>
    </div>
  </a>

  <a href="/posts/hands-on/guide-to-limit-deployments-to-platformsh-only-with-tags-part-two">
    <div>
      <div>
        <span>Thursday, March 14th 2024</span>
      </div>

      <h3>Limit deployments to Platform.sh only when Git tagged: part two</h3>
      <p>In [part one of this series](https://platform.sh/blog/guide-to-limit-deployments-to-platformsh-only-with-tags-part-one/),</p>
    </div>
  </a>
</div>


# Guillaume Moigneu
Source: https://developer.upsun.com/posts/authors/gmoigneu

Articles written by Guillaume Moigneu.

<div>
  <img alt="Guillaume Moigneu" />

  <div>
    <a href="https://github.com/gmoigneu">GitHub</a>
    <a href="https://www.linkedin.com/in/guillaumemoigneu/">LinkedIn</a>
  </div>
</div>

<ShowMore>
  <a href="/posts/ai/how-to-choose-a-code-index-for-your-coding-agent">
    <div>
      <div>
        <span>Tuesday, August 4th 2026</span>
      </div>

      <h3>How to choose a code index for your coding agent</h3>
      <p>Compare Graft and roam-code on a real Go, TypeScript, Swift, and SQL codebase to evaluate context coverage, retrieval quality, and change analysis in practice.</p>
    </div>
  </a>

  <a href="/posts/ai/aiweekly-2026-04-27">
    <div>
      <div>
        <span>Monday, April 27th 2026</span>
      </div>

      <h3>AI Weekly Review - Apr. 27th 2026</h3>
      <p>A press, Youtube and Github review of everything AI</p>
    </div>
  </a>

  <a href="/posts/ai/aiweekly-2026-04-13">
    <div>
      <div>
        <span>Monday, April 13th 2026</span>
      </div>

      <h3>AI Weekly Review - Apr. 13th 2026</h3>
      <p>A press, Youtube and Github review of everything AI</p>
    </div>
  </a>

  <a href="/posts/ai/aiweekly-2026-04-07">
    <div>
      <div>
        <span>Tuesday, April 7th 2026</span>
      </div>

      <h3>AI Weekly Review - Apr. 7th 2026</h3>
      <p>A press, Youtube and Github review of everything AI</p>
    </div>
  </a>

  <a href="/posts/ai/aiweekly-2026-03-30">
    <div>
      <div>
        <span>Monday, March 30th 2026</span>
      </div>

      <h3>AI Weekly Review - Mar. 30th 2026</h3>
      <p>A press, Youtube and Github review of everything AI</p>
    </div>
  </a>

  <a href="/posts/ai/stuck-on-localhost">
    <div>
      <div>
        <span>Thursday, March 26th 2026</span>
      </div>

      <h3>Your agents are stuck on localhost. Upsun isn't.</h3>
      <p>Coding agents made engineers faster, but cycle time hasn't budged. Background agents running on GitHub, GitLab, and Claude Code can break the bottleneck by producing PRs that Upsun deploys and validates automatically. A practical guide to setting it up with real YAML configs, infrastructure-as-code workflows, and preview environments.</p>
    </div>
  </a>

  <a href="/posts/ai/aiweekly-2026-03-23">
    <div>
      <div>
        <span>Monday, March 23rd 2026</span>
      </div>

      <h3>AI Weekly Review - Mar. 23rd 2026</h3>
      <p>A press, Youtube and Github review of everything AI</p>
    </div>
  </a>

  <a href="/posts/ai/aiweekly-2026-03-16">
    <div>
      <div>
        <span>Monday, March 16th 2026</span>
      </div>

      <h3>AI Weekly Review - Mar. 16th 2026</h3>
      <p>A press, Youtube and Github review of everything AI</p>
    </div>
  </a>

  <a href="/posts/ai/aiweekly-2026-03-09">
    <div>
      <div>
        <span>Monday, March 9th 2026</span>
      </div>

      <h3>AI Weekly Review - Mar. 9th 2026</h3>
      <p>A press, Youtube and Github review of everything AI</p>
    </div>
  </a>

  <a href="/posts/ai/aiweekly-2026-03-02">
    <div>
      <div>
        <span>Monday, March 2nd 2026</span>
      </div>

      <h3>AI Weekly Review - Mar. 2nd 2026</h3>
      <p>A press, Youtube and Github review of everything AI</p>
    </div>
  </a>

  <a href="/posts/ai/aiweekly-2026-02-23">
    <div>
      <div>
        <span>Monday, February 23rd 2026</span>
      </div>

      <h3>AI Weekly Review - Feb. 23th 2026</h3>
      <p>A press, Youtube and Github review of everything AI</p>
    </div>
  </a>

  <a href="/posts/ai/agents-md-less-is-more">
    <div>
      <div>
        <span>Monday, February 23rd 2026</span>
      </div>

      <h3>The research is in: your AGENTS.md is probably too long</h3>
      <p>Research shows comprehensive AGENTS.md files actually hurt coding agent performance. Learn why less is more and how to build context files that work.</p>
    </div>
  </a>

  <a href="/posts/ai/aiweekly-2026-02-17">
    <div>
      <div>
        <span>Tuesday, February 17th 2026</span>
      </div>

      <h3>AI Weekly Review - Feb. 17th 2026</h3>
      <p>A press, Youtube and Github review of everything AI</p>
    </div>
  </a>

  <a href="/posts/ai/making-coding-agents-reliable">
    <div>
      <div>
        <span>Tuesday, February 17th 2026</span>
      </div>

      <h3>Making coding agents (Claude Code, Codex, etc.) reliable</h3>
      <p>The bottleneck for AI coding agents isn't model capability. It's your verification infrastructure. Here's how to fix that.</p>
    </div>
  </a>

  <a href="/posts/ai/git-worktrees-for-parallel-ai-coding-agents">
    <div>
      <div>
        <span>Wednesday, February 11th 2026</span>
      </div>

      <h3>Git worktrees for parallel AI coding agents</h3>
      <p>Learn how git worktrees enable parallel AI agent workflows, their limitations, and what an ideal orchestration tool needs.</p>
    </div>
  </a>

  <a href="/posts/ai/will-ai-make-software-companies-worthless">
    <div>
      <div>
        <span>Friday, January 30th 2026</span>
      </div>

      <h3>Will AI make software companies worthless?</h3>
      <p>If anyone can build software with AI, do software companies still matter? The answer is more nuanced than you might think.</p>
    </div>
  </a>

  <a href="/posts/hands-on/how-to-use-harlequin-sql-ide-with-upsun">
    <div>
      <div>
        <span>Wednesday, January 14th 2026</span>
      </div>

      <h3>How to Use Harlequin SQL IDE with Upsun</h3>
      <p>Learn two ways to connect Harlequin SQL IDE to your Upsun PostgreSQL database: using local SSH tunnels or deploying Harlequin directly on the platform.</p>
    </div>
  </a>

  <a href="/posts/discussions/the-universal-commerce-protocol-and-the-inevitable-rise-of-agentic-commerce">
    <div>
      <div>
        <span>Monday, January 12th 2026</span>
      </div>

      <h3>The universal commerce protocol and the inevitable rise of agentic commerce</h3>
      <p>Fifteen years ago, I believed the trajectory of digital commerce was destined for a singular, consolidated fate. To me, the technological landscape was fracturing rapidly; the desktop monopoly had shattered, giving way to the mobile web, native applications, and the nascent experiments of Google Glass and early IoT devices. In my view, for independent brands and retailers, this multiplication of channels represented a terrifying escalation in technical complexity. To sell effectively, I thought a merchant needed not just a website, but a mobile-responsive design, an iOS app, an Android app, and integrations with a growing roster of marketplaces.</p>
    </div>
  </a>

  <a href="/posts/discussions/nextjs-cve-2025-66478">
    <div>
      <div>
        <span>Thursday, December 4th 2025</span>
      </div>

      <h3>Critical Next.js Security Update: CVE-2025-66478 Affects RSC</h3>
      <p>Remote code execution vulnerability in Next.js 15.x and 16.x App Router requires immediate patching. Learn how to secure your applications.</p>
    </div>
  </a>

  <a href="/posts/hands-on/ai-use-case-generate-load-test-scenarios">
    <div>
      <div>
        <span>Thursday, November 27th 2025</span>
      </div>

      <h3>AI use-case: Generate load test scenarios with MCPs</h3>
      <p>Automate Locust load testing by combining Chrome MCP and Context7 to generate realistic user behavior patterns with Claude Code.</p>
    </div>
  </a>

  <a href="/posts/insights/my-terminal-setup-mac-linux">
    <div>
      <div>
        <span>Wednesday, November 26th 2025</span>
      </div>

      <h3>My terminal setup (Mac & Linux)</h3>
      <p>A no-nonsense guide to transforming your terminal from painful to powerful with GhostTTY, NeoVim, and Claude Code</p>
    </div>
  </a>

  <a href="/posts/how-it-works/event-loop-monitoring-in-nextjs-performance-guide">
    <div>
      <div>
        <span>Friday, October 24th 2025</span>
      </div>

      <h3>Event Loop Monitoring in Next.js: Performance Guide</h3>
      <p>Learn to implement event loop monitoring in Next.js applications to identify blocking operations, optimize performance, and scale confidently with production-ready code.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/autoscaling-deep-dive">
    <div>
      <div>
        <span>Monday, October 20th 2025</span>
      </div>

      <h3>Auto-scaling on Upsun Flex. A deep dive.</h3>
      <p>Learn how Upsun's autoscaling dynamically adjusts application instances based on CPU usage, ensuring performance during traffic spikes while optimizing costs.</p>
    </div>
  </a>

  <a href="/posts/tutorials/deploying-open-source-on-upsun">
    <div>
      <div>
        <span>Tuesday, October 7th 2025</span>
      </div>

      <h3>Deploying open-source projects on Upsun: Snipe-IT as an example</h3>
      <p>Learn how to deploy any GitHub-hosted open-source project on Upsun by forking repositories, configuring for deployment, and keeping your fork synchronized with upstream updates.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/explore-plan-execute-methodology">
    <div>
      <div>
        <span>Friday, October 3rd 2025</span>
      </div>

      <h3>Mastering the Explore, Plan, Execute methodology for AI-assisted development</h3>
      <p>Learn how to transform AI coding assistants from eager juniors into rockstar developers using proven context strategies, quality assurance, and the three-phase workflow</p>
    </div>
  </a>

  <a href="/posts/tutorials/building-async-processing-pipelines-with-fastapi-and-celery-on-upsun">
    <div>
      <div>
        <span>Friday, October 3rd 2025</span>
      </div>

      <h3>Building async processing pipelines with FastAPI and Celery on Upsun</h3>
      <p>Learn how to build production-ready async processing pipelines using FastAPI and Celery on Upsun. From architecture design to deployment, discover how to handle long-running tasks without blocking your API responses.</p>
    </div>
  </a>

  <a href="/posts/hands-on/building-internal-ai-agents-for-our-teams-on-upsun">
    <div>
      <div>
        <span>Tuesday, September 30th 2025</span>
      </div>

      <h3>Building internal AI agents for our teams on Upsun</h3>
      <p>Learn how to build and deploy production-ready AI agents on Upsun using Google's ADK, ChromaDB vector database, and Retrieval-Augmented Generation (RAG) to create context-aware, domain-specific agents for your team.</p>
    </div>
  </a>

  <a href="/posts/ai/upsun-mcp-announcement">
    <div>
      <div>
        <span>Monday, September 22nd 2025</span>
      </div>

      <h3>Introducing the Upsun MCP server: bring Upsun into your LLMs</h3>
      <p>Manage your Upsun infrastructure directly through AI assistants with our new Model Context Protocol server - now in beta at mcp.upsun.com</p>
    </div>
  </a>

  <a href="/posts/hands-on/store-embeddings-in-chroma-with-persistent-storage-nodejs-and-python-examples">
    <div>
      <div>
        <span>Wednesday, September 3rd 2025</span>
      </div>

      <h3>Store embeddings in chroma with persistent storage (nodejs and python examples)</h3>
      <p>Learn how to implement Chroma with persistent storage on Upsun using both Node.js and Python, including document ingestion and embedding storage.</p>
    </div>
  </a>

  <a href="/posts/hands-on/connect-multiple-projects-applications-or-services-together">
    <div>
      <div>
        <span>Friday, August 15th 2025</span>
      </div>

      <h3>Connect multiple projects applications or services together</h3>
      <p>Learn how to use Chisel to securely connect applications and services across different Upsun projects, with a practical MariaDB replication example.</p>
    </div>
  </a>

  <a href="/posts/insights/why-your-readme-matters-more-than-ai-configuration-files">
    <div>
      <div>
        <span>Tuesday, August 12th 2025</span>
      </div>

      <h3>AGENTS.md: Why your README matters more than AI configuration files</h3>
      <p>AGENTS.md promises to standardize AI coding assistant configuration, but the real solution is writing better READMEs that serve both humans and AI agents</p>
    </div>
  </a>

  <a href="/posts/insights/why-python-developers-should-switch-to-uv">
    <div>
      <div>
        <span>Thursday, August 7th 2025</span>
      </div>

      <h3>Why Python developers should switch to uv</h3>
      <p>Learn how uv, the revolutionary Python package manager, delivers 100x faster installations and streamlines project management with automatic virtual environments and dependency tracking.</p>
    </div>
  </a>

  <a href="/posts/hands-on/gitlab-push-solution">
    <div>
      <div>
        <span>Monday, July 21st 2025</span>
      </div>

      <h3>Synchronize your air-gapped GitLab with Upsun</h3>
      <p>Configure GitLab CI/CD to deploy to Upsun from private air-gapped GitLab instances using push-based workflows and API automation</p>
    </div>
  </a>

  <a href="/posts/insights/why-configuration-as-code-beats-click-and-deploy">
    <div>
      <div>
        <span>Thursday, June 12th 2025</span>
      </div>

      <h3>Git-Driven Infrastructure: Why Configuration as Code Beats Click-and-Deploy</h3>
      <p>Discover why YAML-driven infrastructure outperforms point-and-click deployment for scalable, maintainable applications. Learn best practices for configuration as code.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/mcp-interaction-types-article">
    <div>
      <div>
        <span>Saturday, June 7th 2025</span>
      </div>

      <h3>Beyond Tool Calling: Understanding MCP's Three Core Interaction Types</h3>
      <p>Discover how prompts, resources, and tools work together in the Model Context Protocol to create richer AI application experiences beyond simple tool calling.</p>
    </div>
  </a>

  <a href="/posts/hands-on/deploy-mcp-servers-on-upsun">
    <div>
      <div>
        <span>Thursday, June 5th 2025</span>
      </div>

      <h3>Build and deploy AI-Native Applications with MCP Servers on Upsun</h3>
      <p>Learn how Model Context Protocol servers work with different transports and deploy them to Upsun for scalable AI-powered applications</p>
    </div>
  </a>

  <a href="/posts/insights/advanced-prompting-techniques-for-coding">
    <div>
      <div>
        <span>Thursday, May 8th 2025</span>
      </div>

      <h3>Advanced prompting techniques for complex coding tasks</h3>
      <p>This articles will give you an overview of prompting strategies that help coding assistants reason through difficult problems and produce higher-quality solutions.</p>
    </div>
  </a>

  <a href="/posts/hands-on/pytorch-running-on-upsun">
    <div>
      <div>
        <span>Thursday, May 1st 2025</span>
      </div>

      <h3>How to run PyTorch in an Upsun application?</h3>
      <p>Learn how to deploy a sentiment analysis application powered by PyTorch and FastAPI on the Upsun cloud platform</p>
    </div>
  </a>

  <a href="/posts/how-tos/context7-mcp">
    <div>
      <div>
        <span>Thursday, May 1st 2025</span>
      </div>

      <h3>Upsun documentation is now available via the Context7 MCP</h3>
      <p>Access Upsun documentation directly from your AI workflows using Context7's Model Context Protocol integration</p>
    </div>
  </a>

  <a href="/posts/hands-on/postgres-mcp-on-upsun">
    <div>
      <div>
        <span>Wednesday, April 30th 2025</span>
      </div>

      <h3>Using PostgreSQL MCP with Upsun Remote Database</h3>
      <p>Learn how to set up an MCP server to connect your Upsun PostgreSQL database to language models like Claude or IDE like VSCode GitHub Copilot and Cursor, enabling natural language data queries without writing SQL.</p>
    </div>
  </a>

  <a href="/posts/hands-on/route-ids-env">
    <div>
      <div>
        <span>Monday, April 28th 2025</span>
      </div>

      <h3>How to automatically inject multi-app endpoints as environment variables</h3>
      <p>Learn how to use Upsun route identifiers and the PLATFORM\_ROUTES variable to easily get and use the hostnames of dynamically deployed applications in your project.</p>
    </div>
  </a>

  <a href="/posts/tutorials/oauth-nextjs-laravel">
    <div>
      <div>
        <span>Monday, April 28th 2025</span>
      </div>

      <h3>OAuth authentication between Next.js and Laravel Passport</h3>
      <p>Learn how to implement secure OAuth authentication between a Next.js frontend and Laravel backend using Passport with the Authorization Code Flow and PKCE.</p>
    </div>
  </a>

  <a href="/posts/unknown/nextjs-cve-2025-2997">
    <div>
      <div>
        <span>Tuesday, March 25th 2025</span>
      </div>

      <h3>Next.js Security Vulnerability (CVE-2025-29927): What Upsun Users Need to Know</h3>
      <p>A comprehensive guide to understanding and addressing the recent Next.js security vulnerability CVE-2025-29927 for applications deployed on Upsun.</p>
    </div>
  </a>

  <a href="/posts/releases/elixir-118-release-available">
    <div>
      <div>
        <span>Wednesday, February 26th 2025</span>
      </div>

      <h3>Apologies to the Elixir community: 1.18 release now available</h3>
      <p>Elixir 1.18 is now available on Upsun and Platform.sh with type checking, LSP improvements, and built-in JSON support.</p>
    </div>
  </a>

  <a href="/posts/hands-on/deploying-chainlit-with-rag">
    <div>
      <div>
        <span>Tuesday, January 14th 2025</span>
      </div>

      <h3>Experiment with Chainlit AI interface with RAG on Upsun</h3>
      <p>Learn to deploy production-ready RAG applications with Chainlit and Python on Upsun. Tutorial covers OpenAI Assistants integration, llama\_index implementation, and secure authentication.</p>
    </div>
  </a>

  <a href="/posts/tutorials/laravel-rest-api-on-upsun">
    <div>
      <div>
        <span>Friday, November 15th 2024</span>
      </div>

      <h3>Creating and deploying a Laravel REST API on Upsun in 10 minutes</h3>
      <p>Follow this comprehensive guide to build and deploy a modern Laravel REST API on Upsun's cloud platform. We'll walk through setting up your local development environment, creating API endpoints, and deploying to production with a custom domain. This tutorial is perfect for developers looking to quickly ship production-ready Laravel applications without dealing with complex infrastructure management.</p>
    </div>
  </a>

  <a href="/posts/tutorials/rails8-upsun-tutorial">
    <div>
      <div>
        <span>Wednesday, October 23rd 2024</span>
      </div>

      <h3>Deploy your first Rails 8 application on Upsun</h3>
      <p>Learn how to build and deploy a modern Rails 8 blog application on Upsun's cloud platform. This hands-on tutorial walks you through local development setup, creating a feature-rich blog application, and deploying it to production with proper monitoring and scaling. Discover why Platform-as-a-Service remains relevant even with Rails 8's new deployment features, and learn best practices for cloud deployment. Perfect for developers wanting to quickly ship production-ready Rails applications without managing complex infrastructure.</p>
    </div>
  </a>

  <a href="/posts/discussions/understanding-cors">
    <div>
      <div>
        <span>Monday, September 30th 2024</span>
      </div>

      <h3>Understanding Cross-Origin Resource Sharing (CORS)</h3>
      <p>Learn about Cross-Origin Resource Sharing (CORS), a crucial web security mechanism. Understand its importance, key concepts, and implementation in Symfony, Next.js, and Laravel. Includes practical examples and tips for testing with curl and Postman, plus Platform.sh configuration guidance.</p>
    </div>
  </a>

  <a href="/posts/discussions/preview-environments-a-developers-secret-weapon">
    <div>
      <div>
        <span>Thursday, September 19th 2024</span>
      </div>

      <h3>Preview Environments</h3>
      <p>Discover how preview environments transform software deployment, reducing stress and improving code quality. Learn about the six essential components for implementing preview environments, including Git, infrastructure as code, and automated DNS management. Find out why preview environments are crucial for catching bugs, testing performance, and enhancing collaboration between technical and non-technical team members. Explore how Upsun's platform leverages preview environments to streamline the development process and deliver higher-quality software products.</p>
    </div>
  </a>

  <a href="/posts/hands-on/harnessing-power-embeddings">
    <div>
      <div>
        <span>Monday, May 20th 2024</span>
      </div>

      <h3>Harnessing the power of Embeddings: a real-world example of a watch recommendation app using a vector database.</h3>
      <p>Learn how to build a real-world watch recommendation application using embeddings and a vector database. This tutorial covers using Postgres with pgvector, Laravel, React, OpenAI, and Groq, deployed on Upsun.</p>
    </div>
  </a>

  <a href="/posts/tutorials/deploying-remixjs-app-on-upsun">
    <div>
      <div>
        <span>Friday, March 1st 2024</span>
      </div>

      <h3>Deploying a Remix JS app on Upsun in 5 minutes</h3>
      <p>Learn how to deploy a Remix JS application on Upsun in just 5 minutes. This tutorial covers creating a project, setting up the Node.js server, and deploying your app.</p>
    </div>
  </a>

  <a href="/posts/tutorials/deploying-laravel-with-horizon-on-upsun">
    <div>
      <div>
        <span>Wednesday, February 28th 2024</span>
      </div>

      <h3>Deploying Laravel with Horizon on Upsun</h3>
      <p>Learn how to deploy a Laravel application with Redis queues and Horizon on Upsun, including PostgreSQL database setup, environment configuration, and domain management.</p>
    </div>
  </a>

  <a href="/posts/unknown/are-your-websites-ready-to-handle-traffic-peaks-this-holiday-season">
    <div>
      <div>
        <span>Monday, November 28th 2022</span>
      </div>

      <h3>Are your websites ready to handle traffic peaks this holiday season?</h3>
      <p>Discover how to optimize your website for increased holiday traffic. Learn best practices for performance and customer experience during the busy sales season.</p>
    </div>
  </a>
</ShowMore>


# Augustin Delaporte
Source: https://developer.upsun.com/posts/authors/guguss

Articles written by Augustin Delaporte.

<ShowMore>
  <a href="/posts/tutorials/sfcon2024-decouple-frontend">
    <div>
      <div>
        <span>Monday, March 24th 2025</span>
      </div>

      <h3>Decouple your Symfony frontend using Next.js</h3>
      <p>How to decouple your frontend from your backend, using a Symfony project as backend and adding a Next.js application for frontend.</p>
    </div>
  </a>

  <a href="/posts/unknown/platformsh-partners-with-mongodb-to-help-customers-build-modern-applications-faster">
    <div>
      <div>
        <span>Thursday, October 6th 2022</span>
      </div>

      <h3>Platform.sh partners with MongoDB to help customers build modern applications faster</h3>
      <p>Announcing MongoDB 5.0 for Enterprise and Elite customers. Enjoy improved security, support, and features. Upgrade now for seamless MongoDB integration.</p>
    </div>
  </a>

  <a href="/posts/unknown/automated-code-updates">
    <div>
      <div>
        <span>Friday, April 15th 2022</span>
      </div>

      <h3>Automated code updates</h3>
      <p>Simplify updates and security for critical apps. Platform.sh offers automated source operations to keep your apps up to date.</p>
    </div>
  </a>

  <a href="/posts/unknown/split-projects-and-users-across-organizations">
    <div>
      <div>
        <span>Friday, April 15th 2022</span>
      </div>

      <h3>Split projects and users across multiple organizations</h3>
      <p>Platform.sh now allows creating multiple organizations to suit your project, billing, and contributor management needs.</p>
    </div>
  </a>

  <a href="/posts/unknown/sso-for-platformsh-now-available-for-openid-connect-and-google">
    <div>
      <div>
        <span>Thursday, June 25th 2020</span>
      </div>

      <h3>SSO available for OpenID Connect and Google</h3>
      <p>Enhance security with Single Sign-On for OpenID Connect and Google. Protect your projects with two-factor authentication and password rotation.</p>
    </div>
  </a>

  <a href="/posts/unknown/improve-visibility-over-your-external-integrations">
    <div>
      <div>
        <span>Tuesday, May 12th 2020</span>
      </div>

      <h3>Improve visibility over your external integrations</h3>
      <p>Stay updated with activities from your integrations in the API or CLI. Easily validate, test, and troubleshoot external integrations with Platform.sh.</p>
    </div>
  </a>

  <a href="/posts/unknown/improving-access-and-security-for-your-projects">
    <div>
      <div>
        <span>Monday, April 20th 2020</span>
      </div>

      <h3>Improving access and security for your projects</h3>
      <p>Improved user security measures, including strong password policies and Single Sign-On (SSO) capabilities for enhanced authentication and mitigation control.</p>
    </div>
  </a>

  <a href="/posts/unknown/why-you-should-care-about-wechat-before-its-too-late">
    <div>
      <div>
        <span>Wednesday, October 31st 2018</span>
      </div>

      <h3>Why you should care about WeChat before it's too late!</h3>
      <p>Learn about WeChat, China's super-app, and discover strategies for reaching its vast user base. WeChat's influence on mobile commerce and marketing.</p>
    </div>
  </a>

  <a href="/posts/unknown/platformsh-joins-the-prestigious-french-tech-tour-china-2017">
    <div>
      <div>
        <span>Sunday, December 3rd 2017</span>
      </div>

      <h3>Platform.sh joins the prestigious French Tech Tour China 2017</h3>
      <p>Join our CEO and team in Singapore, Hong Kong, Shenzhen, Shanghai, and Beijing for the French Tech Tour China 2017. Learn more about Platform.sh's journey.</p>
    </div>
  </a>

  <a href="/posts/unknown/deploy-api-platform-on-platformsh">
    <div>
      <div>
        <span>Wednesday, November 29th 2017</span>
      </div>

      <h3>Simplifying API Platform Deployment on Platform.sh</h3>
      <p>Optimize API development with Platform.sh. Deploy API Platform effortlessly and unlock robust backend capabilities for your APIs</p>
    </div>
  </a>

  <a href="/posts/unknown/what-is-your-timezone">
    <div>
      <div>
        <span>Tuesday, December 27th 2016</span>
      </div>

      <h3>What's your timezone?</h3>
      <p>Discover how Platform.sh, a fully distributed company, manages its global team and communication using Node.js and self-hosted timezone.io.</p>
    </div>
  </a>

  <a href="/posts/releases/github-blackfire-platformsh">
    <div>
      <div>
        <span>Tuesday, August 30th 2016</span>
      </div>

      <h3>Develop on GitHub, Deploy on Platform.sh, Test on Blackfire.io</h3>
      <p>Learn how to easily integrate GitHub, Blackfire, and Platform.sh for streamlined code management, deployment, and performance testing.</p>
    </div>
  </a>

  <a href="/posts/unknown/httpoxy">
    <div>
      <div>
        <span>Wednesday, July 20th 2016</span>
      </div>

      <h3>Httpoxy or how Platform.sh keeps your applications safe</h3>
      <p>Ensure your applications' security! We've fixed the Httpoxy vulnerability in every Platform.sh region, so you're safe without any redeployments.</p>
    </div>
  </a>

  <a href="/posts/unknown/new-features-june">
    <div>
      <div>
        <span>Thursday, June 30th 2016</span>
      </div>

      <h3>June Features Update</h3>
      <p>The latest updates and improvements from Platform.sh. From web interface enhancements to CLI improvements and Drupal 8 with Composer updates.</p>
    </div>
  </a>

  <a href="/posts/unknown/drupal-8-release-party">
    <div>
      <div>
        <span>Thursday, November 19th 2015</span>
      </div>

      <h3>Drupal 8.0 has been released... Party time!</h3>
      <p>Join the global Drupal 8 release celebration! Learn more about Drupal 8 parties and deploy it today on Platform.sh for a free trial.</p>
    </div>
  </a>

  <a href="/posts/unknown/work-with-distribution">
    <div>
      <div>
        <span>Tuesday, July 28th 2015</span>
      </div>

      <h3>The correct way to work with Drupal distributions</h3>
      <p>Learn how to easily build and maintain your Drupal site on top of distributions using Platform.sh's support for Drush Make files.</p>
    </div>
  </a>

  <a href="/posts/unknown/release-docs-3-0">
    <div>
      <div>
        <span>Saturday, July 25th 2015</span>
      </div>

      <h3>Documentation version 3.0 released</h3>
      <p>Announcing Platform.sh documentation version 3.0 with improved guides and easier contributions. Explore the new documentation now!</p>
    </div>
  </a>

  <a href="/posts/unknown/best-horizontal-cloud-platform-eurocloud">
    <div>
      <div>
        <span>Friday, July 10th 2015</span>
      </div>

      <h3>Platform.sh elected Best Horizontal Cloud Platform of the year</h3>
      <p>Platform.sh wins Best Cloud Services for horizontal markets at CLOUD WEEK Paris. Discover how Platform.sh empowers marketing teams for agile web development.</p>
    </div>
  </a>

  <a href="/posts/unknown/blackfire-integration">
    <div>
      <div>
        <span>Monday, February 2nd 2015</span>
      </div>

      <h3>Support for Blackfire Profiler</h3>
      <p>Optimize performance with Blackfire Profiler on Platform.sh. Monitor server resources, identify bottlenecks, and compare codebases for better performance.</p>
    </div>
  </a>

  <a href="/posts/unknown/release-ui-1-10">
    <div>
      <div>
        <span>Monday, January 26th 2015</span>
      </div>

      <h3>UI version 1.10 released</h3>
      <p>Announcing Platform.sh UI version 1.10 with easy SSH key upload and snapshot restoration. Enhance your Platform.sh experience. Explore the new features now!</p>
    </div>
  </a>

  <a href="/posts/unknown/release-ui-1-9">
    <div>
      <div>
        <span>Wednesday, December 3rd 2014</span>
      </div>

      <h3>UI version 1.9 released</h3>
      <p>Announcing Platform.sh UI version 1.9 with quick environment access, easy Git and SSH command copying, and unified configuration screens.</p>
    </div>
  </a>
</ShowMore>


# Ivana Kotur
Source: https://developer.upsun.com/posts/authors/ivana-kotur

Articles written by Ivana Kotur.

<div>
  <a href="/posts/unknown/your-guide-to-gdpr-compliance-training-your-employees">
    <div>
      <div>
        <span>Friday, June 8th 2018</span>
      </div>

      <h3>Your Guide to GDPR Compliance: Training your employees</h3>
      <p>Discover the importance of GDPR staff training for data protection and how it can safeguard your organization. Ensure GDPR compliance with informed employees.</p>
    </div>
  </a>

  <a href="/posts/unknown/your-guide-to-gdpr-compliance-transfers-of-personal-data-to-third-countries">
    <div>
      <div>
        <span>Wednesday, May 30th 2018</span>
      </div>

      <h3>Your Guide to GDPR Compliance: Transfers of personal data to third countries</h3>
      <p>International personal data transfers under GDPR and the conditions for such transfers. Ensure your organization complies with data protection rules.</p>
    </div>
  </a>

  <a href="/posts/unknown/your-guide-to-gdpr-compliance-data-protection-impact-assessment-and-security-measures-for-processing-data">
    <div>
      <div>
        <span>Friday, May 25th 2018</span>
      </div>

      <h3>Your Guide to GDPR Compliance: Data protection impact assessment and security measures for processing data</h3>
      <p>Discover how the GDPR's Data Protection Impact Assessment (DPIA) can help you identify and minimize privacy risks, build trust, and achieve compliance.</p>
    </div>
  </a>

  <a href="/posts/unknown/your-guide-to-gdpr-compliance-data-subject-rights">
    <div>
      <div>
        <span>Wednesday, May 23rd 2018</span>
      </div>

      <h3>Your Guide to GDPR Compliance: Data subject rights</h3>
      <p>Explore GDPR data rights: be informed, access, rectify, erase, restrict processing, data portability, object, and automated decision-making.</p>
    </div>
  </a>

  <a href="/posts/unknown/your-guide-to-gdpr-compliance-the-six-principles-of-processing-personal-data">
    <div>
      <div>
        <span>Friday, April 20th 2018</span>
      </div>

      <h3>Your Guide to GDPR Compliance: The Six Principles of Processing Personal Data</h3>
      <p>Discover the six key data protection principles of GDPR and why they are vital for compliance. Learn how to prioritize your GDPR efforts.</p>
    </div>
  </a>

  <a href="/posts/unknown/your-guide-to-gdpr-compliance-roles-and-responsibilities">
    <div>
      <div>
        <span>Monday, April 9th 2018</span>
      </div>

      <h3>Your Guide to GDPR Compliance: Roles and Responsibilities</h3>
      <p>Learn the roles and responsibilities under GDPR - data subject, data controller, data processor. Get ready for GDPR compliance today!</p>
    </div>
  </a>

  <a href="/posts/unknown/your-guide-to-gdpr-compliance-introduction">
    <div>
      <div>
        <span>Wednesday, April 4th 2018</span>
      </div>

      <h3>Your Guide to GDPR Compliance (Introduction)</h3>
      <p>Get ready for GDPR with our comprehensive guide. Understand its impact, your responsibilities, and how to protect personal data and privacy.</p>
    </div>
  </a>
</div>


# Mark Hanna
Source: https://developer.upsun.com/posts/authors/jackrabbithanna

Articles written by Mark Hanna.

<div>
  <img alt="Mark Hanna" />

  <div>
    <a href="https://github.com/jackrabbithanna">GitHub</a>
  </div>
</div>

<div>
  <a href="/posts/hands-on/civicrm-with-wordpress-bedrock-on-upsun">
    <div>
      <div>
        <span>Tuesday, June 30th 2026</span>
      </div>

      <h3>CiviCRM with WordPress Bedrock on Upsun</h3>
      <p>A guide to deploying CiviCRM on top of a Bedrock-based WordPress installation on Upsun, utilizing an optimized Composer template and MariaDB schemas.</p>
    </div>
  </a>

  <a href="/posts/hands-on/civicrm-drupal-11-on-upsun">
    <div>
      <div>
        <span>Friday, December 19th 2025</span>
      </div>

      <h3>Installing CiviCRM with Drupal 11 on Upsun</h3>
      <p>Learn how to install CiviCRM with Drupal 11 on Upsun, from config.yml and databases to cron, caching, extensions and Skvare’s best-practice template.</p>
    </div>
  </a>
</div>


# Jared Wright
Source: https://developer.upsun.com/posts/authors/jared-wright

Articles written by Jared Wright.

<div>
  <img alt="Jared Wright" />

  <div>
    <a href="https://github.com/jww-sh">GitHub</a>
    <a href="https://www.linkedin.com/in/jaredwaynewright">LinkedIn</a>
  </div>
</div>

<div>
  <a href="/posts/tutorials/deploy-mattermost-on-upsun">
    <div>
      <div>
        <span>Friday, February 27th 2026</span>
      </div>

      <h3>Deploy Mattermost Team Edition on Upsun</h3>
      <p>Learn how to deploy a self-hosted Mattermost Team Edition server on Upsun, with PostgreSQL 16 and OpenSearch 2 configured automatically through a single infrastructure-as-code file.</p>
    </div>
  </a>

  <a href="/posts/hands-on/varnish-104-advanced-traffic-filtering-with-classification-headers-on-upsun">
    <div>
      <div>
        <span>Friday, November 7th 2025</span>
      </div>

      <h3>Varnish 104: Advanced Traffic Filtering with Classification Headers on Upsun</h3>
      <p>Learn how to implement advanced security controls in Varnish on Upsun using classification headers to block malicious traffic, restrict geographic access, filter by ASN, and protect sensitive paths with HTTP Basic Auth.</p>
    </div>
  </a>

  <a href="/posts/hands-on/varnish-103-cache-optimization-with-url-normalization-on-upsun">
    <div>
      <div>
        <span>Friday, October 31st 2025</span>
      </div>

      <h3>Varnish 103: Cache Optimization with URL Normalization on Upsun</h3>
      <p>Learn how to maximize Varnish cache efficiency through URL normalization, query string sorting, and tracking parameter removal to dramatically improve cache hit ratios and reduce backend load.</p>
    </div>
  </a>

  <a href="/posts/hands-on/varnish-102-protecting-your-application-with-rate-limiting-on-upsun">
    <div>
      <div>
        <span>Friday, October 24th 2025</span>
      </div>

      <h3>Varnish 102: Protecting Your Application with Rate Limiting on Upsun</h3>
      <p>Learn how to implement effective rate limiting in Varnish using the vsthrottle VMOD to protect your application from abuse, prevent DDoS attacks, and ensure fair resource allocation.</p>
    </div>
  </a>

  <a href="/posts/hands-on/varnish-101-protecting-paths-with-http-basic-authentication-on-upsun">
    <div>
      <div>
        <span>Friday, October 17th 2025</span>
      </div>

      <h3>Varnish 101: Protecting Paths with HTTP Basic Authentication on Upsun</h3>
      <p>Learn how to implement HTTP Basic Authentication directly in Varnish VCL on Upsun to protect specific paths like admin areas, staging environments, and work-in-progress content without touching your backend.</p>
    </div>
  </a>
</div>


# Jessica Orozco
Source: https://developer.upsun.com/posts/authors/jessica-orozco

Articles written by Jessica Orozco.

<div>
  <a href="/posts/unknown/dont-be-held-to-ransom-security-awareness-with-platformsh">
    <div>
      <div>
        <span>Friday, December 2nd 2022</span>
      </div>

      <h3>Don’t be held to ransom: Security awareness with Platform.sh</h3>
      <p>Learn how to safeguard your organization against ransomware attacks. Explore security measures and proactive steps to protect your company's data.</p>
    </div>
  </a>

  <a href="/posts/unknown/overview-video">
    <div>
      <div>
        <span>Monday, November 15th 2021</span>
      </div>

      <h3>New Platform.sh overview video: a proven, 5-step approach helps explain a complex concept</h3>
      <p>Discover what Platform.sh does in this 5-step overview video. Clear explanations, no technical jargon. Learn how it can benefit your business. Watch now!</p>
    </div>
  </a>
</div>


# Joey Stanford
Source: https://developer.upsun.com/posts/authors/joey-stanford

Articles written by Joey Stanford.

<div>
  <a href="/posts/unknown/building-a-trust-centric-culture-for-success">
    <div>
      <div>
        <span>Wednesday, November 8th 2023</span>
      </div>

      <h3>Building a trust-centric culture for success</h3>
      <p>Trust is more than compliance. It drives employee and customer retention, positive word of mouth, and builds your brand reputation. Find out how to build it.</p>
    </div>
  </a>

  <a href="/posts/unknown/update-to-our-privacy-policy">
    <div>
      <div>
        <span>Monday, November 19th 2018</span>
      </div>

      <h3>Update to our Privacy Policy</h3>
      <p>The latest updates to our Privacy Policy, version 2.1, including grammar fixes, GDPR compliance, and a toll-free contact number for California citizens.</p>
    </div>
  </a>

  <a href="/posts/unknown/were-improving-our-communications-tools-at-platformsh">
    <div>
      <div>
        <span>Friday, October 26th 2018</span>
      </div>

      <h3>We're improving our communications tools at Platform.sh</h3>
      <p>We value your privacy. Learn about our email management system, Marketo, and how to change your opt-in status.</p>
    </div>
  </a>

  <a href="/posts/unknown/platformsh-confirms-that-it-is-ready-for-the-gdpr">
    <div>
      <div>
        <span>Wednesday, May 2nd 2018</span>
      </div>

      <h3>Platform.sh confirms that it is ready for the GDPR</h3>
      <p>Discover what GDPR (General Data Protection Regulation) is and how it impacts your organization's data privacy. Learn about our GDPR measures and guidelines.</p>
    </div>
  </a>

  <a href="/posts/unknown/drupal-critical-core-vulnerability-announced">
    <div>
      <div>
        <span>Wednesday, March 28th 2018</span>
      </div>

      <h3>Drupal critical core vulnerability announced</h3>
      <p>Urgent security update for Drupal users. Update to 8.5.1 / 8.4.9 / 8.3.8 / 7.58 immediately. Platform.sh is working on a platform-level fix.</p>
    </div>
  </a>
</div>


# John Grubb
Source: https://developer.upsun.com/posts/authors/john-grubb

Articles written by John Grubb.

<div>
  <a href="/posts/unknown/screencast-composer-and-continuous-integration">
    <div>
      <div>
        <span>Tuesday, May 9th 2017</span>
      </div>

      <h3>Screencast - Composer and Continuous Integration</h3>
      <p>Discover how Platform.sh simplifies Composer usage and streamlines continuous integration. Learn about managing PHP applications effectively.</p>
    </div>
  </a>

  <a href="/posts/unknown/screencast-yaml">
    <div>
      <div>
        <span>Monday, December 19th 2016</span>
      </div>

      <h3>Screencast - Configuring your Platform.sh Project</h3>
      <p>Learn to set up your project on Platform.sh, manage dependencies with infrastructure as code, and gain independence in this quick technical screencast.</p>
    </div>
  </a>

  <a href="/posts/unknown/screencast-basic-platformsh-workflow">
    <div>
      <div>
        <span>Monday, December 5th 2016</span>
      </div>

      <h3>Screencast - Basic Platform.sh Workflow</h3>
      <p>Discover how Platform.sh makes Git branching and merging easier. Streamline your development process in this Platform.sh from Scratch series.</p>
    </div>
  </a>
</div>


# jrmy-deruss
Source: https://developer.upsun.com/posts/authors/jrmy-deruss

Articles written by jrmy-deruss.

<div>
  <a href="/posts/how-tos/no-downtime-postgres-updates">
    <div>
      <div>
        <span>Thursday, January 9th 2025</span>
      </div>

      <h3>How to update your PostgreSQL database without downtime</h3>
      <p>On paper, releasing a new version of your application that requires upgrading the schema of the database is straightforward. But, changes of code and schema can not be updated in an atomic way, you only need to take care that old code is not performing a query against new schema, and reciprocally.</p>
    </div>
  </a>
</div>


# Kathryn Frazer
Source: https://developer.upsun.com/posts/authors/kathryn-frazer

Articles written by Kathryn Frazer.

<div>
  <a href="/posts/unknown/connecting-with-the-community-at-drupalcon-global">
    <div>
      <div>
        <span>Friday, July 24th 2020</span>
      </div>

      <h3>Connecting with the community at DrupalCon Global</h3>
      <p>Discover our highlights from DrupalCon Global, including our partnership with Lando and booth demos. Stay updated on our Drupal community involvement.</p>
    </div>
  </a>
</div>


# Kemi Elizabeth Ojogbede
Source: https://developer.upsun.com/posts/authors/kemiojo

Articles written by Kemi Elizabeth Ojogbede.

<div>
  <a href="/posts/tutorials/deploying-with-lisp">
    <div>
      <div>
        <span>Monday, March 17th 2025</span>
      </div>

      <h3>Up(sun) and running with Lisp</h3>
      <p>Lisp support was discontinued in March 2025. If you really want to power a Lisp project, feel free to reach out on the [Upsun Community Forum](https://community.upsun.com/).</p>
    </div>
  </a>
</div>


# Kieronsambrook Smith
Source: https://developer.upsun.com/posts/authors/kieronsambrook-smith

Articles written by Kieronsambrook Smith.

<div>
  <a href="/posts/unknown/taking-your-application-to-saas-a-business-decision">
    <div>
      <div>
        <span>Friday, April 17th 2020</span>
      </div>

      <h3>High-performance for cloud application development</h3>
      <p>Learn why some applications make it to a \$2 billion SaaS acquisition while others don't. Explore the path to SaaS success with Platform.sh.</p>
    </div>
  </a>

  <a href="/posts/unknown/a-10x-increase-in-enterprise-valuation-over-two-years-a-saas-case-study">
    <div>
      <div>
        <span>Tuesday, April 7th 2020</span>
      </div>

      <h3>SaaS case study: 10x increase in enterprise valuation</h3>
      <p>Learn how an ecommerce company increased valuation via a Platform.sh cloud transition. Explore SaaS benefits, business value, and insights for your model.</p>
    </div>
  </a>

  <a href="/posts/unknown/devops-gives-you-wings">
    <div>
      <div>
        <span>Tuesday, May 9th 2017</span>
      </div>

      <h3>DevOps gives you wings</h3>
      <p>Discover the importance of DevOps and automation for your organization. Learn how Platform.sh can help you achieve better DevOps for competitive success.</p>
    </div>
  </a>

  <a href="/posts/unknown/ez-systems-partnership">
    <div>
      <div>
        <span>Monday, September 19th 2016</span>
      </div>

      <h3>We partnered with eZ Systems to accelerate development</h3>
      <p>eZ Systems and Platform.sh partner to accelerate development with eZ Platform, offering an accelerated path to build content-rich websites and applications.</p>
    </div>
  </a>

  <a href="/posts/unknown/microsoft-joint-paas-offering">
    <div>
      <div>
        <span>Thursday, June 2nd 2016</span>
      </div>

      <h3>Microsoft and Platform.sh announce joint PaaS offering for High Availability (HA) hosting</h3>
      <p>Platform.sh announces plans for scalable web apps in German datacenters, offering 99.99% uptime, and Azure integration. Learn more today!</p>
    </div>
  </a>

  <a href="/posts/unknown/isv-saas-iaas-providers">
    <div>
      <div>
        <span>Wednesday, May 25th 2016</span>
      </div>

      <h3>Software vendor, SaaS or IaaS - doesn’t matter which. Platform.sh really is the killer app for you!</h3>
      <p>Discover how Platform.sh is revolutionizing SaaS, software vendors, and hosting providers by offering innovative solutions in the cloud computing space.</p>
    </div>
  </a>

  <a href="/posts/unknown/magento-enterprise-cloud-edition-powered-by-platform-sh">
    <div>
      <div>
        <span>Tuesday, April 12th 2016</span>
      </div>

      <h3>Platform.sh Provides PaaS Technology to Magento Commerce</h3>
      <p>Discover how Magento Commerce benefits from Platform.sh's second-generation PaaS for its Enterprise Cloud Edition, enhancing development and release management.</p>
    </div>
  </a>

  <a href="/posts/unknown/safe-harbour-safe">
    <div>
      <div>
        <span>Tuesday, November 3rd 2015</span>
      </div>

      <h3>Concerned about the recent European Court ruling on Safe Harbor?</h3>
      <p>Discover the consequences of the EU-US Safe Harbor agreement invalidation and how Platform.sh offers flexibility to protect your data as needed.</p>
    </div>
  </a>

  <a href="/posts/unknown/five-platform-sh-the-paas-for-drupal-8">
    <div>
      <div>
        <span>Thursday, July 16th 2015</span>
      </div>

      <h3>Five reasons why Platform.sh is the PaaS you need for Drupal 8</h3>
      <p>Discover why Drupal 8 on Platform.sh is making waves. From Swiss publishers to usability testing, explore the Drupal 8 hype. Get ready for the future!</p>
    </div>
  </a>
</div>


# kotnik
Source: https://developer.upsun.com/posts/authors/kotnik

Articles written by kotnik.

<div>
  <a href="/posts/how-it-works/building-observability-from-scratch-three-times-over">
    <div>
      <div>
        <span>Tuesday, April 21st 2026</span>
      </div>

      <h3>Building observability from scratch, three times over</h3>
      <p>A look back at how Platform.sh / Upsun's observability evolved from Nagios on a single box to a unified stack across thousands of VMs, and the migration patterns that made each transition smooth.</p>
    </div>
  </a>
</div>


# Laurent Arnoud
Source: https://developer.upsun.com/posts/authors/laurent-arnoud

Articles written by Laurent Arnoud.

<div>
  <div>
    <a href="https://www.linkedin.com/in/laurent-arnoud-861b44121/">LinkedIn</a>
  </div>
</div>

<div>
  <a href="/posts/insights/rate-limiting-rails-apps-when-you-cant-put-varnish-in-front">
    <div>
      <div>
        <span>Tuesday, May 12th 2026</span>
      </div>

      <h3>Rate limiting Rails apps when you can't put Varnish in front</h3>
      <p>When the edge isn't yours, rate limit from inside the application. How rack-attack works, why limits are about quality of service, and what Rails 8 changed.</p>
    </div>
  </a>
</div>


# Jérôme Vieilledent
Source: https://developer.upsun.com/posts/authors/lolautruche

Articles written by Jérôme Vieilledent.

<div>
  <a href="/posts/hands-on/powerup-your-local-development-with-ddev">
    <div>
      <div>
        <span>Thursday, January 5th 2023</span>
      </div>

      <h3>Power-up Your Local Development with DDEV</h3>
      <p>Get the best local development experience with the DDEV-Platform.sh add-on. Follow our guide, share your feedback, and optimize your workflow</p>
    </div>
  </a>

  <a href="/posts/unknown/the-platformsh-cli-is-ready-to-golang">
    <div>
      <div>
        <span>Thursday, November 17th 2022</span>
      </div>

      <h3>The Platform.sh CLI is ready to Go(lang)</h3>
      <p>New Universal Platform.sh CLI, designed to help developers manage projects efficiently, supporting multiple languages and eliminating PHP dependency.</p>
    </div>
  </a>
</div>


# Lyly Lepinay
Source: https://developer.upsun.com/posts/authors/lyly-lepinay

Articles written by Lyly Lepinay.

<div>
  <a href="/posts/unknown/oliver-sweeney-website-revamp-with-magento-cloud-powered-by-platformsh-oozes-sophistication-and-luxury">
    <div>
      <div>
        <span>Friday, March 17th 2017</span>
      </div>

      <h3>Oliver Sweeney website revamp with Magento Cloud</h3>
      <p>When your company sells luxury items, you want your website to offer that same exclusive, stunning digital experience for your customers too.</p>
    </div>
  </a>

  <a href="/posts/unknown/marketing-manager-paris">
    <div>
      <div>
        <span>Friday, June 10th 2016</span>
      </div>

      <h3>Looking for our new marketing manager! Are you the one?</h3>
      <p>Exciting opportunity to join the award-winning Platform.sh marketing team. Grow your career with a groundbreaking hosting and development tool.</p>
    </div>
  </a>

  <a href="/posts/unknown/larry-garfield-joins-platformsh">
    <div>
      <div>
        <span>Monday, May 2nd 2016</span>
      </div>

      <h3>The one and only Director of Runtimes and Integrations</h3>
      <p>Meet Larry Garfield, our new Director of Runtimes, Integrations, and Services. Discover why he's a perfect fit for Platform.sh and connect with him on Twitter.</p>
    </div>
  </a>
</div>


# Manauwar Alam
Source: https://developer.upsun.com/posts/authors/manauwar-alam

Articles written by Manauwar Alam.

<div>
  <a href="/posts/unknown/release-ui-2-13">
    <div>
      <div>
        <span>Tuesday, August 23rd 2016</span>
      </div>

      <h3>UI version 2.13 released</h3>
      <p>Announcing Platform.sh UI version 2.13 with new enhancements, error notifications, SSH key alerts, and better environment handling. Stay informed and organized. Try it now!</p>
    </div>
  </a>

  <a href="/posts/unknown/release-ui-2-12">
    <div>
      <div>
        <span>Monday, July 18th 2016</span>
      </div>

      <h3>UI version 2.12 released</h3>
      <p>Announcing Platform.sh UI version 2.12 with enhancements for easier setup, domain validation, SSH keys, environment management, and user administration. Explore now!</p>
    </div>
  </a>

  <a href="/posts/unknown/release-ui-2-11">
    <div>
      <div>
        <span>Tuesday, July 5th 2016</span>
      </div>

      <h3>UI version 2.11 released</h3>
      <p>Announcing Platform.sh UI version 2.11 with new warning notifications, environment grouping, autofocus on text inputs, and improved display of environment variables.</p>
    </div>
  </a>
</div>


# Matthias Van Woensel
Source: https://developer.upsun.com/posts/authors/matthias-van-woensel

Articles written by Matthias Van Woensel.

<div>
  <div>
    <a href="https://www.linkedin.com/in/matthias-van-woensel-267a069">LinkedIn</a>
  </div>
</div>

<div>
  <a href="/posts/hands-on/that-cron-should-be-a-worker">
    <div>
      <div>
        <span>Wednesday, March 4th 2026</span>
      </div>

      <h3>That cron should be a worker</h3>
      <p>Long-running crons block your deployments, steal resources from your app container, and create support tickets. Here's when to use workers instead.</p>
    </div>
  </a>

  <a href="/posts/insights/why-you-cant-just-add-infinite-php-fpm-workers">
    <div>
      <div>
        <span>Monday, December 8th 2025</span>
      </div>

      <h3>Why you can't just add infinite PHP-FPM workers</h3>
      <p>Workers need memory. Learn how PHP-FPM sizing hints work, why you can't just add infinite workers, and how to tune your worker count based on actual memory usage.</p>
    </div>
  </a>

  <a href="/posts/insights/why-setting-your-php-memory-limit-to-60gb-wont-help">
    <div>
      <div>
        <span>Monday, December 1st 2025</span>
      </div>

      <h3>Why setting your PHP memory limit to 60GB won't help</h3>
      <p>When you see a PHP memory limit error, your instinct shouldn't be to just increase the limit. Learn what PHP memory\_limit actually does and why blindly increasing it can hurt your site's uptime.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/when-php-fpm-runs-out-of-workers-a-502-error-field-guide">
    <div>
      <div>
        <span>Monday, November 24th 2025</span>
      </div>

      <h3>When php-fpm runs out of workers: a 502 error field guide</h3>
      <p>Your PHP site keeps throwing 502 errors. Your CDN shows 503s. Learn why PHP-FPM workers get exhausted and how to diagnose and fix the real problems.</p>
    </div>
  </a>

  <a href="/posts/insights/the-mystery-of-the-shrinking-database-dump">
    <div>
      <div>
        <span>Monday, November 10th 2025</span>
      </div>

      <h3>The mystery of the shrinking database dump</h3>
      <p>Your database uses 10GB but dumps to 100MB. Discover why database dumps shrink, how InnoDB fragmentation works, and how to reclaim that missing storage space.</p>
    </div>
  </a>
</div>


# Maz Mohammadi
Source: https://developer.upsun.com/posts/authors/maz-mohammadi

Articles written by Maz Mohammadi.

<div>
  <a href="/posts/tutorials/deploying-laravel-reverb-on-upsun">
    <div>
      <div>
        <span>Thursday, May 21st 2026</span>
      </div>

      <h3>Deploying Laravel Reverb on Upsun</h3>
      <p>Build a real-time voting app with Laravel and Reverb, deploy it to Upsun, then scale the WebSocket layer horizontally with Redis pub/sub.</p>
    </div>
  </a>
</div>


# Natalie Harper
Source: https://developer.upsun.com/posts/authors/natalie-harper

Articles written by Natalie Harper.

<div>
  <a href="/posts/releases/context-driven-navigation">
    <div>
      <div>
        <span>Thursday, October 3rd 2024</span>
      </div>

      <h3>Context driven navigation</h3>
      <p>You may have noticed some changes to navigation and user settings on your Platform.sh dashboard.</p>
    </div>
  </a>
</div>


# Nicolas Gommenginger
Source: https://developer.upsun.com/posts/authors/ngommenginger

Articles written by Nicolas Gommenginger.

<div>
  <div>
    <a href="https://www.linkedin.com/in/nicolas-gommenginger">LinkedIn</a>
  </div>
</div>

<div>
  <a href="/posts/discussions/give-your-ai-agent-a-system-that-is-safe-to-break">
    <div>
      <div>
        <span>Tuesday, September 8th 2026</span>
      </div>

      <h3>Give your AI agent a system that is safe to break</h3>
      <p>Handing an agent credentials narrows what it can do, not where its mistakes land. Run it inside a branched environment instead, and the worst outcome is a broken copy of your stack.</p>
    </div>
  </a>

  <a href="/posts/discussions/why-ai-agents-need-cloud-sandboxes">
    <div>
      <div>
        <span>Tuesday, March 31st 2026</span>
      </div>

      <h3>Why AI agents need cloud sandboxes</h3>
      <p>AI agents run real commands on real systems. Learn why cloud sandboxes with production data beat local isolation for safe AI agent workflows.</p>
    </div>
  </a>

  <a href="/posts/discussions/how-product-managers-use-preview-environments-and-ai-to-prototype">
    <div>
      <div>
        <span>Thursday, March 5th 2026</span>
      </div>

      <h3>How product managers use preview environments and AI to prototype</h3>
      <p>Learn how product managers at Upsun use AI coding assistants and preview environments to prototype feature ideas, validate concepts with real data, and share interactive demos with stakeholders.</p>
    </div>
  </a>
</div>


# Nick Hardiman
Source: https://developer.upsun.com/posts/authors/nick-hardiman

Articles written by Nick Hardiman.

<div>
  <a href="/posts/unknown/platform-removes-developer-overhead">
    <div>
      <div>
        <span>Thursday, July 31st 2014</span>
      </div>

      <h3>How the Platform.sh PaaS removes developer overhead</h3>
      <p>Platform.sh is a PaaS designed to bring continuous delivery to Drupal. Explore its features and CLI for agile Drupal development.</p>
    </div>
  </a>
</div>


# Nickanderegg
Source: https://developer.upsun.com/posts/authors/nickanderegg

Articles written by Nickanderegg.

<div>
  <a href="/posts/unknown/out-of-the-lab-Node.js-12-features-graduate-from-experimental-status">
    <div>
      <div>
        <span>Tuesday, January 14th 2020</span>
      </div>

      <h3>Node.js 12 features graduate from experimental status</h3>
      <p>Discover the latest Node.js 12 LTS release with performance optimizations and new features. Upgrade your applications seamlessly with Platform.sh. Learn more!</p>
    </div>
  </a>

  <a href="/posts/unknown/sharpen-your-tusks-it-is-time-for-python-3.8">
    <div>
      <div>
        <span>Wednesday, December 18th 2019</span>
      </div>

      <h3>Sharpen your tusks: it's time for Python 3.8</h3>
      <p>Discover the latest features in Python 3.8, including the walrus operator, self-documenting f-strings, and more. Upgrade your Python applications</p>
    </div>
  </a>
</div>


# Nicolas Grekas
Source: https://developer.upsun.com/posts/authors/nicolas-grekas

Articles written by Nicolas Grekas.

<div>
  <img alt="Nicolas Grekas" />

  <div>
    <a href="https://github.com/nicolas-grekas">GitHub</a>
    <a href="https://www.linkedin.com/in/nicolasgrekas/">LinkedIn</a>
  </div>
</div>

<div>
  <a href="/posts/unknown/how-we-scaled-live-connections-for-1200-developers-at-symfonycon">
    <div>
      <div>
        <span>Wednesday, December 17th 2025</span>
      </div>

      <h3>How we scaled live connections for 1200 developers at SymfonyCon</h3>
      <p>A Symfony core contributor's journey from FrankenPHP 502 errors to a stable multi-app architecture that handled hundreds of live connections at SymfonyCon 2025.</p>
    </div>
  </a>
</div>


# Ori Pekelman
Source: https://developer.upsun.com/posts/authors/ori-pekelman

Articles written by Ori Pekelman.

<ShowMore>
  <a href="/posts/releases/bun-support-is-here">
    <div>
      <div>
        <span>Friday, September 8th 2023</span>
      </div>

      <h3>It's out of the Oven: Bun 1.0 support on Platform.sh</h3>
      <p>Bun 1.0 support is now available on Platform.sh. Discover our comparison results against Yarn and how to test Bun 1.0 out for yourself in this article.</p>
    </div>
  </a>

  <a href="/posts/unknown/shiny-new-platformsh-web-management-console">
    <div>
      <div>
        <span>Thursday, April 11th 2019</span>
      </div>

      <h3>Shiny, new Platform.sh management console</h3>
      <p>Explore the new and improved Platform.sh management console, built for better usability and visualization. Try it now and share your feedback!</p>
    </div>
  </a>

  <a href="/posts/unknown/give-the-gift-of-ruby-this-season">
    <div>
      <div>
        <span>Tuesday, December 18th 2018</span>
      </div>

      <h3>Give the gift of Ruby this season</h3>
      <p>Discover the new features in Ruby 2.5 and how to easily upgrade your Ruby apps to the latest version with Platform.sh. Enjoy improved performance and syntax.</p>
    </div>
  </a>

  <a href="/posts/unknown/spectremeltdown-security-update-notice">
    <div>
      <div>
        <span>Friday, January 5th 2018</span>
      </div>

      <h3>Spectre/Meltdown Security Update Notice</h3>
      <p>Platform.sh addresses the Spectre and Meltdown vulnerabilities with scheduled maintenance. Learn more about the updates and potential downtime.</p>
    </div>
  </a>

  <a href="/posts/unknown/gitlab-integration-is-here">
    <div>
      <div>
        <span>Tuesday, December 12th 2017</span>
      </div>

      <h3>GitLab Integration is here!</h3>
      <p>Easily integrate GitLab with Platform.sh for streamlined code management, deployment, and collaboration. Create environments for every branch and pull request.</p>
    </div>
  </a>

  <a href="/posts/unknown/living-on-the-edge-with-ruby-25-preview">
    <div>
      <div>
        <span>Tuesday, December 12th 2017</span>
      </div>

      <h3>Living on the edge with Ruby 2.5 (preview)</h3>
      <p>Discover how to effortlessly migrate your Ruby and Rails applications to Ruby 2.5 on Platform.sh, with enhanced performance and new features.</p>
    </div>
  </a>

  <a href="/posts/unknown/getting-to-5050-women-men-participation-polyconf-a-very-diverse-conference">
    <div>
      <div>
        <span>Thursday, June 8th 2017</span>
      </div>

      <h3>Getting to 50/50: Polyconf, a very diverse conference</h3>
      <p>Learn about PolyConf 2023, a conference promoting diversity in tech. Discover how Platform.sh supports gender diversity and inclusion in the tech community.</p>
    </div>
  </a>

  <a href="/posts/unknown/sponsoring-predotscale-and-election-drinks">
    <div>
      <div>
        <span>Friday, April 21st 2017</span>
      </div>

      <h3>Sponsoring pre-dotScale and election drinks !</h3>
      <p>Platform.sh invites you to enjoy free drinks at Café Delaville in Paris before the dotSecurity and dotScale conferences. A perfect opportunity to mingle!</p>
    </div>
  </a>

  <a href="/posts/unknown/mongodb_apocalypse">
    <div>
      <div>
        <span>Tuesday, January 10th 2017</span>
      </div>

      <h3>Your instances safe from MongoDB Apocalypse on the Platform.sh PaaS</h3>
      <p>Discover why your MongoDB instances are safe on Platform.sh. Our secure architecture keeps your data protected. Join us for peace of mind!</p>
    </div>
  </a>

  <a href="/posts/unknown/the-year-we-won-php">
    <div>
      <div>
        <span>Monday, January 9th 2017</span>
      </div>

      <h3>2016, The Year We Won PHP</h3>
      <p>Why Platform.sh is the preferred choice for hosting PHP applications. From Drupal and Symfony to Magento and more, we're here to make it run seamlessly.</p>
    </div>
  </a>

  <a href="/posts/unknown/http2">
    <div>
      <div>
        <span>Sunday, January 8th 2017</span>
      </div>

      <h3>Announcing HTTP/2 support!</h3>
      <p>Experience blazing-fast website loading times in 2017 with HTTP/2 support on all Platform.sh regions. No setup required; it's already active!</p>
    </div>
  </a>

  <a href="/posts/unknown/leader-php-hosting-multiple-partnerships">
    <div>
      <div>
        <span>Thursday, December 15th 2016</span>
      </div>

      <h3>Platform.sh at the forefront of PHP hosting in 2016</h3>
      <p>Platform.sh is the go-to PaaS for major PHP vendors like Magento, eZ Systems, TYPO3, and Sensio Labs. Get maximum scalability, stability, and performance.</p>
    </div>
  </a>

  <a href="/posts/unknown/php-session-bug">
    <div>
      <div>
        <span>Thursday, December 17th 2015</span>
      </div>

      <h3>All Platform.sh clients kept automatically safe from serious PHP bug</h3>
      <p>PHP session extension bug and how Platform.sh has automatically updated sites to prevent vulnerability. No action required for our customers.</p>
    </div>
  </a>

  <a href="/posts/unknown/best-horizontal-cloud-solution-for-2015-in-europe">
    <div>
      <div>
        <span>Friday, October 9th 2015</span>
      </div>

      <h3>Platform.sh Best Horizontal Cloud Solution for 2015 in Europe</h3>
      <p>Platform.sh awarded Best Horizontal Cloud Solution in Europe by Eurocloud. Find out more.</p>
    </div>
  </a>

  <a href="/posts/unknown/featured-on-bitbucket">
    <div>
      <div>
        <span>Monday, August 17th 2015</span>
      </div>

      <h3>Platform.sh / Bitbucket Integration, featured on the Bitbucket Blog</h3>
      <p>Discover the Bitbucket integration with Platform.sh. Learn how it works in this short screencast. Get the details on the Bitbucket Blog.</p>
    </div>
  </a>

  <a href="/posts/unknown/platform-sh-hiring-interns">
    <div>
      <div>
        <span>Monday, August 10th 2015</span>
      </div>

      <h3>Hiring interns</h3>
      <p>Explore cloud engineering internships at Platform.sh. Gain hands-on experience with high availability cloud infrastructure and cutting-edge technologies.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/how-platform-paas-works">
    <div>
      <div>
        <span>Tuesday, March 3rd 2015</span>
      </div>

      <h3>How the Platform.sh PaaS works</h3>
      <p>Discover how Platform.sh simplifies PaaS. Focus on your code; we manage the rest. Explore our second-generation PaaS for seamless application development.</p>
    </div>
  </a>

  <a href="/posts/discussions/containers-are-the-new-static-binaries">
    <div>
      <div>
        <span>Thursday, February 26th 2015</span>
      </div>

      <h3>Containers are the new static binaries</h3>
      <p>Platform.sh updates: new languages, MariaDB, and PHP 7.2-alpha support. Stay informed and enjoy your containers.</p>
    </div>
  </a>
</ShowMore>


# oripekelman
Source: https://developer.upsun.com/posts/authors/oripekelman

Articles written by oripekelman.

<div>
  <a href="/posts/unknown/lisp">
    <div>
      <div>
        <span>Thursday, August 8th 2019</span>
      </div>

      <h3>We are happy, relieved and somewhat amused to announce the availability of Common Lisp on Platform.sh</h3>
      <p>Discover the history and uniqueness of Lisp, a programming language often called 'the path not taken,' and learn how to deploy a Lisp web applications.</p>
    </div>
  </a>
</div>


# Otavio Santana
Source: https://developer.upsun.com/posts/authors/otavio-santana

Articles written by Otavio Santana.

<div>
  <a href="/posts/unknown/what-is-new-with-jakarta-nosql-part-II">
    <div>
      <div>
        <span>Wednesday, January 8th 2020</span>
      </div>

      <h3>What’s new with Jakarta NoSQL? (Part II)</h3>
      <p>Discover cloud-native with Jakarta EE, best practices, and deploying applications with Jakarta EE NoSQL. Move to the cloud with Platform.sh.</p>
    </div>
  </a>

  <a href="/posts/unknown/microservices-in-the-cloud-part-two">
    <div>
      <div>
        <span>Friday, August 23rd 2019</span>
      </div>

      <h3>Microservices in the cloud, part two</h3>
      <p>Discover microservices, clean code, SOLID principles, and more. Explore Speaker, Session, Conference services with Eclipse MicroProfile.</p>
    </div>
  </a>

  <a href="/posts/unknown/microservices-in-the-cloud-part-one">
    <div>
      <div>
        <span>Tuesday, August 13th 2019</span>
      </div>

      <h3>Microservices in the cloud, part one</h3>
      <p>Microservices are a software architecture, where the systems are a collection of several independent services. Each service has a specific b</p>
    </div>
  </a>

  <a href="/posts/unknown/jakarta-ee-generation-iv-a-new-hope">
    <div>
      <div>
        <span>Tuesday, July 30th 2019</span>
      </div>

      <h3>Jakarta EE: Generation IV - a new hope</h3>
      <p>Explore Jakarta EE & MongoDB on Platform.sh. Build enterprise apps with Java & NoSQL. Easy deployment with our tutorial.</p>
    </div>
  </a>

  <a href="/posts/unknown/eclipse-microprofiles-gain-agility-release-faster">
    <div>
      <div>
        <span>Monday, July 15th 2019</span>
      </div>

      <h3>Eclipse MicroProfiles: gain agility, release faster</h3>
      <p>Explore how Eclipse MicroProfile optimizes Enterprise Java for microservices architecture. Learn about Java frameworks and Platform.sh for cloud deployment.</p>
    </div>
  </a>

  <a href="/posts/unknown/Spring-MVC-and-MongoDB-a-match-made-in-Platform.sh-heaven">
    <div>
      <div>
        <span>Wednesday, June 19th 2019</span>
      </div>

      <h3>Spring MVC and MongoDB: a match made in Platform.sh heaven</h3>
      <p>Learn how to effortlessly integrate Spring MVC with MongoDB on Platform.sh. Create stand-alone, production-grade applications with ease.</p>
    </div>
  </a>

  <a href="/posts/unknown/java-hello-world-at-platform.sh">
    <div>
      <div>
        <span>Thursday, June 6th 2019</span>
      </div>

      <h3>Java: Hello, World! at Platform.sh</h3>
      <p>Discover how to deploy Java applications on Platform.sh. Learn about Spring Boot, MySQL integration, and continuous deployment for Java apps.</p>
    </div>
  </a>
</div>


# Pawan Alwandi
Source: https://developer.upsun.com/posts/authors/palwandi

Articles written by Pawan Alwandi.

<div>
  <img alt="Pawan Alwandi" />

  <div>
    <a href="https://github.com/pawpy">GitHub</a>
    <a href="https://www.linkedin.com/in/pawanalwandi">LinkedIn</a>
  </div>
</div>

<div>
  <a href="/posts/how-it-works/how-we-caught-a-silent-io-storm-before-it-hit-production">
    <div>
      <div>
        <span>Tuesday, April 14th 2026</span>
      </div>

      <h3>How we caught a silent IO storm before it hit production</h3>
      <p>A sysctl setting that worked fine for years caused over 500 MB/s of disk writes after migrating to Debian 12. MariaDB stalled on pending IO, Redis complained about slow fsync, and RBD-backed storage ground to a halt. The culprit: cgroup v2 changes how the kernel divides dirty page budgets across containers.</p>
    </div>
  </a>
</div>


# Patrick Dawkins
Source: https://developer.upsun.com/posts/authors/patrick-dawkins

Articles written by Patrick Dawkins.

<div>
  <img alt="Patrick Dawkins" />

  <div>
    <a href="https://github.com/pjcdawkins">GitHub</a>
    <a href="https://www.linkedin.com/in/patrickdawkins">LinkedIn</a>
  </div>
</div>

<div>
  <a href="/posts/tutorials/sandboxing-ai-agents-on-upsun">
    <div>
      <div>
        <span>Wednesday, April 8th 2026</span>
      </div>

      <h3>Sandboxing AI agents on Upsun</h3>
      <p>Sandbox AI agents in Upsun containers to protect secrets from prompt injection. Covers Linux primitives, Claude Code, and Codex.</p>
    </div>
  </a>

  <a href="/posts/discussions/building-an-ai-code-review-agent-for-gitlab">
    <div>
      <div>
        <span>Thursday, February 19th 2026</span>
      </div>

      <h3>Building an AI code review agent for our self-hosted GitLab</h3>
      <p>I vibe-coded a GitLab code review agent last month - 40K lines of Python written by Claude - and it has reviewed 1000 merge requests.</p>
    </div>
  </a>

  <a href="/posts/discussions/whatsun-efficient-code-analysis">
    <div>
      <div>
        <span>Thursday, December 18th 2025</span>
      </div>

      <h3>Efficient code analysis for LLMs</h3>
      <p>Learn how Whatsun generates concise codebase summaries to improve the performance and accuracy of AI features.</p>
    </div>
  </a>

  <a href="/posts/discussions/building-ai-feature-necessary-evals">
    <div>
      <div>
        <span>Thursday, December 4th 2025</span>
      </div>

      <h3>Building an AI feature: The necessary evals</h3>
      <p>What we learned building an AI feature: evaluations take most of the time, and your existing tools are enough.</p>
    </div>
  </a>
</div>


# Patrick Klima
Source: https://developer.upsun.com/posts/authors/patrick-klima

Articles written by Patrick Klima.

<div>
  <a href="/posts/unknown/integrations-management-through-platform-sh-console">
    <div>
      <div>
        <span>Thursday, June 18th 2020</span>
      </div>

      <h3>View your external integrations through the console</h3>
      <p>View, create, update, and debug your Platform.sh project's external integrations directly from the console for increased control.</p>
    </div>
  </a>

  <a href="/posts/unknown/new-enterprise-pricing-tiers-fleetops">
    <div>
      <div>
        <span>Wednesday, April 15th 2020</span>
      </div>

      <h3>New pricing tiers make FleetOps accessible</h3>
      <p>New product tiers offering features for managing multiple websites. Explore Platform.sh's Elite tier with Technical Account Management, higher SLAs, and more.</p>
    </div>
  </a>
</div>


# Pjcdawkins
Source: https://developer.upsun.com/posts/authors/pjcdawkins

Articles written by Pjcdawkins.

<div>
  <a href="/posts/unknown/release-cli-3-0">
    <div>
      <div>
        <span>Tuesday, March 22nd 2016</span>
      </div>

      <h3>CLI version 3.0 released</h3>
      <p>Announcing Platform.sh CLI version 3.0 with major changes: new file structure, web root location, and PHP requirement. Upgrade now!</p>
    </div>
  </a>

  <a href="/posts/unknown/platformsh-cli-developments-1-10">
    <div>
      <div>
        <span>Monday, March 16th 2015</span>
      </div>

      <h3>Platform.sh CLI developments</h3>
      <p>Explore the latest updates and features in the Platform.sh CLI, the powerful tool for web developers. Manage your projects with ease. Install or upgrade now!</p>
    </div>
  </a>

  <a href="/posts/unknown/release-cli-1-7">
    <div>
      <div>
        <span>Tuesday, January 20th 2015</span>
      </div>

      <h3>CLI version 1.7 released</h3>
      <p>Announcing Platform.sh CLI version 1.7.1 with new features, improved commands, and enhanced HTTP access control. Install or upgrade using Composer!</p>
    </div>
  </a>

  <a href="/posts/unknown/release-cli-1-2">
    <div>
      <div>
        <span>Wednesday, October 29th 2014</span>
      </div>

      <h3>CLI version 1.2 released</h3>
      <p>Announcing Platform.sh CLI version 1.2.2 with new features, colorful interface, safer commands, and more. Install or upgrade using Composer now!</p>
    </div>
  </a>

  <a href="/posts/unknown/release-cli-1-1">
    <div>
      <div>
        <span>Tuesday, September 9th 2014</span>
      </div>

      <h3>CLI version 1.1 released</h3>
      <p>Platform.sh CLI version 1.1.0 is out with new features and commands. Upgrade now! Learn more on GitHub.</p>
    </div>
  </a>
</div>


# prineet-kaur-bhurji
Source: https://developer.upsun.com/posts/authors/prineet-kaur-bhurji

Articles written by prineet-kaur-bhurji.

<div>
  <a href="/posts/releases/introducing-a-more-complete-logs-forwarding-experience">
    <div>
      <div>
        <span>Friday, November 4th 2022</span>
      </div>

      <h3>Introducing a more complete logs forwarding experience</h3>
      <p>Streamline monitoring with centralized log forwarding. Platform.sh now supports log forwarding to Sumologic, New Relic Logs, Splunk, and more. Discover how!</p>
    </div>
  </a>
</div>


# Prineet Kaurbhurji
Source: https://developer.upsun.com/posts/authors/prineet-kaurbhurji

Articles written by Prineet Kaurbhurji.

<div>
  <a href="/posts/unknown/greater-organization-insights-through-weekly-activity-reports-emails">
    <div>
      <div>
        <span>Monday, April 10th 2023</span>
      </div>

      <h3>Greater organization insights through weekly activity reports emails</h3>
      <p>For our Elite/Enterprise customers, we now will be sending weekly activity reports to provide visibility on the key stats and metrics on all projects.</p>
    </div>
  </a>

  <a href="/posts/unknown/infrastructure-metrics-expanded-to-longer-time-frames">
    <div>
      <div>
        <span>Wednesday, February 1st 2023</span>
      </div>

      <h3>Infrastructure Monitoring Metrics with Longer Time Frames</h3>
      <p>Unlock valuable insights with longer time frames in infrastructure metrics on Platform.sh. Make informed decisions for better capacity planning.</p>
    </div>
  </a>
</div>


# Florian Margaine
Source: https://developer.upsun.com/posts/authors/ralt

Articles written by Florian Margaine.

<div>
  <img alt="Florian Margaine" />

  <div>
    <a href="https://github.com/ralt">GitHub</a>
    <a href="https://www.linkedin.com/in/florian-margaine-43971136">LinkedIn</a>
  </div>
</div>

<ShowMore>
  <a href="/posts/insights/session-storage-gets-complicated-faster-than-you-think">
    <div>
      <div>
        <span>Wednesday, September 30th 2026</span>
      </div>

      <h3>Session storage gets complicated faster than you think</h3>
      <p>Explore session storage tradeoffs across files, PostgreSQL, Redis, and Valkey, from expiration and cleanup to memory limits. Test your options on Upsun Cloud.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/airflow-on-a-locked-down-platform">
    <div>
      <div>
        <span>Tuesday, September 22nd 2026</span>
      </div>

      <h3>Airflow on a locked-down platform</h3>
      <p>Running Apache Airflow on Upsun's hardened containers takes 30 lines of C and a decision about how much task isolation you actually want back.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/how-to-host-a-website-that-isnt-publicly-reachable">
    <div>
      <div>
        <span>Thursday, September 3rd 2026</span>
      </div>

      <h3>How to host a website that isn't publicly reachable</h3>
      <p>Some applications should never answer a request from the open internet. Here are the ways to make one unreachable on Upsun, and how to pick between them.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/why-lets-encrypt-certificate-renewals-fail">
    <div>
      <div>
        <span>Tuesday, August 25th 2026</span>
      </div>

      <h3>Why Let's Encrypt certificate renewals fail</h3>
      <p>Certificate renewals fail for a handful of recurring reasons. Here's how the HTTP-01 challenge works and what breaks it, from IPv6 records to CDN rules.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/how-ssh-authentication-works-on-upsun">
    <div>
      <div>
        <span>Tuesday, August 18th 2026</span>
      </div>

      <h3>How SSH authentication works on Upsun Cloud</h3>
      <p>Decode the SSH certificate the Upsun CLI provisions for you, then follow it through the SSH proxy: CA trust, revocation, access documents, and MFA.</p>
    </div>
  </a>

  <a href="/posts/insights/which-stack-would-you-pick-for-an-interactive-ai-app-today">
    <div>
      <div>
        <span>Friday, July 31st 2026</span>
      </div>

      <h3>Which stack would you pick for an interactive AI app today?</h3>
      <p>Coding agents changed how new teams pick a tech stack. A tour of 8 ecosystems for interactive AI apps, and why "can we run it" beats "can we write it".</p>
    </div>
  </a>

  <a href="/posts/how-it-works/backup-consistency-why-it-matters-and-how-upsun-handles-it">
    <div>
      <div>
        <span>Tuesday, July 21st 2026</span>
      </div>

      <h3>Backup consistency: why it matters and how Upsun handles it</h3>
      <p>Learn what backup consistency means at the filesystem and service levels, and how Upsun balances consistent backups with zero-disruption live backups.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/can-you-trust-the-x-client-ip-header">
    <div>
      <div>
        <span>Tuesday, July 14th 2026</span>
      </div>

      <h3>Can you trust the X-Client-IP header?</h3>
      <p>Why the X-Client-IP header on Upsun holds the real visitor IP behind Fastly, Cloudflare, and CloudFront, and how to log real client IPs behind any other CDN.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/write-a-git-server-with-per-branch-permissions-in-five-minutes">
    <div>
      <div>
        <span>Tuesday, July 7th 2026</span>
      </div>

      <h3>Write a Git server with per-branch permissions in five minutes</h3>
      <p>Upsun's most basic API is a Git server. Build one in Python with Dulwich and Paramiko, and add per-branch read permissions in a single method.</p>
    </div>
  </a>

  <a href="/posts/insights/why-emacs-is-still-my-interface-to-my-computer">
    <div>
      <div>
        <span>Tuesday, June 30th 2026</span>
      </div>

      <h3>Why Emacs is still my interface to my computer</h3>
      <p>Why I still use Emacs every day: one consistent interface for editing, Git with Magit, terminals, a Claude Code agent per project, and the rest of my computer.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/cloning-a-terabyte-in-a-minute-and-the-limit-hiding-behind-it">
    <div>
      <div>
        <span>Tuesday, June 23rd 2026</span>
      </div>

      <h3>Cloning a terabyte in a minute, and the limit hiding behind it</h3>
      <p>Upsun clones a terabyte production environment in under a minute using Ceph copy-on-write. Here is the 16-level clone-depth limit behind it, why flattening is the price you pay, and what it says about engineering trade-offs.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/how-redundancy-and-failover-work-on-upsun">
    <div>
      <div>
        <span>Tuesday, June 16th 2026</span>
      </div>

      <h3>How redundancy and failover work on Upsun</h3>
      <p>Upsun handles redundancy and failover inside your region, at the compute, storage, and network layers. Here's where it happens, how fast it is, and the trade-offs behind it.</p>
    </div>
  </a>

  <a href="/posts/insights/code-matters-less-than-ever-and-more-than-ever">
    <div>
      <div>
        <span>Tuesday, June 9th 2026</span>
      </div>

      <h3>Code matters less than ever, and more than ever</h3>
      <p>AI made code cheap to write and cheap to throw away, so it matters less than ever. It also matters more, because debugging, reviews, and velocity all depend on it.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/upsun-deployment-hooks-and-commands-which-one-to-use-and-when">
    <div>
      <div>
        <span>Thursday, June 4th 2026</span>
      </div>

      <h3>Upsun deployment hooks and commands: which one to use, and when</h3>
      <p>Build hooks, deploy hooks, pre\_start, start, and post\_start all shape how Upsun deploys your app. Learn what each one does and when to reach for it.</p>
    </div>
  </a>

  <a href="/posts/insights/ddev-is-in-good-hands">
    <div>
      <div>
        <span>Thursday, May 21st 2026</span>
      </div>

      <h3>DDEV is in good hands</h3>
      <p>DDEV is alive, actively maintained, and back with its foundation. A look at our chapter in the project, why we got involved, and why we are happy to step out of the way.</p>
    </div>
  </a>

  <a href="/posts/insights/the-not-so-hidden-cost-of-ai-scrapers">
    <div>
      <div>
        <span>Tuesday, May 5th 2026</span>
      </div>

      <h3>The (not so) hidden cost of AI scrapers</h3>
      <p>AI scrapers drive up your hosting cost while real users wait. Use robots.txt, cache normalization, and sane application limits to take the pressure off.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/how-upsun-provisions-tls-certificates-at-scale">
    <div>
      <div>
        <span>Thursday, April 9th 2026</span>
      </div>

      <h3>How Upsun provisions TLS certificates at scale</h3>
      <p>Every Upsun environment gets HTTPS automatically. Here's how the certificate system works, from wildcards to Let's Encrypt automation.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/why-upsun-moved-from-lvm-to-ceph">
    <div>
      <div>
        <span>Thursday, April 2nd 2026</span>
      </div>

      <h3>Why we moved from LVM to Ceph for container storage</h3>
      <p>Upsun migrated from LVM to Ceph for container storage to separate compute from storage, enable instant volume migration, and make VMs disposable again.</p>
    </div>
  </a>

  <a href="/posts/discussions/governance-is-a-contract-chain-and-youre-in-it">
    <div>
      <div>
        <span>Tuesday, March 24th 2026</span>
      </div>

      <h3>Governance is a contract chain, and you're in it</h3>
      <p>Governance is a chain of contracts from certification bodies to you. AI didn't change the chain, but it produces code faster than humans can review it.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/rpm-repo-s3">
    <div>
      <div>
        <span>Tuesday, March 17th 2026</span>
      </div>

      <h3>How we host an RPM repository on AWS S3</h3>
      <p>Learn how to host an RPM repository entirely on AWS S3 with no active components, minimal cost, and authenticated access using IAM.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/natural-scaling-for-multi-country-ecommerce">
    <div>
      <div>
        <span>Thursday, March 12th 2026</span>
      </div>

      <h3>Natural scaling for multi-country ecommerce</h3>
      <p>Multi-country ecommerce is a textbook case for natural scaling. Instead of cramming every country into one store, give each its own. Here's why.</p>
    </div>
  </a>

  <a href="/posts/how-tos/replicate-your-production-outage-on-staging">
    <div>
      <div>
        <span>Tuesday, March 10th 2026</span>
      </div>

      <h3>Replicate your production outage on staging</h3>
      <p>After fixing a production outage, you need to prove the fix works under the same traffic. Here's how to replicate real production traffic on an Upsun staging environment using the observability API and k6.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/your-waf-is-buffering-ours-is-streaming">
    <div>
      <div>
        <span>Wednesday, February 18th 2026</span>
      </div>

      <h3>Your WAF is buffering. Ours is streaming.</h3>
      <p>Most WAFs buffer your entire request before validating it. That's slow. Upsun's technical WAF validates requests while streaming them to your backend, so you don't pay a latency tax for security.</p>
    </div>
  </a>

  <a href="/posts/hands-on/scriberr-on-upsun">
    <div>
      <div>
        <span>Tuesday, February 10th 2026</span>
      </div>

      <h3>Scriberr on Upsun</h3>
      <p>Learn how to deploy Scriberr, an AI-powered transcription tool, on Upsun for self-hosted audio and video transcription.</p>
    </div>
  </a>

  <a href="/posts/insights/the-only-correct-way-to-git-pull-and-merge">
    <div>
      <div>
        <span>Tuesday, February 3rd 2026</span>
      </div>

      <h3>The only correct way to git pull and merge</h3>
      <p>A strongly opinionated guide to git pull and merge strategies that will make your commit history actually useful. Learn when to rebase, when to merge, and why the defaults are lying to you.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/spf-dkim-dmarc-what-are-those-for-anyway">
    <div>
      <div>
        <span>Thursday, January 29th 2026</span>
      </div>

      <h3>SPF, DKIM, DMARC, what are those for anyway?</h3>
      <p>Finally understand what SPF, DKIM, and DMARC actually do, why email needs them, and how to set them up without wanting to flip a table.</p>
    </div>
  </a>

  <a href="/posts/insights/the-third-way-to-scale-that-nobody-talks-about">
    <div>
      <div>
        <span>Tuesday, January 20th 2026</span>
      </div>

      <h3>The third way to scale that nobody talks about</h3>
      <p>Beyond vertical and horizontal scaling lies a third approach that most scaling discussions ignore. Learn about natural scaling, where you sidestep the problem entirely.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/how-weve-been-hardening-containers-since-before-docker-made-it-cool">
    <div>
      <div>
        <span>Tuesday, January 13th 2026</span>
      </div>

      <h3>How we've been hardening containers since before Docker made it cool</h3>
      <p>Docker's hardened images are great, but we've been doing this for years. Here's the automated pipeline that's been securing hundreds of container images behind the scenes at Upsun.</p>
    </div>
  </a>

  <a href="/posts/hands-on/stop-testing-jcr-apps-in-production">
    <div>
      <div>
        <span>Tuesday, January 6th 2026</span>
      </div>

      <h3>Stop testing JCR apps in production</h3>
      <p>Learn why JCR-based applications benefit from fast, production-grade environment cloning. Discover how Upsun removes one of JCR's biggest operational challenges through instant repository duplication.</p>
    </div>
  </a>

  <a href="/posts/hands-on/migration-day-executing-your-upsun-cutover">
    <div>
      <div>
        <span>Tuesday, December 16th 2025</span>
      </div>

      <h3>Migration day: executing your Upsun cutover</h3>
      <p>A step-by-step guide to migration day: maintenance windows, cutover sequences, verification, and post-migration monitoring strategies.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/keeping-the-peace-how-zookeeper-stops-database-nodes-from-fighting">
    <div>
      <div>
        <span>Tuesday, December 9th 2025</span>
      </div>

      <h3>Keeping the peace: how ZooKeeper stops database nodes from fighting</h3>
      <p>Learn how Upsun uses Zookeeper's sequences, watchers, and ephemeral nodes to coordinate MariaDB clusters and workers across distributed systems without breaking your application.</p>
    </div>
  </a>

  <a href="/posts/how-tos/planning-your-upsun-migration-the-6-9-week-roadmap">
    <div>
      <div>
        <span>Tuesday, December 2nd 2025</span>
      </div>

      <h3>Planning your Upsun migration: the 6-9 week roadmap</h3>
      <p>Learn why 6-9 weeks is the ideal timeline for Upsun migrations, with expert insights on planning, testing, and avoiding common pitfalls.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/we-switched-from-lvm-to-sparse-files">
    <div>
      <div>
        <span>Friday, November 14th 2025</span>
      </div>

      <h3>We switched from LVM to... sparse files?!</h3>
      <p>How we eliminated 90% of VM evacuation time by replacing LVM with sparse files for temporary storage. A tale of inertia, performance bottlenecks, and surprisingly effective solutions.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/we-made-our-infrastructure-read-only-and-never-looked-back">
    <div>
      <div>
        <span>Monday, November 3rd 2025</span>
      </div>

      <h3>We made our infrastructure read-only and never looked back</h3>
      <p>Learn why read-only infrastructure eliminates entire classes of security attacks, improves reproducibility, and simplifies compliance while enabling predictable deployments.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/fake-ip-till-you-make-ip">
    <div>
      <div>
        <span>Tuesday, October 14th 2025</span>
      </div>

      <h3>Fake IP till you make IP</h3>
      <p>How Upsun uses virtual IPs and NAT to keep your database connections stable even when containers move between VMs. A look at the networking tricks behind relationship stability.</p>
    </div>
  </a>

  <a href="/posts/insights/build-time-environment-variables-considered-harmful">
    <div>
      <div>
        <span>Monday, October 6th 2025</span>
      </div>

      <h3>Build-time environment variables considered harmful</h3>
      <p>Build-time environment variables break deployment caching, compromise security, and force unnecessary rebuilds. Learn why runtime configuration is the better alternative.</p>
    </div>
  </a>

  <a href="/posts/insights/why-you-should-replace-postgresql-with-git-for-your-next-project">
    <div>
      <div>
        <span>Friday, September 19th 2025</span>
      </div>

      <h3>Why you should replace PostgreSQL with Git for your next project</h3>
      <p>Explore how Git's internal architecture makes it a surprisingly capable database alternative. Learn Git's data structures through a practical todo app implementation that might make you reconsider your database choices.</p>
    </div>
  </a>

  <a href="/posts/hands-on/run-tailscale-on-upsun-secure-vpn-connections">
    <div>
      <div>
        <span>Tuesday, September 16th 2025</span>
      </div>

      <h3>Run Tailscale on Upsun: Create secure VPN connections for your applications</h3>
      <p>Learn how to integrate Tailscale VPN with your Upsun applications to create secure, private network connections between your containers and infrastructure.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/cut-aws-bandwidth-costs-95-with-dm-cache">
    <div>
      <div>
        <span>Tuesday, September 9th 2025</span>
      </div>

      <h3>How we cut AWS bandwidth costs 95% with dm-cache: fast local SSD caching for network storage</h3>
      <p>Learn how Upsun solved costly inter-AZ bandwidth billing by implementing dm-cache with local SSDs, achieving 95% read traffic reduction and 30x performance improvement.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/how-do-we-do-incremental-but-really-full-backups-on-top-of-ceph">
    <div>
      <div>
        <span>Monday, August 25th 2025</span>
      </div>

      <h3>High-performance backups: How Ceph snapshots enable incremental full backups</h3>
      <p>Learn how Upsun leverages Ceph's RBD export-diff feature to implement high-performance incremental backups that maintain full restore capabilities for large-scale container storage.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/how-upsun-built-stateless-mesh-networking-for-high-density-containers">
    <div>
      <div>
        <span>Wednesday, August 6th 2025</span>
      </div>

      <h3>How Upsun built stateless mesh networking for high-density containers</h3>
      <p>Discover how Upsun's innovative stateless mesh networking architecture handles thousands of containers without databases or bottlenecks.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/debian-repo-s3">
    <div>
      <div>
        <span>Wednesday, January 29th 2025</span>
      </div>

      <h3>How we host a Debian repository on AWS S3</h3>
      <p>Pretty cool fact about our internal Debian repositories: they’re hosted entirely on AWS S3. Why is that cool? For 2</p>
    </div>
  </a>

  <a href="/posts/how-it-works/how-do-you-manage-ssh-keys-in-your-organization">
    <div>
      <div>
        <span>Wednesday, October 21st 2020</span>
      </div>

      <h3>SSH certificates with Platform.sh</h3>
      <p>Learn how Platform.sh simplifies provisioning SSH certificates for secure and keyless SSH authentication, enhancing security and making compliance easier.</p>
    </div>
  </a>

  <a href="/posts/unknown/gitflow-is-now-supported">
    <div>
      <div>
        <span>Wednesday, August 24th 2016</span>
      </div>

      <h3>GitFlow is now supported on Platform.sh!</h3>
      <p>Learn about our recent infrastructure update with bug fixes and GitFlow branch name support. Enjoy the new features on Platform.sh!</p>
    </div>
  </a>
</ShowMore>


# Ramanathanramakrishnamurthy
Source: https://developer.upsun.com/posts/authors/ramanathanramakrishnamurthy

Articles written by Ramanathanramakrishnamurthy.

<div>
  <a href="/posts/unknown/magento-performance-optimization">
    <div>
      <div>
        <span>Tuesday, February 4th 2025</span>
      </div>

      <h3>Magento performance optimization–Actionable tips and strategies</h3>
      <p>Is your ecommerce store traffic resulting in enough conversions.</p>
    </div>
  </a>
</div>


# Rémi Lejeune
Source: https://developer.upsun.com/posts/authors/remi-lejeune

Articles written by Rémi Lejeune.

<div>
  <a href="/posts/releases/redis-release">
    <div>
      <div>
        <span>Wednesday, June 4th 2025</span>
      </div>

      <h3>Redis 8.0 is here</h3>
      <p>We are excited to announce that **Redis 8.0** is now available for all customers.</p>
    </div>
  </a>

  <a href="/posts/releases/file_size_limit">
    <div>
      <div>
        <span>Wednesday, May 7th 2025</span>
      </div>

      <h3>New file size limits explained</h3>
      <p>To ensure the optimal performance, stability, and reliability of our Git infrastructure, we are introducing a limit on the size of individual files that can be pushed to your project repositories.</p>
    </div>
  </a>

  <a href="/posts/releases/valkey-release">
    <div>
      <div>
        <span>Wednesday, April 16th 2025</span>
      </div>

      <h3>Valkey is now available</h3>
      <p>We're excited to announce the availability of [Valkey](https://valkey.io/), a high-performance, open-source key/value database, now offered as a managed service on Upsun. Valkey serves as a drop-in alternative to Redis, particularly relevant following recent licensing changes to the Redis project.</p>
    </div>
  </a>

  <a href="/posts/how-tos/help-reduce-resource-consumption-put-your-preview-environments-on-pause">
    <div>
      <div>
        <span>Friday, August 18th 2023</span>
      </div>

      <h3>Help reduce resource consumption: Put your preview environments on pause</h3>
      <p>You can now manually pause your idle preview environments or have them automatically paused after 14 days of being idle to minimize your resource usage.</p>
    </div>
  </a>

  <a href="/posts/unknown/its-time-for-version--all-new-upgrades-for-our-api-server">
    <div>
      <div>
        <span>Thursday, January 26th 2023</span>
      </div>

      <h3>Introducing version 19: New upgrades for our API server</h3>
      <p>Unlock the power of Version 19 upgrades, boosting API server performance. Upgrade with Platform.sh for a seamless experience and enhanced capabilities.</p>
    </div>
  </a>

  <a href="/posts/unknown/introducing-our-new-api-and-metrics-servers-upgrades">
    <div>
      <div>
        <span>Thursday, December 15th 2022</span>
      </div>

      <h3>Introducing our new API and Metrics servers upgrades</h3>
      <p>Updates: Jenkins 'H' pattern for cron jobs, result filters for activity scripts, cancellable build and source operations, and the clear build cache activity.</p>
    </div>
  </a>
</div>


# Taras Kruts
Source: https://developer.upsun.com/posts/authors/ribel

Articles written by Taras Kruts.

<div>
  <a href="/posts/hands-on/the-real-story-of-setting-up-drupal-canvas-with-ai">
    <div>
      <div>
        <span>Friday, February 13th 2026</span>
      </div>

      <h3>From DrupalCon keynote to live Upsun demo: the real story of setting up Drupal Canvas with AI</h3>
      <p>Discover how the Lemberg Solutions team set up Drupal Canvas with an AI assistant: how long it took, the challenges we faced and lessons we learned.</p>
    </div>
  </a>
</div>


# Robert Douglass
Source: https://developer.upsun.com/posts/authors/robert-douglass

Articles written by Robert Douglass.

<div>
  <a href="/posts/unknown/global-app-cache-our-managed-tiered-cdn-feature-for-global-page-and-asset-cache-coverage">
    <div>
      <div>
        <span>Wednesday, April 5th 2017</span>
      </div>

      <h3>Global App Cache: Managed CDNs for optimal performance</h3>
      <p>CDN caching boosts website speed and reliability. Learn how our Global App Cache combines multiple CDNs for optimal delivery and 99.99% uptime.</p>
    </div>
  </a>

  <a href="/posts/unknown/a-cloud-for-symfony">
    <div>
      <div>
        <span>Friday, December 2nd 2016</span>
      </div>

      <h3>A Cloud for Symfony</h3>
      <p>Discover SensioCloud, the new comprehensive cloud offering for Symfony applications. Managed services, optimized runtimes, and scalability.</p>
    </div>
  </a>

  <a href="/posts/unknown/typo3-8-starting-platformsh-cloud">
    <div>
      <div>
        <span>Thursday, October 27th 2016</span>
      </div>

      <h3>TYPO3 CMS 8 starting today with Platform.sh in the cloud</h3>
      <p>Try TYPO3 CMS 8 on Platform.sh with Microsoft Azure in Germany. Scale your projects, enjoy developer-friendly features, and ensure data protection.</p>
    </div>
  </a>

  <a href="/posts/unknown/typo3-platformsh-cloud-integration">
    <div>
      <div>
        <span>Thursday, October 13th 2016</span>
      </div>

      <h3>TYPO3 and Platform.sh announce cloud readiness and tech preview of strategic integration</h3>
      <p>Test TYPO3 on Platform.sh cloud hosting. Discover the benefits of this partnership with continuous delivery hosting. Ideal for Composer-based applications.</p>
    </div>
  </a>

  <a href="/posts/unknown/cloud-adoption-europe-data-privacy">
    <div>
      <div>
        <span>Tuesday, June 21st 2016</span>
      </div>

      <h3>Cloud adoption in Europe: Addressing data privacy concerns</h3>
      <p>Discover the advantages of cloud services and data privacy considerations for European enterprises, including Platform.sh's partnership with Microsoft Azure.</p>
    </div>
  </a>
</div>


# roland-molnar
Source: https://developer.upsun.com/posts/authors/roland-molnar

Articles written by roland-molnar.

<div>
  <a href="/posts/discussions/triage-bot">
    <div>
      <div>
        <span>Wednesday, December 18th 2024</span>
      </div>

      <h3>How did we migrate issues from GitLab to Linear?</h3>
      <p>We migrated our issues from GitLab to Linear due to GitLab's limited issue-tracking features. To handle thousands of issues and tight timelines, we developed a migration tool using GitLab Triage Bot and Linear's GraphQL API. The tool mapped issue states, assignees, labels, and comments, and transformed GitLab epics into Linear issues with sub-issues. It was successful overall and enabled team-by-team migration for flexibility. Now, [we’re open-sourcing the migrator](https://github.com/upsun/gitlab-triage-linear-migrator) to help others facing similar challenges.</p>
    </div>
  </a>
</div>


# Sabri Helal
Source: https://developer.upsun.com/posts/authors/sabri-helal

Articles written by Sabri Helal.

<div>
  <a href="/posts/releases/continuous-profiling-comparisons">
    <div>
      <div>
        <span>Wednesday, October 23rd 2024</span>
      </div>

      <h3>Continuous profiling comparisons</h3>
      <p>Upsun’s new continuous profiling comparisons feature provides deeper insights into application performance, enabling you to easily contrast performance metrics over time or between code versions.</p>
    </div>
  </a>

  <a href="/posts/unknown/greener-hosting-starts-with-transparency">
    <div>
      <div>
        <span>Friday, April 22nd 2022</span>
      </div>

      <h3>Greener hosting starts with transparency</h3>
      <p>Platform.sh enhances transparency about its carbon footprint. Make informed choices on where to deploy your projects with data on environmental impact.</p>
    </div>
  </a>
</div>


# Shannon Vettes
Source: https://developer.upsun.com/posts/authors/shannon-vettes

Articles written by Shannon Vettes.

<div>
  <a href="/posts/unknown/1000-tickets-strong">
    <div>
      <div>
        <span>Wednesday, October 22nd 2014</span>
      </div>

      <h3>1000 tickets strong</h3>
      <p>Join us in recognizing the milestone of 1,000 support tickets, showcasing rapid responses, high satisfaction, and efficient issue resolution.</p>
    </div>
  </a>

  <a href="/posts/unknown/sa-core-2014-005">
    <div>
      <div>
        <span>Wednesday, October 15th 2014</span>
      </div>

      <h3>Platform.sh and Drupal 7.32 Core SQL Injection</h3>
      <p>Learn about the Drupal 7.32 security update and the steps taken by Platform.sh to protect your Drupal website from a severe SQL injection vulnerability.</p>
    </div>
  </a>
</div>


# Shawn Ogasawara
Source: https://developer.upsun.com/posts/authors/shawn-ogasawara

Articles written by Shawn Ogasawara.

<div>
  <div>
    <a href="https://www.linkedin.com/in/shawn-ogasawara-83a9a0/">LinkedIn</a>
  </div>
</div>

<div>
  <a href="/posts/hands-on/unstable-website-use-queues">
    <div>
      <div>
        <span>Thursday, February 5th 2026</span>
      </div>

      <h3>Unstable website? Use queues.</h3>
      <p>Your site throws 502 errors when external APIs are slow. The fix isn't more resources. It's offloading that work to background jobs so your responses stay fast.</p>
    </div>
  </a>
</div>


# Shedrack Akintayo
Source: https://developer.upsun.com/posts/authors/shedrack-akintayo

Articles written by Shedrack Akintayo.

<div>
  <a href="/posts/unknown/beginners-guide-to-platformsh">
    <div>
      <div>
        <span>Tuesday, August 17th 2021</span>
      </div>

      <h3>A beginner’s guide to Platform.sh</h3>
      <p>Beginner's guide to Platform.sh: a complete end-to-end cloud Platform-as-a-Service for development teams. Discover the features and developer experience.</p>
    </div>
  </a>
</div>


# Sophie Van Der Kindere
Source: https://developer.upsun.com/posts/authors/sophie-van-der-kindere

Articles written by Sophie Van Der Kindere.

<div>
  <a href="/posts/unknown/whats-the-deal-with-eu-headquartered-iaas-providers">
    <div>
      <div>
        <span>Monday, November 13th 2023</span>
      </div>

      <h3>International data protection with EU-entities of US-headquartered IaaS providers</h3>
      <p>Learn why we use EU-headquartered IaaS providers for maximum data protection and the additional measures we have in place with our providers for GDPR.</p>
    </div>
  </a>
</div>


# Stephen Weinberg
Source: https://developer.upsun.com/posts/authors/stephen-weinberg

Articles written by Stephen Weinberg.

<div>
  <a href="/posts/unknown/deploy-to-the-moon">
    <div>
      <div>
        <span>Friday, April 1st 2016</span>
      </div>

      <h3>Platform.sh announces world’s first LDN for web applications</h3>
      <p>Platform.sh achieves the extraordinary by deploying PHP apps on the lunar surface. Experience the world's first Lunar Delivery Network (LDN).</p>
    </div>
  </a>
</div>


# sylvain-lendrevie
Source: https://developer.upsun.com/posts/authors/sylvain-lendrevie

Articles written by sylvain-lendrevie.

<div>
  <a href="/posts/releases/platformsh-is-always-one-step-ahead-announcing-postgresql--python--and-ruby--for-our-users">
    <div>
      <div>
        <span>Monday, January 16th 2023</span>
      </div>

      <h3>Platform.sh is always one step ahead: Announcing PostgreSQL 15, Python 3.11, and Ruby 3.2 for our users</h3>
      <p>Explore the new features and performance improvements in Python 3.11, PostgreSQL 15, and Ruby 3.2. Stay up-to-date with the latest programming languages.</p>
    </div>
  </a>
</div>


# Tamara Bacchia
Source: https://developer.upsun.com/posts/authors/tamara-bacchia

Articles written by Tamara Bacchia.

<div>
  <a href="/posts/unknown/platformsh-un-global-compact-sdgs-2025">
    <div>
      <div>
        <span>Wednesday, July 30th 2025</span>
      </div>

      <h3>Platform.sh reaffirms commitment to the UN Global Compact and the SDGs</h3>
      <p>We’re pleased to confirm that Platform.</p>
    </div>
  </a>
</div>


# Mickael Gaillard
Source: https://developer.upsun.com/posts/authors/theosakamg

Articles written by Mickael Gaillard.

<div>
  <img alt="Mickael Gaillard" />

  <div>
    <a href="https://github.com/theosakamg">GitHub</a>
  </div>
</div>

<div>
  <a href="/posts/how-tos/meta-version-updater-introduction">
    <div>
      <div>
        <span>Wednesday, April 1st 2026</span>
      </div>

      <h3>Automating Runtime and Service Tracking with Meta Version Updater</h3>
      <p>Meta is Upsun’s shared reference layer for runtimes, services, regions, and extensions. Learn why we built it, how it works, and how it powers the next generation of Upsun documentation and tooling.</p>
    </div>
  </a>

  <a href="/posts/how-it-works/meta-reference-source-introduction">
    <div>
      <div>
        <span>Wednesday, March 25th 2026</span>
      </div>

      <h3>Centralising Upsun Technical References with Meta-Upsun</h3>
      <p>How Upsun centralised runtime, service, region, and PHP reference data into a single public API to improve consistency, automation, and documentation accuracy.</p>
    </div>
  </a>

  <a href="/posts/releases/upsun-node-sdk-announcement">
    <div>
      <div>
        <span>Wednesday, February 25th 2026</span>
      </div>

      <h3>Announcing the Official Upsun Node.js SDK</h3>
      <p>Discover how the Upsun Node SDK simplifies API access and speeds up integrations, with clear documentation and modern tooling.</p>
    </div>
  </a>

  <a href="/posts/how-tos/fastlycdn-pluginapp-activation">
    <div>
      <div>
        <span>Tuesday, October 7th 2025</span>
      </div>

      <h3>Streamline Your CDN Management with Fastly CDN Plugin App \[BETA]</h3>
      <p>Managing Content Delivery Network (CDN) configurations alongside your application deployments can be a complex task, often requiring developers to switch between multiple interfaces and tools. The Fastly CDN plugin app bridges this gap by bringing Fastly CDN management directly into your Upsun console, creating a seamless workflow for developers who want to manage their CDN configurations without leaving their primary development environment.</p>
    </div>
  </a>

  <a href="/posts/ai/upsun-mcp-announcement">
    <div>
      <div>
        <span>Monday, September 22nd 2025</span>
      </div>

      <h3>Introducing the Upsun MCP server: bring Upsun into your LLMs</h3>
      <p>Manage your Upsun infrastructure directly through AI assistants with our new Model Context Protocol server - now in beta at mcp.upsun.com</p>
    </div>
  </a>

  <a href="/posts/use-cases/n8n-saved-my-life">
    <div>
      <div>
        <span>Thursday, July 3rd 2025</span>
      </div>

      <h3>How n8n saved our Advocacy impact on Social Media!</h3>
      <p>Learn how n8n workflows improve internal communication and amplify our Advocacy social media impact.</p>
    </div>
  </a>

  <a href="/posts/releases/vscode-extension">
    <div>
      <div>
        <span>Tuesday, May 6th 2025</span>
      </div>

      <h3>Supercharge your workflow with the Upsun VSCode Extension</h3>
      <p>If you're working on Upsun projects with VSCode, the **Upsun VSCode extension** is an essential tool to enhance your development experience. Learn more...</p>
    </div>
  </a>

  <a href="/posts/tutorials/deploying-clamav-service">
    <div>
      <div>
        <span>Thursday, April 24th 2025</span>
      </div>

      <h3>Deploy ClamAV on Upsun, on service mode.</h3>
      <p>Learn how to deploy ClamAV service on Upsun. This tutorial covers ClamAV integration on service scan mode.</p>
    </div>
  </a>

  <a href="/posts/tutorials/deploying-clamav-onetime">
    <div>
      <div>
        <span>Friday, February 14th 2025</span>
      </div>

      <h3>Deploy ClamAV on Upsun, on one-time scan</h3>
      <p>Learn how to deploy ClamAV service on Upsun. This tutorial covers ClamAV integration on one-time scan mode.</p>
    </div>
  </a>
</div>


# Thomas di Luccio
Source: https://developer.upsun.com/posts/authors/thomasdiluccio

Articles written by Thomas di Luccio.

<div>
  <a href="/posts/releases/composer-2.9">
    <div>
      <div>
        <span>Thursday, December 25th 2025</span>
      </div>

      <h3>Composer 2.9 lands on Upsun PHP Images: Here’s what you need to know</h3>
      <p>Remote code execution vulnerability in Next.js 15.x and 16.x App Router requires immediate patching. Learn how to secure your applications.</p>
    </div>
  </a>

  <a href="/posts/releases/composable-image-embraces-real-world-diversity">
    <div>
      <div>
        <span>Thursday, December 11th 2025</span>
      </div>

      <h3>One project, many needs: How Composable Image embraces real-world diversity</h3>
      <p>Applications rarely fit inside a single tidy runtime box. They evolve through experiments, architectural shifts, quick MVP spikes that outlast their intended lifespan, and the continuous layering of new business needs.</p>
    </div>
  </a>

  <a href="/posts/use-cases/wordpress-performance-optimization-with-blackfire">
    <div>
      <div>
        <span>Tuesday, April 16th 2024</span>
      </div>

      <h3>Meeting Jonny Harris: WordPress performance optimization with Blackfire</h3>
      <p>Jonny Harris is a WordPress core contributor and committer based in the UK and a member of the WordPress Performance</p>
    </div>
  </a>

  <a href="/posts/unknown/infrastructure-metrics-for-all-professional-projects">
    <div>
      <div>
        <span>Tuesday, May 3rd 2022</span>
      </div>

      <h3>Infrastructure Metrics available for all Professional projects</h3>
      <p>Gain insight into your application's behavior with observability and metrics on Platform.sh. Monitor CPU, RAM, disk space, and more for informed decisions.</p>
    </div>
  </a>
</div>


# Tom Helmer Hansen
Source: https://developer.upsun.com/posts/authors/tom-helmer-hansen

Articles written by Tom Helmer Hansen.

<div>
  <a href="/posts/unknown/how-digital-agency-adapt-innovates-without-heavy-lifting">
    <div>
      <div>
        <span>Wednesday, February 3rd 2021</span>
      </div>

      <h3>How digital agency Adapt innovates—without heavy-lifting</h3>
      <p>Discover how to optimize websites using Statamic on Laravel with Platform.sh. Flexible, secure, and editor-friendly solutions for developers and editors.</p>
    </div>
  </a>
</div>


# Upsun
Source: https://developer.upsun.com/posts/authors/upsun

Articles written by Upsun.

<ShowMore>
  <a href="/posts/unknown/evolve-partner-summit-awards">
    <div>
      <div>
        <span>Monday, September 23rd 2024</span>
      </div>

      <h3>It's almost time…Platform.sh’s Evolve Partner Summit Awards</h3>
      <p>We’d love for you to join us in Paris to celebrate the incredible work you’ve done.</p>
    </div>
  </a>

  <a href="/posts/unknown/pandemic-caused-spike-in-cybercrime">
    <div>
      <div>
        <span>Thursday, May 26th 2022</span>
      </div>

      <h3>The pandemic has indeed caused a massive spike in cybercrime</h3>
      <p>Insights from Joey Stanford, VP of Privacy & Security at Platform.sh, on cybersecurity trends, challenges, and the future of security for modern businesses.</p>
    </div>
  </a>

  <a href="/posts/unknown/managing-multiple-website">
    <div>
      <div>
        <span>Thursday, January 27th 2022</span>
      </div>

      <h3>The secret to managing multiple websites</h3>
      <p>Learn how a unified DevOps strategy can help manage a diverse website portfolio at scale while controlling costs and driving predictability with Platform.sh.</p>
    </div>
  </a>

  <a href="/posts/unknown/lazard-names-platformsh-to-their-t100-index">
    <div>
      <div>
        <span>Monday, February 1st 2021</span>
      </div>

      <h3>Lazard names Platform.sh to their T100 Index</h3>
      <p>Lazard recognizes Platform.sh as a top European company with disruptive potential. Learn how we enable innovation and flexibility for businesses.</p>
    </div>
  </a>

  <a href="/posts/unknown/platformsh-joins-gaia-x">
    <div>
      <div>
        <span>Monday, December 7th 2020</span>
      </div>

      <h3>Platform.sh joins the Gaia-X data infrastructure initiative</h3>
      <p>Platform.sh partners with Gaia-X, boosting EU data security and processing. Trusted by leading European institutions, we're committed to a secure data future.</p>
    </div>
  </a>

  <a href="/posts/unknown/microsoft-azure-west-datacenter">
    <div>
      <div>
        <span>Tuesday, September 8th 2020</span>
      </div>

      <h3>Expansion of Microsoft Azure Data Center services</h3>
      <p>Platform.sh expands to Microsoft Azure West US 2, offering agile teams in the West faster access. Learn more about our end-to-end web platform.</p>
    </div>
  </a>

  <a href="/posts/unknown/platformsh-covid-19-response">
    <div>
      <div>
        <span>Tuesday, March 17th 2020</span>
      </div>

      <h3>A note to Platform.sh customers about COVID-19 preparedness</h3>
      <p>Platform.sh remains fully operational during the COVID-19 pandemic. Learn about our measures to ensure business continuity and employee safety.</p>
    </div>
  </a>

  <a href="/posts/releases/deploy-strapi-on-platformsh">
    <div>
      <div>
        <span>Tuesday, March 3rd 2020</span>
      </div>

      <h3>Platform.sh–deploying the future of content with one click</h3>
      <p>Platform.sh and Strapi empower developers with a headless CMS solution for streamlined digital experiences. Deploy Strapi instantly. Learn more</p>
    </div>
  </a>

  <a href="/posts/unknown/strong-customer-authentication">
    <div>
      <div>
        <span>Thursday, September 26th 2019</span>
      </div>

      <h3>Strong Customer Authentication will be required for European credit and bank card payments</h3>
      <p>Get ready for Strong Customer Authentication (SCA) in Europe. Ensure your Platform.sh account complies with new credit card payment security regulations.</p>
    </div>
  </a>

  <a href="/posts/unknown/security-updates-for-php-rolling-out-now">
    <div>
      <div>
        <span>Wednesday, September 11th 2019</span>
      </div>

      <h3>Security updates for PHP: rolling out now</h3>
      <p>Stay secure with the latest PHP updates. Learn how Platform.sh ensures your protection with automatic upgrades. No action needed on your part.</p>
    </div>
  </a>

  <a href="/posts/unknown/version-will-be-required-in-type-what-it-means-for-your-projects">
    <div>
      <div>
        <span>Monday, July 22nd 2019</span>
      </div>

      <h3>Version will be required in type: what it means for your projects</h3>
      <p>Important changes to Platform.sh configuration requirements. Learn how including versions in your configurations impacts your projects.</p>
    </div>
  </a>

  <a href="/posts/unknown/four-days-four-languages-four-frameworks-day-3-gatsbyjs-the-reactbased-static-site-generator">
    <div>
      <div>
        <span>Thursday, February 28th 2019</span>
      </div>

      <h3>4 days, 4 languages, 4 frameworks, Day 3: GatsbyJS</h3>
      <p>Explore how to run GatsbyJS, a Progressive Web App (PWA), on Platform.sh. Learn about JAMstack architecture and deploy your Gatsby site easily.</p>
    </div>
  </a>

  <a href="/posts/unknown/four-days-four-languages-four-frameworks-day-2-running-hugo">
    <div>
      <div>
        <span>Wednesday, February 27th 2019</span>
      </div>

      <h3>4 days, 4 languages, 4 frameworks, Day 2: Running Hugo</h3>
      <p>Learn how to build a static site with Hugo on Platform.sh. Hugo is a fast and light static site generator that's easy to use with Platform.sh.</p>
    </div>
  </a>

  <a href="/posts/unknown/four-days-four-languages-four-frameworks-on-platformsh">
    <div>
      <div>
        <span>Tuesday, February 26th 2019</span>
      </div>

      <h3>Four days, four languages, four frameworks on Platform.sh</h3>
      <p>Learn how to run Brightspot CMS, a Java-based content management system, on Platform.sh with Apache Tomcat, MySQL, and Solr. Deploy with ease</p>
    </div>
  </a>

  <a href="/posts/unknown/platformsh-wins-2018-stratus-award-for-cloud-computing">
    <div>
      <div>
        <span>Thursday, August 30th 2018</span>
      </div>

      <h3>Platform.sh Wins 2018 Stratus Award for Cloud Computing</h3>
      <p>Platform.sh wins 2018 Stratus Award for Cloud Computing in the Platform-as-a-Service category by Business Intelligence Group.</p>
    </div>
  </a>

  <a href="/posts/unknown/platformsh-raises-34m-to-bring-speed-and-confidence-to-enterprise-cloud-deployments">
    <div>
      <div>
        <span>Wednesday, May 23rd 2018</span>
      </div>

      <h3>Platform.sh raises \$34M in series C funding</h3>
      <p>Platform.sh secures \$34M in Series C funding to accelerate growth and support customers in North America. Simplify cloud infrastructures with Platform.sh.</p>
    </div>
  </a>

  <a href="/posts/unknown/platformsh-is-ready-to-make-an-impact-in-china">
    <div>
      <div>
        <span>Wednesday, January 24th 2018</span>
      </div>

      <h3>Platform.sh is ready to make an Impact in China</h3>
      <p>Platform.sh is partnering with Impact China 2018 to help China ready startups expand their operations in China and offer cloud hosting services in the region.</p>
    </div>
  </a>

  <a href="/posts/unknown/symfony-documentation-pull-requests">
    <div>
      <div>
        <span>Thursday, September 10th 2015</span>
      </div>

      <h3>Platform.sh hosts Symfony documentation GitHub pull requests</h3>
      <p>Symfony's documentation now uses Platform.sh for automatic code deployment into isolated environments, simplifying review and testing.</p>
    </div>
  </a>

  <a href="/posts/unknown/ceo-interviewed-on-bfm-business">
    <div>
      <div>
        <span>Wednesday, July 8th 2015</span>
      </div>

      <h3>CEO of Commerce Guys is interviewed by the main French Business TV Channel about Platform.sh</h3>
      <p>Fred Plais, Platform.sh CEO, discusses Platform.sh's innovation and European Grant on French business TV channel interview.</p>
    </div>
  </a>

  <a href="/posts/unknown/european-horizon-2020-grant">
    <div>
      <div>
        <span>Thursday, June 25th 2015</span>
      </div>

      <h3>Platform.sh awarded a €1.95M grant</h3>
      <p>PaaS leader Platform.sh receives EU innovation grant. Explore their ambitious roadmap for multi-cloud, distributed storage, and more.</p>
    </div>
  </a>

  <a href="/posts/unknown/2015-06-european-cloud-leadership-born-in-france">
    <div>
      <div>
        <span>Tuesday, June 23rd 2015</span>
      </div>

      <h3>European cloud leadership is being born before our very own eyes in France</h3>
      <p>Discover how Platform.sh achieved success following Commerce Guys with 250+ customers worldwide.</p>
    </div>
  </a>

  <a href="/posts/unknown/groundbreaking-drupal-8-news-portal-goes-live-platformsh">
    <div>
      <div>
        <span>Wednesday, May 13th 2015</span>
      </div>

      <h3>Groundbreaking Drupal 8 news portal goes live on Platform.sh</h3>
      <p>Platform.sh, PaaS leader, is hosting one of the first Enterprise production sites on Drupal 8. Platform.sh enhances development workflows.</p>
    </div>
  </a>

  <a href="/posts/unknown/us-platform-adoption">
    <div>
      <div>
        <span>Wednesday, November 5th 2014</span>
      </div>

      <h3>Leading digital agencies adopt Platform.sh to support Continuous Delivery</h3>
      <p>Discover the benefits of Platform.sh for hosting Drupal and Symfony web applications. Streamline development, reduce costs, and improve deployment.</p>
    </div>
  </a>

  <a href="/posts/unknown/wunderkraut-chooses-platform">
    <div>
      <div>
        <span>Tuesday, September 30th 2014</span>
      </div>

      <h3>Wunderkraut adopts Platform.sh for all of its 14 international offices</h3>
      <p>Wunderkraut announces their partnership for adopting Platform.sh in all 14 international offices, enhancing cloud hosting and development.</p>
    </div>
  </a>

  <a href="/posts/unknown/platform-removes-developer-overhead-6">
    <div>
      <div>
        <span>Tuesday, September 23rd 2014</span>
      </div>

      <h3>FlixBus launches new eCommerce Service on Platform.sh Enterprise</h3>
      <p>sh is a one-stop solution offering a new paradigm in collaborative web development and live hosting London, U.</p>
    </div>
  </a>

  <a href="/posts/unknown/commerce-guys-launches-platform">
    <div>
      <div>
        <span>Tuesday, May 13th 2014</span>
      </div>

      <h3>Commerce Guys Launches Platform.sh, Continuous Delivery Cloud on Amazon Web Services</h3>
      <p>Discover Platform.sh, a revolutionary cloud hosting solution for Drupal, Symfony, and PHP-based applications. Achieve up to 25% savings on developer effort.</p>
    </div>
  </a>
</ShowMore>


# Veronika Tolkachova
Source: https://developer.upsun.com/posts/authors/veronika-tolkachova

Articles written by Veronika Tolkachova.

<div>
  <div>
    <a href="https://www.linkedin.com/in/veronika-tolkachova-169167a2">LinkedIn</a>
  </div>
</div>

<div>
  <a href="/posts/hands-on/zero-downtime-deployments-with-upsun">
    <div>
      <div>
        <span>Wednesday, December 3rd 2025</span>
      </div>

      <h3>Zero-downtime deployments: now in open beta</h3>
      <p>We've launched zero-downtime deployments in open beta. Deploy your applications without service interruption.</p>
    </div>
  </a>
</div>


# Vince Parker
Source: https://developer.upsun.com/posts/authors/vince-parker

Articles written by Vince Parker.

<div>
  <a href="/posts/discussions/cve-2024-45337">
    <div>
      <div>
        <span>Friday, December 13th 2024</span>
      </div>

      <h3>CVE-2024-45337</h3>
      <p>This article was originally published on the [Platform.sh blog](https://platform.sh/blog/uncovered-and-patched-golang-vunerability/).</p>
    </div>
  </a>

  <a href="/posts/unknown/uncovered-and-patched-golang-vunerability">
    <div>
      <div>
        <span>Friday, December 13th 2024</span>
      </div>

      <h3>Security vulnerability uncovered and patched in the golang.org/x/crypto /ssh package</h3>
      <p>Misimplementation of PublicKeyCallback leads to authorization bypass in Go's x/crypto/sshPlatform.</p>
    </div>
  </a>
</div>


# Vincenzo Russo
Source: https://developer.upsun.com/posts/authors/vinnie-russo

Articles written by Vincenzo Russo.

<div>
  <a href="/posts/unknown/human-impact-of-adopting-platformsh">
    <div>
      <div>
        <span>Tuesday, October 29th 2024</span>
      </div>

      <h3>A tale of people: the human impact of adopting Platform.sh</h3>
      <p>I have a complicated relationship with people.</p>
    </div>
  </a>
</div>


# Yuriy Babenko
Source: https://developer.upsun.com/posts/authors/yuriy-babenko

Articles written by Yuriy Babenko.

<div>
  <a href="/posts/unknown/what-the-heck-is-a-cdn">
    <div>
      <div>
        <span>Friday, November 27th 2020</span>
      </div>

      <h3>What the heck is . . . a CDN?</h3>
      <p>Ask a non-technical professional what the most challenging part of their job is and you’ll often hear, “Understanding what the heck our developers are talking about.</p>
    </div>
  </a>
</div>


# Website fleet management: challenges and opportunities
Source: https://developer.upsun.com/posts/business/website-fleet

A solution to manage website fleets, automate code updates, and streamline operations for organizations with numerous websites and applications.

<PostMeta />

How many websites and applications do you think the average medium to large organization runs? Dozens? Hundreds?
Thousands?

Waaaay back in 2015, Forrester Research interviewed digital leaders at enterprise organizations and found that, on
average, they were maintaining 268 customer-facing sites. That seemed like a lot at the time!

Fast forward to 2019, and the challenge looks far worse.

<img alt="Image showing various large organizations and their domain counts" />

> Public-facing sites and applications have proliferated across organizations, from global CPG and life-sciences
> companies to colleges and universities, agencies, and software companies.

These applications range from critical anchor properties—like corporate or brand .coms and .edus—to campaign
microsites with limited lifespans, and department or project sites that proliferate at universities.

No matter how big or small, every website or app is a point of risk—and a potential source of waste from duplicated
efforts to host, maintain, and secure—if you don’t have a platform strategy.

## What are the challenges in managing website fleets?

1. How does IT respond to this patchwork of websites, using different CMSs and tooling (from Drupal to Java to Node.js),
   often built by different teams or by digital agencies?
2. How does the organization control costs and drive predictability?
3. How do websites built and maintained by different teams remain secure?
4. How do organizations maintain the right governance of all of the organization’s digital property and processes?
5. How do organizations out-innovate their competitors–large and small?
6. How do teams and organizations know that they’re constantly improving?

Running tens or hundreds or thousands of websites and applications across an organization is a huge challenge. But it’s
also a massive opportunity–if done right.

With the right platform strategy and tools, organizations can create a win/win solution for both digital teams focused
on building great customer experiences *and* IT organizations charged with keeping all those sites and apps secure and
performant (not to mention cost efficient!).

Platform.sh solves many of these technology problems with a set of tools to
[manage multiple websites](https://platform.sh/blog/managing-multiple-website/) and web apps at scale. At the same time,
we can facilitate a win/win scenario between groups that have often been at odds.

## The Platform.sh vision for website fleets

Platform.sh powers website fleets today for well-known brands and organizations—Orange, the University of Missouri,
Unity, EBSCO, and The British Council, to name a few. But we’ve got big news.

### First - we’re announcing a new key feature for teams managing website fleets at scale: *Source Operations*.

Wish your site—or 1,000 of your sites—could update *themselves* when they need security patches? Source
Operations can do that. Want to take the innovation happening in one business unit and deliver those features across
your fleet? Source Operations can do that, too.

Today, we’re delivering a public beta of the Source Operations feature that enables Platform.sh customers to automate
code updates to their sites. We’ve created a series of posts to explain how it works in detail:

1. [Source Operations: automate maintenance, from single sites to fleets](https://platform.sh/blog/automating-updates-source-operations/)
2. [Three ways to manage website fleets](/posts/engineering/three-ways-to-manage-a-fleet) (scheduled automation, scripting, and GUIs)
3. [Admiral: how to keep your fleet afloat](https://platform.sh/blog/admiral-an-example-of-website-fleet-automation/) (an example
   framework for fleet automation with Platform.sh)

Yeah, we couldn’t resist the puns with that third one, sorry.

> The TL;DR summary: Source Operations enables mass updating of site code for your fleet of web apps and almost anything
> other action you can script.
>
> Like the *idea* of WordPress or Drupal multisite, but wish you could update sites selectively? Now you can.

Source Operations is available as a public beta *today*, and you can check out our
[documentation here](https://docs.platform.sh/configuration/app/source-operations.html#source-operations) for more detail.

### We’re rolling out more fleet-focused features over the coming months

Source Operations is just the first of many additions to the Platform.sh fleet management toolset. In the next several
months look for:

* Enhancements to user and organization management in the Platform.sh console and API
* Integration with external user authentication systems to manage your development teams
* Robust logs and metrics at the site and organization level
* Sweet dashboard capability to keep apprised of the state of your apps–and your site fleet

### We’re building on the Platform.sh core capability

That means you’ll get polyglot support for dozens of languages and frameworks, declarative infrastructure, where a few
lines of config transform into containerized services in an instant, and a
[GitOps](/posts/core-concepts/getting-gitops-right)-driven workflow that adapts to the way your team
works. Oh, and of course, you can deploy across multiple cloud providers in 25 regions around the world, with 24x7
support.

## How to get started with a fleet strategy

Platform.sh can provide the tools you need to deliver improved time to value and align digital and IT organizations. We
want to go a step further and help you with your website fleet management strategy, too.

Ready to start? [I'd love to hear from you directly](https://community.upsun.com/).

## More content on website fleet management to read and share

* Read our whole series introducing Source Operations, with an in-depth look at how you can power your own website fleet:
  * [Source Operations: automate maintenance, from single sites to fleets](https://platform.sh/blog/automating-updates-source-operations/)
  * [Three ways to manage website fleets](/posts/engineering/three-ways-to-manage-a-fleet) (scheduled automation, scripting, and GUIs)
  * [Admiral: how to keep your fleet afloat](https://platform.sh/blog/admiral-an-example-of-website-fleet-automation/) (an example framework for fleet automation with Platform.sh)


# Eliminating Database Password Risk with Network Isolation
Source: https://developer.upsun.com/posts/core-concepts/eliminating-database-pwd-risk-with-network-isolation

By removing default database passwords, Upsun reduces common credential risks (leaks, reuse, hardcoding) and relies on stronger security controls like SSH keys and private networking.


<PostMeta />

The topic is a common question from security teams accustomed to traditional "on-premise" or "flat-network" architectures.
In a traditional setup, a database password is the primary (and often only) line of defense.
In a modern, cloud-native architecture like Upsun’s, we use Identity and Network-Based Security,
which is fundamentally more robust than a simple shared secret (password).

**Quick summary**: Our platform is built on a **Security by Design** philosophy that prioritizes network isolation
and explicit authorization over shared secrets, which are often a point of vulnerability.
By removing the default database password, we remove the risk of that password being leaked, hardcoded in scripts,
or checked into version control. Instead, we rely on cryptographically secure SSH keys and network isolation,
ensuring that your data remains private and accessible only to the applications and users you have explicitly authorized.
Here is a more comprehensive breakdown of why our default configuration is not only secure
but often superior to traditional password-based setups.

<img alt="Network isolation principle" />

## 1. Zero External Exposure (No Public Route)

The most common reason for a database breach is a database being accidentally exposed to the public internet.
On our platform, **databases have no public IP addresses and no route to the outside world**. The database service runs in a private,
isolated virtual network. There is no "front door" for an attacker to knock on, meaning brute-force attacks or
credential-stuffing attempts against your database are architecturally impossible from the outside.

## 2. Multi-Layered Logical and Physical Isolation

We utilize a defense-in-depth approach to ensure that your data is siloed:

* **Environment Isolation**: Every environment (Production, Staging, Dev) is fully isolated. We use Linux **namespaces, seccomp, and cgroups** to ensure that processes in one environment cannot see or interact with another.
* **Project Isolation**: Each project is restricted by strict filtering rules. Communication between two projects is only possible
  via public APIs/Web requests; they cannot "talk" to each others' internal services.

## 3. Explicit Service Authorization (The "Need-to-Know" Principle)

In a traditional network, if an attacker gains access to any server, they can often "scan" the internal network
for other services (like a DB).

In our architecture, **nothing is accessible by default**. For an application to talk to a database,
the connection must be **explicitly declared** in the configuration. If the relationship is not defined,
the network routing literally does not exist between those two containers. This implements a "Zero Trust" model within your own cluster.

## 4. Secure Administrative Access via SSH Tunneling

When a human developer needs to access the database, they do not connect to the database port directly.
Instead, they must use a **secure SSH tunnel**.

* This requires **SSH Key-based authentication**, which is significantly more secure than a standard password.
* The user must have **explicit permission** (RBAC) to access the environment via the CLI.
* The **tunnel encrypts the data** in transit and ensures that only authorized, authenticated users can bridge the gap between their local machine and the private network.

## 5. Compliance and Third-Party Validation

Our security model isn't just a theoretical preference; it is audited and validated by leading global security standards. We maintain compliance with:

* **PCI DSS**: For handling payment card data.
* **SOC 2 Type 2**: For operational security and data privacy.
* **ISO 27001**: For information security management systems.

Numerous highly regulated organizations across financial and consumer sectors have conducted deep technical due diligence on this architecture and have verified that it meets or exceeds strict internal and global security standards.

## 6. Flexibility: Optional Password Generation

While we believe network isolation is a stronger security primitive than a shared secret, we recognize that certain organizational
policies or specific application requirements may still require a password.

The platform remains flexible: if your security policy mandates a password, you can explicitly enable **password generation**
for your MySQL/PostgreSQL services as documented [here](https://docs.upsun.com/add-services/mysql.html#password-generation).

***

As organizations continue to evolve their security strategies, moving beyond traditional password-based protection is becoming essential. Solutions like Upsun leverage network isolation to offer a robust alternative, reducing the risks associated with credential leaks and unauthorized access. However, true security is never about a single solution — it’s about building multiple layers of defense. By combining network isolation with other best practices, you can create a resilient environment that protects your data from emerging threats. Now is the time to evaluate your own infrastructure and consider how these principles, as implemented by Upsun, can help you stay ahead in the ever-changing landscape of cybersecurity.


# Getting GitOps right
Source: https://developer.upsun.com/posts/core-concepts/getting-gitops-right

Source code management has never been simpler with GitOps from Platform.sh. We'll help you get started with automating your deployments.

<PostMeta />

The Git version control system is 15 years old and has by all accounts taken over the development world. It's unusual
and weird to find a serious software project that isn't using Git today (though a few holdouts still have lots of
auxiliary tools built around Subversion they haven't managed to jettison yet). The great thing about Git, though, is
that it's capable of so much more than just a place to dump source code.

In recent years, many organizations (including Platform.sh) have adopted Git as a central part of their
[application deployment](https://upsun.com/blog/web-application-deployment-best-practices/) process, not just their code
storage. Collectively this change has become known as "GitOps" -- because adding an "Ops" suffix to something makes it
cool; Internet rules -- but what it means in practice varies widely by the organization. Like any vaguely defined trend,
not all implementations are created equal.

The term was coined in 2017 (as far as I can find) and at its core boils down to three defining points:

* Git as the single source of truth of a system
* Git as the place where we control all environments
* All changes are observable/verifiable

These are good aspirational GitOps principles, but what do they mean in practice?

For Platform.sh, it means "what we've been doing since 2014." Yep, Platform.sh is the hipster of GitOps.

## Git’s extensibility for infrastructure as code

Git as the single source of truth for code is seemingly obvious. It's a version control system; that's what it does.
The important details are the definition of "single" and "truth."

What makes Git useful for more than just code storage is that it's extensible. You can attach hooks to various events,
pushes in particular, and trigger arbitrary actions on those events using the code in the repository as input.

That, in turn, allows you to put more than "just" code in Git. Or rather, more than just application code. For example,
you can include definitions of what your infrastructure should be, declaratively. One of the triggers attached to a
push operation is then "make my infrastructure look like that," which requires software that knows how to change your
infrastructure accordingly. Those actions are usually run by a job server, which is a fancy way of saying "a server that
runs scripts when stuff happens."

That's the origin of "infrastructure as code," a pattern that developed somewhat before GitOps but is a key part of it.
The [Git repository](https://docs.platform.sh/development/private-repository.html) then becomes the source of
truth for both application code *and* the infrastructure needed to run that code.

There is an important caveat here, though. We mentioned "software that knows how to change your infrastructure
accordingly." By infrastructure, we're referring to what language runtime is installed, what other packages are
installed, what other services are in use (databases, cache servers, search indexes, etc.), which of them are allowed to
talk to each other, and so on. That, in turn, requires software-managed infrastructure, or what is more commonly called
"cloud computing." (Not to be confused with "The Cloud," which is market-speak for "someone else's hard drive.") And
cloud computing, in turn, is almost always implemented using [containers](https://platform.sh/blog/what-the-heck-is-a-container/). And all
of that is an awful lot of moving parts under the hood.

## How GitOps transforms workflows for infrastructure management

The combination of a Git repository and container tooling allows for the Git repository to serve not only as "the place
information is stored," but as "the place changes are made." Code changes are obvious, but the repository also becomes
the place that infrastructure is changed. If Postgresql needs to be updated, that becomes a change-in-Git just the same
as updating a code dependency. If a second application runtime needs to be added, say for a new background NodeJS
process, that becomes a change-in-Git just the same as writing a new custom plugin for your application.

Those changes include the creation or destruction of new environments. In the most common scenario (and the one used by
Platform.sh), every Git branch is, or can be, a new environment. Because the infrastructure is all software-driven
containers, creating a completely new instance of Nginx, PHP-FPM, Elasticsearch, MariaDB, or whatever else for each
branch becomes "just" a coding problem. Thus, "make a new test environment with its own collection of servers" turns
into "push a new Git branch, and maybe flip a switch."

The end result, and the desired result, is folding all of the various buttons and dials and switches to control the
entire application, across multiple environments, into variations on "edit something in Git, commit, and push," which is
a workflow developers are intimately familiar with.

Or, put another way, GitOps replaces DevOps by replacing the ops engineer with a small shell script in a Git hook.

## Challenges beyond centralized source control in GitOps

Of course, it's not quite as simple as that. Life never is. While Git as the central source of truth has plenty of
advantages, it doesn't solve all issues. Those need to be solved by additional tooling that is part of the
infrastructure management layer rather than of the application-specific bits (which all belong in Git).

One area in which Git is quite useless is logging. Logs are important, in particular logs of when and how a given task
succeeded or failed, but you would never put logs in Git. (Someone out there is about to say "challenge accepted." Trust
me, it's a bad idea.) When something goes wrong (it always does), you want to have a record of not just which commits
happened when but which commits triggered what script, which deployed which code, which code caused which infrastructure
changes, and which infrastructure changes caused what failure. That requires extra tooling.

Another aspect is secrets management. API keys, passwords, and other secret or semi-secret data needs to be kept
separate from your code. Committing keys to a repository is a sadly common security mistake, and you want to be able to
avoid that. That requires having some other mechanism to track secrets, potentially encrypted, and inject them into an
environment when it's created.

You will also need to inject environment-specific information. API keys are one such piece of information, as you
generally don't want to use your production payment gateway key in a throw-away test environment where you're running
integration tests. (Don't ask how I know that.) But it also includes database credentials (since each environment is a
separate server), the domain name an environment is running on (which an application often needs for security reasons),
or even the performance-sensitive information like the number of CPU cores available (for applications that are
multi-threaded or spawn multiple worker processes). None of that can or should be in Git, but managed separately and
injected into each environment.

Another tricky question is validation. Infrastructure-as-code is great when the "code" has no bugs. Which never happens,
because code. So at what stage do you validate the infrastructure definition? Before it's committed? After? When you try
to update the environment and it fails? There's a number of possible ways to solve that, all with trade-offs.

While GitOps, as a concept, calls for all changes to be observable and verifiable, Git itself only helps partially. The
rest falls to the tooling around it.

## GitOps best practices to avoid implementation pitfalls

In the words of Albert Einstein, “The definition of genius is taking the complex and making it simple.” Genius is quite
hard, of course. Making GitOps-type workflows work is a lot of work, and presenting a reliable and straightforward
interface to it is even harder. The ideal vision is "you push code to Git, black magic happens, and your application is
safely updated--tada!" But that "black magic" is doing a lot of lifting.

There are a lot of moving parts to a successful GitOps configuration, more than most people realize, and some
implementations leave out many parts. Often these are cobbled together using Kubernetes, kubectl, Helm, OpenShift,
Docker Swarm, Mesos, or Rancher hooked up to Jenkins, Travis CI, or Circle CI, plus an ELK stack, a couple nginx
instances, and various other tools that sort of work together most of the time, if you configure them *just* right.

It's also easy to get wrong. For example, some GitOps-style implementations set up a separate repository for each
environment rather than just a branch. That creates entirely pointless complication and makes everything harder. Please
don't do that.

Most tools used in setting up a GitOps-style workflow are also extremely flexible. While flexibility is good, it also
runs into Parker's Law. ("With great power comes great responsibility.") Often, they have so many moving parts and
configuration options that figuring out how to configure them just right is a full time job unto itself. That's why
there are even tools (Helm) to manage tools (Kubernetes) to manage tools (Docker) to manage tools
([Linux namespaces](https://upsun.com/blog/the-container-is-a-lie/)). And it's
[YAML](https://docs.platform.sh/overview/yaml/what-is-yaml.html) all the way down.

## If GitOps were easy, it would be called Platform.sh

Platform.sh is, in a sense, a "not having to build and maintain a complicated GitOps pipeline"-as-a-Service. We've
already built it and made smart decisions about how certain pieces should work (like, don't have a separate repository
for each environment; we don't support that, don't do it), so your number of decisions is reduced to a more manageable
and appropriate level.

![Automation](https://imgs.xkcd.com/comics/automation.png)
[Credit: XKCD](https://xkcd.com/1319/)

Since we knew we were building that level of system from the start and didn't need to make absolutely everything an
adjustable dial, that meant we were able to simplify the conceptual system greatly. There are many more moving parts
behind Platform.sh than most customers ever see, but there's still far fewer moving parts than an equivalent
Kubernetes/Jenkins/ELK/[AWS](https://platform.sh/aws-alternative/) home-grown solution.

In Platform.sh's case, for instance, "all changes are verifiable" is one of the reasons we use a read-only file system
for applications. While that is problematic for some poorly written legacy applications that try to mix their
environment configuration and application configuration into a single file
([you know who you are](https://platform.sh/blog/6-things-to-do-to-make-your-application-cloud-friendly/)), it guarantees that there are no
"fix it in production" hot fixes that get lost as soon as a new build is triggered.

Secrets management is handled through [environment variables](https://docs.platform.sh/development/variables.html),
which can be marked sensitive or not and vary by environment or not.

Environment-sensitive information, like the domain or database credentials, are also injected via environment variables.
That makes it a little more secure, too, in part because developers never even need to know what the credentials are.
Passwords are auto-generated, and the user never needs to interact with them at all.

### Config files validation, activity recording, and simplified inter-container configuration

We made the decision to validate configuration files on Git push. That's not the only possible place to do so, but it's
what makes sense in our system. That means if a Git push is accepted, the configuration files at least validate
syntactically. They may still have bad configuration in them you don't want, but that's just a bug like any other.
(That's what ephemeral staging environments are for!)

Platform.sh doesn't have a dedicated, user-accessible job server. Instead, we provide direct hooks for the three most
common "jobs":

* [Building the application](/posts/unknown/production-artifact) (the [`build` hook](https://docs.platform.sh/configuration/app/build.html#build-hook))
* Exclusive setup after the application is deployed (the [`deploy` hook](https://docs.platform.sh/configuration/app/build.html#deploy-hook))
* Non-exclusive setup after the application is deployed (the [`post_deploy` hook](https://docs.platform.sh/configuration/app/build.html#post-deploy-hook))

Each is an arbitrary shell script that can be of whatever complexity necessary for your application, without having to
think about Jenkins or Travis CI or other extra configuration.

All actions are recorded as Activities in our system, which can be exposed either programmatically or through the web UI.
You can always go back and find out not just who edited what code and when, but who triggered what action and when.

Complex inter-container configuration has been reduced to the bare minimum of YAML, which translates to appropriate
service configuration under the hood. For instance, you don't need to manually keep track of what containers have what
IPs and what open ports. Instead, the `.platform.app.yaml` file identifies services you want to connect to (the
`relationships` section), and the necessary network configuration "just happens," resulting in a predictable internal
domain name and environment variable you can rely on.

## Simplify source code management with Platform.sh’s GitOps

GitOps, as a concept, is wonderful. It allows you to use a tool developers already know well, Git, and use that as the
control panel for most of your deployment life while retaining a single source-of-truth for both your code and your
logical infrastructure. And the larger your team, the larger the benefit.

GitOps as an implementation, though, has far more moving parts than you'd expect, even with available off-the-shelf
tools. Like any complex system, making it seem simple is hard and easy to get wrong. For most developers that make their
money off of the code they write and the service they offer, maintaining a GitOps infrastructure is an incidental
complexity they simply don't need. Most would be better served by a GitOps-in-a-box service. And that's what
Platform.sh offers.


# HTTPS and TLS certificates: Always served fresh
Source: https://developer.upsun.com/posts/core-concepts/https-and-tls-certificates-always-served-fresh

Goodbye to expired certificates! We now auto-renew TLS certificates for your websites, ensuring end-to-end encryption without interruptions.

<PostMeta />

## Never face an expired certificate again.

Platform.sh has offered Transport Layer Security (TLS) certificates for HTTPS connections automatically
[since early 2017](https://platform.sh/blog/free-ssl-certificates-for-every-project-every-environment/), courtesy of
[Let's Encrypt](https://letsencrypt.org/). In the modern age, all websites should be encrypted end to end. The one
caveat, though, has been that certificate renewal only happened on deployment. For an actively maintained site getting
regular updates, that's fine. But for fire-and-forget sites that are only updated very rarely, renewal upon deployment
can lead to expired certificates, which are decidedly less good for security. Less good is not good, though, so we
decided to fix that.

We're happy to announce that we've enabled auto-renewal on all Let's Encrypt TLS certificates (formerly known as SSL
certificates and now represented by this acronym). This change is rolling out now in stages and should be complete
within the next month or so.

## Redeploy all the sites

The way it works is only a small extension of how renewals work now. Let's Encrypt certificates are valid for three
months. One month before a certificate is due to expire, we have a background process that contacts Let's Encrypt and
asks for a renewed certificate. If for whatever reason that process hiccups (due to rate limits, sunspots, or other
issues), it will automatically retry until it gets a new certificate.

That new certificate isn't active yet, however. New certificates only take effect on the next redeploy. When a new
certificate is available, therefore, we now automatically trigger a redeploy. Because the only change in the deploy is
"swap in the new certificate," the process is fast, taking only seconds. No other code or configuration changes.

## Custom certificates

If you're using a custom TLS certificate, we cover those, too. Seven days before a custom certificate is set to expire,
we’ll issue a Let's Encrypt certificate and swap that in instead. If you want to keep using the custom certificate,
upload a renewed certificate more than a week before it expires and we'll leave it alone.

## Out with the old

We previously recommended that customers set up a cron task to redeploy their site every two weeks in order to ensure
any waiting new certificates were installed. Since we’re now doing that automatically, that cron task is no longer
necessary. If you have that cron task running, we recommend you drop it. It won't hurt anything if it's still there, but
it's no longer necessary.

The long and short of it is that expired certificates on Platform.sh should be a thing of the past.


# How Meta-Upsun improved Validation Schema and Developer eXperience
Source: https://developer.upsun.com/posts/core-concepts/meta-upsun-validation-schema-dx-improvement

The introduction of Meta-Upsun enabled dynamic validation schemas and version enumeration for Upsun services and runtimes, significantly improving developer experience.


<PostMeta />

The release of [Meta-Upsun](https://devcenter.upsun.com/posts/meta-reference-source-introduction/) marks a major advancement in Upsun’s validation capabilities. Developers no longer need to manually check [Upsun documentation](https://developer.upsun.com/docs) or risk using unsupported versions for services and runtimes. Meta-Upsun provides dynamic, always up-to-date validation schemas for services and runtimes, ensuring configuration is accurate and reliable.

## Schemastore update

[Schemastore.org](https://www.schemastore.org/) now links directly to the Upsun validation schema streamlining configuration of `config.yaml` files. This integration ensures developers receive the latest validation rules and best practices, as detailed in our [developer guide](https://devcenter.upsun.com/posts/validate-yaml-config/).

The Schemastore entry for Upsun now references our [dedicated API endpoint](https://meta.upsun.com/api-docs#tag/validation/GET/schema/upsun), so your IDE always uses the most current schema.

The updated validation schema uses `$ref` pointers for service and runtime types, linking to Meta-Upsun API endpoints that enumerate the latest supported versions. See below for examples of the schema definitions:

<img alt="Sample of the runtime type validation schema definition" />

<img alt="Sample of the service type validation schema definition" />

## Dynamic version enumeration via API

Meta-Upsun introduces two new endpoints:

* [`GET /validation/schema/runtime-versions`](https://meta.upsun.com/api-docs#tag/validation/GET/schema/runtime-versions)
  <img alt="Sample of the runtime API endpoint enum result" />
  * [`GET /validation/schema/service-versions`](https://meta.upsun.com/api-docs#tag/validation/GET/schema/service-versions)
    <img alt="Sample of the service API endpoint enum result" />
    These endpoints pull data from [registry.json](https://meta.upsun.com/api-docs#tag/images/GET/image), ensuring the list of valid versions is always up-to-date and reflects actual platform support.

## Smarter validation schema

The main schema ([`GET /validation/schema/upsun`](https://meta.upsun.com/api-docs#tag/validation/GET/schema/upsun)) dynamically references these endpoints. Whether you specify a runtime or service, you get the correct, current version enumeration automatically.

## Better Developer eXperience (DX)

With dynamic schema integration in your IDE, you’re prevented from specifying unsupported versions and no longer need to search documentation for valid options. The schema guides you, reducing errors and saving time.

Below are examples of how autocompletion works for runtime and service types in Visual Studio Code:

**Example for Runtime type autocomplete in Visual Studio Code**:

<img alt="Example of a runtime.type autocomplete in VSCode" />

**Example for Service type autocomplete in Visual Studio Code**:

<img alt="Example of a service.type autocomplete in VSCode" />

Meta-Upsun’s enhancements to validation and version management represent a significant leap for Upsun’s developer experience, making configuration safer, faster, and more reliable.

To learn more about Upsun, visit our comprehensive [documentation](https://developer.upsun.com/docs).


# Building an AI feature: The necessary evals
Source: https://developer.upsun.com/posts/discussions/building-ai-feature-necessary-evals

What we learned building an AI feature: evaluations take most of the time, and your existing tools are enough.


<PostMeta />

In September, we launched [`upsun init`](https://docs.upsun.com/administration/cli/init.html), a CLI command that analyzes your codebase and generates an Upsun configuration file. Previously, we had [documented](https://docs.upsun.com/) our configuration extensively with examples and templates, and a non-AI version of the same command, but supporting a larger variety of applications would have added a lot of complexity. AI seemed like the right solution for handling many languages, frameworks, databases, and deployment patterns with less effort.

## What we learned

We built this feature as a small team of software engineers, with no data science or machine learning background. We had read enough about AI to know that data and evaluations (evals) would be challenging, but still the degree surprised us. AI integration itself is straightforward, but the domain-specific work consumes most of the time: essentially, determining what "good" output actually looks like.

About 90% of the *code* of our AI component is what you would need in any normal backend service: API structure, input validation, logging, error handling, and tests. The AI itself is a relatively small piece: call an API, parse and validate the response. It's familiar to anyone who has integrated with external payment processors or authentication systems before. Tool calling and streaming add some complexity but again nothing unusual.

The real challenge of AI engineering is managing uncertainty. LLMs are useful precisely *because* they produce output we cannot fully predict. But we also need reliability: we need to know the service can achieve its goals even though we can't know all possible results in advance.

Engineers deal with unpredictability in other aspects of software - network errors, disk failures, varying load - by gathering data and building safeguards such as retries, timeouts, and redundancy. So the indeterminacy of AI is not an entirely new concept, but it is a lot more prominent, and it can be frustrating. Building a system to validate and assess output is the main part of any non-trivial AI project: as the community likes to say, "evals are all you need".

## Building the evaluation pipeline

There is a chicken-and-egg problem in AI. To assess the output you would first want to gather a "golden" dataset of ideal output. But how do you build that dataset without a way to assess it? Often the answer will involve asking humans to find, create or label data manually.

For our Upsun configuration project, we went through our own documentation and templates and asked colleagues for expertise in various languages and use cases. We created a new internal tool to help us build and test sample Upsun projects with their corresponding YAML configuration.

Once we had enough data to work with, we could use our samples to compare against AI output to help create the evals. We integrated these into our existing Go tests, our project's Makefile, and our GitLab CI infrastructure. Evals run on every commit and in every merge request, and can also be configured with different models or parameters, such as `EVAL_MODEL=gpt-5.1 make eval`. No special AI tooling is required, and using these common structures means that new engineers can onboard and contribute with confidence.

We also focused on performance, minimizing context and tool calling, parallelizing where possible, and preferring smaller and faster models. This contributes to a smoother user experience and helps to speed up the tests. Faster evals mean you can test more samples, models and parameters more frequently. A local eval takes a few seconds, and the full CI pipeline (build, linting, unit tests, and a list of evals) runs in 5-10 minutes, costing roughly 25 cents in AI usage per run. The cost is negligible compared to the value: every commit gets validated, and we can evaluate new models as they become available, without changing our workflow.

GitLab CI lets you configure many parallel jobs through a matrix, varying them through environment variables:

```yaml theme={null}
evals:
  extends: .eval-template
  parallel:
    matrix:
      - TEST_REPO: drupal
      - TEST_REPO: gatsby-v5.14
      - TEST_REPO: hugo-v0.150
      - TEST_REPO: jekyll-v4.4
      - TEST_REPO: laravel-v12_mysql
      - TEST_REPO: nextjs
      # ...
```

The result looks like this:

<img alt="GitLab CI pipeline showing parallel eval jobs for different frameworks" />

Building our first AI feature turned out to be quite approachable in terms of code, and we didn't need to use AI-specific tools and frameworks. The hard work is definitely in gathering data and building tests. We learned that we would certainly want to allow plenty of time for this in other AI projects, and that it really helps to keep it simple and use existing practices.

## Try Upsun today

Want to see how AI-assisted configuration works in practice? [Start your free trial](https://auth.upsun.com/register) and try the `upsun init` command on your own projects. Upsun provides a complete platform for deploying and managing your applications with features like automatic scaling, built-in CI/CD, and now AI-powered configuration.


# Building an AI code review agent for our self-hosted GitLab
Source: https://developer.upsun.com/posts/discussions/building-an-ai-code-review-agent-for-gitlab

I vibe-coded a GitLab code review agent last month - 40K lines of Python written by Claude - and it has reviewed 1000 merge requests.


<PostMeta />

AI code review tools are everywhere now. GitHub has Copilot reviews, there's CodeRabbit, Qodo, Greptile, and something new every other week. If you're on GitHub with a standard stack, you're spoiled for choice.

We're not on GitHub. We run self-hosted [GitLab](https://gitlab.com/), track issues in [Linear](https://linear.app/), and have the kind of internal setup that makes off-the-shelf integrations difficult. So I built our own review agent. It's been running on 25 projects, has processed around 1000 merge requests (each with \~2 reviews on average), and costs about 50 cents per review. Here's what I learned.

## The starting point

Six months earlier, a colleague had already built a working AI review system for our GitLab. It ran as a manual CI job: Claude Code with access to the git diff, commit log, and a prompt. Under 200 lines of code. It worked, teams used it, and it proved that AI reviews were worth doing.

The limitation was scope. It could see what changed, but not the surrounding code, the rest of the codebase, or any external context. That was a deliberate choice: it was simple and fast. But I wanted to see what would happen if the agent could do what good human reviewers do: search the codebase, read related files, check the issue tracker, and understand the broader context of a change. Sean Goedecke's [blog post](https://www.seangoedecke.com/good-code-reviews/) on code reviews was part of the inspiration.

## Why custom?

Our engineering stack includes our self-hosted GitLab, Linear for issue tracking, and plenty of other internal systems and tools. If you're buying an external review tool, you need it to work with all of those, and most don't.

Building our own means the agent can obtain Linear issue details, apply review standards specific to each project, and use GitLab's [CLI](https://gitlab.com/gitlab-org/cli), web searches and other tools to go beyond the local checkout. Each integration makes the reviews noticeably better, and each one would be difficult or impossible with an off-the-shelf tool.

## Vibe coding a large Python project

I have normally avoided Python. I have written scripts, but building a significant async service would not be something I would normally have attempted.

Recent model advances changed this. [Claude Opus 4.5](https://www.anthropic.com/news/claude-opus-4-5) arrived in late November 2025, and with it a level of coding ability that made working in an unfamiliar language feel productive rather than frustrating. I started this project in January. More recently, [Opus 4.6](https://www.anthropic.com/news/claude-opus-4-6) improved things further. The [Claude Agent SDK](https://platform.claude.com/docs/en/agent-sdk/overview) (released September 2025) provided the agentic tooling to make the workflow practical.

In the first two weeks, the project grew to about 25K lines of application code and 22K lines of tests. It handles webhook events from GitLab and Linear, classifies requests, triggers CI pipelines, runs Claude agents with sandboxed tool access, and posts results back to GitLab comments and Linear [agent sessions](https://linear.app/developers/agent-interaction). There are broadly four agent task types (review, conversation, planning, and coding), each with different prompts, tool permissions and security constraints.

I really like the phrase "vibe coding", but I don't mean it to say that there is no oversight or judgement. I made the architectural and UX decisions, read what the AI thought and wrote, and debugged when things broke. But the barrier to working in Python dropped so far that the language choice became almost entirely irrelevant (I only picked it because of the Claude Agent SDK).

Some of the more complex features illustrate this well. Incremental reviews - where the agent remembers what it said on a previous review, sees only what changed since, resolves its own comments when issues are fixed, and handles force-push and rebase correctly - involve fiddly commit and diff tracking. It's the kind of thing I'd normally spend days (or longer) getting right, which I couldn't afford on an internal, experimental tool. With AI assistance, I focused on the design (what state to track, when to resolve, how to handle rebases) and the AI handled the implementation details. This part did actually take more than one attempt to get right, but each change took minutes instead of hours.

## How the agent works

The review agent is triggered by a webhook. When you open or update a merge request, the agent picks it up automatically. By the time a human reviewer comes to look at the MR, a summary and inline comments are already there.

Here's what happens during a review:

1. The system launches a review job (in a GitLab CI pipeline)
2. It clones the repository, fetches the MR description and previous comments, and passes those to Claude in a prompt
3. The agent will then search the codebase for related code and patterns using its built-in tools
4. It looks up the linked issue using the [Linear MCP](https://linear.app/docs/mcp) for context on intent and requirements
5. It produces structured JSON output: a summary and inline comments with exact file and line references

Each inline comment has a severity level and optionally a code suggestion that the author can apply with one click in GitLab. This structure makes the reviews predictable and actionable.

A few other details worth mentioning:

**Security.** The review agent is read-only; file write and edit tools are blocked. All shell commands run inside a [Bubblewrap](https://github.com/containers/bubblewrap) sandbox with a network allowlist restricted to package registries and our GitLab instance. Credentials are automatically redacted from AI responses before they're posted.

**Fast classification.** When someone mentions `@agent` in a comment, a fast classifier (Claude Haiku) categorizes the request: simple question, review request, coding task, etc. Simple questions get answered immediately by Haiku. Complex requests get routed to Opus via the CI pipeline. This keeps the cheap things cheap.

**Incremental reviews.** On subsequent pushes, the agent compares against its previous review. It knows what changed, avoids repeating itself, and resolves its own discussion threads when the author fixes an issue. This works even after force-push and rebase by tracking the relevant commit SHAs.

## The numbers

| Metric | Value |
| - | - |
| Projects using the agent | 25 |
| Merge requests reviewed | 1000+ |
| Average reviews per MR | \~2 |
| Cost per review | \~\$0.50 |
| Cost per MR | \~\$1.00 |
| Model | Claude Opus 4.6 |

Adoption was opt-in. Teams enable it with a single command that installs a webhook on their project.

The agent also has an experimental coding mode: it can implement features from Linear issues, including writing detailed plans, creating branches, and opening merge requests. It has already written code to improve itself (when directed). I still need to gain more confidence in this workflow before it can be considered stable.

## What I learned

**Agents do a lot better with tools.** When Claude can search the codebase, read related files, and check external context, it produces reviews that are qualitatively different from a prompt-with-a-diff. The agent finds issues that aren't visible in the diff alone: inconsistencies with patterns used elsewhere, missing error handling that only matters in context, and changes that contradict the MR description or the linked issue.

**Internal tools are an ideal project for vibe coding.** The stakes are low: if something breaks, you fix it, and you're very close to the users. Iteration is fast. And you end up with something that fits your workflow exactly, which no purchased tool will do. While building the review agent, I worked on several other internally focused projects including an AI gateway for colleagues and several smaller tools. The pattern holds: if it's internal and you understand the requirements, AI-assisted development is remarkably productive.

**Making reviews consistently useful is the hard problem.** The agent produces accurate and insightful-looking reviews most of the time. But it still sometimes flags trivial issues, and very occasionally hallucinates (such as claiming "Go 1.25 does not exist"). Improving the signal-to-noise ratio is ongoing prompt engineering work, and it's work I can focus on now that the infrastructure is in place.

The agent's coordination system runs, of course, on [Upsun](https://upsun.com/), and for now the agent SDK tasks run on GitLab CI. In the process of building this I have learned a lot about what I would want from an autonomous agent system and I'm hoping to explore that further.


# Containers are the new static binaries
Source: https://developer.upsun.com/posts/discussions/containers-are-the-new-static-binaries

Platform.sh updates: new languages, MariaDB, and PHP 7.2-alpha support. Stay informed and enjoy your containers.

<PostMeta />

<Note>
  Containerization technologies offer higher density vs VMs but also some very useful abstractions. If not orchestrated, and built in a consistent and repeatable way they can become a maintenance nightmare (as relying on any kind of blobbish static executables can be).Both the performance impact and the complexity they can present can be managed by applying what we believe are very rational patterns.

  – TLDR; Now go read the whole thing.
</Note>

## A dreaded interview question

As an interview question I ask “What are some of the advantages and some of the disadvantages of static binaries against
dynamically linked binaries?” The correct answer is “static binaries are easier to deploy but harder to update.” You get
bonus points for saying “there will be differences in startup times” (if libraries are already cached by the OS, dynamic
linking might yield better performance, or on the contrary, if on a cold cache the OS has to seek all over the disk to
find many small files, going dynamic may take longer). “Memory footprint will be higher for static binaries” is again a
correct answer. And of course “Disk space utilization will be higher for static binaries”.

Now, you may say that except the first thing - “harder to update” - all of these other considerations have little to no
consequence; disk space is so cheap, memory is getting cheaper. So… who cares? Deployment is a pain well worth a bit of
overhead. And in the use-cases of yonder you might be right, Linux never really suffered from DLL Hell, still the upside
sounds compelling for static binaries. If you have a single instance of your program running on a server the overhead
will be negligible in all but the most extreme use cases. And you think, well updating may be just a teeny-weeny harder,
but with all my DevOps goodness I should be fine.

## Come containers.

We like containers. Platform.sh runs as a high density grid of micro-containers. I posit that containers compound this
issue; and that where these days the sorrow starts ebbing (it will run deep and wide, bear with me).

We know why containers are great, right? And it’s not only the performance gains (as measured against other forms of
virtualization). They give us a new abstraction. And a damn good one. Applications are more than code. More than the
executable that we run. An application is one with its underlying infrastructure. It is nothing without its
configuration, its data, its place in a topology. Just a bunch of useless bits. And the container is just that “the
minimal set of stuff needed to run the application, bundled together in one place, with no external dependencies”. This
is precisely the abstraction that Docker added on top of LXC by not being “a lighter vm” but insisting on the
portability of a single application. Or more precisely a single service that can be a part of an application.

So basically containers are the new static binaries. They take the idea further. They “statically bind” not only the
code but everything else. Basically everything we said about static binaries will be true for “containers as
applications”; They are easier to deploy. And they are harder to upgrade. And, by the way, the overhead they represent
might also now be compounded if they are running static binaries. If you have thousands of containers running on server
(and we do) the “inconsequential” overhead of those has just been multiplied by a couple of factors. The more we think
about those containers as blobs the more they resemble good old virtualization. They become new “VM appliances”.

[<img alt="Russian Matroshka" />](https://commons.wikimedia.org/wiki/File%3ARussian-Matroshka_no_bg.jpg)
You would argue this is untrue because of the micro-services approach. Every container is a single service, more
horizontal in nature, not an obese “appliance”. But here we see that it is hard to delineate precisely the bounds of
what makes an “application”. These days an application will usually be an ensemble, a graph composed of multiple
services; As such our single container, though already useful is not yet the whole thing. If the application is for
example a web application, it may rely on not only an internal API but also caching mechanisms, a search engine, and
maybe a second App to handle CMS content, there is a very good chance that without a specific Nginx config, it won’t
run. Without all of these in a coherent state we are back to useless bits. With containers deploying each part of this
service graph is easier. As each service will probably simply expose to the others a single TCP socket. The opacity here
is extremely useful as an abstraction. But without careful architecture you get hit by the same penalties as static
binaries: higher overhead, higher cost of update.

When looking at the orchestration layer, the opacity of each component, of each container, having everything bound
together neatly in one place, without the need to know any of the internals, makes our life clearly easier. This is a
kind of plug-and-play architecture. A lego of components. But at the price of higher overhead and probably long-term
instability. It might be plug and play, well, like Windows 95 was, because the internal opacity can also bring us
flakiness. Where in a traditional architecture we would have had maybe two or three servers for a simple application, we
might now have the equivalent of dozens for the same functional perimeter. Each component is separated, but they way
they are glued together can be unstable. Do you really want to try to switch off and on again your datacenter in order
to resolve an issue? Plug and play is nice, but when talking about deployments consistency is more important. Please
remember that this is not something imposed by the Container orientation by itself; LXC and other containerization-like
techniques are just isolating a binary from the rest of the OS. With enough care we can pay very little to no overhead
at all. If we work on the correct abstractions we can avoid the flakiness. More on that later.

Now, lets get back to the first counterargument to static binaries, the updating thing.

## Updating things in a blob world

Imagine that we have a security issue in a library. Lets say in a popular, widely used one (that never happens, right?)
we might very well have thousands and thousands of copies of the vulnerable routines hidden away in binaries, themselves
hidden inside the blobs that are containers. There are very few tools to help us discover which those might be, and
which binary used which library at which version. A problem like this is not something that is bound to happen soon. But
this is something that is bound to happen. Imagine that many of the services you are running, have been pulled from a
public repository of “container images”. How will you know which one is affected? And the more “micro-service” you went,
the more of these images you are going to have. The complexity is staggering. Here at Platform.sh we can run above a
thousand five hundred containers per host and have hundreds of hosts across which we run containers. As a rule of thumb,
the smaller the granularity of services we run the happier we are, which is also why minimizing overhead is of extreme
important to us. Without a consistent, traceable build process, without an orchestration layer, reacting to a critical
flaw in a widely used library would amount to “a riddle, wrapped in a mystery, inside an enigma;” in the words of
Winston Churchill.

Now, say what you may about Debian; compare this nightmare scenario, updating those opaque blobs inside opaque blobs
coming from a third party… to updating a single shared library and gracefully restarting a bunch of servers. That day,
The Debian Way wins.

There are of-course many ways to lessen the blow. And the first that comes to mind is imposing fully traceable,
repeatable builds. This means that the good practice is to build your container images from source. It is much easier to
find vulnerable containers through scanning their underlying code, and if everything is automated from build to
deployment it means that you pay no cost for deploying the exact same version again (the built container, being simply a
cache of the build process). The cost to redeploy an updated version is also marginal (patch the source, push to git, a
single image is built and voilà.). This is how we do it in Platform.sh.

Containers in Platform.sh are truly still blobs; We build each one once. They are still a content addressable thing. If
you deploy 100 MySQL servers in a grid, on each host it is going to be on, we are only going to pay the disk space and
much of the memory penalty once. Everything shared will only cost the OS once. This is because all our containers are
read-only. We mount anything that might be mutable on a different filesystem, so the r/w parts are always explicit. When
we need to upgrade a piece of software, this just means pushing the commit, and it gets built and deployed. And because
the relationships in a topology are semantic, because we understand who depends on whom, now it is just an issue of
refreshing clusters, which happens without downtime.

## Abstractions

Containers and VMs are not only run-time concepts. It’s not only about their efficiency, they are also abstractions, and
most of what we do in software is about expressing the correct level of abstraction. Abstractions serve us to hide
complexity and put system frontiers. They allow us to separate responsibilities, they allow us to manage change. But
Blobs by themselves are not abstractions, anyway these are not useful ones. They are the ABI, “Application Binary
Interface” not an API, they are implementation details. For precisely this reason, having a “build process” for your
apps and then your containers is not enough, not by a long shot. You want this build process to have other qualities,
primarily that the more you go towards the outer layers of your build the more declarative and less imperatively scripty
you get. In Platform.sh we not only build the Application, we also build the infrastructure. And the build is based
simply on declaring the dependencies of the application.

## Consistent Change

We want declarative infrastructures because we are pursuing what can seem as an oxymoron - consistent source based
deployments (where the source moves). You want to be able to update everything, update it dynamically, update it safely,
and update it all the time, but you don’t want the application to break all the time. So in Platform.sh the git commit
that represents an application holds two things at the same time: an immutable reference to the source (application but
also any dependencies such as the precise version of your database, or even the memory that was allocated to a service),
and an immutable reference to the built containers that represents a hash of the binary blob (the built file system).
You get the benefits of static binaries. The whole shebang, together, will always run, together, as an integral unit. It
no longer has any external dependencies. But it the fact the what we manage together is not only the consistent state of
each micro-container, but also the graph of services, their relations, the order in which they need to run, the order in
which they need to stop. How to #ze them and how to gracefully restart them; How to clone them and how to move them
between hosts. These are the orchestration level abstractions, that we believe to be an integral part of the application
that allow us to confidently, continuously deploy.

With the extra layers of orchestration, by letting git be the repo of all things, you can now also update. Just push a
new commit; We will rebuild everything that needs to be rebuilt, and know how to “diff” the current infrastructure from
the one that is newly described and update the running environments so the new world represents its description. And now
the infrastructure is at a new commit. It is again immutable. If you were to revert, you will get the precise state in
which you were before. And you can always diff. You can always know what has precisely changed between two application
deployment states.

## Infrastructure rot

<img alt="Falling apart" />

Building afresh, and declarative immutable infrastructures is what defends your application from infrastructure rot.
Because like code, infrastructures rot, and maybe faster. A tweaked configuration parameter here, a changed memory
allocation there; then cloned a VM or a Container (now running on different specs…) Why is this parameter there now?
No one will know. And no-one will dare change it. Infrastructures rot like code does. When fear of change comes. When
there are no commit messages. Copy and pasted code has no semantics; It may work, but it rots. The same is true for any
part of the whole infrastructure.

## But Puppet and Friends?

<img alt="Puppets" />

But there are so many nice automation tools these days, you might say; And the code that runs the scripts is of course
in a git repo… We love Puppet, and we love Fabric, we use both and all of these (with Ansible and Salt, and even Chef,
are great useful tools). But as long as you are shuffling around Blobs and putting them into production, as long as the
deployment is not managed with the application as a single entity there is no real difference between doing this and
using FTP on production (well that’s a bit harsh maybe… still you have no real consistency guarantees, you have no
guarantee that deployment and application will not diverge). You might of course be one of the golden ones, already
doing continuous deployment and have heavily invested in both testing your deployment and in huge amounts of homemade
tooling to make the whole thing smooth. When you continuously deploy with these methods, you may not be able to avoid
failure, but as you detect it at a smaller granularity, you don’t let the thing rot. It may continuously break, but you
can continuously repair it. So, failure here is in no way unavoidable, avoiding it is simply very costly.

Somewhat orthogonal to configuration management and deployers, we can see of late the emergence of an orchestration
layer for containers; from the older Mesos project to the more recent Swarm, Fleet, Flynn and Kubernetes (and probably a
dozen others, seems to be a new one every week). Most still lack maturity, and from these, the one that accounts for
many of the concerns I am raising is probably Kubernetes. It exposes some of the primitives that would allow with
sufficient investment to create an orchestration layer that allows for consistent operations. But it is a very low level
beast. It exposes a lot of moving parts... which defeats some of the purpose. We wanted to
[containerize](https://platform.sh/blog/what-the-heck-is-a-container/) firstly because we wanted a simple abstraction. There are so many
moving parts that transposing now a whole cluster becomes difficult. If an app is just a small Symfony thing, that just
depends on MySQL and ElasticSearch the whole configuration for this should be no more than a 10 lines file. But being
simple should still allow it to have all the orchestration capabilities of a more complicated App. It may be simple buy
it may still be critical; It may still need to evolve fast.

This might be a transitory phase. As these projects mature and evolve higher abstractions may appear to hide away the
details. But for the moment when you go the way of the container; When you have chosen the static route, there are few
options that are not extremely costly to avoid infrastructure rot. Updating the stuff stays hard.

## The zeitgeist is going static

It is almost a funny thing, to see this circular trend between “Dynamic” and “Static” be it types, compilation or tests…
and now infrastructures and deployments. And the pendulum over the last two years or so is clearly swaying back to
static; Ruby was all the rage just a small decade ago.

How many projects have you seen lately whose main value proposition seems to be “The same thing, reimplemented in Go, as
a single static binary”?

Now, don’t get me wrong, if at its start I had little consideration for the design goals of the language, I have grown
much warmer to it; its “no-nonsense” approach coupled with the very lively community around it have produced many a
great project.

And here at Platform.sh, though most of our code is in Python, we write all of our high throughput concurrent servers in
Go, and we are very happy with it; It’s more than “concurrency for idiots”: many small language features make quickly
writing robust network servers easier than in most other languages (probably not Erlang or Elixir, but again deploying
and managing those does demand so much more know-how).

So this is not a rant against Go. Not one against static typing, or static tests, not even static infrastructures. In
the words of the GoLang FAQ “… although Go has static types the language attempts to make types feel lighter weight than
in typical OO languages. “

Static typing is great because you really want the error to pop before you deploy the code and run it. Static tests are
great because they are faster, and you can never really know what paths a running program will take. And statically
linked binaries are great because easier deployments which also means faster adoption when you are doing Bleeding-Edge
Github style open source. Static Immutable infrastructures are great because do you really want these kind of things to
be where your bugs get expressed? And Static Containers can also be great. As long as you remember that “All this has
happened before, and all of it will happen again.”

So... if you are going the container way I really believe you should think of the following:

* Going descriptive versus script oriented orchestration. Name things give them a role.
* Colocating everything that is a dependency; If you need it in order to run the app, its part of the app.
* Going Micro-Container. Watching every ounce of overhead. Watching every cache that gets busted. Deduplicating
  everything that can be.
* Building everything. Building all the time.
* Knowing an application is a graph. And its an ordered one. All dependencies must be managed all operations on a
  cluster must be ordered.
* Versioning everything.

And you’ll be fine. By the way, we are.

If you find this compelling... check out how Platform.sh supplants the paradigm of dev-staging-prod with one allowing
you to clone an entire production cluster in a matter of seconds, creating a live ad-hoc environment for every git
branch.


# CPU vs GPU for AI: most AI applications don't need GPUs
Source: https://developer.upsun.com/posts/discussions/cpu-vs-gpu

How to build and deploy an Angular application on Upsun.

<PostMeta />

If you're adding AI features to your application (content moderation, recommendations, search, chat, etc) you're integrating inference into your backend, not training models. That's a different conversation than what GPU marketing addresses.

For most enterprise applications, AI interference runs on the same CPU infrastructure as the rest of the application. So, the question isn't "do I need AI hardware?" but "can my existing infrastructure handle AI inference alongside everything else my application does?".

For most applications, the answer is yes.

## What your application actually does

When your application handles a request that involves AI, here's what happens:

1\.  Receive request and authenticate (CPU)\
2\.  Validate input and check business rules (CPU)\
3\.  Fetch relevant data from your database (CPU)\
4\.  Transform data into the format your model expects (CPU)\
5\.  Run inference (CPU or GPU)\
6\.  Apply business logic to the prediction (CPU)\
7\.  Update database, trigger workflows (CPU)\
8\.  Format and return response (CPU)

<Note>
  Step 5 - running inference - is the only place a GPU might matter. Everything else is standard application logic that runs on CPU.
</Note>

Your application spends most of its time doing application things. Authentication, database queries, business logic, API calls, caching. AI inference is one step in a larger workflow. The question is whether that one step requires different hardware than the rest of your application.

## When your application needs GPU infrastructure

Most applications don't. GPU infrastructure makes sense in specific scenarios:

* You're using **massive Generative models**: If you've chosen to self-host large transformer models (i.e. LLMs) rather than using an API (such as [OpenAI](https://openai.com/), [Anthropic](https://www.anthropic.com/), etc).

* Your application serves **extreme volumes**: If you handle thousands of AI-powered requests per second and can batch them, a GPU's throughput can be more cost-effective than a massive fleet of CPU instances.

* You're **training or fine-tuning**: If your application includes a training pipeline (retraining models on user data) that's where GPUs are essential.

## Why CPU infrastructure works for most applications

You're deploying an application, not a model: Your application needs databases, caching, background jobs, API endpoints. Adding AI inference is one more feature, not a reason to redesign your entire infrastructure. If you can run inference on the same instances that handle your API traffic, your deployment stays simple.

**Production-ready models run on CPUs**: Models optimised for production use run efficiently on modern CPUs. [DistilBERT](https://huggingface.co/docs/transformers/main/model_doc/distilbert) for language tasks, [MobileNet](https://huggingface.co/docs/transformers/v4.38.0/model_doc/mobilenet_v2) for image classification, [XGBoost](https://xgboost.readthedocs.io/en/stable/) for structured data. These aren't toy models; they power real applications at scale. Even large models can work fine if your use case allows slower inference. Background jobs, async workflow and batch processing don’t need millisecond response times. Match your infrastructure to your actual requirements.

Your application **traffic probably doesn't justify GPU cost**: Unless you're serving thousands of AI requests per second, the cost of GPU infrastructure exceeds the cost of running inference on CPU. CPUs scale naturally with your application traffic. GPUs require sustained high utilisation to justify their cost.

**Infrastructure complexity matters**: CPU-only deployment means your team uses the tools and workflows they already know. Standard containers, familiar debugging, local development without special hardware. No GPU drivers, no CUDA versions, no specialised orchestration. For teams building applications, this is significant.

## Architecting AI into your application

You have two deployment patterns:

**Monolithic** (simpler): Run inference in your application backend alongside your other logic. Your API servers handle HTTP requests, database queries, business logic, and AI inference. Everything runs on CPU instances. This works well for most applications and keeps deployment straightforward.

**Separated** (more flexible): Run your application on CPU instances and call a separate model serving layer for inference. That serving layer can be CPU or GPU depending on your needs. This pattern makes sense when you have multiple applications sharing models, or when inference requirements differ significantly from your application's requirements.

Start with the monolithic pattern. If you outgrow it, migrate to separated serving. The migration is easier than starting with complex infrastructure you don't need yet.

## Making the decision for your application

The default is CPU-based deployment. Move to GPU only when you have measured evidence that you need it.

**Deploy on CPU** when (most applications):

* Building an application with AI features, not an AI-first product
* Using models designed for production deployment
* Application serves typical web/API traffic patterns
* Team uses standard deployment workflows
* Getting to production quickly matters
* Your application is only using the openai API

**Consider GPU** when (high-scale applications):

* Measured CPU inference latency violates your SLAs after trying optimised models
* Application consistently serves thousands of AI requests per second
* Cost analysis shows GPU infrastructure is more economical at your scale
* You've already optimised everything else and inference is the bottleneck

Start with CPU deployment on your existing infrastructure. Add AI inference to your application alongside your other features. Measure latency and cost under real traffic. If it works, you're done. If not, you have real data to guide infrastructure decisions.

Most applications never need to make the jump to GPU. And that's perfectly fine.

Use this decision tree to help!

```mermaid theme={null}
%%{init: {'theme':'base', 'themeVariables': { 'fontSize':'16px'}}}%%
flowchart TD
  Start([Need GPU for AI?])
    Start --> Q1[Training or<br/>fine-tuning?]
    
    Q1 -->|Yes| GPU1(USE GPU)
    Q1 -->|No| Q2[Large generative<br/>models?]
    
    Q2 -->|No| CPU1(USE CPU)
    Q2 -->|Yes| Q3[High volume<br/>1000+ req/sec?]
    
    Q3 -->|No| CPU2(USE CPU<br/>Start simple)
    Q3 -->|Yes| GPU2(USE GPU)
    
    classDef cpuResult fill:#D0F302,stroke:none,color:#000,font-weight:bold;
    classDef gpuResult fill:#6046FF,stroke:none,color:#FFF,font-weight:bold;
    classDef question fill:#FFF,stroke:#000,stroke-width:2px,color:#000;
    classDef startNode fill:#000,stroke:none,color:#D0F302,font-weight:bold;
    
    class CPU1,CPU2 cpuResult;
    class GPU1,GPU2 gpuResult;
    class Q1,Q2,Q3 question;
    class Start startNode;
```

## The bottom line

If you're building an application with AI features, you're adding inference to an existing application architecture. Your application already runs on CPU infrastructure - web servers, databases, caching, background jobs. AI inference is one more capability, not a reason to redesign everything.

For most applications, running inference on your existing CPU infrastructure works. The models optimised for production deployment run efficiently on modern CPUs. Your traffic patterns probably don't justify GPU infrastructure costs. Your team already knows how to deploy and debug applications on CPU instances.

Start simple. Deploy AI features on your existing infrastructure. Measure performance under real traffic. If CPU inference meets your requirements, you're done. That's where the majority of production AI applications end up, and there's no shame in being part of that majority. Shipping working software beats over-engineering infrastructure.

If you need more performance, you have options: optimize your model, separate model serving from your application tier, or - only if necessary - move to GPU infrastructure. Make those decisions based on measured need, not assumptions.

Build for your current requirements. Most applications adding AI features don't need GPUs.


# CVE-2024-45337
Source: https://developer.upsun.com/posts/discussions/cve-2024-45337



<PostMeta />

<Note>
  This article was originally published on the [Platform.sh blog](https://platform.sh/blog/uncovered-and-patched-golang-vunerability/).
</Note>

## Overview

On September 5th 2024, the engineering team at Platform.sh discovered a security vulnerability in the `golang.org/x/crypto/ssh` package. Upon investigating an unexpected `Panic: runtime error: invalid memory address or nil pointer dereference` message in our edge proxy, the engineers discovered our own misimplementation and common misuse of the `PublicKeyCallback` function. We quickly remediated and found no reason to believe this vulnerability was exploited before we patched.

Systems that implement this callback function incorrectly, end up with a vulnerability that allows an authorization bypass in Go's `x/crypto/ssh`. Our analysis suggests that this issue is prevalent across multiple projects utilizing this (`golang.org/x/crypto/ssh`) package, leading to potentially severe security implications.

At the time of writing there are [\~19k known importers of this ssh package](https://pkg.go.dev/golang.org/x/crypto/ssh?tab=importedby).

While this is ultimately a bug in the usage of the package by end-users, we believe that the design of the `PublicKeyCallback` function and its documentation is contributing to the vulnerability, which has the potential to affect a broad spectrum of users in the wild. Given the broad impact potential we chose to disclose the vulnerability to the Go Security team.

## Timeline

* **September 5th, 2024**: Engineering discovered security auth bypass in `x/crypto/ssh`.
* **September 12th 2024**: Reported findings to Go Security team and implemented mitigations.
* **October 2nd, 2024**: Go security team reviewed our report and confirmed our findings.
* **December 6, 2024**: [Go security team made pre-announcement](https://groups.google.com/g/golang-announce/c/ZA1tNV10Mcs).
* **December 11, 2024**: Go security team made [public](https://groups.google.com/g/golang-announce/c/-nPEi39gI4Q) [disclosure](https://github.com/golang/go/issues/70779) and released [v0.31.0](https://pkg.go.dev/golang.org/x/crypto@v0.31.0/ssh) of `golang.org/x/crypto`.

## Context

The SSH-2 protocol, specified in [RFC 4253](https://datatracker.ietf.org/doc/html/rfc4253), was designed in its current form back in 2006 as an evolution of the original SSH-1 protocol going back to 1995. Back in SSH-1 times, the client authentication was done as a challenge/response protocol outlined under `SSH_AUTH_RSA` on pages 11-12 [here](https://www.ietf.org/archive/id/draft-ylonen-ssh-protocol-00.txt). This allowed clients to ask the server where a particular key had the potential to be accepted:

> "The client sends `SSH_CMSG_AUTH_RSA` with public key modulus (n) as an argument. **The server may respond immediately with `SSH_SMSG_FAILURE` if it does not permit authentication with this key.** Otherwise it generates a challenge." [^1]

The SSH-2 protocol changed this to a static signature based on data that is already known by the two parties, but kept a query mechanism in place as a way to improve performance and usability. [Section-7 of RFC 4252](https://datatracker.ietf.org/doc/html/rfc4252#section-7):

> "Private keys are often stored in an encrypted form at the client host, and the user must supply a passphrase before the signature can be generated. Even if they are not, the signing operation involves some expensive computation. **To avoid unnecessary processing and user interaction, the following message is provided for querying whether authentication using the "publickey" method would be acceptable.**" [^2]

## Details

The `golang.org/x/crypto/ssh` package is an implementation of the SSH-2 protocol. The golang implementation hides the complexity of the "query that a key might be accepted / actually authenticate" dance under a single API.

`PublicKeyCallback` is called only once for a particular key, before the client has proven possession of the private key, via a cache implemented in `server.go#L621`.
The comments in `PublicKeyCallBack` function below have critical implementation details that are easily overlooked.

```go {filename="server.go"} theme={null}
// PublicKeyCallback, if non-nil, is called when a client
// offers a public key for authentication. It must return a nil error
// if the given public key can be used to authenticate the
// given user. For example, see CertChecker.Authenticate. A
// call to this function does not guarantee that the key
// offered is in fact used to authenticate. To record any data
// depending on the public key, store it inside a
// Permissions.Extensions entry.
PublicKeyCallback func(conn ConnMetadata, key PublicKey) (*Permissions, error)
```

The ease of misimplementation for this function was previously mentioned in issue [#20094 from April 2017](https://github.com/golang/go/issues/20094), and clarifying code comments were [subsequently added](https://go-review.googlesource.com/c/crypto/+/45311/7/ssh/server.go#69).

Despite the description hinting that `PublicKeyCallBack` func needs to be implemented in a stateless way, what can happen, if the func is stateful, is a client can successfully query a public key that it doesn't use. Where doing so only requires knowledge of the public key which, by nature of being public, is very know-able. For example, the public keys of all github users are public if you append `.keys` to the user url.

<Note>
  [Here are Damien Tournoud's (our CTO) public keys for your enjoyment](https://github.com/damz.keys).
</Note>

The flaw in this process occurs because the `PublicKeyCallback` is not called again after the client presents the key, allowing the attacker to gain access without possessing the private key for the queried key.

## Relevance to Upsun & Platform.sh

Our SSH gateways allow our customers to access containers running on our infrastructure using standard SSH tools and are based on the open source `golang.org/x/crypto/ssh` package.

We favour open source technologies and enjoy [contributing and supporting open source projects we love](https://platform.sh/community/open-source/). Catching and addressing an issue like this is something our teams take great pride in. It genuinely feels awesome when you can make the tools you use better for everyone else.

Given the reach of this issue (19k importers) we believed the upstream Go team was best suited to handle the disclosure. We encourage others to also disclose responsibly and have confidence in their upstream maintainers. As developers ourselves we understand it can often be a thankless job, and unwarranted complications are not welcome. Eliminating unnecessary complexities for developers is the core our products are built on.

Before this devolves too much into a “puff piece,”  if you relate with any of these sentiments please reach out!

## Our recommendations

If you have a Go project depending on crypto/ssh, update the package to the newest version with:

```bash theme={null}
go get -u golang.org/x/crypto/ssh
```

Then, if your code has a `PublicKeyCallback` method (implementing the `ssh.ServerConfig` interface), you will need to ensure that:

* The callback must be stateless, or in other words, it must not have any side effects. As the comments on the interface suggest, return any state directly in the function as part of the `ssh.Permissions` object.
* Do not assume that the public key is authenticated at this stage. Use the `PostSuccessAuthCallback` if you need to run code after the client has proved possession of the private key. This will be passed the same `ssh.Permissions` object.

Even if the `PublicKeyCallback` is not part of your own code, remember to check that you are not using any other packages that misimplement the same callback. If so, they will also need to be updated, fixed or removed.

The package maintainers were very understanding and professional as we communicated that users of the `x/crypto/ssh` package expect that the key used by the client for authentication (if successful) matches the one passed to the most recent call to `PublicKeyCallback`.

The maintainers' cache fix should mitigate this vulnerability for the majority of implementations, unfortunately it cannot fix all.

[^1]: Ylonen, T. (1995) [The SSH (Secure Shell) Remote Login Protocol](https://www.ietf.org/archive/id/draft-ylonen-ssh-protocol-00.txt#:~:text=private%20host%20key.-,SSH_AUTH_RSA,-The%20idea%20behind). IETF.

[^2]: Ylonen, T. (2006) [The Secure Shell (SSH) Authentication Protocol](https://datatracker.ietf.org/doc/html/rfc4252#section-7). IETF.


# Give your AI agent a system that is safe to break
Source: https://developer.upsun.com/posts/discussions/give-your-ai-agent-a-system-that-is-safe-to-break

Handing an agent credentials narrows what it can do, not where its mistakes land. Run it inside a branched environment instead, and the worst outcome is a broken copy of your stack.

<PostMeta />

An agent that can only read your code is a fancy linter. Ask it to reproduce the bug from the ticket, run the migration and check what broke, or find out whether that query is really slow, and it needs the rest of the system: the database with real rows in it, the cache, the search index, the app that ties them together.

Running the agent somewhere is the solved half. The interesting half is what it can reach once it's running, and what it costs when it gets something wrong.

## The usual shape of the problem

On most platforms, your app and its services are separate things. The platform runs your code. The database, the queue, and the search index are independent services, sometimes from other providers, sometimes from the same one, each provisioned on its own and reached over the network with its own credential. It works, and the separation is often deliberate.

It does mean an agent starts with access to nothing. To make it useful you hand it credentials to the real services, and that's the awkward part. A long-lived token in an environment variable is already a bad idea when a human holds it. It's worse when the holder is an agent that can hallucinate.

There's no single answer to that, only one mechanism per service: a connection string injected as an environment variable here, a short-lived scoped credential there for the providers that issue them, an access policy somewhere else again. Each is reasonable on its own, and the better ones do narrow what the agent can do and how long it can do it. You still assemble them service by service, and then maintain them.

A narrower credential limits what the agent can do. It doesn't change where those actions land. A tighter credential pointed at production is still pointed at production.

Point it somewhere else, then, at staging instances rather than the live ones. Plenty of teams do exactly that, and it works. It's also a chore that never ends. You need a non-production instance of every service the agent touches, the database and everything around it, and each provider has its own way of giving you one. Some branch a copy on demand. Others leave you running a second instance by hand. Then you keep every schema in step with production, seed each one with data realistic enough to be worth testing against, and repeat the exercise the next time someone adds a service. Miss one, and the agent is quietly back on that service's production instance. Nothing warns you, because everything keeps working, right up until it doesn't. What you maintain isn't a copy of your system, it's a set of separate copies of its parts, each drifting at its own speed.

There's another way to arrange this, and it starts one level down.

## The environment is the unit

On Upsun, a project isn't only your application. It's your applications and your services, described together in one `.upsun/config.yaml` and deployed together into one cluster. The Postgres instance, the Redis instance, the OpenSearch index, and the three apps that talk to them are one deployable thing.

Because the whole stack is one unit, it copies as one unit. Branch an environment and you get all of it: the code at that commit, the services, and the data inside them, cloned copy-on-write and running in isolation from the parent. That's the mechanism behind preview environments, and it [predates anyone's interest in agents by years](/posts/discussions/instant-data-cloning-was-a-bet-ai-agents-are-the-payoff). It exists so a reviewer can click a link on a pull request and see a feature working against real data.

It turns out that's roughly what an agent wants too.

## A task is a container inside that environment

A [task](/docs/configure-apps/tasks) is an on-demand, run-to-completion container. You declare it alongside your apps and services, it's injected into the environment's cluster when triggered, it runs one command, and it's removed when that command exits.

```yaml {filename=".upsun/config.yaml"} theme={null}
  applications:
    myapp:
      type: php:8.4
      relationships:
        database: {}

  services:
    database:
      type: postgresql:17

  tasks:
    myagent:
      source:
        root: /agent
      type: nodejs:22
      run:
        command: node agent.js
        timeout: 3600
      hooks:
        build: npm ci
      relationships:
        database: {}
        app: "myapp:http"
```

The `relationships` block is where the interesting bit lives. Inside the task container, those connections appear in `PLATFORM_RELATIONSHIPS` exactly as they do for an application. The agent reads its database credentials the same way `myapp` reads them, from the same place, in the same format.

There was no token to hand out, because there's nothing outside the environment to hand one out for. The database sits in the environment and is reachable only from inside it: services have no public IP and no inbound route from the internet, so there's no front door to knock on from anywhere else. Access inside the cluster isn't automatic either. If a relationship isn't declared, the network route between those two containers doesn't exist. And the credentials the agent reads were generated for this environment when it was created, so they don't work anywhere else. The agent inherits its access the way every other container does, by being in the environment and being declared.

## Triggering one without handing out a key

Tasks run from the Console, from the CLI with `upsun task:run myagent`, or through the API. The third case is the interesting one, where your application triggers the agent itself.

That could have required an API token stored in the app. It doesn't. You declare what the app is allowed to do with [workload authorizations](/docs/configure-apps/image-properties/authorizations):

```yaml {filename=".upsun/config.yaml"} theme={null}
  applications:
    myapp:
      authorizations:
        - type: task        # may trigger and operate this task
          resource: myagent
          action: operate
        - type: env         # may read the environment API
          action: view
```

At runtime the app asks a local proxy for a short-lived token carrying exactly those permissions. It's the same principle as scoped credentials everywhere else, applied to the trigger rather than to the data, and the permission is declared in the config file next to the code it governs.

Each run creates an activity, the same object a deploy or a backup creates, so an agent run has an ID, a live status, streamed logs, and a cancel endpoint. Whatever you already use to watch a deploy works on an agent.

## The blast radius is one environment

Now put the two halves together. Run the task in a branched environment, and the agent has a complete, realistic system to act in, where the worst outcome is a broken copy.

That changes which permissions are worth arguing about. You don't have to hold a meeting about whether the agent should be allowed to write to the database, because the database is disposable. Let it write. Let it run the migration, drop the table, fill the cache with nonsense. If it goes badly, delete the environment and branch a fresh one, and you're back to a known-good full stack in the time it takes to clone.

An agent that can only read is limited to suggesting things. An agent that can write, somewhere writing is cheap, can check its own work: apply the migration, run the suite, look at the result, try again. Being able to be wrong safely is most of what makes an agent useful.

## What this doesn't solve

Three caveats, because none of this is magic.

A clone of production contains production data. The isolation is real, and the environment can't touch production, but the rows in it are still your customers' rows. If the agent writes them to a log, a report, or a model provider's API, you've moved production data somewhere new. Upsun supports [sanitizing databases](/docs/development/sanitize-db) in a deploy hook so preview environments carry realistic but scrubbed data, and that matters considerably more once something autonomous is reading them. It's opt-in. Turn it on.

Tighter isolation is configuration you add. Every Upsun container is already rootless, namespace-isolated, syscall-filtered, and running from a read-only application filesystem, with nothing to switch on. That's what keeps containers out of each other. It's not the same as restricting the agent's own process within its container, which is the layer that matters when the agent reads content you didn't write. Stripping environment variables, cutting network access, and giving the agent's shell a read-only filesystem are all standard Linux tools, covered step by step in [sandboxing AI agents on Upsun](/posts/tutorials/sandboxing-ai-agents-on-upsun).

External services are still external. The environment gives the agent your stack. It doesn't give it the third-party APIs your application calls, and for those you're back to handing out credentials, with the usual answers: scope them narrowly, keep them short-lived, revoke them centrally. The difference is scope, because for most of what an agent does day to day, the systems it needs are the ones already in the environment.

## The takeaway

The interesting question about agent infrastructure isn't where the process runs. Ephemeral compute is a solved problem, and everyone is converging on the same answer, Upsun included. Tasks are a good execution primitive precisely because they're boring: a container and a command.

The question that matters is what the process can reach, and how much it costs when it's wrong. Answer that with credentials and you spend your time narrowing scopes, because every action still lands on the live system. Answer it with an environment and the question mostly stops being about permissions. The agent gets full access to a complete system, and the system is one you can throw away.

Environment cloning wasn't built for agents. It was built so a reviewer could look at a pull request running against real data. The property that made it good for review, a complete stack that's safe to break, is the same one that makes it good for something that will definitely break it.


# Golang 1.24 is looking seriously awesome
Source: https://developer.upsun.com/posts/discussions/go-124



<PostMeta />

The Golang team just released the [first release candidate of Golang 1.24](https://tip.golang.org/doc/go1.24). At Upsun, we use Golang extensively for everything in our hot path, especially for the routing of HTTP requests throughout our infrastructure. Here is what we are looking forward to the most.

### Some nice performance improvements

We have not looked into these very closely yet, but they seem nice:

* 2-3% performance improvement across the board, driven by "a new builtin map implementation based on Swiss Tables, more efficient memory allocation of small objects, and a new runtime-internal mutex implementation"[^1]; and
* Two new cgo directives (`noescape` and `nocallback`)[^2] that have the potential to reduce the overhead of calling C code from Go in some cases

[^1]: *Runtime*, [Go 1.24 Release Notes](https://tip.golang.org/doc/go1.24#runtime).

[^2]: *Tools, Cgo*; [Go 1.24 Release Notes](https://tip.golang.org/doc/go1.24#cgo).

### A weak pointer implementation (finally!)

Probably my favorite, Go 1.24 includes an implementation of a weak pointer.

A weak pointer is a reference to an object that does not prevent the garbage collector from collecting it. In practice, the implementation is simply a `weak.Pointer[T]` (which nicely mirrors `atomic.Pointer[T]`), which has a `Value() *T` method.

This new weak pointer concept -- in addition to the `unique` package [introduced in Go 1.23](https://go.dev/blog/unique) -- has the potential of powering nice improvement of memory usage in real-world Go applications.

### Post-quantum cryptography

This release introduces support for post-quantum cryptography in the `crypto/tls` package. The standard library now includes ML-KEM, "a post-quantum key exchange mechanism formerly known as Kyber and specified in [FIPS 203](https://doi.org/10.6028/NIST.FIPS.203)" [^3].

Post-quantum cryptography, if you haven't been following, is a reference to a new set of cryptographic algorithms that are deemed resistant to attacks by quantum computers, which could potentially break many of the current commonly used cryptographic algorithms.

[^3]: *New crypto/mlkem package*; [Go 1.24 Release Notes](https://tip.golang.org/doc/go1.24#crypto-mlkem).

### Encrypted Client Hello (ECH) in `crypto/tls`

The goal of Encrypted Client Hello (ECH), and of its predecessor Encrypted SNI (ESNI) is to bring a long standing privacy gap in TLS: while the actual communication over TLS is private, the identity of the server isn't. The protocol uses a public key, distributed via DNS and obtained using DNS-over-HTTPS, for encryption during the client's first flight.

This is an option we are going to look into offering on Platform.sh and Upsun at one point. We still need to figure out how to best do that.

### `encoding/json` gets better support for zero value through the new `omitzero` tag

This release fixes a long-standing issue in `encoding/json`: the `omitempty` tag only supports a subset of types, and has a definition that is at odd with the standard definition of the zero value in the language. The new `omitzero` tag now allows you to specify that a field should be omitted from the serialization if it has the zero value for its type.

The current `omitempty` option specifies that the field should be omitted from the encoding *"if the field has an empty value, defined as `false`, `0`, a `nil` pointer, a `nil` interface value, and any empty array, slice, map, or string"*. This has always been unfortunate, because Golang has different definition of what a ["zero value"](https://go.dev/ref/spec#The_zero_value) is: *"`false` for booleans, `0` for numeric types, `""` for strings, and `nil` for pointers, functions, interfaces, slices, channels, and maps"*.

If you compare the two definitions, you would note they are identical for booleans, all numeric types, empty arrays and interface values. But they handle slices and maps differently:

* `omitempty` will omit any empty slices or maps (i.e. slices or maps that satisfy `len(S) == 0`), which includes slices or maps that are `nil`
* `omitzero` on the other hand will only omit slices or maps that are `nil`

They also handle non-pointer struct values differently. Take [this example](https://go.dev/play/p/UWVF3QAlAS0?v=gotip):

```golang {fileName="omitzero-example.go"} theme={null}
package main

import (
	"encoding/json"
	"log"
)

type Foo struct {
	OmitEmpty Bar `json:"omitempty,omitempty"`
	OmitZero  Bar `json:"omitzero,omitzero"`
}

type Bar struct {
	A int `json:"a"`
}

func main() {
	data, _ := json.Marshal(&Foo{})
	log.Printf("Generates: %s", string(data))
}
```

It generates:

```json theme={null}
{"omitempty": {"a": 0}}
```

Given the above, our recommendation would be to continue using `omitempty` for maps and slices, but use `omitzero` for everything else.

### A new `tool` directive in `go.mod`

This release adds a new `tool` directive to `go.mod`, allowing you to specify dependencies to build tools without having to resort to the current convention of having an empty `tools.go` somewhere in your project.

Previously, a project depending on the `stringer` tool to generate string versions of enums would have somewhere a file containing something like:

```golang theme={null}
//go:build ignore

package foo

import (
	_ "golang.org/x/tools/cmd/stringer"
)
```

And you would execute that tool with a `go:generate` line like this:

```
//go:generate go run golang.org/x/tools/cmd/stringer -type Foo
```

It worked well enough. But now in Golang 1.24, you can simply add a `tool` directive to your `go.mod`, like this:

```
tool golang.org/x/tools/cmd/stringer
```

This tool becomes available by just running:

```
//go:generate go tool stringer -type Foo
```

Not a huge deal, but still a nice quality of life improvement.

### Context support in the `testing` package

I have been wanting this for a while. The `*testing.T` and `*testing.B` types now have a `Context() context.Context` method, returning a context that is canceled just before `Cleanup` functions are called.

This will allow replacing:

```golang theme={null}
func TestFoo(t *testing.T) {
    ctx, cancelFn := context.WithCancel(context.Background())
    t.Cleanup(cancelFn)

    // [...]
}
```

with:

```golang theme={null}
func TestFoo(t *testing.T) {
    ctx := t.Context()

    // [...]
}
```

Another nice quality of life improvement, and the potential to make it easier and more natural to build cleaner tests.

### A new `testing/synctest` package for testing concurrent code

This is still experimental, but looks really fun. It is a new package that allows you to define "bubbles" of goroutines into which a fake clock is provided (i.e. `time.Now()` returns something different). This will eventually make it easier to test time-sensitive concurrent code, where the best practice right now is to provide a clock function returning the current time (i.e. a `func() time.Time`), so that fake time can be injected during tests (it is, for example, how the `github.com/juju/ratelimit` token-bucket implementation [is tested](https://github.com/juju/ratelimit/blob/v1.0.2/ratelimit.go#L45)).

### A lot of other things

The Golang team really gave us a nice present this holiday season. There is so much more to mention:

* An improved finalizer support with `runtime.AddCleanup`;
* The new `encoding.TextAppender` and `encoding.BinaryAppender` interfaces, and their support on many types throughout the standard library;
* Cryptographically secure random text strings with the new `rand.Text` function;
* ... and so much more.

Read the [full draft release notes](https://tip.golang.org/doc/go1.24), and don't hesitate to come and discuss your favorite parts with us on the [Upsun Community Forum](https://community.upsun.com/)!


# Governance is a contract chain, and you're in it
Source: https://developer.upsun.com/posts/discussions/governance-is-a-contract-chain-and-youre-in-it

Governance is a chain of contracts from certification bodies to you. AI didn't change the chain, but it produces code faster than humans can review it.

<PostMeta />

"Governance" is one of those words that feels like it belongs to someone else. A compliance team, maybe, or a VP who sends emails with "audit" in the subject line. It's easy to assume it doesn't have much to do with your day-to-day work as a developer.

That assumption is wrong. If you work in a regulated industry, governance is already yours whether you wanted it or not. And if you're using AI tools to write code, you're producing work faster than anyone around you can review it.

## Governance is a chain of contracts

Strip away the jargon, and governance is really a chain of contracts. Each link in the chain creates obligations that flow downward.

Your company holds a certification (ISO 27001, SOC 2, PCI DSS, pick your flavor; [Upsun holds all of them](https://upsun.com/trust-center/)). That certification comes from a certification body that audits your company against a set of controls. Your company agreed to maintain those controls in exchange for the right to display the certification logo on its website and hand it to prospective customers.

Your company also has contracts with its customers. Those contracts often reference the certification explicitly: "We are SOC 2 Type II compliant, and here's the report to prove it." Customers signed on that basis. They're trusting that the controls described in the certification are actually in place.

Then there's your employment contract. You agreed to follow company policies, which include the controls required by the certification. You might not have read that part carefully, but the obligation is there.

So the chain looks like this: certification body sets the standard, company commits to the standard, you commit to the company. Governance is the practice of keeping this chain coherent. Making sure that what the certification body expects, what the company promises its customers, and what you actually do on a daily basis are all the same thing.

## Blame culture vs. root cause

Here's where governance gets its bad reputation.

In a poorly run organization, the contract chain becomes a weapon. Something goes wrong in production, and management traces the chain downward until they find someone to blame. The chain exists, but it's only invoked after the fact, as a forensic tool for assigning fault.

This is not governance. This is dysfunction wearing governance's clothes.

In a well-run organization, governance does the opposite. Because the chain of contracts makes expectations explicit, everyone knows what they're accountable for *before* something goes wrong. When an incident happens, you can run a blameless postmortem precisely because accountability was already clear. You're not trying to figure out who should have done what; you're figuring out why the system allowed a failure to happen despite the controls.

The scary part of governance isn't the accountability itself. It's ambiguity. When nobody knows where their obligations start and end, every incident becomes a political exercise. Governance, done properly, removes that ambiguity.

## AI didn't change the chain

Your SOC 2 auditor doesn't care whether Copilot wrote your code or you typed every character by hand. The control says "code must be reviewed before merging to production." Whether the code originated from a human brain or a large language model is irrelevant to the control.

Your customer's SLA doesn't have an "AI did it" clause. If a deployment breaks their service, the contractual obligation is the same regardless of how the breaking change was authored.

Your employment contract doesn't distinguish between code you typed and suggestions you accepted from an AI assistant. You committed the code. You pushed it. Your name is on the pull request.

The chain of contracts hasn't changed at all. Every link is exactly where it was before AI tools entered the picture. The certification body still expects the same controls. The company still promises the same things to its customers. You're still bound by the same employment terms.

## The speed gap

What AI did change is the speed at which you produce work that flows through this chain.

Before AI tools, writing code was usually the slowest part of the chain. It generally took longer than reviewing it, testing it, or deploying it. The governance controls (code review, testing, approval workflows) tended to have spare capacity because the input rate was naturally limited by how fast a person could think and type.

AI flipped that. You can now generate code faster than anyone can review it. The bottleneck moved from production to verification, and the governance structure wasn't designed for that.

This is a hard constraint. A reviewer can only hold so much context in their head at once. They can only carefully read so many pull requests per day, and every hour spent reviewing is an hour they're not writing their own code. There's no "review harder" setting. When AI enables you to open ten pull requests in the time you used to open three, the review quality per pull request drops, or the review queue grows, or both. Either way, the controls that the certification body expects are degraded.

The chain doesn't need to change for this to become a problem. Certification bodies don't need to say anything about AI; the existing controls already cover the situation. "Code must be reviewed before production" doesn't stop applying because the code was generated faster. The question isn't whether the governance chain will adapt. It's whether you and your team can find the right balance between AI-assisted speed and the review throughput your controls actually require.

## Understanding the chain gives you clarity

None of this should make you anxious. It should make you informed.

The accountability was already yours before AI tools showed up. Your name was already on the pull request. Your company was already bound by its certifications. Your customers were already relying on those commitments.

What's different now is that you can produce more work, faster, than any human can verify. The governance structure doesn't need to change, but how you work within it does. Knowing the chain exists, understanding where the contracts connect, and recognizing the limits of human review capacity gives you something useful: the ability to make deliberate choices about how fast you move and how carefully you verify.

Governance isn't a bureaucratic obstacle. It's a map of who promised what to whom. Reading the map is the first step toward working within it without getting surprised by it.


# How product managers use preview environments and AI to prototype
Source: https://developer.upsun.com/posts/discussions/how-product-managers-use-preview-environments-and-ai-to-prototype

Learn how product managers at Upsun use AI coding assistants and preview environments to prototype feature ideas, validate concepts with real data, and share interactive demos with stakeholders.


<PostMeta />

There's a gap between having a product idea and actually showing it to someone. Product managers write briefs in Linear, describe features in Slack threads, maybe sketch wireframes. All text. All static. And then you hope everyone reads it, imagines the same thing you're imagining, and feels as excited as you do about a concept that only exists in your head.

That rarely happens.

At Upsun, we've been closing that gap: PMs talk to an AI coding assistant, generate a working prototype, push a branch, and share a live URL. The whole thing takes an afternoon. It doesn't replace designers doing proper designs in Figma, and it doesn't replace engineers writing production code. But it fills a hole in the early ideation stage that no amount of well-written tickets can fill.

## The gap between idea and validation

There's a dead zone at the very beginning of any product idea. You have a rough concept and you need to communicate it to people who weren't inside your head when you thought of it. A Linear project or a Slack thread doesn't have the same power of influence as seeing an idea in an interface and playing with it directly.

Product managers aren't designers and they aren't developers either. They have ideas and deep knowledge of the problems and needs of the customers, but lack the traditional tools to make those ideas tangible quickly. Talking to an AI coding assistant changes that equation. You tell Claude what you want to test, iterate on a rough spec through conversation, and end up with something interactive that people can click on and react to. It's faster than opening a Figma file, and considerably faster than writing a spec detailed enough for someone else to build from.

## A prototype is worth a thousand briefs

The code quality is irrelevant. This is vibe coding in the truest sense: the generated code must be thrown away. It should never, under any circumstances, end up in production. You're not building software, you're communicating an idea. The prototype exists to be seen, reacted to, and then deleted.

One of our colleagues built a rough prototype for a feature idea, just to show what it could look like. It was a proof of concept, nothing more. But weeks later, engineers referenced that prototype when planning a real initiative around the same topic. A scrappy afternoon demo turned into the starting point for actual engineering work.

That's what prototypes do that briefs can't. They generate momentum. People see an interactive demo and say "oh, and we could also do this" and "what if we added that." The conversation shifts from "should we build this?" to "how should we build this?" And then proper design and engineering take over.

## Prototypes also prove ideas are bad

This works in the other direction too, and that might be even more valuable.

If you spend 30 minutes talking to Claude about a feature idea and the result feels wrong when you see it... you've saved everyone a lot of time. Delete the branch, the environment disappears, and you move on. No lengthy product brief. No technical discovery. No three weeks of back-and-forth before someone finally admits the idea doesn't work. Quick invalidation is underrated.

## Why this only works with real data

Say you want to test a new category page layout for an e-commerce site. You build something locally with three test categories named "Category 1," "Category 2," and "Category 3." It looks fine. But your production store has 47 categories with real names, real images, and wildly different product counts. The layout that looked clean with three placeholders falls apart.

Local environments have fake data. Staging has stale data. Upsun preview environments clone your production environment, data included. When you create a branch from production, your preview runs under the same conditions with the same data. It's disposable, but it's not degraded. You're testing your idea against reality, not against a sanitized version of it.

For a deeper look at how preview environments work and what makes them different from traditional staging setups, see [Preview environments: a developer's secret weapon](/posts/discussions/preview-environments-a-developers-secret-weapon).

## Git push is the whole workflow

There's no deploy pipeline to configure. No environment to provision. You push a branch and an environment exists. Every branch gets its own isolated world with its own URL, database, and services. It's not a shared staging environment where four people are fighting for access. Push again to update it. Delete the branch when you're done and everything disappears.

## You can do this too

None of this is internal tooling. Any team running on Upsun can do the same thing tomorrow. Point an AI coding assistant at your codebase, describe what you want to prototype, push the branch, and share the preview URL. Product managers, designers exploring layout ideas, support engineers reproducing customer issues... anyone who needs to get an idea out of their head and into something people can interact with.

This isn't an AI strategy memo. It's a daily habit. The code is messy. The prototypes are rough. But ideas move faster from "I think this could work" to "look at this and tell me what you think," and that's the gap that actually needed closing.


# Instant data cloning was a bet. AI agents are the payoff.
Source: https://developer.upsun.com/posts/discussions/instant-data-cloning-was-a-bet-ai-agents-are-the-payoff

How Upsun's data-first architecture, built a decade ago for CMS and e-commerce needs, turns out to be the exact infrastructure AI agents need: instant, isolated, production-identical environments with real data.


<PostMeta />

A bit over ten years ago, a small team inside a Drupal Commerce agency made a decision that seemed, at the time, wildly ambitious: **deployments should include data**. Not "data as an afterthought." Not "here's a script to restore a database dump." Data as a first-class citizen of every environment, instantly cloned alongside code, services, and files in one atomic operation.

That bet took two years of R\&D. At the time, Docker wasn't standard. Kubernetes didn't exist. The competition was Heroku, and Heroku was great at deploying code, but code alone wasn't enough. If you ran a CMS like Drupal, your content lived in the database. If you ran a Magento store, you couldn't load-test a storefront without production-scale catalog data. The same goes for [JCR-based apps](https://devcenter.upsun.com/posts/hands-on/stop-testing-jcr-apps-in-production) like Adobe Experience Manager or Magnolia, where the entire content structure, templates, and workflows live in the repository. The team needed automated deployments that carried the full stack: applications, services, files, and data. So they built it.

It wasn't a moonshot for a future driven by AI, or some grand infrastructure vision. It was a practical response to real problems: CMS content is meaningless without its database, e-commerce performance testing is fiction without production data... The motivation was mundane. The engineering was not.

## What cloning the data actually gives you

When you branch an environment on Upsun, the platform snapshots the metadata of your runtimes (frontend, backend, API server...), services (databases, message queues...), and files. It doesn't copy bytes. That's why cloning takes a couple of seconds whether your database is 500 MB or 500 GB. You get a fully independent preview environment (with its own URL, its own resources, its own permissions...) with zero interconnection to the source. Delete something in the clone, the original doesn't notice.

This exact same mechanism powers other Upsun key capabilities like:

* Branching, which creates a new preview environment from an existing one (like production).
* Backups, which capture a point-in-time snapshot that can be confidently restored.
* Synchronizing, which pulls fresh data from a parent environment.

Different use cases, same copy-on-write foundation.

And speed matters much more than you'd think. A clone that takes 30 minutes is a clone you avoid creating. A clone that takes 8 seconds is a clone you create without thinking about it. That difference changes behavior, and changing behavior is where infrastructure decisions compound.

## Agents need the same primitives

Today, AI agents have moved from "generate a code snippet" to "take this task, figure out what to do, and do it". That shift changed what agents need from infrastructure. A code suggestion can run in a sandbox or on a local machine. An agent that modifies database schemas, runs migrations, or load-tests an API endpoint needs a real environment with real data, real config, and real running services.

The requirements look familiar: an isolated environment that mirrors production, created fast enough to be disposable, destroyed when the task is done. That's what Upsun's cloning gives you. An agent gets a full copy of production (data, services, config) in seconds. It works against real state, not a synthetic approximation. When it's done, the environment disappears.

This isn't a feature built for AI. It's a feature built ten years ago that happens to be what AI agents need today.

## Reproducing bugs: the user\_7 problem

My own staff user account at Upsun ([user\_7@example.com](mailto:user_7@example.com)) has years of migration history baked into it. Every schema change, every feature flag toggle, every edge case in billing logic accumulated over time in that account's data. User 7 triggers bugs that nobody else can reproduce, because no fresh test account carries that history.

You can't fake this with seed data. You can't write a fixture that recreates years of organic state transitions. The only way to reproduce user 7's bugs is to test against user 7's actual data.

With Upsun data cloning, an agent grabs a full copy of the production environment (user 7 and all), branches it, and starts testing. It can mutate data, break things, try every combination of inputs, and the original environment stays untouched. When the agent identifies the root cause, it reports back. The clone gets deleted. No production risk, no manual environment setup, no waiting for a database dump to finish importing.

## Performance optimization without touching production

You can't measure real query performance against a test database with 50 rows. You can't profile cache hit rates without production traffic patterns reflected in the data. Performance work needs production-like conditions, and faking those conditions is a losing game.

Upsun data cloning solves this cleanly. Clone the production environment, upsize the preview environment to match production resources, then point a load-testing tool at it. Run [Blackfire](https://www.blackfire.io/) profiling against realistic traffic. Get measurable, actionable recommendations: this query needs an index, this loop should be batched, this cache TTL is too aggressive.

An agent automates this entire loop. Clone, configure, run the load test, collect profiling data, analyze results, present a ranked list of optimizations with projected impact. No one touches production. The environment gets thrown away when the analysis is done.

## Isolation and data safety

Giving an agent access to production data means thinking about PII. If the agent runs on a third-party AI provider's infrastructure, you probably don't want customer emails and credit card tokens flowing through someone else's model. But there's a tension here: scrub too aggressively and you lose the exact data quirks that make cloning valuable for bug reproduction in the first place.

It's your call. You can [configure sanitization rules](https://docs.upsun.com/development/sanitize-db.html) that run automatically when data is cloned into a non-production environment, choosing which fields get anonymized and which stay intact. Some teams scrub everything sensitive. Others keep more data in tightly controlled environments where agents operate under strict access policies. The point is that the mechanism exists at the cloning step, so you make the trade-off once and it applies to every clone.

Permissions matter too. Upsun supports fine-grained access control at the environment-type level. A production environment can have a completely different permission set than a staging or development environment. API tokens can be scoped so that an agent gets write access to its clone but can't touch production. This isn't a bolt-on; it's how the permission model has always worked.

## The payoff

Metadata-level cloning, copy-on-write storage, full-stack environment branching, configurable data sanitization. These are the building blocks of agent-ready infrastructure, and they've been in production for a decade. Upsun doesn't need to bolt on agent support because the foundation was already there.

It's a funny thing about infrastructure bets. The ones that age well aren't usually the ones that predicted the future correctly. They're the ones that solved a real, immediate problem with enough generality that the solution turned out to be useful for problems nobody anticipated. Cloning production data in seconds was built for CMS editors and e-commerce teams. It turns out AI agents need the exact same thing.

The bet paid off. Not because anyone predicted this particular use case, but because solving one hard problem well tends to stay useful longer than you'd expect.


# Critical Next.js Security Update: CVE-2025-66478 Affects RSC
Source: https://developer.upsun.com/posts/discussions/nextjs-cve-2025-66478

Remote code execution vulnerability in Next.js 15.x and 16.x App Router requires immediate patching. Learn how to secure your applications.

<PostMeta />

A critical vulnerability in Next.js requires immediate attention if you're running applications with the App Router. The issue, tracked as CVE-2025-66478, has received a CVSS score of 10.0—the highest severity rating possible.

This vulnerability affects the React Server Components (RSC) protocol and can allow remote code execution when processing attacker-controlled requests. The issue stems from an upstream React implementation vulnerability (CVE-2025-55182) that impacts Next.js applications using the App Router.

## Which versions are affected?

The vulnerability affects Next.js applications using React Server Components with the App Router in these versions:

* Next.js 15.x (all minor versions)
* Next.js 16.x (all minor versions)
* Next.js 14.3.0-canary.77 and later canary releases

**Good news**: Next.js 13.x, Next.js 14.x stable releases, Pages Router applications, and the Edge Runtime are not affected.

## What's the risk?

The vulnerable RSC protocol allowed untrusted inputs to influence server-side execution behavior. Under specific conditions, an attacker could craft requests that trigger unintended server execution paths. This can result in remote code execution in unpatched environments.

The Next.js team is intentionally limiting technical details to protect developers who haven't upgraded yet.

## How to fix this now

Upgrade to the latest patched version in your release line:

```bash {filename="Terminal"} theme={null}
# For Next.js 15.0.x
npm install next@15.0.5

# For Next.js 15.1.x
npm install next@15.1.9

# For Next.js 15.2.x
npm install next@15.2.6

# For Next.js 15.3.x
npm install next@15.3.6

# For Next.js 15.4.x
npm install next@15.4.8

# For Next.js 15.5.x
npm install next@15.5.7

# For Next.js 16.0.x
npm install next@16.0.7
```

If you're running Next.js 14.3.0-canary.77 or later canary releases, downgrade to the latest stable 14.x release:

```bash {filename="Terminal"} theme={null}
npm install next@14
```

There's no configuration option to disable the vulnerable code path. Upgrading is your only option.

## Update your Upsun deployments

After updating your Next.js version locally, commit the changes and push to your repository. Upsun will automatically rebuild and redeploy your application with the patched version.

```bash {filename="Terminal"} theme={null}
# Update your package.json
npm install next@15.0.5

# Commit the change
git add package.json package-lock.json
git commit -m "Security: Update Next.js to 15.0.5 (CVE-2025-66478)"

# Push to trigger deployment
git push upsun main
```

Your Upsun environment will rebuild with the secure Next.js version during the deployment process.

## Test before production

Use Upsun's preview environments to test the update before deploying to production. Create a new branch, update Next.js, and push:

```bash {filename="Terminal"} theme={null}
git checkout -b security-update
npm install next@15.0.5
git add package.json package-lock.json
git commit -m "Security: Update Next.js to 15.0.5"
git push upsun security-update
```

Upsun creates a complete preview environment with a production clone. You can test the updated version thoroughly before merging to your production branch.

## Verify your update

After deployment, check your running Next.js version in your Upsun environment:

```bash {filename="Terminal"} theme={null}
upsun ssh
cd /app
npm list next
```

This confirms you're running a patched version.

## Credit and disclosure

Lachlan Davidson discovered and responsibly disclosed this vulnerability. The coordinated disclosure process allowed the Next.js team to develop and release patches before public announcement.

## Learn more

Read the full technical details in the [Next.js security advisory](https://nextjs.org/blog/CVE-2025-66478) and the upstream [React CVE-2025-55182 advisory](https://www.cve.org/CVERecord?id=CVE-2025-55182).

For questions about deploying secure Next.js applications on Upsun, check our [Next.js deployment guide](https://docs.upsun.com/get-started/stacks/nextjs.md).

***

**Deploy secure Next.js applications on Upsun with built-in preview environments and automated deployments. [Create your free account](https://upsun.com) to get started.**


# Preview Environments
Source: https://developer.upsun.com/posts/discussions/preview-environments-a-developers-secret-weapon

Discover how preview environments transform software deployment, reducing stress and improving code quality. Learn about the six essential components for implementing preview environments, including Git, infrastructure as code, and automated DNS management. Find out why preview environments are crucial for catching bugs, testing performance, and enhancing collaboration between technical and non-technical team members. Explore how Upsun's platform leverages preview environments to streamline the development process and deliver higher-quality software products.


<PostMeta />

Most developers have a love-hate relationship with deployment. We love seeing our code running in production, but we hate the stress of wondering if it will actually work the way we want it to or if it will have any side effects (regressions).

This is where preview environments come in.

<img alt="Preview Environments on Upsun" />

A preview environment is a complete copy of your production setup, spun up automatically for each new feature or bugfix. It's like a dress rehearsal for your code before it hits the big stage.

## Why bother with this? Isn't it overkill?

Not really. Here's why:

**It's a reality check.** Your code might work fine on your machine, but will it work in production? A preview environment lets you find out before you're committed. In the world of software development, there's a common phrase: "It works on my machine." This is often followed by the unspoken "...but I have no idea if it will work anywhere else."

Preview environments eliminate this uncertainty. They provide a production-like setting where you can test your code in an environment that closely mimics the real thing. For example, imagine you're developing a new feature for an e-commerce platform. On your local machine, everything seems perfect. But when you deploy it to a preview environment, you discover that it conflicts with a caching mechanism used in production. By catching this early, you save yourself (and your users) from a potentially disastrous deployment.

**It's a universal translator.** Non-technical people can see and play with new features before they go live. Communication between developers and non-technical stakeholders can often feel like a game of telephone. Preview environments bridge this gap by providing a tangible, interactive representation of new features. Consider a scenario where you're building a new dashboard for a marketing team. Instead of showing mockups or trying to explain the functionality in a meeting, you can send them a link to the preview environment. They can click around, test different scenarios, and provide feedback based on actual usage. This improves understanding and catches usability issues early in the development process.

**It's a time machine for bugs.** You can run regression tests against a mirror of production, catching problems before they become everybody's problem. Regression testing is crucial, but it's often challenging to do effectively without a production-like environment. Preview environments solve this problem by providing a perfect replica for testing. Let's say you're working on a complex financial application. A seemingly minor change to a tax calculation function could have far-reaching consequences. With a preview environment, you can run your entire suite of regression tests against this change, ensuring that it hasn't broken any existing functionality. If a bug is introduced, you catch it before it affects real users and their financial data.

**It's a lie detector for your development environment.** Your laptop might be lying to you about how your code will behave. A preview environment tells the truth. Local development environments, while convenient, can often mask issues that only appear in production. Different operating systems, library versions, or even hardware can lead to discrepancies. For instance, you might develop on a Apple Silicon Mac, but your production environment runs on AMD64 Linux. A preview environment running on the same stack as production will reveal any OS-specific issues that your local environment hides. This could include anything from file path discrepancies to differences in how specific libraries behave.

**It's a crystal ball for performance.** You can stress test your changes and see how they'll hold up under real-world conditions. Performance issues often only reveal themselves under load, which is hard to simulate in a local environment. Preview environments allow you to conduct realistic performance testing. Imagine you've optimized a database query that will significantly speed up your application. In a preview environment, you can run load tests that simulate thousands of concurrent users, confirming that your optimization works as expected under stress. This kind of insight is invaluable for ensuring smooth deployments and maintaining user experience. Bonus points if you have an Application Performance Monitoring tool like Blackfire setup to test code performance on every build automatically.

In short, preview environments make deployments less of a nail-biting experience and more of **a confident strut**.

## But what do you need to make this happen?

It's not just a matter of spinning up a few extra servers. You need:

1. **Git.** Git is the foundation of modern version control and collaborative development. It's not just about tracking changes; it's about enabling parallel development streams. With Git, you can create feature branches, experiment freely, and merge changes confidently. This branching model is what makes preview environments possible in the first place. For example, a team working on an e-commerce platform could have separate branches for a new checkout process, an improved search function, and a redesigned product page - all of which can be previewed independently.

2. **Infrastructure as code.** Your entire setup needs to be reproducible at the push of a button. This is where the magic happens. Infrastructure as Code (IaC) allows you to define your entire infrastructure in text files. This means you can version control your infrastructure just like your code. When you create a preview environment, you're not just deploying code; you're spinning up an entire, identical copy of your production environment. This could include web servers, databases, caching layers, and even third-party services. The benefit? You're testing your changes in an environment that's as close to production as possible, drastically reducing the "it works on my machine" syndrome.

3. **A data layer that can be cloned quickly and safely.** You need production-like data, but you can't risk messing with actual production data. This is a crucial and often overlooked aspect. Real-world bugs often only appear with real-world data. But you can't just copy your production database - that would be a security nightmare. Instead, you need a system that can quickly create a sanitized copy of your production data. You don't want to wait hours while your production PostgreSQL instance is dumping data that you will have to reimport painfully.

4. **Deployment and monitoring tools that work across multiple environments.** It would help if you had robust tools to handle this complexity when dealing with numerous preview environments alongside your staging and production setups. The benefit is twofold: you can catch performance issues before they hit production and compare metrics between your preview and production environments to ensure your changes are having the desired effect.

5. **Automatic DNS and SSL certificate management.** Because life's too short to configure subdomains for every preview manually. This is where the rubber meets the road in terms of making preview environments truly useful. Each preview should have its unique, secure URL automatically generated. The benefit is that stakeholders can access and review changes without any technical setup. A product manager could click a link to see how a new feature looks and functions in a true-to-life environment.

6. **Sophisticated access control.** You don't want just anyone poking around in your previews. Security is paramount, especially when you're dealing with near-production environments. This should allow you to control who can access which previews and what they can do in those environments. For example, you might want your QA team to have full access to all previews while giving more limited access to external stakeholders or clients. The benefit is that you can confidently share previews widely, fostering collaboration without compromising security.

By implementing these six key components, you're not just setting up preview environments—you're fundamentally changing how your team develops and delivers software. You're creating a system where ideas can be quickly prototyped, tested, and refined in realistic environments. This leads to faster iteration cycles, higher-quality code, and better products.

**Teams working on complex, mission-critical applications can reap enormous returns on efficiency, quality, and peace of mind.**

This is why we built Upsun from the ground up around preview environments and our instant carbon-copy data layer, so you don't have to engineer your own platform and directly enjoy all the benefits.


# The universal commerce protocol and the inevitable rise of agentic commerce
Source: https://developer.upsun.com/posts/discussions/the-universal-commerce-protocol-and-the-inevitable-rise-of-agentic-commerce



<PostMeta />

## Introduction: The delayed unification of digital commerce

### A vision deferred: the fifteen-year arc

Fifteen years ago, I believed the trajectory of digital commerce was destined for a singular, consolidated fate. To me, the technological landscape was fracturing rapidly; the desktop monopoly had shattered, giving way to the mobile web, native applications, and the nascent experiments of Google Glass and early IoT devices. In my view, for independent brands and retailers, this multiplication of channels represented a terrifying escalation in technical complexity. To sell effectively, I thought a merchant needed not just a website, but a mobile-responsive design, an iOS app, an Android app, and integrations with a growing roster of marketplaces.

```mermaid theme={null}
flowchart TB
    M[Independent Brand]

    subgraph Channels["📱 Required Channels"]
        W[Desktop Website]
        MR[Mobile-Responsive Site]
        iOS[iOS Native App]
        Android[Android Native App]
    end

    subgraph Marketplaces["🛒 Marketplace Integrations"]
        AMZ[Amazon]
        EBAY[eBay]
        GSHOP[Google Shopping]
        MORE[+ More...]
    end

    M --> W
    M --> MR
    M --> iOS
    M --> Android
    M --> AMZ
    M --> EBAY
    M --> GSHOP
    M --> MORE

    style M fill:#495867,stroke:#000,color:#fff
    style Channels fill:#E8F9A3,stroke:#000
    style W fill:#B5A8FF,stroke:#000
    style MR fill:#B5A8FF,stroke:#000
    style iOS fill:#B5A8FF,stroke:#000
    style Android fill:#B5A8FF,stroke:#000
    style Marketplaces fill:#ffa69e,stroke:#000
    style AMZ fill:#ff686b,stroke:#000
    style EBAY fill:#ff686b,stroke:#000
    style GSHOP fill:#ff686b,stroke:#000
    style MORE fill:#ff686b,stroke:#000
```

At that specific juncture, it seemed inevitable to me that the friction of maintaining proprietary web properties would become insurmountable for all but the largest conglomerates. The prevailing hypothesis among forward-thinking analysts was that independent brands would retreat from the "storefront" model entirely.

Instead of maintaining complex, customer-facing technical stacks, I believed brands would evolve into **pure catalog providers—content** and logistics nodes feeding into massive, **centralized distributors like Amazon, Google Shopping**, and emerging marketplaces. My expectation was that the user interface, the "shop", would decouple completely from the merchant, centralized by tech giants who could master the fragmented device landscape better than any single retailer.

That consolidation did not happen. **My hypothesis was wrong. Or at least, premature.**

Instead, the opposite occurred. The last decade saw the explosion of Direct-to-Consumer (DTC) brands, powered by the democratization of "headless" commerce infrastructure. Platforms like Shopify, BigCommerce, and flexible PaaS solutions empowered merchants to maintain their own unique digital identities. The proliferation of channels did not force consolidation; it fostered a diverse, albeit fragmented, ecosystem where the brand website remained the sun around which marketing orbits revolved. Humans, it turned out, valued the brand experience, the storytelling, and the direct connection enough to navigate to brand.com rather than buying everything through a centralized aggregator interface.

### The arrival of the agentic era

We are now standing at the precipice of the shift that was predicted a decade and a half ago. The catalyst, however, is not a new device form factor like "smart glasses," but a fundamental change in the nature of the buyer itself. We are entering the era of **Agentic Commerce**, where the primary entity navigating the web is no longer a human clicking links, but an autonomous Artificial Intelligence (AI) agent executing tasks.

The rise of agentic systems, powered by Large Language Models (LLMs) and standardized interaction protocols, is finally forcing the unification of the e-commerce ecosystem. Unlike the device fragmentation of 2010, which brands could overcome with responsive design, the agentic shift fundamentally alters the *mechanism* of commerce. An AI agent does not care about your brand's font choice, your hero banner's emotional resonance, or your carefully curated "About Us" page. **It cares about structured data, API latency, inventory accuracy, and semantic relevance**.

This shift validates the fifteen-year-old prediction: the interface is finally decoupling from the inventory. When a user asks an advanced agent to "find me a red waterproof hiking jacket under \$200 that can be delivered to Denver by Friday," the agent does not visit five websites to browse. It queries a network of data sources, negotiates capability, and executes a transaction. In this world, the merchant's "web property" becomes less of a visual destination for humans and more of a structured data source for machines.

### The view from Upsun: Traffic patterns in transition

As a cloud application platform powering thousands of e-commerce workloads, Upsun occupies a unique vantage point to observe this transition in real-time. We are witnessing a definitive structural shift in traffic composition.

In 2024, automated bot traffic surpassed human-generated traffic for the first time in a decade, accounting for **51% of all internet traffic**. While a significant portion of this remains "bad bots" (credential stuffers, inventory hoarders, and DDoS actors) a rapidly growing segment is "agentic traffic". Adobe Analytics data reveals that traffic to U.S. retail sites from generative AI browsers and chat services surged by **4,700% year-over-year** in July 2025.

This is not merely "more traffic"; it is a different *kind* of traffic. Human traffic is browsing-heavy, read-intensive, and highly cacheable. Agent traffic is query-heavy, often transactional, and computationally expensive. The "use case" of the e-commerce website is evolving from a digital catalog for humans to an API endpoint for autonomous agents.

The introduction of the **Universal Commerce Protocol (UCP)** by Google, in collaboration with Shopify and other retail giants, is the infrastructure response to this reality. It provides the "common language" required for these bots to be efficient, reducing the hallucinations that plague LLM-based shopping today. **However, while UCP solves the interoperability problem, it introduces profound new challenges for merchant infrastructure, resource management, and strategic independence.**

## The Universal Commerce Protocol (UCP): A technical deep dive

### Solving the N-to-N integration problem

To understand UCP, one must first understand the bottleneck it resolves. In the nascent days of AI commerce, an agent (like ChatGPT or Gemini) desiring to purchase a product from a merchant (like a Shopify store or a custom Magento build) faced an "N x N" integration problem.

* **The Agent's Problem:** To shop at 1,000 different stores, the agent needed to understand 1,000 different checkout flows, API schemas, and authentication methods.
* **The Merchant's Problem:** To sell on every emerging AI surface (ChatGPT, Perplexity, Gemini, Claude), the merchant needed to build and maintain bespoke integrations (MCP, API's, etc.) for each platform.

UCP creates a unified abstraction layer. It collapses this complexity into a "1-to-Many" model. A merchant implements the UCP standard once, and any UCP-compliant agent can discover their catalog, negotiate a cart, and execute a checkout.

### The architecture of agentic interaction

UCP is not a single API but a suite of specifications designed to modularize the commerce journey. Its architecture rests on three primary pillars: **Services**, **Capabilities**, and **Extensions**.

<img alt="ucp-diagram" />

#### Services and discovery

The entry point for any UCP interaction is the **Discovery Manifest**. Merchants utilizing UCP publish a standardized JSON file at a "well-known" endpoint: `/.well-known/ucp`. This is the digital handshake.

When an AI agent encounters a merchant's domain, it requests this file to understand "what language this shop speaks." The manifest declares:

1. **Supported Services:** High-level domains like `dev.ucp.shopping` or `dev.ucp.travel`.
2. **Versions:** Ensuring backward compatibility as the protocol evolves.
3. **Payment Configurations:** Which payment handlers (e.g., Stripe, Shop Pay) are accepted.

This dynamic discovery is crucial. It means agents do not need hard-coded logic for every store. They query the manifest, parse the capabilities, and adapt their behavior instantly.

#### Capabilities: the atomic units of commerce

Capabilities define the functional primitives of the interaction. The `dev.ucp.shopping` service, for example, is composed of several core capabilities:

* **Product Discovery:** A standardized schema for searching inventory. Unlike traditional SEO schema (which is passive), this capability allows for active querying of stock levels and variants.
* **Cart Management:** APIs for creating a session, adding line items, and updating quantities.
* **Checkout:** The complex logic of tax calculation, shipping selection, and finalizing the order.
* **Order Management:** Webhooks and endpoints for tracking status (shipped, delivered, returned)

#### Extensions: handling retail complexity

Retail is messy. A furniture store selling custom sofas has fundamentally different requirements than a digital goods store selling software keys. UCP handles this variance through **Extensions**.

* **Fulfillment Extensions:** Allow negotiation of delivery windows ("Tuesday between 2-4 PM") or pickup locations.
* **Discount Extensions:** Enable the application of promo codes or loyalty points logic during the checkout negotiation.
* **Identity Extensions:** Facilitate linking a user's Google or Apple ID with their merchant loyalty account using OAuth 2.0 patterns.

This extensibility prevents the protocol from becoming a rigid, "lowest common denominator" standard. It allows merchants to expose their unique value propositions (e.g., "Same-Day Delivery") in a machine-readable format that agents can understand and prioritize.

### The transport layer: agnosticism in action

A critical innovation of UCP is its transport agnosticism. It defines the *structure* of the data but is flexible regarding *how* that data moves.

* **REST APIs:** The most common binding for web infrastructure, allowing standard HTTP POST/GET requests to drive agent actions.
* **Model Context Protocol (MCP):** A breakthrough standard for LLMs. MCP allows an AI model to "see" the merchant's UCP endpoints as "tools" it can invoke. Instead of hallucinating a checkout URL, the model calls the checkout() tool defined via MCP, ensuring deterministic execution.
* **Agent2Agent (A2A):** This protocol facilitates direct negotiation between a "Buyer Agent" (acting for the consumer) and a "Seller Agent" (acting for the merchant). In high-value B2B scenarios, A2A allows agents to haggle over price or bulk terms without human intervention.

### The payment layer: splitting instruments and handlers

Perhaps the most technically sophisticated component of UCP is its payment architecture. To solve the trust issue "How do I let a bot spend my money?" UCP separates **Payment Instruments** from **Payment Handlers**.

* **Instruments:** The method of payment (e.g., a specific credit card, a tokenized wallet credential).
* **Handlers:** The processor (e.g., Stripe, Adyen, PayPal).

When an agent executes a purchase, it does not pass raw credit card numbers. It uses **Cryptographic Mandates** (via the Agent Payments Protocol, AP2). The user issues a signed digital mandate authorizing the agent to spend `"up to \$100 at Target."` The agent passes this cryptographic proof to the merchant's handler. The handler verifies the signature and processes the funds.

This "Security-First" design ensures that the merchant remains the **Merchant of Record (MoR)**, retaining liability and control, while the agent acts merely as a secure courier for the user's intent.

## The infrastructure shift: From human browsing to machine execution

For Upsun engineers and customers, the adoption of UCP implies a radical shift in system architecture and resource utilization. The traffic patterns of 2026 will bear little resemblance to those of 2016.

### The decline of the cache hit

For twenty years, e-commerce scalability relied on a simple premise: Read-Heavy / Write-Light.\
Humans browse aggressively. They view category pages, product detail pages (PDPs), and "About Us" sections. This content is static or semi-static. It lives in the Edge Cache (CDN). When a flash sale hits, 99% of the traffic is absorbed by Varnish or Fastly, with only the final "Add to Cart" and "Checkout" requests hitting the origin database.

Agentic Commerce inverts this ratio. An AI agent does not "browse" visual pages. It does not load high-resolution hero images, CSS files, or JavaScript bundles. It queries data directly via API.

* **The request:** `POST /ucp/search { "query": "running shoes", "size": "10", "delivery\_max\_days": 2 }`
* **The reality:** This request is dynamic. It requires a real-time database query to check inventory levels across multiple warehouses to confirm the 2-day delivery constraint. It cannot be served from a static cache.

**Implication for Upsun Users:** As UCP adoption grows, we will see a migration of load from the Edge (CDN) to the Application and Database layers.

* **Throughput vs. Bandwidth:** Bandwidth usage (serving images) may decrease, but CPU and Memory usage (processing JSON logic) will spike.
* **Database Pressure:** Real-time inventory checks by thousands of agents simultaneously will create "hot rows" in databases. The "Thundering Herd" problem, previously limited to DDoS attacks, becomes a standard operating condition of agent-based shopping.

### The "Thundering Herd" of agents

Consider the mechanics of an AI shopping assistant. A user asks, "Find the best price for a Sony A7V camera." The agent instantly queries 50 different retailers simultaneously to compare pricing and shipping.

* **Simultaneity:** Unlike human traffic, which ramps up (users wake up, log on), agent traffic is bursty and instantaneous. A single user query triggers 50 concurrent API calls to 50 different merchants.
* **Retry Logic:** If an API endpoint is slow (latency > 200ms), agents may be programmed to time out and retry or abandon. Machine tolerance for latency is far lower than human tolerance.

**Infrastructure Response:** Merchants on Upsun must leverage Horizontal Scaling. The ability to instantly spin up additional API worker containers to handle a burst of agentic queries is no longer a luxury—it is a survival requirement. Fixed-size server architectures will fail under the unpredictability of agentic loads.

### Semantic caching: the new performance frontier

If traditional URL-based caching fails for dynamic agent queries, what replaces it? The answer is **Semantic Caching**.

* **The Problem:** Query A ("Red dress") and Query B ("Crimson evening wear") are different strings but semantically similar. A standard cache treats them as unique misses.
* **The Solution:** Infrastructure must implement Vector Databases (like Qdrant or pgvector on Upsun) to cache the *meaning* of a request. If the agent asks a question that is semantically close to a cached result, the system can serve the cached JSON without hitting the primary SQL database.

This introduces a new component to the e-commerce stack: The **Vector Cache Layer**. Upsun users will need to deploy services like Chroma alongside their MariaDB or PostgreSQL instances to intercept and resolve agent queries efficiently.

### The resource usage shift: metrics table

| Metric | Traditional Commerce (Human) | Agentic Commerce (AI) | Infrastructure Impact |
| :- | :- | :- | :- |
| **Primary Request Type** | GET (HTML/Assets) | POST (JSON Data) | Higher CPU usage for parsing/logic. |
| **Cache Hit Rate** | High (>80%) | Low (\<10%) | Shift from CDN to Origin Server. |
| **Session Duration** | Minutes (Browsing) | Milliseconds (Execution) | High concurrency spikes. |
| **Traffic Pattern** | Diurnal (Day/Night) | Bursty / Event-Driven | Need for rapid auto-scaling. |
| **Inventory Checks** | At Checkout Only | Pre-Checkout (High Volume) | Heavy read load on Database. |
| **Conversion Rate** | Low (2-3%) | High (Intent-Driven) | Higher value per API call. |

## Strategic implications for retailers: adapting to the machine customer

The shift to UCP is not just a technical upgrade; it is a rewriting of the rules of retail engagement. For independent merchants, this presents a paradox of opportunity and existential risk.

### The "Great Decoupling": Zero-Click Commerce

Gartner predicts a **25% decline in traditional search volume** by 2026 as users shift to AI assistants. This phenomenon, known as "The Great Decoupling," means that purchase intent is being captured and fulfilled *within* the AI interface.

* **The Old World:** User searches Google -> Clicks link -> Visits brand.com -> Buys.
* **The Agentic World:** User asks Gemini -> Agent negotiates via UCP -> Transaction completes in Gemini.

**The Impact:** The merchant's website traffic (sessions, pageviews) will plummet. However, *conversion volume* may stay steady or rise, provided the merchant is UCP-compatible. The website is no longer the destination; it is the fulfillment center for the agent's request.

### Data as the new storefront

In an agentic world, your Products Catalog Feed is your storefront.\
If an agent cannot parse your return policy, shipping window, or stock level via structured UCP data, your product effectively may not exist. The visual appeal of your site matters zero to an algorithm.

* **Fulfillment Data:** Agents prioritize certainty. A merchant who exposes "3-5 day shipping" (vague) will lose to a merchant who exposes a precise "Delivery by Thursday 4 PM" via UCP's fulfillment extension. The Third Party Logistics integration becomes a marketing asset.
* **Inventory Accuracy:** If an agent attempts to buy a product that turns out to be out-of-stock, it learns. The "reliability score" of that merchant may drop, and the agent will deprioritize them in future queries. Inventory accuracy is now an GEO/SEO ranking factor.

### Generative Engine Optimization (GEO): on top of SEO

Just as merchants spent the last decade mastering SEO (keywords, backlinks), they must now master **GEO (Generative Engine Optimization)**.

* **Optimization Goal:** To be the "cited source" or the "recommended product" in an LLM's answer.
* **Tactics:** This requires "fact-dense" content. Vague marketing fluff ("The best in class!") would be ignored by LLMs. Specific, structured attributes ("Made of 100% merino wool, 200gsm weight, ethical source certified") are prioritized.
* **Structured Data:** Implementing comprehensive `Schema.org` markup and UCP manifests is the prerequisite for GEO visibility.

### The Bidding War: ad placement in the agent age

The most ominous question for independent merchants is: How does an agent decide?\
When a user says "Buy me detergent," and the agent has 50 valid UCP options, which one does it choose?

* **Algorithmic Bias:** Currently, agents optimize for user constraints (price, speed).
* **The Future:** It is inevitable that this decision layer will be monetized. I am pretty sure we will see the rise of **Agentic Bidding**. Merchants will bid not for a banner ad, but for the *agent's preference*.
* **"Direct Offers":** Google is already piloting "Direct Offers" in AI Mode, allowing merchants to inject discounts directly into the chat stream when high intent is detected. This is the precursor to a Cost-Per-Recommendation (CPR) ad model.

### The Merchant of Record: a double-edged sword

UCP explicitly maintains the brand as the **Merchant of Record (MoR)**.

* **The Good News:** You own the customer data. You own the transaction. You are not just a supplier to Amazon; you are the seller.
* **The Bad News:** You own the liability. If the AI agent hallucinates a feature ("This watch is waterproof to 100m" when it is only 30m) and the user buys it, *you* process the return. *You* eat the chargeback risk. The separation of the "sales agent" (Google) from the "responsible party" (Merchant) creates a liability gap that legal frameworks have yet to address.

## Challenges and risks: navigating the transition

### The "surgical" shopper and margin compression

Data from Cyber Week 2025 shows that AI-driven shoppers are "surgical." They are value-focused, precision-oriented, and more immune to impulse buys.

* **Loss of Upsell:** In a traditional checkout, you can display "Customers also bought..." to boost Average Order Value (AOV). In an agentic transaction, the agent buys exactly what was requested and nothing else.
* **Margin Erosion:** Agents are ruthless price comparers. They can check 50 sites in 100ms to find the lowest price. This commoditizes goods and pressures margins for retailers who cannot differentiate on service, branding or exclusivity.

### Ecosystem control and fees

While UCP is "open source," its ecosystem is dominated by giants. Google, Shopify, and Stripe are the primary architects.

* **Dependency:** Small merchants may find implementation too complex, forcing them to rely on platforms like Shopify to handle UCP. This deepens the "platform tax."
* **Payment Fees:** The modular payment handler system is elegant, but it ensures that payment processors (and the platforms embedding them) continue to extract their percentage. There is a risk that "Agentic Fees" will be layered on top of transaction fees, similar to how app stores operate today.

### Technical debt

Implementing UCP requires a level of API maturity that many legacy retailers lack. Real-time inventory syncing, webhook-based order management, and tokenized payment flows are non-trivial engineering challenges. Merchants stuck on legacy monolithic ERPs will find themselves locked out of the agentic economy until a complete rewrite.

## Upsun recommendations: engineering for the future

For the developer community and business leaders on Upsun, the roadmap is clear. We must build infrastructure that is **Agent-Ready**.

### Architectural Recommendations

1. **Prioritize Horizontal Scaling:** Move away from "big iron" servers. Configure your Upsun applications to scale horizontally (adding more containers) rather than vertically. Agent traffic is bursty; your infrastructure must be elastic.
2. **Implement Vector Caching:** Explore adding **Qdrant** or **pgvector** services to your Upsun stack. Implementing a semantic cache layer will protect your primary database from the query load of thousands of agents.
3. **Adopt API-First Principles:** Ensure your product catalog and inventory systems are exposed via performant, RESTful APIs. The UCP manifesto is essentially a mandate for API-first commerce.

### Operational Strategy

1. **Publish the Manifest:** Create and host the `/.well-known/ucp` file. Even if you are not fully ready for transactional agents, enabling **Discovery** capabilities ensures your products are visible to the new search crawlers.
2. **Use Preview Environments for Agent Testing:** One of Upsun's core features, **Preview Environments**, is the perfect sandbox for this new world. You can clone your production environment, unleash a test swarm of AI agents against it, and verify how your APIs handle the load *without* risking your live site. This "Production Clone" capability is your safety net for testing UCP integrations.
3. **Security Configurations:** Update your Web Application Firewall (WAF) rules. You must distinguish between "good agents" (UCP-compliant, authenticated via headers) and "bad scrapers." Rate limiting should be intelligent, not blanket.

## Conclusion: the new frontier of commerce

The Universal Commerce Protocol is not merely a technical specification; it is the constitution of a new digital economy. It confirms that the future of commerce is unified, automated, and mediated by software.

**Independent merchants are not dead**. UCP gives you a fighting chance to be discoverable and transactable in an AI-dominated world without surrendering your data to a walled garden. You remain the Merchant of Record. You own the customer.

But the bar for technical competence has been raised. The "storefront" is no longer a visual experience you control; it is a data stream you must optimize. The competition is no longer local; it is algorithmic. And the intermediaries (Google, Shopify, the payment networks) have solidified their position as the toll-takers of this new highway.

For the independent merchant, the path forward is to embrace the protocol. Fight for data accuracy. Optimize for the machine customer. And leverage flexible, scalable infrastructure like Upsun to handle the "thundering herd" of agents that are coming to shop.

The agentic era has arrived. The question is not whether you will participate, but whether you will be ready when the agents come knocking.

## Glossary of terms

* **UCP (Universal Commerce Protocol):** The open standard for agent-merchant interoperability.
* **MoR (Merchant of Record):** The entity legally responsible for the transaction and customer data.
* **GEO (Generative Engine Optimization):** Optimizing content to be cited/recommended by AI models.
* **MCP (Model Context Protocol):** A standard for LLMs to connect to external data tools.
* **AP2 (Agent Payments Protocol):** A protocol for delegating secure payment authority to agents.
* **A2A (Agent2Agent):** A protocol for autonomous negotiation between software agents.

## Works cited

1. Agentic Commerce Impact Could Reach \$385 Billion by 2030 | Morgan Stanley, accessed January 12, 2026, [https://www.morganstanley.com/insights/articles/agentic-commerce-market-impact-outlook](https://www.morganstanley.com/insights/articles/agentic-commerce-market-impact-outlook)
2. Agentic Commerce How AI Agents Are Transforming Online Buying, accessed January 12, 2026, [https://www.livemint.com/focus/agentic-commerce-how-ai-agents-are-transforming-online-buying-11768029990660.html](https://www.livemint.com/focus/agentic-commerce-how-ai-agents-are-transforming-online-buying-11768029990660.html)
3. AI-Driven Bots Surpass Human Traffic - Bad Bot Report 2025 - Thales CPL, accessed January 12, 2026, [https://cpl.thalesgroup.com/about-us/newsroom/2025-imperva-bad-bot-report-ai-internet-traffic](https://cpl.thalesgroup.com/about-us/newsroom/2025-imperva-bad-bot-report-ai-internet-traffic)
4. Examining AI Agent Traffic: Powering the Shift to Agentic Commerce - HUMAN Security, accessed January 12, 2026, [https://www.humansecurity.com/learn/blog/ai-agent-statistics-agentic-commerce/](https://www.humansecurity.com/learn/blog/ai-agent-statistics-agentic-commerce/)
5. Generative AI-Powered Shopping Rises with Traffic to U.S. Retail Sites - Adobe for Business, accessed January 12, 2026, [https://business.adobe.com/blog/generative-ai-powered-shopping-rises-with-traffic-to-retail-sites](https://business.adobe.com/blog/generative-ai-powered-shopping-rises-with-traffic-to-retail-sites)
6. Ecommerce Trends: Adobe saw generative AI-powered shopping rise 4700% in July, accessed January 12, 2026, [https://www.digitalcommerce360.com/2025/08/21/adobe-generative-ai-powered-shopping-data-july-2025/](https://www.digitalcommerce360.com/2025/08/21/adobe-generative-ai-powered-shopping-data-july-2025/)
7. Google Universal Commerce Protocol (UCP) Guide, accessed January 12, 2026, [https://developers.google.com/merchant/ucp](https://developers.google.com/merchant/ucp)
8. Under the Hood: Universal Commerce Protocol (UCP) - Google for Developers Blog, accessed January 12, 2026, [https://developers.googleblog.com/under-the-hood-universal-commerce-protocol-ucp/](https://developers.googleblog.com/under-the-hood-universal-commerce-protocol-ucp/)
9. Building the Universal Commerce Protocol (2026) - Shopify Engineering, accessed January 12, 2026, [https://shopify.engineering/UCP](https://shopify.engineering/UCP)
10. Universal Commerce Protocol could make checkout buttons obsolete - PPC Land, accessed January 12, 2026, [https://ppc.land/universal-commerce-protocol-could-make-checkout-buttons-obsolete/](https://ppc.land/universal-commerce-protocol-could-make-checkout-buttons-obsolete/)
11. The New Fulfillment Data Layer: What UCP Means for 3PLs, accessed January 12, 2026, [https://www.fulfill.com/blog-posts/ucp-fulfillment-data-layer-3pl-guide](https://www.fulfill.com/blog-posts/ucp-fulfillment-data-layer-3pl-guide)
12. Universal-Commerce-Protocol/ucp - GitHub, accessed January 12, 2026, [https://github.com/Universal-Commerce-Protocol/ucp](https://github.com/Universal-Commerce-Protocol/ucp)
13. How the Model Context Protocol (MCP) Works - Lucidworks, accessed January 12, 2026, [https://lucidworks.com/blog/how-the-model-context-protocol-works-a-technical-deep-dive](https://lucidworks.com/blog/how-the-model-context-protocol-works-a-technical-deep-dive)
14. Meet A2A: Google's Agent-to-Agent Protocol Explained for Developers | by Parv Bhargava, accessed January 12, 2026, [https://bhargavaparv.medium.com/meet-a2a-googles-agent-to-agent-protocol-explained-for-developers-24120d1cafff](https://bhargavaparv.medium.com/meet-a2a-googles-agent-to-agent-protocol-explained-for-developers-24120d1cafff)
15. Agent to agent, not tool to tool: an engineer's guide to Google's A2A protocol - WorkOS, accessed January 12, 2026, [https://workos.com/blog/engineers-guide-to-googles-a2a-protocol](https://workos.com/blog/engineers-guide-to-googles-a2a-protocol)
16. Announcing Agent Payments Protocol (AP2) | Google Cloud Blog, accessed January 12, 2026, [https://cloud.google.com/blog/products/ai-machine-learning/announcing-agents-to-payments-ap2-protocol](https://cloud.google.com/blog/products/ai-machine-learning/announcing-agents-to-payments-ap2-protocol)
17. Shopware PaaS performance guide for scalable stores | Upsun, accessed January 12, 2026, [https://upsun.com/blog/shopware-performance-guide/](https://upsun.com/blog/shopware-performance-guide/)
18. AI Agent Is Hitting Your APIs - Are You Ready? - Speedscale, accessed January 12, 2026, [https://speedscale.com/blog/ai-agent-is-hitting-your-apis-are-you-ready/](https://speedscale.com/blog/ai-agent-is-hitting-your-apis-are-you-ready/)
19. How to Prepare for Agentic Commerce: The 9-Step Framework for AI-Driven Shopping, accessed January 12, 2026, [https://www.humansecurity.com/learn/blog/how-to-prepare-for-agentic-commerce/](https://www.humansecurity.com/learn/blog/how-to-prepare-for-agentic-commerce/)
20. Autoscaling | Upsun Docs, accessed January 12, 2026, [https://docs.upsun.com/manage-resources/autoscaling.html](https://docs.upsun.com/manage-resources/autoscaling.html)
21. The Hidden Cost of AI Agents: A Caching Solution - DZone, accessed January 12, 2026, [https://dzone.com/articles/the-hidden-cost-of-ai-agents-a-caching-solution](https://dzone.com/articles/the-hidden-cost-of-ai-agents-a-caching-solution)
22. CDNs are central to enhancing the delivery of AI-augmented customer experiences, accessed January 12, 2026, [https://itbrief.asia/story/cdns-are-central-to-enhancing-the-delivery-of-ai-augmented-customer-experiences](https://itbrief.asia/story/cdns-are-central-to-enhancing-the-delivery-of-ai-augmented-customer-experiences)
23. 2025 Organic Traffic Crisis: Zero-Click & AI Impact Analysis Report - The Digital Bloom, accessed January 12, 2026, [https://thedigitalbloom.com/learn/2025-organic-traffic-crisis-analysis-report/](https://thedigitalbloom.com/learn/2025-organic-traffic-crisis-analysis-report/)
24. Generative Engine Optimization Strategies (GEO) for 2026 - Go Fish Digital, accessed January 12, 2026, [https://gofishdigital.com/blog/generative-engine-optimization-strategies/](https://gofishdigital.com/blog/generative-engine-optimization-strategies/)
25. Agentic payments: a new frontier in digital commerce - Kearney, accessed January 12, 2026, [https://www.kearney.com/industry/financial-services/article/agentic-payments-a-new-frontier-in-digital-commerce](https://www.kearney.com/industry/financial-services/article/agentic-payments-a-new-frontier-in-digital-commerce)
26. AI-Based Bidding is the Future of Advertising - Catalina, accessed January 12, 2026, [https://www.catalina.com/perspectives-blog/ai-advertising-bidding-future-media-buying](https://www.catalina.com/perspectives-blog/ai-advertising-bidding-future-media-buying)
27. New tech and tools for retailers to succeed in an agentic shopping era - Google Blog, accessed January 12, 2026, [https://blog.google/products/ads-commerce/agentic-commerce-ai-tools-protocol-retailers-platforms/](https://blog.google/products/ads-commerce/agentic-commerce-ai-tools-protocol-retailers-platforms/)
28. Agentic Commerce is a Huge Opportunity for Retailers; it’s Also a Liability Storm, accessed January 12, 2026, [https://www.retailtouchpoints.com/features/executive-viewpoints/agentic-commerce-is-a-huge-opportunity-for-retailers-its-also-a-liability-storm](https://www.retailtouchpoints.com/features/executive-viewpoints/agentic-commerce-is-a-huge-opportunity-for-retailers-its-also-a-liability-storm)
29. Cyber Week 2025: The Rise of Agentic Commerce and the Surgical Shopper - CMS Wire, accessed January 12, 2026, [https://www.cmswire.com/customer-experience/cyber-week-2025-the-rise-of-agentic-commerce-and-the-surgical-shopper/](https://www.cmswire.com/customer-experience/cyber-week-2025-the-rise-of-agentic-commerce-and-the-surgical-shopper/)
30. Agentic commerce: Promise, paradox and the path forward - Worldpay, accessed January 12, 2026, [https://www.worldpay.com/en/insights/articles/agentic-commerce-paradox-and-promise](https://www.worldpay.com/en/insights/articles/agentic-commerce-paradox-and-promise)
31. The Rise of Agentic Commerce Platforms in 2025 - BigCommerce, accessed January 12, 2026, [https://www.bigcommerce.com/blog/agentic-commerce-platforms/](https://www.bigcommerce.com/blog/agentic-commerce-platforms/)
32. Need more juice? Scaling made simple | Upsun, accessed January 12, 2026, [https://upsun.com/blog/scaling-demo/](https://upsun.com/blog/scaling-demo/)
33. Unlocking Edge AI: A Deep Dive into the Blackbox Projects PostgreSQL Remote MCP Server - Skywork.ai, accessed January 12, 2026, [https://skywork.ai/skypage/en/unlocking-edge-ai-blackbox-postgresql/1978331891706273792](https://skywork.ai/skypage/en/unlocking-edge-ai-blackbox-postgresql/1978331891706273792)
34. Real-world data makes AI agents reliable - Upsun, accessed January 12, 2026, [https://upsun.com/blog/ai-agent-testing-production-clone/](https://upsun.com/blog/ai-agent-testing-production-clone/)


# How did we migrate issues from GitLab to Linear?
Source: https://developer.upsun.com/posts/discussions/triage-bot



<PostMeta />

We migrated our issues from GitLab to Linear due to GitLab's limited issue-tracking features. To handle thousands of issues and tight timelines, we developed a migration tool using GitLab Triage Bot and Linear's GraphQL API. The tool mapped issue states, assignees, labels, and comments, and transformed GitLab epics into Linear issues with sub-issues. It was successful overall and enabled team-by-team migration for flexibility. Now, [we’re open-sourcing the migrator](https://github.com/upsun/gitlab-triage-linear-migrator) to help others facing similar challenges.

## The background

More than a year ago we decided to find a better solution to manage our issues and initiatives. We found GitLab’s issue tracking features to be limited and not flexible enough to support our needs, so we started a research project to find a better issue management tool. In order to find the best match, we collected our use cases and requirements and ranked all potential solutions based on what is important to us vs. what the tools were capable of. This is how we came to the decision to migrate to [Linear](https://linear.app/), a cool and flexible solution to track issues and projects.

The problem is, Linear doesn’t have an official importer from GitLab. We had thousands of issues, so we had to come up with something—and the time was tight.

## Using GitLab Triage Bot

The first idea was a full, stand-alone migrator with a database (to track migration tasks, progress, errors and to map IDs between the two systems), but for various reasons we only had a few weeks to spin up an MVP to show teams how their issues would look in Linear. At that time, we used [GitLab Triage Bot](https://gitlab.com/gitlab-org/ruby/gems/gitlab-triage/) to help maintain healthy projects and issues across different teams.

We already had a few extensions that helped us to run Triage Bot on different projects and groups. It had a set of handy CI-related scripts and functions that allowed us to create multiple YAML files for the Triage Bot, and then set target projects/groups in that file. So, instead of running the bot with the target project as parameter, a script reads the folder that contains these policies and creates CI pipeline jobs for each file and target project combination.\
You can read more in this article…

## How does it work?

As Triage Bot can list issues and execute actions on them easily, the next part was just to call [Linear’s GraphQL API](https://developers.linear.app/docs/graphql/working-with-the-graphql-api) to import a given issue and set some basic properties. To create a Linear issue, we simply need two things: target team and issue title. We have the title, that’s easy, but how do we set the target team?

### Set the Linear team

As we currently have guilds in our engineering department and we already used scoped labels on issues to set which guild an issue belongs to, we decided to use this label. In GitLab, we use the following format: `Guild::Guild Name`. In Linear we decided to use `Guild: Guild Name` naming scheme for teams, so we just needed to do a lookup in Linear to find the team ID based on its name.

### Issue states

As we currently have guilds in our engineering department and we already used scoped labels on issues to set which guild an issue belongs to, we decided to use this label. In GitLab, we use the following format: `Guild::Guild Name`. In Linear we decided to use `Guild: Guild Name` naming scheme for teams, so we just needed to do a lookup in Linear to find the team ID based on its name.

### Closed issues

Some teams decided to leave closed issues in GitLab, some teams wanted to migrate them. As we use Triage Bot conditions to list issues, and we could have triage YAML files per team, it was just an extra condition in the Triage Bot rule.

### Assignee(s)

The migrator also sets issue assignee. As GitLab supports multiple assignees, but Linear doesn’t, it only takes the first assignee.

### Labels

Migrating labels was a bit tricky. Both GitLab and Linear support some sort of label grouping, but in Linear the group name is not included in the label name as in GitLab (where we have scoped labels, `::` acting as separator between the group and the label. Labels must be unique in Linear, not just within a group, so you can’t have a `colors/green` and `eco/green` label at the same time.

To solve this problem, we simply ignore the group name in GitLab, so `colors::green` and `eco/green` will be `green` in Linear (whether or not `green` is in a label group).

The migrator doesn't create any labels. If the label in Linear doesn't exist, it will simply ignore it. Labels should be created in Linear upfront, which gives flexibility to create them in the workspace or team level and within a group or stand-alone.

### Comments

After the migrator creates the issue, it imports all the comments from GitLab. It maintains the creation data and processes both threaded comments and normal comments.

### Epics

Linear doesn't have the concept of epics, so we decided to migrate epics as issues and issues under epics as sub-issues. But this is optional, if a team doesn't want to migrate their epics, only issues will be migrated. The hardest part was to keep track of the new IDs that the imported issues get in Linear to maintain parent-child relationships. As the migrator doesn't have a database, we decided to maintain a migration map in memory. But because the script can be run multiple times, it acts only as a cache, and if the linear issue ID is not in there, we use the comment that the migrator adds to the Linear issue to search for the issue (as comments are easily searchable in Linear).

### Author

Linear has a [`createAsUser`](https://developers.linear.app/docs/oauth/oauth-actor-authorization) attribute when creating issues and comments via the API (only available when using OAuth Actor Authorization) which allows us to set who created the issue or comment originally - even if that user doesn’t exist in Linear.

### Links to merge requests

Both in GitLab and Linear, issues can be linked to merge requests. The migrator migrates these links too.

### Status

How it tracks the status, use labels in Linear and GitLab.\
As there is no database behind the migrator, but we wanted to track progress, it sets the `Linear::Migrated` label when an issue was migrated, and `Linear::Migration Failed` when it failed for some reason.

In Linear, all new issues are created with the label `Migrating from GitLab - in progress`. If all the comments and links are migrated, it then removes this and adds `Migrated from GitLab`. This is useful if the migration fails in the middle - e.g. a comment cannot be migrated, so the issue is missing some data - better to delete and re-import again.

### Tests

As with software in general, it is hard to test all scenarios, we have a good test coverage in unit tests, where we test certain portions of the code. But because it relies on two external APIs, it’s very difficult to test everything, especially how it will behave with the real APIs. In the unit tests, we mock API responses, but the best test is if you can run it against the real APIs. Thankfully, GitLab Triage Bot has a dry-run mode, where it processes all the epics/issues, but instead of making any change, it simply prints what it would do.

The Linear part is more tricky, as we can’t have a real dry-run. We decided to use Linear’s API in read-only mode, when the script is in dry-run. This means it prints out the mutations instead of actually running them. But this is quite limited, as comments and links can only be migrated once the issue is created. So we have an extra option (in an environment variable) to run real Linear mutations even in dry-run. This allows us to test the migration in Linear but not change anything in GitLab.

Mass-deleting issues in Linear is easy, and it is also possible to use a test workspace. Once we were happy with the results, we could run the migration for real.

### Run in CI

We wanted the migration to be as self-service for teams as possible, we have set up CI jobs to run it every hour automatically. If a team wanted their issues being migrated, they could create a merge request, containing a new policy file that is for their projects. Once that merge request was merged, the bot picked it up and migrated the issues.\
Additionally, a dry-run was running for all merge requests commits, so it was easier to spot issues beforehand.

## Conclusion

Migration is always challenging, both technically and organisationally. Looking back, it was a good decision to do it team-by-team, and not in one go. Although we had many more ideas on how to improve the migration (e.g. it does not migrate attached images), we were quite happy with it in the end.

<img alt="Screenshot of the triage bot migration results" />

While we might not need it again (although we have set it up to be there and watch for any new issues, and move them across), we decided to open-source it, so others in the same situation don’t have to write it again.\
We hope you find it useful!

## Use it, fork it, contribute!

You can find our work on GitHub: [https://github.com/upsun/gitlab-triage-linear-migrator](https://github.com/upsun/gitlab-triage-linear-migrator)


# Understanding Cross-Origin Resource Sharing (CORS)
Source: https://developer.upsun.com/posts/discussions/understanding-cors

Learn about Cross-Origin Resource Sharing (CORS), a crucial web security mechanism. Understand its importance, key concepts, and implementation in Symfony, Next.js, and Laravel. Includes practical examples and tips for testing with curl and Postman, plus Platform.sh configuration guidance.


<PostMeta />

Today, it is becoming more common to decouple your frontend (usually a JS framework) and your backend (Node.js, PHP, Python, etc.) or even leverage micro-services.
However, web browsers implement security measures that restrict such cross-origin requests by default. This is where `Cross-Origin Resource Sharing` (`CORS`) comes into play.

Understanding `CORS` is crucial for developers building modern web applications, as it allows you to access resources from different origins while maintaining security safely. Let's dive into the world of `CORS` and explore its key concepts.

## Fundamentals

### The `Same-Origin Policy`

Before we delve into `CORS`, it's essential to understand the `Same-Origin Policy`, which is the foundation of web security.

The `Same-Origin Policy` is a critical security mechanism implemented by web browsers. It restricts web pages from making requests to a domain different from the one serving the web page. An origin is considered the same if the protocol, domain, and port all match.

For example:

* `https://example.com/page1` and `https://example.com/page2` have the same origin
* `https://example.com` and `http://example.com` have different origins (different protocol)
* `https://example.com` and `https://example.com:3000` have different origins (different port)
* `https://example.com` and `https://api.example.com` have different origins (different subdomain)

The `Same-Origin Policy` is important because it prevents malicious scripts on one page from obtaining access to sensitive data on another page through the `Document Object Model` (`DOM`).
However, this policy can be too restrictive for legitimate cross-origin requests, which is where `CORS` comes in.

### What is `CORS`?

Cross-Origin Resource Sharing (`CORS`) is a mechanism that allows many resources (e.g., fonts, JavaScript, etc.) on a web page to be requested from another domain outside the domain from which the resource originated.

`CORS` works by adding new HTTP headers that allow servers to describe which origins are permitted to read that information from a web browser. It's a way to relax the `Same-Origin Policy` in a controlled manner.

For example, if a user visits `https://example.com` and that page wants to make an AJAX request to `https://api.example.com`, it will be blocked by default due to the `Same-Origin Policy`. `CORS` provides a way for the server at `https://api.example.com` to say, "I will accept requests from `https://example.com`."

### `CORS` Headers

`CORS` is implemented through a series of HTTP headers. The most important ones are:

* `Access-Control-Allow-Origin`: Specifies which origins can access the resource. It can be a specific origin, `"*"` for any origin, or null.
* `Access-Control-Allow-Methods`: Specifies the HTTP methods (`GET`, `POST`, etc.) allowed when accessing the resource.
* `Access-Control-Allow-Headers`: Indicates which HTTP headers can be used during the actual request.
* `Access-Control-Allow-Credentials`: Indicates whether the response to the request can be exposed when the credentials flag is true.

For example, a server might send these headers:

```
Access-Control-Allow-Origin: https://example.com
Access-Control-Allow-Methods: GET, POST, PUT
Access-Control-Allow-Headers: Content-Type
```

These headers tell the browser that `https://example.com` is allowed to make `GET`, `POST`, and `PUT` requests to this resource and can include the `Content-Type` header in its requests.

Understanding these headers is important because they form the core of how `CORS` works. As a developer, you must configure your application to send the appropriate headers based on your security requirements.

### Simple vs. Preflight Requests

`CORS` requests can be divided into two categories: simple requests and preflight requests.

Simple requests don't trigger a `CORS` preflight. They are typically `GET`, `HEAD`, or `POST` requests with only simple headers. The browser sends these directly, and the server can respond with `CORS` headers.

Preflight requests are used for more complex HTTP requests. Before sending the actual request, the browser first sends an HTTP `OPTIONS` request to the server, asking for permission.

For example, a `PUT` request with a custom header would trigger a preflight request:

```
OPTIONS /resource HTTP/1.1
Origin: https://example.com
Access-Control-Request-Method: PUT
Access-Control-Request-Headers: X-Custom-Header
```

The server would then respond with the appropriate `CORS` headers, telling the browser whether the actual request is allowed.

Understanding the difference between simple and preflight requests is important because it affects how your server needs to handle `CORS` requests and can impact the performance of your application.

### `CORS` and Security

While `CORS` allows for more flexible web applications, it's important to understand that it's not a security feature in itself. `CORS` doesn't protect your server from unauthorized access; it tells the browser to allow certain `cross-origin` requests.

Proper security measures, such as authentication and authorization, should always be implemented on the server side. **`CORS` should be configured to allow only the necessary origins, methods, and headers.**

For example, instead of using `Access-Control-Allow-Origin: *`, which allows any origin, you should specify the exact origins:

```
Access-Control-Allow-Origin: https://trusted-site.com
```

## Configuration Examples

### Symfony (PHP)

In [Symfony](https://symfony.com/), you can use the [NelmioCorsBundle](https://symfony.com/bundles/NelmioCorsBundle/current/index.html) to handle `CORS`.
Here's an example configuration:

1. Install the bundle:
   ```bash {filename="Terminal"} theme={null}
   composer require nelmio/cors-bundle
   ```

2. Configure `CORS` in your `config/packages/nelmio_cors.yaml`:

   ```yaml {filename="config/packages/nelmio_cors.yaml"} theme={null}
   nelmio_cors:
     defaults:
       origin_regex: true
       allow_origin: ['%env(CORS_ALLOW_ORIGIN)%']
       allow_methods: ['GET', 'OPTIONS', 'POST', 'PUT', 'PATCH', 'DELETE']
       allow_headers: ['Content-Type', 'Authorization']
       expose_headers: ['Link']
       max_age: 3600
     paths:
       '^/api/':
         allow_origin: ['%env(CORS_ALLOW_ORIGIN)%']
         allow_headers: ['X-Custom-Auth']
         allow_methods: ['POST', 'PUT', 'GET', 'DELETE']
         max_age: 3600
   ```

3. Set the `CORS_ALLOW_ORIGIN` environment variable in your `.env` file:

   ```{filename=".env"} theme={null}
   CORS_ALLOW_ORIGIN=^https?://(localhost|example\.com)(:[0-9]+)?$
   ```

### Next.js (JavaScript)

In [Next.js](https://nextjs.org/), you can configure `CORS` by creating a custom API route.
Here's an example:

1. Create a file `pages/api/cors.js`:

   ```javascript {filename="pages/api/cors.js"} theme={null}
   import Cors from 'cors'
   import initMiddleware from '../../lib/init-middleware'

   // Initialize the cors middleware
   const cors = initMiddleware(
     Cors({
       methods: ['GET', 'POST', 'OPTIONS'],
     })
   )

   export default async function handler(req, res) {
     // Run cors
     await cors(req, res)

     // Rest of the API logic
     res.json({ message: 'Hello World' })
   }
   ```

2. Create the `lib/init-middleware.js` file:

   ```javascript {filename="lib/init-middleware.js"} theme={null}
   export default function initMiddleware(middleware) {
     return (req, res) =>
       new Promise((resolve, reject) => {
         middleware(req, res, (result) => {
           if (result instanceof Error) {
             return reject(result)
           }
           return resolve(result)
         })
       })
   }
   ```

3. Install the `cors` package:

   ```{filename="Terminal"} theme={null}
   npm install cors
   ```

This configuration will apply `CORS` to the specific API route. You can adjust the options in the `Cors()` function call to fit your needs.

Certainly! I'll add an example for [Laravel](https://laravel.com/) to the `CORS` Configuration Examples section. Here's the updated section with Laravel included:

### Laravel (PHP)

[Laravel](https://laravel.com/) provides built-in support for `CORS` through its middleware. Here's how you can configure `CORS` in a Laravel application:

1. Laravel 7 and above come with `CORS` support out of the box. For earlier versions, you may need to install the `fruitcake/laravel-cors` package:

   ```{filename="Terminal"} theme={null}
   composer require fruitcake/laravel-cors
   ```

2. Publish the `CORS` configuration file:

   ```{filename="Terminal"} theme={null}
   php artisan vendor:publish --tag="cors"
   ```

   This will create a `config/cors.php` file.

3. Configure `CORS` in `config/cors.php`:

   ```php {filename="config/cors.php"} theme={null}
   <?php

   return [
     'paths' => ['api/*'],
     'allowed_methods' => ['*'],
     'allowed_origins' => ['http://localhost:3000', 'https://example.com'],
     'allowed_origins_patterns' => [],
     'allowed_headers' => ['*'],
     'exposed_headers' => [],
     'max_age' => 0,
     'supports_credentials' => false,
   ];
   ```

   This configuration:

   * Applies `CORS` to all routes under `/api`
   * Allows all HTTP methods
   * Allows requests from `http://localhost:3000` and `https://example.com`
   * Allows all headers
   * Doesn't expose any headers
   * Doesn't set a max age for preflight requests
   * Doesn't allow credentials (cookies, HTTP authentication) in `CORS` requests

4. If you need more fine-grained control, you can create a `CORS` middleware for specific routes. Create a file `app/Http/Middleware/Cors.php`:

   ```php {filename="app/Http/Middleware/Cors.php"} theme={null}
   <?php

   namespace App\Http\Middleware;

   use Closure;

   class Cors
   {
     public function handle($request, Closure $next)
     {
       return $next($request)
         ->header('Access-Control-Allow-Origin', 'https://example.com')
         ->header('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS')
         ->header('Access-Control-Allow-Headers', 'X-Requested-With, Content-Type, X-Token-Auth, Authorization');
     }
   }
   ```

   Then, register this middleware in `app/Http/Kernel.php`:

   ```php {filename="app/Http/Kernel.php"} theme={null}
   protected $routeMiddleware = [
     // ...
     'cors' => \App\Http\Middleware\Cors::class,
   ];
   ```

   You can now apply this middleware to specific routes or route groups:

   ```php theme={null}
   Route::middleware(['cors'])->group(function () {
     Route::get('/api/data', 'DataController@index');
   });
   ```

This Laravel configuration gives you flexibility in handling `CORS` for your entire application or for specific routes. Remember to adjust the allowed `origins`, `methods`, and `headers` according to your application's needs and security requirements.

Certainly! I'll add a new section to the article about querying an API protected with `CORS` using curl and Postman. Here's the new section:

## Querying `CORS-Protected` APIs

While `CORS` is primarily a browser security feature, it's often useful to test APIs directly using tools like [curl](https://curl.se/) or [Postman](https://www.postman.com/). Here's how you can work with `CORS-protected` APIs using these tools:

### Using curl

curl doesn't enforce `CORS` restrictions, as it's not a web browser. However, to simulate a `CORS` request or to test your server's `CORS` configuration, you can send the appropriate headers with your request.

1. Simple GET request:

   ```bash {filename="Terminal"} theme={null}
   curl -H "Origin: http://example.com" \
        -H "Access-Control-Request-Method: GET" \
        -H "Access-Control-Request-Headers: X-Requested-With" \
        -X OPTIONS --verbose \
        https://api.example.com/data
   ```

   This sends a preflight `OPTIONS` request. The server's response will include the `CORS` headers if it's configured correctly.

2. POST request with custom headers:

   ```bash {filename="Terminal"} theme={null}
   curl -H "Origin: http://example.com" \
        -H "Content-Type: application/json" \
        -H "X-Requested-With: XMLHttpRequest" \
        -X POST -d '{"key":"value"}' \
        https://api.example.com/data
   ```

   This sends a `POST` request with a custom header, which would typically trigger a preflight request in a browser.

### Using Postman

[Postman](https://www.postman.com/) is more user-friendly for testing APIs and provides a GUI for constructing requests.

1. Setting up a `CORS` request in Postman:
   * Open a new request in Postman
   * Set the HTTP method (`GET`, `POST`, etc.)
   * Enter the API URL
   * Go to the "Headers" tab
   * Add the following headers:
     * Key: `Origin`, Value: `http://example.com`
     * Key: `Access-Control-Request-Method`, Value: `POST` (or whatever method you're using)
     * Key: `Access-Control-Request-Headers`, Value: `Content-Type, X-Requested-With` (or whatever headers you're using)

2. Sending a preflight request:
   * Set the method to `OPTIONS`
   * Send the request
   * Check the response headers for `CORS-related` headers

3. Sending the actual request:
   * Set the method back to your intended method (`GET`, `POST`, etc.)
   * If it's a `POST` request, go to the "Body" tab and add your payload
   * Send the request

### Interpreting the Results

When testing with curl or Postman, pay attention to the response headers. Look for:

* `Access-Control-Allow-Origin`: Should match your `Origin` or be `'*'`
* `Access-Control-Allow-Methods`: Should include the method you're using
* `Access-Control-Allow-Headers`: Should include any custom headers you're sending

If these headers are present and correct, it means the server is configured to allow `CORS` requests from your specified origin.

### Important Notes

1. Remember that curl and Postman don't enforce `CORS` policies. They'll send the request regardless of the server's `CORS` configuration. This is useful for testing but doesn't reflect how a web browser would behave.

2. If you're testing an API that requires authentication, make sure to include the necessary authentication headers or tokens in your requests.

3. Some APIs might have additional security measures beyond `CORS`, such as [CSRF](https://fr.wikipedia.org/wiki/Cross-site_request_forgery) tokens. You may need to account for these in your tests.

4. When testing in production environments, be cautious about sending too many requests, as this might trigger rate limiting or security alerts.

By using these tools, you can effectively test and debug `CORS` configurations on your APIs, ensuring they're set up correctly before integrating them into your web applications. This approach can save a lot of time and frustration when dealing with `CORS` issues in development.

## Platform.sh & Upsun Configuration

When working with **[Platform.sh](https://platform.sh/)** or **[Upsun](https://www.upsun.com/)**, you can dynamically set the allowed origins for `CORS` based on the `$PLATFORM_ROUTES` environment variable. This is particularly useful for handling multiple environments (development, staging, production) with different URLs.

Here's an example of how you might parse the `$PLATFORM_ROUTES` variable and use it to set the allowed origins:

```php theme={null}
<?php

// Parse the PLATFORM_ROUTES variable
$routes = json_decode(base64_decode(getenv('PLATFORM_ROUTES')), true);

// Extract the domains from the routes
$domains = array_map(function($route) {
  return parse_url($route['original_url'], PHP_URL_HOST);
}, $routes);

// Remove duplicates and null values
$allowed_origins = array_filter(array_unique($domains));

// Add any additional origins you always want to allow
$allowed_origins[] = 'localhost';

// Now use $allowed_origins in your CORS configuration
```

This approach allows you to dynamically set the allowed origins based on your Platform.sh or Upsun routes, ensuring that your `CORS` configuration remains correct across all your environments without manual intervention.


# Efficient code analysis for LLMs
Source: https://developer.upsun.com/posts/discussions/whatsun-efficient-code-analysis

Learn how Whatsun generates concise codebase summaries to improve the performance and accuracy of AI features.


<PostMeta />

AI agents excel at understanding large codebases in depth. But sometimes you don't need depth, and you don't want to wait so long.

We wanted a way to get a quick overview of a repository, so we made [Whatsun](https://github.com/upsun/whatsun). It's an open-source tool that reads the structure and dependencies in a codebase of any size, producing a very concise summary. It can be used as a CLI or a Go library. Whatsun does not itself use AI, so it's fast, predictable, and secure. But that speed is exactly why it works well with AI: it handles the quick structural analysis upfront, saving the AI from slower and more expensive processing. This helps to power our AI-assisted configuration feature, which is available through the CLI’s [`upsun init`](/posts/discussions/building-ai-feature-necessary-evals) command for local code, and which you can also try [on the web](https://config.upsun.com) for a public GitHub repository. Of course, we also used AI to help build Whatsun itself.

## The problem

At Upsun we support applications written in many different languages, built with many different tools. These diverse applications can coexist in the same repository as part of a single Upsun project, and this complexity is why we are leveraging AI to help with configuration.

Our AI context for an Upsun project started with a system prompt, a [`tree`](https://en.wikipedia.org/wiki/Tree_\(command\)) and some documentation. As we [evaluated](/posts/discussions/building-ai-feature-necessary-evals) the AI's results, our approach to the context evolved, and we found we needed more precise information that was able to vary according to the type of project.

Another approach would be to ask the LLM to fetch the context it needs, giving it tools to read anything it likes. This can work beautifully in coding agents such as Claude Code, but it did not suit our needs: it would take much longer, cost too much (requiring large reasoning models), and expose too much unnecessary information.

Our AI prompt now includes Whatsun's output, alongside conditional context retrieved automatically based on Whatsun's findings, such as framework-specific documentation.

## The digest

Whatsun produces a *digest* of a repository, in three parts:

1. **A file tree** that limits detail progressively, minimizing [tokens](https://blogs.nvidia.com/blog/ai-tokens-explained/). The tree respects `.gitignore`, which greatly improves performance as it avoids the need to traverse unnecessary directories (like `node_modules`).

2. **Reports** showing detected frameworks, build tools, and package managers. The reports are generated based on configurable rules, explained below.

3. **Selected file contents** from important files like `README.md`, `AGENTS.md`, or `docker-compose.yml`. This will also include files specific to certain findings: for example, `compose.yaml` will be included if Symfony is detected. The contents are limited to the first 2 KB.

The result is a succinct snapshot with the level of detail that we find most helpful.

For example, below is the `reports` section for our [demo project](https://github.com/upsun/demo). It shows that the project contains a Flask backend and a React frontend, managed by `uv` and `bun`.

```yaml theme={null}
reports:
    .:
        - result: bun
          ruleset: package_managers
          groups: [js]
    backend:
        - result: flask
          ruleset: frameworks
          groups: [python]
        - result: uv
          ruleset: package_managers
          groups: [python]
    frontend:
        - result: express
          metadata: {version: 4.21.2}
          ruleset: frameworks
          groups: [js]
        - result: reactjs
          metadata: {version: 18.3.1}
          ruleset: frameworks
          groups: [js]
        - result: bun
          ruleset: package_managers
          groups: [js]
```

## Declarative rules

As we were exploring what this tool could do, we wanted it to be simple to configure, but we didn't want to restrict its potential. We chose [Common Expression Language (CEL)](https://cel.dev/), which lets you write rules as configuration. Each rule is evaluated on every directory of the codebase and then may contribute a result.

Here is an example rule:

```yaml theme={null}
django:
  when: fs.depExists("python", "django")
  then: django
```

The `when` clause is a CEL expression. In this case, in each directory, it invokes a dependency manager function to check whether `django` is required as a Python dependency. The use of other web frameworks in a codebase can be harder to detect. They may be composed of various packages that may or may not indicate use of the framework, such as Symfony's flexible components and libraries. A 'framework' may even be used without any visible presence in the repository, in the case of static site generators. Or it may leave a file as a clue:

```yaml theme={null}
when: fs.fileExists("hugo.toml") || fs.fileExists("hugo.yaml") || fs.fileExists("hugo.json") || fs.fileExists(".hugo_build.lock")
then: hugo
```

The rules-based system makes this very flexible without extra Go code. In theory, other sets of rules for other kinds of analysis could be added in future or provided by library callers.

## Multilingual dependency detection

Whatsun parses package manager manifests for nine languages to get an overview of dependencies: Go, JavaScript, Python, PHP, Ruby, Rust, Java, .NET, and Elixir. Some of these, such as JavaScript and Python, each have numerous package managers. Fortunately, adding new integrations is a particularly good use case for AI, for research and generating code and tests.

## Security and privacy

Upsun requires a security and privacy review of new features, and of course AI-powered features are no exception. A Git repository stores code, and should never usually contain secrets nor personal information, but it remains a possibility. Such data would not be of any use for understanding the code, and it should not be sent to an AI vendor. Whatsun avoids this using multiple layers of protection.

Firstly, it respects developer intent: `.aiignore` and `.aiexclude` files can be used to declare what should not be analyzed. Unfortunately, this isn't a common standard yet, but the former is supported by JetBrains's Junie and the latter by Google's Gemini. As mentioned above, Whatsun also reads and respects `.gitignore` files, for both privacy and efficiency.

Secondly, if a file's content is included, Whatsun sanitizes it. It uses [Gitleaks](https://github.com/gitleaks/gitleaks) for secret detection, redacting API keys and credentials. It also redacts email addresses to remove personally identifiable information, detects and skips binary files, and strips comments to avoid leaking internal notes.

## Performance

Speed is a priority for Whatsun's user experience, scalability, and ease of development.

Whatsun caches the configured CEL rules during build, so that they do not need to be recompiled. It traverses directories in parallel, and then executes rules in parallel, ensuring directory contents are cached between steps to avoid unnecessary [`stat()`](https://en.wikipedia.org/wiki/Stat_\(system_call\)) calls. It operates on Go's `io/fs` virtual filesystem, meaning it can process a Git repository cloned in memory or on disk in the same way.

The resulting digest is designed to minimize tokens, which helps in a few ways: a faster response, less context confusion, and lower costs.

## Caveats

Whatsun is built for the 80% case: surface-level understanding, not deep analysis. It does not provide the full-file context that an AI would need to edit code. And while the rules cover quite a few cases, they would require quite a bit of maintenance to become or remain comprehensive.

## Try it

Whatsun is open-source and [available on GitHub](https://github.com/upsun/whatsun).

If you are building an AI developer tool, you might find Whatsun useful for enhancing context.

Or you can download the `whatsun` CLI, run it on your project, and see what it produces:

```shell theme={null}
go install github.com/upsun/whatsun/cmd/whatsun@latest
```

We'd be glad to hear what you think, and contributions are very welcome.


# Why AI agents need cloud sandboxes
Source: https://developer.upsun.com/posts/discussions/why-ai-agents-need-cloud-sandboxes

AI agents run real commands on real systems. Learn why cloud sandboxes with production data beat local isolation for safe AI agent workflows.


<PostMeta />

AI agents don't just generate text anymore. They execute shell commands, modify files, query databases, call APIs, and push code. Every major coding agent (Claude Code, Codex, Cursor, ...) now operates this way: the model reasons about what to do, and the harness executes real commands on a real system.

That's what makes them useful. It's also what makes them risky.

This article is part one of a two-part series on sandboxing AI agents on Upsun. This piece covers why sandboxing matters and why cloud environments are the right place for it. Part two, coming next week, will cover the step-by-step technical implementation: configuring Claude Code, Codex, and building your own sandbox from scratch with standard Linux tools.

## Why agents are a security problem

An AI agent can read your environment variables and make outbound network calls. It processes content written by others: pull request descriptions, issue comments, dependency READMEs. That combination is what makes prompt injection dangerous. An attacker doesn't need to compromise your infrastructure. They just need to put the right text in a place the agent will read.

This has already happened in production. Prompt injection attacks have been [reported against](https://blog.simonwillison.net/tags/lethal-trifecta/) Microsoft 365 Copilot, GitHub's MCP server, and GitLab Duo Chat. The industry consensus now treats LLM-generated code as untrusted by default. Not because models are malicious, but because their output is shaped by input you don't fully control.

The solution is sandboxing: restricting what the agent's process can see, touch, and reach. But where you run that sandbox matters almost as much as how you configure it.

## Local sandboxing: good for coding, bad for validation

Running agents on your laptop with tools like bubblewrap or Docker gives you basic isolation. The agent can't easily read files outside its working directory, and network access can be restricted. For interactive coding sessions where you're watching the output and approving each step, this works well enough.

But local sandboxing has hard limits that appear the moment you need agents to do more than edit files.

**No realistic environment.** A coding agent on your laptop can modify source code and run unit tests. It can't validate a database migration against production-scale data. It can't check how a caching change behaves with your actual service configuration. It can't verify that a platform configuration update behaves correctly with the services your application depends on. Local sandboxing gives you code isolation, not environment isolation.

**No reproducibility.** Your laptop has its own OS version, package versions, and quirks. An agent that passes tests locally may still fail later because the environment is different. A sandbox is only as useful as the environment it mirrors, and a laptop doesn't mirror much.

**No collaboration.** When an agent runs locally, the output stays on your machine. Your team can't visit a preview URL to see the changes. Your CI pipeline can't validate them against a real environment. The agent's work is invisible until you manually push it somewhere.

**No scalability.** You can run one, maybe two agent sessions on a laptop before it crawls. Companies running agents across dozens of projects need hundreds of concurrent sessions. Local machines don't scale.

Cloud sandboxing addresses all of these. But not all cloud sandboxes are equal.

## Agents need infrastructure, not just containers

Most sandbox platforms provide isolated containers for running code. That's a good start, but it misses something fundamental about what makes agents valuable.

An agent fixing a performance issue doesn't just modify a source file. It needs to understand how the application behaves with realistic data, real queries, and actual services. An agent running a database migration needs a database that contains the kind of data it will encounter in production. An agent adjusting configuration needs access to real metrics and real service topology.

This is the difference between a **code sandbox** and an **environment sandbox**. Code sandboxes let agents modify files safely. Environment sandboxes let agents understand, test, and validate their changes against reality.

Early adopters are already proving this out. Engineering teams that give their agents access to real databases, testing frameworks, telemetry, and live previews report significantly higher trust and adoption. Some teams now attribute a substantial share of their merged pull requests to agents. That level of trust does not come from letting an agent run `npm test` in an empty container. It comes from letting it verify its work in a realistic environment.

The pattern is clear. Agents that can only modify code are useful. Agents that can validate their changes against real infrastructure are transformative. And validation requires a cloud environment that looks, behaves, and contains the same things as production.

## Upsun already has the right building blocks

Upsun wasn't designed specifically for AI agents. It was built for developers who need fast, isolated, production-like environments for every branch. It turns out agents need the same thing.

The platform provides two levels of protection that are relevant for agent sandboxing. The first is container-level security: every container runs rootless, with namespace isolation, syscall filtering, and a read-only application filesystem. These protections are always on, with zero configuration. Part two of this series will cover this layer in detail, including how to add in-container tools like bubblewrap for additional process-level isolation.

The second level is what makes Upsun genuinely different for agent workloads: **environment-level isolation**.

## Preview environments: full-stack sandboxes with real data

When you create a Git branch on Upsun, the platform creates a complete, isolated deployment of your entire application. Not just the code, but the data, the services, the configuration, and the network topology. The entire stack, cloned in seconds thanks to [copy-on-write storage](/posts/discussions/instant-data-cloning-was-a-bet-ai-agents-are-the-payoff). Every branch gets its own URL, its own database, its own services.

For human developers, this means safe experimentation. For AI agents, it means something more profound: **a full-stack sandbox with production data that can be destroyed without consequence**.

**Database migrations against real data.** The agent creates a branch, gets a clone of production data, writes a migration, runs it, and checks the results. If the migration fails or corrupts data, delete the branch. Production never noticed. Try doing that on your laptop with a 200 GB PostgreSQL database.

**Performance validation with real service topology.** The agent deploys a code change to a preview environment and profiles it. Same database version, same cache configuration, same message queue setup as production. The performance numbers are meaningful because the infrastructure is identical. Not a Docker Compose file with default settings, but the same managed services running the same versions with the same data.

**Configuration changes you can actually trust.** The agent modifies `.upsun/config.yaml`, pushes to the branch, and the platform redeploys the preview environment with the new configuration. If it breaks, the branch is self-contained. Production keeps running.

Most sandbox providers give you isolated containers. Upsun gives you isolated **environments** that are faithful copies of your entire production stack. The agent doesn't test against a simplified mock. It tests against reality.

Preview environments are also ephemeral by design. You create a branch for the agent, let it work, review the result, and delete the branch when you're done. Inactive environments can pause automatically, which keeps this model practical for experimentation.

For a deeper look at data cloning and why it matters for agents, see [Instant data cloning was a bet. AI agents are the payoff.](/posts/discussions/instant-data-cloning-was-a-bet-ai-agents-are-the-payoff).

## The Git workflow as a safety net

Every Upsun environment is tied to a Git branch. This means agent execution fits naturally into the development workflow your team already uses:

1. Agent creates a branch
2. Upsun creates an isolated environment for that branch
3. Agent makes changes, runs tests, and validates against the services in that environment
4. Agent opens a pull request
5. Human reviews and merges (or rejects)
6. Branch is deleted, environment disappears

The agent's work is visible, reviewable, and reversible. No hidden changes, no direct production access, no mystery state living on somebody's laptop. The history lives in Git and in the platform activity log.

This is fundamentally different from agents that apply changes directly to a running system. With Upsun's branch-based model, agents propose changes through the same workflow your team already uses. The sandbox isn't just a security boundary. It's a collaboration tool.

This also means you can run agents with different levels of autonomy. A fully autonomous agent creates branches, makes changes, and opens pull requests for human review. A human-in-the-loop agent pauses at key decision points and asks for approval before proceeding. Both models work naturally within the Git workflow, and both benefit from the same environment isolation.

## An environment, not a product

One thing worth noting: sandboxing on Upsun isn't a separate product you buy or a toggle you flip. It's a configuration pattern built from existing platform capabilities. Container isolation is always on. Environment boundaries are always enforced. Data cloning works the same way for agents as it does for developers. In-container sandboxing tools like bubblewrap are standard Linux packages you install through composable images.

This matters because the AI agent landscape is moving fast. The tools, frameworks, and best practices are changing month to month. A sandboxing approach that depends on a specific vendor's agent runtime or a proprietary isolation layer will break when the landscape shifts. Upsun's approach gives you standard Linux tools on a platform that already handles the hard parts (isolation, data cloning, environment lifecycle), and you compose them however your workload requires.

## Getting started

You don't need to wait for a specialized agent platform to run agents safely in the cloud. If you're on Upsun, you already have the building blocks:

* **Environment isolation** with complete separation between branches
* **Preview environments** for disposable, full-stack experimentation with real data
* **Instant data cloning** for production-like testing in seconds
* **Git-based workflow** for reviewable, reversible changes
* **Container security** with rootless execution, seccomp, and read-only filesystems
* **Composable images** for installing any sandboxing tools you need

Start with a branch. Push your agent's code. Let it work against a real environment. Review the results. Delete the branch when you're done.

For the full technical guide to configuring in-container sandboxing on Upsun (Claude Code, Codex, or from scratch), stay tuned for part two of this series, coming next week.

To get started with Upsun, [create a free trial account](https://upsun.com/). For more on running AI workloads on the platform, see the [AI agent hosting documentation](https://developer.upsun.com/docs/get-started/ai/aiagent).


# Source Operations and Activity Scripts for Drupal teams
Source: https://developer.upsun.com/posts/engineering/save-your-drupal-team-hours-and-effort-with-source-operations-and-activity-scripts

Learn how to automate Drupal updates on Platform.sh using Source Operations and Activity Scripts, saving your development team time and effort.

<PostMeta />

FleetOps—running a large fleet of apps and websites efficiently, securely, and predictably—is a challenge for every
organization. One difficulty facing organizations managing multiple Drupal sites is keeping their dependencies current.
For instance, each time a crucial security update is released, how many resources end up being spent making sure each
site has properly been patched? How many team hours could be saved by automating dependency processes?

On Platform.sh, you can deploy your Drupal projects complete with a set of customized Source Operations that will
automatically check for and apply updates using Composer to a development environment.

This still leaves your team keeping a constant eye out for updates that need to be reviewed or merged. That’s why
Platform.sh gives you access to Activity Scripts that you can use to set up alerts for when updates are ready to review
and merge into production. Your development team can now spend their energy on things that actually need their attention.

We’ve created an [easy-to-follow video](https://www.youtube.com/watch?v=1RRDzi0TGRI\&feature=youtu.be) outlining all the
steps for setting up Source Operations and Activity Scripts for your Drupal projects. In less than ten minutes, you’ll
be ready to automate your sites and free up your development team for high value work.

<iframe />

You can also visit our documentation site to get even more information on
[Source Operations](https://docs.platform.sh/configuration/app/source-operations.html) and
[Activity Scripts](https://docs.platform.sh/integrations/activity.html). You’ll also find an
[example activity script](https://docs.platform.sh/integrations/activity/slack.html) that will post a message to a
Slack channel every time it is triggered.


# Three ways to manage a website fleet
Source: https://developer.upsun.com/posts/engineering/three-ways-to-manage-a-fleet

Efficient multi-website management using Source Operations on Platform.sh. Automate updates, builds, and deployments for a large number of websites with ease.

<PostMeta />

As hinted in the [previous post](https://platform.sh/blog/automating-updates-source-operations/), one of the potential use cases for
[Source Operations](https://docs.platform.sh/configuration/app/source-operations.md) is managing and updating a fleet of
sites—a common situation, especially for organizations that have large numbers of sites running identical or nearly
identical code, but in their own projects. Traditional approaches to fleet management involve *pushing* updates to an
array of sites. What Source Operations enables is the ability to have sites *"pull"* updates — en masse,
individually, or as a subset — and own the process of managing the site from the receiving end rather than the
sending end.

With a pull-based approach, of course, it's still useful to have a way to automate updating a large set of sites at once,
building a preview environment, and subsequently merging them. (Just because you *can* deploy updates directly to
production without review doesn't mean you *should.*) Because we provide a robust set of primitives, there are a number
of ways you could build on top of them to create a customized, personalized workflow for
[managing multiple sites](https://platform.sh/blog/managing-multiple-website/).

In this post, we'll look at three ways to build a fleet management workflow on Platform.sh.

In each case, we'll assume that every project has the following source operation defined:

```yaml {filename=".platform.app.yaml"} theme={null}
source:
  operations:
    upstream-update:
      command: |
        set -e
        git remote add upstream $UPSTREAM_REMOTE
        git fetch --all
        git merge upstream/master
```

When triggered, it will merge in any changes from an upstream
<a href="https://docs.platform.sh/development/private-repository.html">Git repository</a> defined in an environment
variable and redeploy that code on that branch. Note that this is just an example script that lacks good error handling,
but is easier to explain for now. There are also, of course, ample other ways to handle a site updating itself, such as
pulling new packages from a private language repository on demand.

## Fully automatic scheduled updates with cron

Because a source operation can be triggered from the CLI tool, it can also be triggered from cron.

First, [install the CLI and add an API key configured](https://docs.platform.sh/gettingstarted/cli/api-tokens.html) to
make it available from the application container. Then, add the following cron job in the `.platform.app.yaml` of the
upstream repository (which will, therefore, be included in all of its clones):

```yaml {filename=".platform.app.yaml"} theme={null}
crons:
    update:
        spec: '0 0 * * *'
        cmd: |
            if [ "$PLATFORM_BRANCH" = upstream-update ]; then
                platform environment:sync code data --no-wait --yes
                platform source-operation:run upstream-update --no-wait --yes
        	fi
```

Now, at about midnight UTC, a cron job will run on each branch, but will be a no-op on most. However, on the branch
named `upstream-update` it will first sync both code and data from the parent branch (presumably `master`) to get the
latest updates, then run a code update on itself.

As a result, the `upstream-update` environment will always have the latest production code and data (as of midnight)
*plus* the latest upstream dependency updates. *You now have an environment that self-updates and previews the resulting
changes.* Whoever manages each individual site can then do a visual review of that branch and, when happy with it, just
click "Merge" from the Management Console in their browser.

Keep your site up to date with just a few mouse clicks.

## Triggering Source Operations updates on demand with scripting

If you'd rather only trigger updates when you actively decide to, rather than nightly, the Platform.sh CLI is highly
scriptable. At the most basic end, one could whip up a small bash script like so:

```bash {filename="Terminal"} theme={null}
platform environment:sync code data -p abc123 -e upstream-update --no-wait --yes
platform source-operation:run upstream-update  -p abc123 -e upstream-update --no-wait --yes
platform environment:sync code data -p def456 -e upstream-update --no-wait --yes
platform source-operation:run upstream-update  -p def456 -e upstream-update --no-wait --yes
```

That code would certainly work to trigger a source operation update across a number of sites, but it's a bit clunky.

Fortunately, the CLI has a helpful `multi` command that can internalize that task for you. Instead of the above, you can
do:

```bash {filename="Terminal"} theme={null}
platform multi --projects=abc123,def456  --continue 'environment:sync code data -e upstream-update --no-wait --yes'
platform multi --projects=abc123,def456  --continue 'source-operation:run upstream-update -e upstream-update --no-wait --yes'
```

And with just those two lines, the CLI will trigger a Sync of both projects' `upstream-update` branches, then queue up
the source operation behind them. For more projects, just list more project IDs in the list.

As with the cron approach, site owners can then click Merge in the UI at their leisure. Alternatively, the CLI can
trigger the merge, too:

```bash {filename="Terminal"} theme={null}
platform multi --projects=abc123,def456 --continue 'merge -e upstream-update --no-wait --yes'
```

And every project will merge `upstream-update` to master, which triggers a new build-and-deploy for production.

The list of project IDs can be comma or whitespace delimited, which means you could also read them from a file, like so:

```bash {filename="Terminal"} theme={null}
platform multi --projects="$(< projects.txt)" --continue 'merge -e upstream-update --no-wait --yes'
```

Because the CLI is scriptable, you could also wrap more complex behavior into a bash script, Python script, PHP script,
or whatever else to build the commands dynamically. Such a script is left as an exercise for the reader.

## Creating a GUI to manage your website fleet with Source Operations

Both of the above methods will scale to a few dozen sites in a fleet. When you're talking about hundreds or even
thousands of sites, though, you may want a more robust solution. Past a certain scale, you want a nice GUI that lets you
mass-manage sites.

Everything the Platform.sh CLI or Management Console do is just a combination of Git commands and API calls. Those
[APIs are documented](https://api.platform.sh/), and of course Git is, well, Git. That means one could build a custom
application to issue calls against that API however and whenever desired. Like, say, from your own web application
(which can itself be hosted on Platform.sh).

We have built a proof of concept of such an application. The application itself is very rudimentary and still lacks
important features like user management (BYO authentication), but it's enough to demonstrate the basic operations you
can do. It's built with Symfony and the EasyAdminBundle, which provides the CRUD UI.

<img alt="Project list" />

The dashboard lists multiple projects owned by the same Platform.sh user. It's largely an automated list of Doctrine
objects. (Doctrine is the standard ORM for Symfony.) Projects can be added through this application as well:

<img alt="New Project Screen" />

Projects are created from an "Archetype," which is just a simple record of an upstream Git repository and some
configuration data, like the name of the environment to use for updates. It can also be placed in any Platform.sh
region. More settings could easily be added.

On `Save`, the application issues an API call to Platform.sh to create a new project with the specified criteria. The
project is then initialized with a clone of the Archetype Git repository.

Once a project is created and tracked by the application, it can issue API calls against one or more projects in a
batched set.

<img alt="Selected projects and available commands" />

* "Backup" is just an API call to trigger a backup on the master environment.
* "Update" triggers a sync on the update branch and then runs the source operation.
* "Merge update" triggers a simple merge of the update branch to master.
* "Delete" deletes the projects from the dashboard, *and* from Platform.sh.

This demo application is not production usable in its current state, of course, but demonstrates the sort of custom
mass-management dashboard one could build. In fact, some of our customers have already built White Label SaaS tools to
do such management themselves, including managing billing and accounts for their own customers. They didn't even tell us
they were doing it! (That's a good sign that our APIs are where we want them.)

Naturally, there are ample other ways to wrap a user interface around the Platform.sh API, depending on your specific
use case.

## Platform.sh is designed to give you flexibility for your fleet workflow

Regardless of how many sites you have and how you want to manage them, there are options available. Our goal is to let
you build the perfect SaaS, fleet deployment, or other management toolchain for your organization. Between the
Platform.sh REST API and our new [Source Operations feature](https://platform.sh/blog/automating-updates-source-operations/), the
components are there to let you build what you want, how you want, as you want.


# AI use-case: Generate load test scenarios with MCPs
Source: https://developer.upsun.com/posts/hands-on/ai-use-case-generate-load-test-scenarios

Automate Locust load testing by combining Chrome MCP and Context7 to generate realistic user behavior patterns with Claude Code.

<PostMeta />

I don't know about you, but one task I have always been dreading for every critical project is actually creating the load-test performance scenarios... Whether that was with Apache JMeter or any other one, I've spent countless hours creating and debugging them. Handling cookies, customer login, etc.

As I needed to run another test on a new website, I started poking around the idea of using Claude Code to generate the test ... You can actually automate this process by connecting two Model Context Protocol (MCP) servers, Chrome MCP and Context7, to generate comprehensive test scenarios that match actual user navigation patterns.

## How MCPs automate scenario generation

Model Context Protocol (MCP) servers connect AI assistants like Claude Code to external data sources and tools. By combining two MCPs, you can automate load test creation:

1. **Chrome MCP** - Analyzes your live application by browsing pages, extracting navigation patterns, and understanding user flows
2. **Context7 MCP** - Retrieves current Locust documentation to generate syntactically correct test code

Here's how the workflow connects:

```mermaid theme={null}
%%{init: {'theme':'base', 'themeVariables': { 'fontSize':'16px'}}}%%
graph LR
    A[Claude Code] -->|Browses & analyzes| B[Chrome MCP]
    A -->|Fetches docs| C[Context7 MCP]
    B -->|Navigation patterns| D[Your Website]
    C -->|Locust syntax| E[Locust Docs]
    A -->|Generates| F[locustfile.py]

    style A fill:#E8F9A3,stroke:#495867,stroke-width:3px,color:#495867
    style B fill:#B5A8FF,stroke:#495867,stroke-width:2px,color:#495867
    style C fill:#B5A8FF,stroke:#495867,stroke-width:2px,color:#495867
    style D fill:#ffa69e,stroke:#495867,stroke-width:2px,color:#495867
    style E fill:#ffa69e,stroke:#495867,stroke-width:2px,color:#495867
    style F fill:#E8F9A3,stroke:#495867,stroke-width:3px,color:#495867
```

## Setting up your environment

Before generating tests, configure both MCP servers in your Claude Code environment.

### Install Chrome MCP

The Chrome MCP lets Claude Code control a Chrome browser to explore your application:

```bash {filename="Terminal"} theme={null}
claude mcp add -t stdio npx chrome-devtools-mcp@latest --scope user
```

<Note>
  The `--scope user` parameter make the MCP global for all projects.
</Note>

### Configure Context7 MCP

Context7 provides access to technical documentation:

```bash {filename="Terminal"} theme={null}
claude mcp add --transport http context7 https://mcp.context7.com/mcp --header "CONTEXT7_API_KEY: YOUR_API_KEY"  --scope user
```

*Note: The API key is optional and only required if you are generating a high usage of Context7.*

### Install the Locust tool

Set up Locust in a virtual environment to keep dependencies isolated:

```bash {filename="Terminal"} theme={null}
# Create a virtual environment
python3 -m venv locust-env

# Activate it (macOS/Linux)
source locust-env/bin/activate

# Or on Windows
# locust-env\Scripts\activate

# Install Locust
pip install locust

# Verify installation
locust --version
```

Keep this environment activated when running your load tests. You can deactivate it later with `deactivate`.

## Generating load tests for an e-commerce site

Let's generate Locust tests for an e-commerce platform. This example demonstrates how Claude Code uses both MCPs to create realistic user scenarios.

We are going to use the Magento Association website as an example:

<img alt="Magento Association" />

### Upsun resources for preview environments

Before running load tests, configure your test environment properly. Upsun now allows you to [customize resources for preview environments](/images/posts/hands-on/ai-use-case-generate-load-test-scenarios/change-resources.webp), making it perfect for realistic load testing without impacting production.

You can temporarily provision the same resource levels as your production environment on a preview environment just for the duration of your tests. This means no more running tests against production at night or hoping staging accurately reflects production performance. Spin up a preview environment with production-equivalent CPU, memory, and storage, run your comprehensive load tests, analyze the results, and then scale it back down—all without risking your live site.

<img alt="Change resources" />

### Prompt Claude Code

Start by describing what you need:

```text {filename="claude"} theme={null}
Analyze the e-commerce site at https://example-shop.com/ and generate Locust 
load test scenarios. Create three user types:

1. Browser - go to the home page, views products, searches, but doesn't buy (70% of users)
2. Campaign - go to a product page directly 
3. Shopper - adds items to cart and review the cart (25% of users)

Use Chrome MCP to explore the site navigation and Context7 to get current 
Locust documentation. Generate a complete locustfile.py with realistic timing.

Once done, give me the instruction to run the test.
```

<iframe title="YouTube video player" />

### What Claude Code does

Claude Code executes this workflow:

```mermaid theme={null}
%%{init: {'theme':'base', 'themeVariables': { 'fontSize':'14px'}}}%%
graph LR
    A[User Prompt] --> B[Analyze Site]
    B --> C[Chrome MCP Explores]
    C --> D[Extract Patterns]
    D --> E[Fetch Locust Docs]
    E --> F[Context7 Retrieves]
    F --> G[Generate Code]
    G --> H[locustfile.py]

    style A fill:#E8F9A3,stroke:#495867,stroke-width:2px,color:#495867
    style B fill:#B5A8FF,stroke:#495867,stroke-width:2px,color:#495867
    style C fill:#B5A8FF,stroke:#495867,stroke-width:2px,color:#495867
    style D fill:#ffa69e,stroke:#495867,stroke-width:2px,color:#495867
    style E fill:#B5A8FF,stroke:#495867,stroke-width:2px,color:#495867
    style F fill:#B5A8FF,stroke:#495867,stroke-width:2px,color:#495867
    style G fill:#ff686b,stroke:#495867,stroke-width:2px,color:#495867
    style H fill:#E8F9A3,stroke:#495867,stroke-width:3px,color:#495867
```

1. **Analyzes the site structure** using Chrome MCP:
   * Navigates through product categories
   * Identifies search functionality
   * Maps the checkout process
   * Notes authentication requirements

2. **Retrieves Locust documentation** via Context7:
   * Gets syntax for HttpUser classes
   * Checks task decorator usage
   * Reviews wait\_time configurations
   * Verifies weight attribute usage

3. **Generates the test file** combining both sources of information

### Example generated output

The generated test creates three distinct user types with different behaviors and weights:

```mermaid theme={null}
%%{init: {'theme':'base', 'themeVariables': { 'fontSize':'14px'}}}%%
graph LR
    A[Load Test Users] --> B[Browser 70%]
    A --> C[Campaign 5%]
    A --> D[Shopper 25%]

    B --> B1[View Homepage]
    B --> B2[Browse Categories]
    B --> B3[View Products]
    B --> B4[Search]

    C --> C1[Campaign Landing]
    C --> C2[View Product]
    C --> C3[Explore Category]

    D --> D1[Browse Products]
    D --> D2[Add to Cart]
    D --> D3[View Cart]
    D --> D4[Update Cart]

    style A fill:#E8F9A3,stroke:#495867,stroke-width:3px,color:#495867
    style B fill:#B5A8FF,stroke:#495867,stroke-width:2px,color:#495867
    style C fill:#ff686b,stroke:#495867,stroke-width:2px,color:#495867
    style D fill:#ffa69e,stroke:#495867,stroke-width:2px,color:#495867
    style B1 fill:#B5A8FF,stroke:#495867,stroke-width:1px,color:#495867
    style B2 fill:#B5A8FF,stroke:#495867,stroke-width:1px,color:#495867
    style B3 fill:#B5A8FF,stroke:#495867,stroke-width:1px,color:#495867
    style B4 fill:#B5A8FF,stroke:#495867,stroke-width:1px,color:#495867
    style C1 fill:#ff686b,stroke:#495867,stroke-width:1px,color:#495867
    style C2 fill:#ff686b,stroke:#495867,stroke-width:1px,color:#495867
    style C3 fill:#ff686b,stroke:#495867,stroke-width:1px,color:#495867
    style D1 fill:#ffa69e,stroke:#495867,stroke-width:1px,color:#495867
    style D2 fill:#ffa69e,stroke:#495867,stroke-width:1px,color:#495867
    style D3 fill:#ffa69e,stroke:#495867,stroke-width:1px,color:#495867
    style D4 fill:#ffa69e,stroke:#495867,stroke-width:1px,color:#495867
```

<Note>
  You can review the generated [`locustfile.py` on Github](https://gist.github.com/gmoigneu/180fdc2516f734be69ed10628c4a1d6f)
</Note>

## Running your generated tests

Once you have the locustfile, start testing:

```bash {filename="Terminal"} theme={null}
# Install Locust if needed
pip install locust

# Run with web interface
locust -f locustfile.py --host=https://example-shop.com

# Run headless for CI/CD
locust -f locustfile.py \
  --host=https://example-shop.com \
  --users=100 \
  --spawn-rate=10 \
  --run-time=5m \
  --headless
```

Access the web interface at `http://localhost:8089` to monitor test execution, view statistics, and adjust user counts.

<img alt="Locust Graph" />

<img alt="Locust Stats" />

## What's next?

Generating the test scenarios is just the beginning. Claude Code can continue assisting throughout your entire load testing workflow. Once your tests are running, you can ask Claude Code to **analyze the Locust output**, **identify performance bottlenecks** from the statistics, and interpret failure patterns. Simply share the results with Claude Code and request an analysis.

Beyond diagnostics, Claude Code can **suggest specific code optimizations based on your test results**. If certain endpoints show high response times or failure rates, Claude Code can examine your application code, propose caching strategies, recommend database query optimizations, or suggest architectural improvements. This closes the loop from test generation to actionable performance improvements, all within a single AI-powered workflow.

***

Ready to automate your load testing? [Create a free Upsun account](https://upsun.com) to deploy and run your generated Locust tests in isolated environments with full observability.


# Building internal AI agents for our teams on Upsun
Source: https://developer.upsun.com/posts/hands-on/building-internal-ai-agents-for-our-teams-on-upsun

Learn how to build and deploy production-ready AI agents on Upsun using Google's ADK, ChromaDB vector database, and Retrieval-Augmented Generation (RAG) to create context-aware, domain-specific agents for your team.

<PostMeta />

At Upsun, we believe the best way to understand a technology is to build something real with it. That's why we created **AI-Brain**, a multiple AI agents system designed to help our teams to create high-quality technical content and understand our product better. This article is the story of how we built it, why we made specific architectural decisions, and what we learned along the way.

More importantly, this article shows you how to build your own internal AI agents on Upsun. Agents that understand your domain, follow your guidelines, and produce consistent, high-quality outputs. The article will focus on building a content writer agent for a Marketing team but the concepts can be applied to any other role.

<img alt="Agent screenshot" />

## The challenge: Beyond generic AI responses

Generic AI assistants are impressive, but they fall short when you need domain-specific expertise. Ask ChatGPT to write a technical article about your company, and you'll get something generic—accurate in structure perhaps, but lacking the nuance, brand voice, and technical depth your team needs.

The problem isn't the model's capability, it's the **context**. Large language models don't inherently know about your company's:

* Technical documentation and best practices
* Brand voice and messaging guidelines
* Content templates and formatting standards
* Product-specific features and terminology
* Team personas and target audiences

We needed an agent that could write content and produce answers to questions as if it were a member of our team. Someone who had read all our documentation, understood our brand voice, and could reference our existing articles for technical accuracy.

## The solution: Context building, not prompt engineering

Our key insight was this: **building better agents isn't about writing better prompts, it's about building better context**.

Traditional prompt engineering tries to cram everything into the user's message:

```python theme={null}
# Traditional approach - everything in the prompt
user_message = f"""
Write an article about Redis caching.

Here are our brand guidelines: {50_pages_of_guidelines}
Here are code examples: {hundreds_of_examples}
Here's our style guide: {detailed_style_guide}
Now write the article...
"""
```

This approach has fundamental problems:

* **Token limits**: You hit model context windows quickly or encounter context rotting issues
* **Cost**: Every query pays for the same massive context
* **Maintenance**: Updating guidelines means updating every prompt
* **Relevance**: Most of that context isn't relevant to the specific request

Instead, we built a system that separates **static context** from **dynamic context**:

```mermaid theme={null}
graph LR
    A[User Request] --> B[Agent]
    C[Static Knowledge<br/>Guidelines, Templates<br/>Brand Voice] --> B
    D[Dynamic Retrieval<br/>Relevant Docs<br/>Code Examples] --> B
    B --> E[Generated Response]

    style A fill:#D0F302,stroke:#000,color:#000
    style B fill:#6046FF,stroke:#000,color:#fff
    style C fill:#fff,stroke:#000,color:#000
    style D fill:#fff,stroke:#000,color:#000
    style E fill:#D0F302,stroke:#000,color:#000
```

* **Static Knowledge**: Injected once into the agent's instructions—brand voice, writing standards, personas
* **Dynamic Retrieval**: Retrieved on-demand using RAG (Retrieval-Augmented Generation)—relevant documentation, code examples, technical details

This hybrid approach gives us the best of both worlds: consistency from static context and freshness from dynamic retrieval.

## Architecture overview: The big picture

Before diving into implementation details, let's understand the system architecture:

```mermaid theme={null}
graph LR
    A[GitHub Repos <br/>blog, docs, etc.] --> B[Daily Ingestion<br/>Cron Job]
    B --> C[ChromaDB<br/>Vector Database]
    D[Static Knowledge<br/>Rules & Guidelines] --> E[Google ADK Agent]
    C --> F[RAG Query Engine]
    F --> E
    E --> G[Web Interface]
    E --> H[CLI Interface]

    style A fill:#fff,stroke:#000,color:#000
    style B fill:#D0F302,stroke:#000,color:#000
    style C fill:#6046FF,stroke:#000,color:#fff
    style D fill:#fff,stroke:#000,color:#000
    style E fill:#6046FF,stroke:#000,color:#fff
    style F fill:#D0F302,stroke:#000,color:#000
    style G fill:#fff,stroke:#000,color:#000
    style H fill:#fff,stroke:#000,color:#000
```

The system has five main components:

1. **Document Ingestion**: Daily cron job that syncs Git repositories, processes markdown files, and updates embeddings in ChromaDB
2. **ChromaDB Vector Database**: Stores document embeddings for semantic search
3. **RAG Query Engine**: Retrieves relevant content using vector similarity search
4. **Google ADK Agent**: Orchestrates responses using static knowledge and dynamic retrieval
5. **User Interfaces**: Web and CLI interfaces for interaction

Let's explore each component in detail.

## Component 1: ChromaDB Vector Database

ChromaDB is an open-source embedding database designed for building AI applications with semantic search capabilities. Think of it as a specialized database that stores text alongside vector representations (embeddings) that capture semantic meaning.

### Why vector databases?

Traditional keyword search fails with semantic queries:

* **Query**: "How do I cache data for better performance?"
* **Keyword match**: Looks for exact words like "cache", "data", "performance"
* **Semantic match**: Understands concepts like caching, Redis, performance optimization, CDNs

Vector databases solve this by:

1. Converting text to high-dimensional vectors (embeddings) that capture meaning
2. Finding similar content using vector similarity (cosine distance)
3. Returning results ranked by semantic relevance

### ChromaDB Setup on Upsun

We deploy [ChromaDB as a separate application on Upsun](https://docs.upsun.com/add-services/chroma.html). Here's the configuration from our `.upsun/config.yaml`:

```yaml {filename=".upsun/config.yaml"} theme={null}
applications:
  chroma:
    type: "python:3.12"
    source:
      root: "chroma"

    dependencies:
      python3:
        uv: "*"

    hooks:
      build: |
        uv init
        uv add chromadb

    web:
      commands:
        start: "uv run --no-sync chroma run --host 0.0.0.0 --port $PORT --path /app/.db"

    mounts:
      ".db":
        source: "storage"
        source_path: "db"
      ".chroma":
        source: "storage"
        source_path: "chroma"
```

Key aspects of this configuration:

* **Python 3.12**: ChromaDB requires Python 3.11+
* **UV package manager**: Fast, modern Python dependency management
* **Persistent storage**: The `mounts` section ensures embeddings survive deployments
* **Dynamic port**: Upsun automatically assigns the `$PORT` variable

### Document schema

Each document chunk in ChromaDB has this structure:

```python theme={null}
{
    "id": "a1b2c3d4e5f6g7h8",  # MD5 hash (16 chars)
    "document": "Actual text content of the chunk...",
    "embedding": [0.123, -0.456, ...],  # 1536-dimensional vector
    "metadata": {
        # File metadata
        "file_path": "/path/to/documents/repo/file.md",
        "file_name": "redis-caching.md",
        "directory": "posts",

        # Repository metadata
        "repository": "upsun-devcenter",
        "relative_path": "dev/content/posts/redis-caching.md",

        # Frontmatter metadata (from YAML)
        "title": "Optimizing Performance with Redis Caching",
        "description": "Learn how to implement Redis caching...",
        "date": "2024-01-01",
        "author": "Platform Team",
        "tags": "performance,redis,caching",

        # Chunk metadata
        "chunk_index": 0,
        "total_chunks": 3,
        "chunk_token_count": 1200,

        # Ingestion metadata
        "ingestion_timestamp": "2024-01-15T10:30:00"
    }
}
```

This rich metadata allows for adding criterias when querying the database:

* **Filtering**: "Only search documentation, not blog posts"
* **Attribution**: "This content came from article X"
* **Recency**: "Prioritize recently updated content"

## Component 2: Document ingestion system

The ingestion system is responsible for keeping ChromaDB synchronized with our Git repositories that hold most of our technical content (documentation, the devcenter, blogs). It runs daily via an Upsun cron job and processes markdown files with intelligent chunking.

### The ingestion flow

```mermaid theme={null}
graph LR
    A[Cron Trigger<br/>3 AM UTC] --> B[Clone/Pull<br/>Git Repos]
    B --> C[Detect<br/>Changed Files]
    C --> D[Extract<br/>Frontmatter]
    D --> E[Chunk Text<br/>1500 tokens]
    E --> F[Generate<br/>Embeddings]
    F --> G[Store in<br/>ChromaDB]
    G --> H[Save State]

    style A fill:#D0F302,stroke:#000,color:#000
    style B fill:#fff,stroke:#000,color:#000
    style C fill:#fff,stroke:#000,color:#000
    style D fill:#fff,stroke:#000,color:#000
    style E fill:#fff,stroke:#000,color:#000
    style F fill:#6046FF,stroke:#000,color:#fff
    style G fill:#6046FF,stroke:#000,color:#fff
    style H fill:#D0F302,stroke:#000,color:#000
```

### SSH authentication for private repositories

One challenge was securely accessing private GitHub repositories. We solved this with SSH key authentication:

```python {filename="ingest.py"} theme={null}
class GitRepositoryManager:
    def setup_ssh_key_file(self) -> bool:
        """Create temporary SSH key file from environment variable."""
        key_content = os.getenv("GITHUB_KEY").strip()
        key_content = key_content.replace('\\n', '\n')

        # Validate BEGIN/END format
        if not (key_content.startswith('-----BEGIN') and
                key_content.endswith('-----')):
            return False

        # Create temporary file with proper permissions (0400)
        with tempfile.NamedTemporaryFile(mode='w', delete=False) as temp_file:
            temp_file.write(key_content)
            self.temp_key_file = temp_file.name

        os.chmod(self.temp_key_file, stat.S_IRUSR)
        return True

    def clone_or_update_repo(self, repo_config: RepositoryConfig):
        """Clone or pull repository with SSH authentication."""
        git_env = os.environ.copy()
        if self.temp_key_file:
            ssh_command = f'ssh -i {self.temp_key_file} -o StrictHostKeyChecking=no'
            git_env['GIT_SSH_COMMAND'] = ssh_command

        if repo_path.exists():
            # Pull updates and track changes
            repo = git.Repo(repo_path)
            old_commit = repo.head.commit.hexsha

            with repo.git.custom_environment(**git_env):
                origin = repo.remotes.origin
                origin.pull()

            new_commit = repo.head.commit.hexsha
            changed_files = self._get_changed_files(repo, old_commit, new_commit)
        else:
            # Clone new repository
            repo = git.Repo.clone_from(repo_config.url, repo_path, env=git_env)
```

The SSH key is stored as an environment variable in Upsun and the Git commands use custom environment to specify SSH key.
The script tracks commit hashes to detect changes and make sure we are only ingesting new content.

### Intelligent text chunking

Not all text chunks are created equal. We use a token-aware chunking strategy that balances context preservation with embedding model limits:

```python {filename="ingest.py"} theme={null}
class DocumentProcessor:
    def __init__(self, chunk_size: int = 1500, chunk_overlap: int = 200):
        self.chunk_size = chunk_size  # tokens
        self.chunk_overlap = chunk_overlap  # tokens
        self.tokenizer = tiktoken.get_encoding("cl100k_base")

    def chunk_text(self, text: str, metadata: Dict, file_path: Path) -> List[DocumentChunk]:
        """Split text into overlapping chunks optimized for embeddings."""
        # Tokenize entire document
        tokens = self.tokenizer.encode(text)

        # If shorter than chunk_size, return single chunk
        if len(tokens) <= self.chunk_size:
            return [self._create_single_chunk(text, tokens, metadata, file_path)]

        chunks = []
        chunk_index = 0

        # Create sliding window chunks with overlap
        for start in range(0, len(tokens), self.chunk_size - self.chunk_overlap):
            end = min(start + self.chunk_size, len(tokens))
            chunk_tokens = tokens[start:end]
            chunk_text = self.tokenizer.decode(chunk_tokens)

            # Skip very small end chunks (< 100 tokens)
            if len(chunk_tokens) < 100:
                break

            chunk_id = self._generate_chunk_id(file_path, chunk_index, chunk_text)

            chunks.append(DocumentChunk(
                content=chunk_text,
                metadata={
                    **metadata,
                    'chunk_index': chunk_index,
                    'chunk_token_count': len(chunk_tokens),
                    'chunk_start_token': start,
                    'chunk_end_token': end
                },
                chunk_id=chunk_id,
                file_path=str(file_path),
                chunk_index=chunk_index
            ))

            chunk_index += 1

        return chunks
```

**Chunking strategy explained**:

* **Chunk size: 1500 tokens** (\~6000 characters)
  * Large enough to preserve context
  * Small enough for embedding model limits
  * Roughly 2-3 paragraphs of technical content

* **Overlap: 200 tokens** (\~800 characters)
  * Ensures concepts split across chunks remain findable
  * Provides context continuity
  * Helps with concepts mentioned near chunk boundaries

* **Token encoding: `cl100k_base`**
  * Same tokenizer used by GPT-3.5 and GPT-4
  * Ensures accurate token counting
  * Prevents embedding model errors

### Incremental updates

Efficiency matters. We only process files that have changed:

```python {filename="ingest.py"} theme={null}
class ChromaDBManager:
    def replace_file_chunks(self, file_path: str, chunks: List[DocumentChunk]) -> bool:
        """Replace all chunks for a file: delete old, add new."""
        # Step 1: Query for existing chunks
        results = self.collection.query(
            query_texts=["dummy"],
            n_results=1000,
            where={"file_path": file_path},
            include=["metadatas"]
        )

        # Step 2: Delete old chunks
        if results["ids"]:
            self.collection.delete(ids=results["ids"][0])

        # Step 3: Add new chunks with embeddings
        self.collection.upsert(
            documents=[chunk.content for chunk in chunks],
            metadatas=[self._prepare_metadata(chunk.metadata) for chunk in chunks],
            ids=[chunk.chunk_id for chunk in chunks]
        )

        return True
```

This approach queries ChromaDB for existing chunks from the file and deletes old chunks in a single operation. Then adds new chunks with fresh embeddings and tracks the state in `repo_state.json` to skip unchanged files

## Component 3: RAG (Retrieval-Augmented Generation)

RAG is the secret sauce that makes our agent domain-aware. Instead of relying solely on the model's training data, we dynamically retrieve relevant information from our vector database.

### How RAG Works

```mermaid theme={null}
graph LR
    A[User Query:<br/>'Redis caching'] --> B[Generate<br/>Keywords]
    B --> C[Create<br/>Embeddings]
    C --> VRP

    subgraph VRP[Vector Retrieval Pipeline]
        D[Vector<br/>Similarity Search]
        E[Rank by<br/>Relevance]
        F[Format<br/>as Context]
        D --> E
        E --> F
    end

    F --> G[Agent Response]

    style A fill:#D0F302,stroke:#000,color:#000
    style B fill:#fff,stroke:#000,color:#000
    style C fill:#6046FF,stroke:#000,color:#fff
    style D fill:#6046FF,stroke:#000,color:#fff
    style E fill:#fff,stroke:#000,color:#000
    style F fill:#D0F302,stroke:#000,color:#000
    style G fill:#D0F302,stroke:#000,color:#000
```

### Two-Stage RAG Implementation

Our RAG system uses a two-stage approach:

**Stage 1: Keyword Generation**
Instead of searching with the raw user query, we use OpenAI to generate optimal search keywords:

```python {filename="chromadb_client.py"} theme={null}
def _generate_keywords(self, user_request: str) -> List[str]:
    """Use OpenAI to generate optimal search keywords."""
    response = self.openai_client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[
            {
                "role": "system",
                "content": """Generate 3-5 specific search keywords for finding
                relevant documentation. Focus on technical terms and concepts."""
            },
            {
                "role": "user",
                "content": user_request
            }
        ]
    )

    # Parse keywords from response
    keywords = self._parse_keywords(response.choices[0].message.content)
    return keywords
```

For example, the query "How do I cache data?" might generate keywords:

* `redis caching`
* `upsun cache configuration`
* `performance optimization`
* `cache eviction policies`

This improves retrieval quality significantly compared to searching with the raw query.

**Stage 2: Vector Retrieval**
For each keyword, we query ChromaDB:

```python {filename="chromadb_client.py"} theme={null}
def _retrieve_chunks(self, keyword: str, n_results: int) -> List[Dict]:
    """Query ChromaDB with keyword embedding."""
    results = self.collection.query(
        query_texts=[keyword],
        n_results=n_results,
        include=["documents", "metadatas", "distances"]
    )

    return self._process_results(results)
```

Under the hood, ChromaDB:

1. Creates an embedding for the keyword using OpenAI's `text-embedding-3-small`
2. Computes cosine similarity against all document embeddings
3. Returns the top N most similar chunks
4. Ranks results by similarity score (distance)

### Formatting retrieved context

Raw chunks aren't usable directly. We format them into structured markdown that the agent can understand:

```python {filename="utils.py"} theme={null}
def _format_as_markdown(self, results: List[Dict]) -> str:
    """Format retrieved chunks as structured markdown."""
    output = "## Retrieved Upsun Content\n\n"

    for result in results:
        output += f"### {result['metadata']['title']}\n"
        output += f"**Source**: {result['metadata']['repository']}\n"
        output += f"**File**: {result['metadata']['file_name']}\n\n"
        output += f"{result['document']}\n\n"
        output += "---\n\n"

    return output
```

This gives the agent where the information comes from (metadata), the actual content and a clear separation between sources.

### RAG in action: An example

Let's trace a real query through the system:

**User Query**: "Write an article about Redis caching on Upsun"

**Generated Keywords**:

```python theme={null}
[
    "redis cache configuration",
    "upsun redis service",
    "cache performance optimization",
    "redis best practices"
]
```

**Retrieved Chunks** (top 6 across all keywords):

1. Redis service configuration from platformsh-docs
2. Caching strategies article from devcenter
3. Redis performance tuning from blog post
4. Cache eviction policies documentation
5. Redis connection pooling example
6. Real-world Redis implementation case study

**Formatted Context** (sent to agent):

```markdown theme={null}
## Retrieved Upsun Content

### Configuring Redis as a service
**Source**: platformsh-docs
**File**: add-services/redis.md

To add Redis to your Upsun project, add the following to your
`.upsun/config.yaml` file:

[... content continues ...]

---

### Performance optimization with caching
**Source**: upsun-devcenter
**File**: posts/caching-strategies.md

Caching is one of the most effective ways to improve application
performance...

[... content continues ...]
```

This context is now combined with static knowledge and the user's request to generate the final response.

## Component 4: Static knowledge base

While RAG provides dynamic and relevant content, static knowledge ensures consistency and brand alignment. Our static knowledge lives in two directories:

### `/knowledge/` Directory

Contains foundational content injected into every agent interaction. The list of injected files can be customized per agent as they all don't need the same knowledge.

Here are some examples from our AI-Brain internal project:

* `upsun_writing_guidelines.md`: Tone, style, voice
* `upsun_technical_context.md`: Platform capabilities, terminology
* `content_templates.md`: Article structures, formats
* `personas.md`: Target audience personas
* `icp.md`: Ideal customer profile
* `messaging_positioning.md`: Value propositions, key messages
* `talking_points.md`: Common themes and narratives

### `/rules/` Directory

Contains operational rules and constraints:

* `content-creator.md`: Role definition and responsibilities
* `format.md`: Formatting requirements
* `styleguide.md`: Language conventions
* `upsun.md`: Additional rules and guidelines about the brand

### Loading static knowledge

The agent loads this content once at initialization:

```python {filename="utils.py"} theme={null}
def _load_knowledge_base() -> str:
    """Load all static knowledge files from knowledge/ directory."""
    knowledge_path = Path(__file__).parent.parent.parent.parent.parent / "knowledge"
    knowledge_content = ""

    knowledge_files = [
        "upsun_writing_guidelines.md",
        "upsun_technical_context.md",
        "content_templates.md",
        "personas.md",
        "icp.md",
        "messaging_positioning.md",
        "talking_points.md"
    ]

    for file_name in knowledge_files:
        file_path = knowledge_path / file_name
        if file_path.exists():
            with open(file_path, 'r', encoding='utf-8') as f:
                knowledge_content += f"## {file_name}\n\n{f.read()}\n\n"

    return knowledge_content
```

This content (\~50KB) is loaded once and reused across all queries, providing consistency, efficiency and authority. Every response follows the same guidelines and the agent "knows" company standards inherently.

## Component 5: Google ADK Agent

Now we bring everything together with Google's Agent Development Kit (ADK), a framework for building production-ready AI agents.

### Why did we choose Google ADK?

Google ADK stood out for several compelling reasons. First, it's **model-agnostic**, meaning we can work with OpenAI, Anthropic, Google, or even local models without changing our core implementation. The framework excels at **tool integration**, making it trivial to add custom capabilities like our RAG research function.

For complex workflows, ADK supports **multi-agent orchestration**, allowing multiple specialized agents to collaborate seamlessly. We also appreciated the **deployment flexibility**. The same agent code can be deployed via CLI, web UI, or API without modification. Finally, ADK handles **conversation management** automatically, taking care of state, history, and context tracking so we can focus on building great agent experiences rather than infrastructure.

<Note>
  Google ADK limits the use of the Google's `web_search` tool to `gemini` models. Fortunately a lot of other tools like `tavily` can replace this and work with any model.
</Note>

### Agent structure

Here's the core agent definition:

```python {filename="devcenter_writer/agent.py"} theme={null}
from google.adk.agents import Agent
from google.adk.models.lite_llm import LiteLlm

# Step 1: Load static knowledge
knowledge_base = _load_knowledge_base()

# Step 2: Initialize ChromaDB connection
chroma_client = create_chromadb_client(
    collection_name="upsun_documents"
)

# Step 3: Create query engine for RAG
query_engine = create_query_engine(chroma_client)

# Step 4: Define RAG research tool
def research_tool(user_request: str) -> str:
    """Research tool that uses RAG to retrieve relevant content."""
    if not query_engine:
        return "## ChromaDB not available\n\nRAG functionality unavailable."

    return query_engine.research_topic(user_request, max_results=6)

# Step 5: Compose instruction with static knowledge
instruction = f"""You are the Dev Center Writer, a specialized technical writing agent
for the Upsun marketing team with advanced RAG capabilities.

KNOWLEDGE BASE:
{knowledge_base}

RAG CAPABILITIES:
You have access to a ChromaDB vector database containing Upsun blog posts, articles,
and documentation. You can use the research_tool to:
1. Generate relevant research keywords using OpenAI based on user requests
2. Query the ChromaDB vector database for related Upsun content
3. Retrieve and integrate relevant information into your responses

Always use the research_tool when you need to find specific information about Upsun
features, best practices, or existing content.

Your primary responsibilities:
1. Create comprehensive technical tutorials for the Upsun DevCenter
2. Write clear, step-by-step implementation guides
3. Develop best practices documentation
4. Ensure content follows Upsun's technical writing standards

When writing content:
- Use retrieved documentation to ensure technical accuracy
- Follow the brand voice and guidelines from your knowledge base
- Structure content according to provided templates
- Include practical code examples and real-world scenarios
- Always validate technical details against retrieved documentation
"""

# Step 6: Create the agent
root_agent = Agent(
    name="devcenter_writer",
    model=LiteLlm(model="anthropic/claude-sonnet-4-5-20250929"),
    description="Specialized technical writing agent for creating Upsun Dev Center content",
    instruction=instruction,
    tools=[research_tool]  # RAG tool available to agent
)
```

And yes, some parts of this article were written with that agent.

<Note>
  Based on our testing, Claude Sonnet always produce the best results but your experience may vary greatly from one use-case to the other. As we use `LiteLLM` as an abstraction, it is straightforward to use multiple models based on the agent or even inside one specific agent so models can review and validate each other.
</Note>

### The power of context building

Notice what we've achieved here. The agent has:

1. **Static Context** (in `instruction`):
   * 50KB of brand guidelines, templates, personas
   * Loaded once, available for every query
   * Ensures consistency across all responses

2. **Dynamic Context** (via `research_tool`):
   * Retrieves relevant docs on-demand
   * Only fetches what's needed for each query
   * Provides fresh, accurate technical information

3. **Tool Access** (via `tools` parameter):
   * Can call `research_tool` when needed
   * Agent decides when to retrieve additional context
   * Autonomous research capability

This separation of concerns is what makes the system maintainable and scalable.

### Agent execution flow

When a user makes a request, here's what happens:

```mermaid theme={null}
graph TD
    A[User Request] --> B[ADK Framework]
    B --> C[Agent Receives<br/>Request]
    C --> D{Needs More<br/>Context?}
    D -->|Yes| E[Call research_tool]
    E --> F[Generate Keywords]
    F --> G[Query ChromaDB]
    G --> H[Format Results]
    H --> I[Combine Context]
    D -->|No| I
    I --> J[Generate Response<br/>with Claude]
    J --> K[Return to User]

    style A fill:#D0F302,stroke:#000,color:#000
    style E fill:#6046FF,stroke:#000,color:#fff
    style F fill:#fff,stroke:#000,color:#000
    style G fill:#6046FF,stroke:#000,color:#fff
    style H fill:#fff,stroke:#000,color:#000
    style I fill:#D0F302,stroke:#000,color:#000
    style J fill:#6046FF,stroke:#000,color:#fff
    style K fill:#D0F302,stroke:#000,color:#000
```

The agent autonomously decides when to use the research tool based on the user's request and its available context.

## Deploying on Upsun: Multi-application architecture

Here's where Upsun's multi-application support shines. We deploy our system as two independent applications that communicate internally.

### Why multi-application?

1. **Separation of concerns**: ChromaDB and the agent have different resource needs
2. **Independent scaling**: Scale database separately from application
3. **Service isolation**: ChromaDB failures don't affect agent (and vice versa)
4. **Clear boundaries**: Each service has its own configuration and storage

### Upsun Configuration

Here's our complete `.upsun/config.yaml`:

```yaml theme={null}
applications:
  # Main AI Agent Application
  app:
    source:
      root: "/"

    type: "python:3.12"

    # UV package manager for fast installs
    dependencies:
      python3:
        uv: "*"

    # Relationship to ChromaDB application
    relationships:
      chroma: chroma:http

    # Build process using UV
    hooks:
      build: |
        # Sync dependencies from uv.lock
        uv sync --frozen

    # Persistent storage for Git repositories
    mounts:
      'documents':
        source: storage
        source_path: documents

    # Daily document ingestion cron job
    crons:
      ingest:
        spec: '0 3 * * *'  # 3 AM UTC daily
        commands:
          start: uv run python ingest_documents.py
          stop: killall python
        shutdown_timeout: 30

    # Web server configuration
    web:
      commands:
        start: "uv run --no-sync adk web src/ai_brain/agents --port=8888"

    # Environment variables
    variables:
      env:
        UV_CACHE_DIR: "/tmp/uv-cache"
        PYTHONPATH: "."

  # ChromaDB Vector Database Application
  chroma:
    type: "python:3.12"

    source:
      root: "chroma"

    dependencies:
      python3:
        uv: "*"

    hooks:
      build: |
        uv init
        uv add chromadb

    web:
      commands:
        start: "uv run --no-sync chroma run --host 0.0.0.0 --port $PORT --path /app/.db"

    # Persistent storage for ChromaDB data
    mounts:
      ".db":
        source: "storage"
        source_path: "db"
      ".chroma":
        source: "storage"
        source_path: "chroma"

    variables:
      env:
        UV_CACHE_DIR: "/tmp/uv-cache"
        PYTHONPATH: "."

# Route configuration
routes:
  "https://{default}/":
    type: upstream
    upstream: "app:http"
```

### Key configuration insights

**1. Application Relationships**

```yaml theme={null}
relationships:
  chroma: chroma:http
```

This creates an internal network connection between applications. Upsun automatically provides:

* `CHROMA_HOST`: Internal hostname for ChromaDB
* `CHROMA_PORT`: Port number for ChromaDB
* No external network calls required
* Fast, secure inter-application communication

**2. Persistent Storage (Mounts)**

```yaml theme={null}
mounts:
  'documents':
    source: storage
    source_path: documents
```

Mounts persist data across deployments:

* `documents/`: Cloned Git repositories
* `.db/` and `.chroma/`: ChromaDB data and indexes

Without mounts, every deployment would re-clone repositories and rebuild embeddings, expensive and slow.

**3. Cron Jobs for Automation**

```yaml theme={null}
crons:
  ingest:
    spec: '0 3 * * *'  # 3 AM UTC daily
    commands:
      start: uv run python ingest_documents.py
      stop: killall python
    shutdown_timeout: 30
```

Automated daily ingestion:

* Runs at 3 AM UTC (low-traffic window)
* Pulls latest changes from Git
* Updates ChromaDB incrementally
* Graceful shutdown with timeout

**4. UV Package Manager**

```yaml theme={null}
dependencies:
  python3:
    uv: "*"

hooks:
  build: |
    uv sync --frozen
```

You can find more information on [UV](https://github.com/astral-sh/uv) on [our article](/posts/insights/why-python-developers-should-switch-to-uv). We use the following arguments:

* **`--frozen` flag**: Fails if dependencies don't match lockfile
* **`--no-sync` flag**: Prevents write attempts at runtime

**5. Environment Variables**

Set via `upsun variable:create`:

```bash theme={null}
# OpenAI API key for embeddings
upsun variable:create --level environment --name OPENAI_API_KEY --value "sk-..."

# Anthropic API key for embeddings and LLM
upsun variable:create --level environment --name ANTHROPIC_API_KEY --value "..."

# GitHub SSH private key for repository access
upsun variable:create --level environment --name GITHUB_KEY --value "-----BEGIN OPENSSH PRIVATE KEY-----
...
-----END OPENSSH PRIVATE KEY-----"
```

These are automatically available to both applications and remain secure.

## Performance and cost

<img alt="Article Generation" />

Real-world performance from our production system:

### Ingestion performance

* **Documents Processed**: 243 files
* **Total Chunks Created**: \~1,200 chunks
* **Processing Time**: 8-15 minutes (depends on OpenAI API latency)
* **Incremental Updates**: Only changed files processed (typically 1-5 files/day)
* **Storage Size**: \~5-10 MB for embeddings
* **Cost**: \~\$0.10-0.20 per full ingestion (OpenAI embedding costs)

### RAG Query Performance

* **Keyword Generation**: \~500ms (OpenAI API)
* **Vector Similarity Search**: \~50-100ms per keyword (ChromaDB)
* **Total Retrieval Time**: \~1-2 seconds for 3 keywords
* **Results Returned**: 6 most relevant chunks (\~3,000-5,000 tokens)
* **Cost**: \~\$0.01 per query (keyword generation + retrieval)

### Agent response performance

* **Static Knowledge Loading**: \~50ms (cached after first load)
* **RAG Retrieval**: \~1-2 seconds
* **LLM Generation**: \~5-15 seconds (depends on output length)
* **Total Response Time**: \~8-20 seconds for complete article
* **Cost**: \~\$0.05-0.15 per article (depends on length)

These are acceptable performance characteristics for an internal tool.

If you need faster responses, consider several optimization strategies: caching frequent queries to avoid redundant processing, pre-generating embeddings for common topics that are queried regularly, using faster models like GPT-3.5-turbo for keyword generation while keeping higher-quality models for final content generation, and implementing streaming responses to provide incremental results as they're generated rather than waiting for complete output.

## Best practices and lessons learned

After building and deploying this system, here are our key takeaways:

### Context building beats prompt engineering

The most important lesson we learned is to separate concerns rather than cramming everything into prompts. **Static context** like brand guidelines and standards should be injected once in agent instructions, while **dynamic context** from documentation and examples should be retrieved on-demand via RAG. This clear separation scales to unlimited documentation without hitting token limits, and makes the system far more maintainable than traditional prompt engineering approaches.

### Chunking strategy matters

Through experimentation, we found that chunk size dramatically affects retrieval quality. Chunks that are **too small** (500 tokens) fragment concepts and produce poor results, while chunks that are **too large** (3000 tokens) lose precision and retrieve irrelevant sections. Our **sweet spot of 1500 tokens** balances context preservation with search precision. Equally critical is the 200-token overlap between chunks, which prevents concepts split across boundaries from being lost during retrieval.

### Two-stage RAG improves quality

While direct query-to-embedding search works, adding keyword generation as a first stage significantly improves results. Using a language model to generate 3-5 targeted search keywords from the user's request improves recall by finding content even with different phrasing, enables better semantic matching since keywords capture intent more precisely, and produces more focused results through technical terminology.

### Rich metadata pays dividends

Investing in rich metadata during ingestion enables powerful filtering capabilities later. You can search only official documentation versus blog posts, prioritize recently updated content, filter by content type like tutorials or guides, or query by tags for specific topics. Don't skimp on metadata during ingestion—it's one of the highest-value investments you can make in your RAG system.

### Incremental processing saves resources

Full re-ingestion of our 243 documents takes 15-20 minutes and costs \$0.10-0.20 in API fees. By implementing incremental updates that only process changed files and track state with Git commit hashes, we typically process just 1-5 files per day, saving 95% of processing time and costs. This makes daily updates practical and economical.

### Monitor and iterate

Not all embeddings perform equally well. Continuously monitor similarity scores to understand retrieval relevance, gather user feedback on whether the agent finds the right content, and track false negatives where queries return no useful results. Use this feedback loop to refine your chunking strategy, adjust metadata, and improve keyword generation prompts.

### Static knowledge ensures consistency

Without static knowledge injected into the agent's instructions, outputs vary unpredictably—writing style shifts between responses, brand guidelines get missed, target audience considerations are forgotten, and formatting becomes inconsistent. Static knowledge provides the "personality" and standards that make every output consistent and on-brand, regardless of what dynamic content gets retrieved.

## The future of internal AI agents

Building AI-Brain taught us that **successful AI agents aren't about having the best model. They are about building the best context**.

By separating static knowledge (brand voice, guidelines, standards) from dynamic retrieval (technical documentation, code examples), we created an agent that **writes like our team** by following brand guidelines consistently, **stays technically accurate** by retrieving current documentation on demand, **scales effortlessly** to handle unlimited documentation without hitting token limits, and **remains maintainable** because knowledge files can be updated independently without touching agent code.

This architecture adapts to any domain. For **customer support**, combine static response guidelines with dynamic knowledge base retrieval. For **code generation**, pair static coding patterns with dynamic code search across your repositories. For **data analysis**, merge static methodologies with dynamic data retrieval. For **documentation**, unite static writing standards with dynamic content search across your docs.

The tools are remarkably accessible. **Google ADK** provides a free, open-source agent framework that handles orchestration. **ChromaDB** offers a free, open-source vector database for semantic search. **OpenAI** and **Claude** operate on pay-per-use models with no infrastructure requirements. **Upsun** delivers a managed platform that eliminates DevOps complexity entirely.

Your next steps:

1. **Identify a use case**: What internal task could benefit from AI assistance?
2. **Gather static knowledge**: What guidelines should the agent always follow?
3. **Identify dynamic sources**: What documentation should be searchable?
4. **Start small**: Build a prototype with 10-20 documents
5. **Iterate**: Add more documents, refine prompts, improve retrieval
6. **Deploy**: Use Upsun's cloud application platform for production

***

**Resources**:

* [Google ADK Documentation](https://google.github.io/adk-docs/)
* [ChromaDB Documentation](https://docs.trychroma.com/)
* [OpenAI Embeddings Guide](https://platform.openai.com/docs/guides/embeddings)
* [Upsun Multi-App Guide](https://docs.upsun.com/create-apps/multi-app.html)
* [UV Package Manager](https://github.com/astral-sh/uv)

**Questions?** Join the [Upsun Community Forum](https://community.upsun.com/).


# Installing CiviCRM with Drupal 11 on Upsun
Source: https://developer.upsun.com/posts/hands-on/civicrm-drupal-11-on-upsun

Learn how to install CiviCRM with Drupal 11 on Upsun, from config.yml and databases to cron, caching, extensions and Skvare’s best-practice template.


<PostMeta />

CiviCRM is a popular open source CRM that integrates with a number of Content Management Systems including Drupal, Wordpress, and Joomla, or can be installed standalone. This guide describes how to set up and install CiviCRM on Drupal 11 using Upsun’s infrastructure.

## **What this guide covers**

This article shows how to:\
•	Install CiviCRM on Drupal 11 using a ready-to-use composer template\
•	Deploy the project on Upsun with a production-ready configuration\
•	Apply best practices developed from running CiviCRM sites in production over many years

By the end, you’ll have a working CiviCRM installation running on Upsun in just a few minutes.

## **Why CiviCRM + Drupal on Upsun**

After working with CiviCRM and Drupal across many different hosting setups, I’ve found Upsun to be a particularly strong fit for running CiviCRM in production.

## **About the CiviCRM Drupal template**

You can [view the template here](https://github.com/Skvare/drupal-civicrm-upsun-template/). This template is derived from an Upsun Drupal 11 starting template, and if you’ve installed Drupal on Upsun before, then you will have no problem getting started. If you are new to Upsun, visit the [documentation](https://docs.upsun.com/get-started/stacks/drupal.html). There is an upsun [config.yaml](https://github.com/Skvare/drupal-civicrm-upsun-template/blob/main/.upsun/config.yaml) included in this template, which expands on the default with best practices and additions particular to CiviCRM.

You can clone this repository, add the git remote to your Upsun project code repository, push, and it will deploy and create the environment automatically.

## **Before you begin**

You must update 3 environment variables in the [Upsun Variables UI](https://docs.upsun.com/development/variables.html) before installation of CiviCRM. The variables are: `CIVICRM_SITE_KEY`, `CIVICRM_CRED_KEY` and `CIVICRM_SIGN_KEY`.
Refer to the [CiviCRM documentation](https://docs.civicrm.org/sysadmin/en/latest/setup/secret-keys/) for how to generate unique keys for your installation.\
![][image1]

## **Installing Drupal and enabling CiviCRM**

Go to your project’s domain, and [install Drupal](https://www.drupal.org/docs/getting-started/installing-drupal) per normal. Proper [Drupal settings files](https://github.com/Skvare/drupal-civicrm-upsun-template/blob/main/web/sites/default/settings.php) are already in place, so it will install into the database setup by Upsun that is defined in the config.yml automatically.

Once Drupal is installed, visit the “Extend” page at `/admin/modules` to install modules.
Find “CiviCRM”, check the box, and click the “Install” button.
A proper [civicrm.settings.php](https://github.com/Skvare/drupal-civicrm-upsun-template/blob/main/web/sites/default/civicrm.settings.php) is already included in this template, and everything will work automatically. ![][image2]\
Once CiviCRM is installed, install the CiviCRM Drush module.
The provided [Upsun config.yml](https://github.com/Skvare/drupal-civicrm-upsun-template/blob/main/.upsun/config.yaml#L207) executes drush commands provided by this module to execute CiviCRM scheduled jobs and send mailings.
Create an ‘Administrator’ user with the username “Cron User” that will be used when the drush command is executed.

A submodule, “CiviCRM Theme” installs automatically with CiviCRM. This allows setting which Drupal theme is used for CiviCRM administration pages. Visit /admin/appearance and try using Claro for good results.

![][image3]

## **That’s it!**

CiviCRM is now installed on a high quality infrastructure, with a professional configuration in less than 5 minutes. Upsun with this template is literally that easy. You can visit it at /civicrm and see the CiviCRM menu.

Feel free to install the other CiviCRM integration modules to make the most out of your installation.

Note that at the time of this writing there are two patches installed by composer for CiviCRM in this template. Those will be removed in the near future when they are merged. For years CiviCRM would not allow installation with a pre-existing civicrm.settings.php in the codebase, and these patches remove that condition. The code base file system is read-only on Upsun, so it is not possible for the installation to create this file. Not to worry, this file provided has everything you need.

## **Upsun configuration details for CiviCRM**

If you’re interested in details of the Upsun config.yml specifically for CiviCRM and additional features, keep reading!! I’ll describe this and teach how to add CiviCRM extensions with Skvare’s [CiviCRM extension composer plugin](https://github.com/skvare/civicrm-extension-plugin/).

## **Databases**

CiviCRM can be installed into the same database as Drupal, or its own separate database. We install CiviCRM into its own database to keep the data from the applications separate. All features of CiviCRM and the Drupal integration modules work the same both ways.\
We’re using the latest version of Maria DB, 11.8

The database service is [defined](https://github.com/Skvare/drupal-civicrm-upsun-template/blob/main/.upsun/config.yaml#L239) as below:

```yaml {filename=".upsun/config.yaml",base_url="https://github.com/Skvare/drupal-civicrm-upsun-template/blob/main/"} theme={null}
services:  
  db:
    type: mariadb:11.8
    configuration:
      properties:        
        max_allowed_packet: 64
        max_heap_table_size: 32
        table_definition_cache: 2000
        table_open_cache: 2000
        default_charset: utf8mb4
        default_collation: utf8mb4_unicode_ci
        innodb_adaptive_hash_index: 0
        optimizer_use_condition_selectivity: 4
      schemas:
        - main
        - civicrm
      endpoints:        
        mysql:
          default_schema: main
          privileges:
            main: admin
            civicrm: admin
        civicrm:
          default_schema: civicrm
          privileges:
            main: admin
            civicrm: admin
```

This configures a database “mysql” for Drupal, and one “civicrm” for CiviCRM. We set the some sane database defaults, including the charset and collation to industry standard.

Then the relationships for the application to the database [defined](https://github.com/Skvare/drupal-civicrm-upsun-template/blob/main/.upsun/config.yaml#L55C1-L57C30) as:

```yaml {filename=".upsun/config.yaml",base_url="https://github.com/Skvare/drupal-civicrm-upsun-template/blob/main/"} theme={null}
    relationships:
        database: 'db:mysql'
        civicrm: 'db:civicrm'
```

## **Nginx / PHP**

We like a little more [sophisticated configuration](https://github.com/Skvare/drupal-civicrm-upsun-template/blob/main/.upsun/config.yaml#L9) for PHP than default examples have.
Upsun has the capability of using [Composable Images](https://docs.upsun.com/create-apps/app-reference/composable-image.html).
This allows installation of over 80K different software [NixOS packages](https://search.nixos.org/packages) and initial setup this way gives maximum future potential.

```yaml {filename=".upsun/config.yaml",base_url="https://github.com/Skvare/drupal-civicrm-upsun-template/blob/main/"} theme={null}
applications:
  drupal:
    type: 'composable:25.05'
    stack:
      - php@8.3:
          extensions:
            - opcache
            - redis
            - sodium
            - apcu
            - blackfire
            - imagick
      - gnupg
      - patch
      - duplicity
      - python3
      - upsun
      - python3Packages.numpy
      - python3Packages.boto3
      - php83Extensions.mbstring
      - php83Extensions.iconv
      - php83Extensions.redis
      - php83Extensions.opcache
      - php83Extensions.sodium
      - php83Extensions.apcu
      - php83Extensions.blackfire
      - php83Extensions.imagick
```

Doing this we must [specify the composer installation command](https://github.com/Skvare/drupal-civicrm-upsun-template/blob/main/.upsun/config.yaml#L110) during the build phase of a deployment.

```yaml {filename=".upsun/config.yaml",base_url="https://github.com/Skvare/drupal-civicrm-upsun-template/blob/main/"} theme={null}
    hooks:
        # The build hook runs after Composer to finish preparing up your code.
        # No services are available but the disk is writeable.
        build: |
            set -e
            #Run Composer install
            composer install --no-dev --prefer-dist --no-progress --no-interaction
```

Nginx configuration is standard per Drupal except we’ve added a couple of items specifically for CiviCRM.\
Certain directories are blocked from direct web access

```yaml {filename=".upsun/config.yaml",base_url="https://github.com/Skvare/drupal-civicrm-upsun-template/blob/main/"} theme={null}
'^/sites/default/files/civicrm/(ConfigAndLog|upload|templates_c|custom)':
  allow: false
```

We allow access to the CiviCRM extensions directory. The popular extension CiviCRM mosaico requires web access to some html templates for its default templates. You can remove this snippet if you do not plan on using Mosaico

```yaml {filename=".upsun/config.yaml",base_url="https://github.com/Skvare/drupal-civicrm-upsun-template/blob/main/"} theme={null}
        locations:
            # All requests not otherwise specified follow these rules.
            # Allow Mosaico HTML templates to be loaded.
            '/sites/default/civicrm/extensions':
                root: 'web/sites/default/civicrm/extensions'
                allow: true
                scripts: false
                expires: 15m
                passthru: false
```

## Template cache file mounts

Both Drupal and CiviCRM have separate directories where compile PHP template file caches are stored. By default the locations of these directories are inside the standard public files directory at ./web/sites/default/files/php and ./web/sites/default/files/civicrm/templates\_c

It is better to not have any PHP files whatsoever in the public files directory, so we change the locations of these directories to ./web/sites/default/php and ./web/sites/default/civicrm/templates\_c

In the Upsun [config.yml](https://github.com/Skvare/drupal-civicrm-upsun-template/blob/main/.upsun/config.yaml#L79) we configure 2 separate public file mounts for these locations

```yaml {filename=".upsun/config.yaml",base_url="https://github.com/Skvare/drupal-civicrm-upsun-template/blob/main/"} theme={null}
        '/web/sites/default/civicrm/templates_c':
            source: instance
            source_path: 'templates_c'
        # Drupal php cache
        '/web/sites/default/php':
            source: instance
            source_path: 'php'
```

We’ve configured the [Drupal settings file](https://github.com/Skvare/drupal-civicrm-upsun-template/blob/main/web/sites/default/settings.upsun.php#L179) and the [CiviCRM settings file](https://github.com/Skvare/drupal-civicrm-upsun-template/blob/main/web/sites/default/civicrm.settings.php#L245) to make the application use them.

## Cron

As mentioned previously, installing the [CiviCRM Drush](https://drupal.org/project/civicrm_drush) module is required for this configuration.\
CiviCRM Drush provides a number of drush commands, including commands to execute CiviCRM API calls from the command line.\
The CiviCRM Drush module requires a Drupal user with necessary permissions for the various actions performed by the commands.\
Create a new Drupal user with username “Cron User”. Give this user “Administrator” role.

In the [config.yaml we define](https://github.com/Skvare/drupal-civicrm-upsun-template/blob/main/.upsun/config.yaml#L200) 3 cron jobs, one to execute all CiviCRM scheduled jobs, executing every 30 minutes.

```yaml {filename=".upsun/config.yaml",base_url="https://github.com/Skvare/drupal-civicrm-upsun-template/blob/main/"} theme={null}
    crons:
      # Run Drupal's cron tasks.
      job_execute:
        spec: '*/30 * * * *'
        commands:
          start: |
                cd web
                drush --name='Cron User' civicrm:api job.execute auth=0 --yes
```

The next executes the Send Mailings scheduled job every 5 minutes. In this way we maximize the efficiency of sending large mailings. CiviCRM supports simultaneous mailing jobs.

```yaml {filename=".upsun/config.yaml",base_url="https://github.com/Skvare/drupal-civicrm-upsun-template/blob/main/"} theme={null}
      job_process_mailing:
        spec: '*/5 * * * *'
        commands:
          start: |
                cd web
                drush --name='Cron User' civicrm:api job.process_mailing auth=0 --yes
```

Finally the standard Drupal cron command, configured here to run hourly

```yaml {filename=".upsun/config.yaml",base_url="https://github.com/Skvare/drupal-civicrm-upsun-template/blob/main/"} theme={null}
      drupal_cron:
        spec: '0 */1 * * *'
        commands:
          start: |
                cd web
                drush cron --yes
```

## Environment Variables

The Drupal and CiviCRM settings files are configured to support some environmental variables that can be set per project or per environment in Upsun.\
In the initial instructions above I specified CIVICRM\_SITE\_KEY, CIVICRM\_CRED\_KEY and CIVICRM\_SIGN\_KEY.

### CiviCRM Caching

This template configured Redis as a caching mechanism. To enable CivICRM’s use of Redis, set CIVICRM\_CACHING\_TYPE with a value of “Redis”. This can be done either in the provided Upsun config.yml or through Upsun’s project or environment variables web pages.

## Adding CiviCRM Extensions

The CiviCRM extension ecosystem does not always support fetching CiviCRM extensions with normal composer require statements. We have developed a composer plugin to help manage extensions by being able to fetch them via .zip file download.\
See [composer.json](https://github.com/Skvare/drupal-civicrm-upsun-template/blob/main/composer.json#L158) for examples as we have bundled common extension in this template.

```json {filename="composer.json"} theme={null}
 "uk.co.vedaconsulting.mosaico": {
     "url": "https://download.civicrm.org/extension/uk.co.vedaconsulting.mosaico/3.8.1752072010/uk.co.vedaconsulting.mosaico-3.8.1752072010.zip"
                },
```

See the [README](https://github.com/skvare/civicrm-extension-plugin/) for full instructions and options.

**Author experience and approach**

As CTO at [Skvare](https://skvare.com/homepage) I’ve been developing Drupal and CiviCRM websites for over 13 years. Over this time I’ve used a wide range of hosting infrastructures, including platforms we’ve maintained ourselves. I’ve found Upsun to be a high-quality, easy-to-use option that is fully compatible with CiviCRM. In this article, I share my experience and a composer template that captures those learnings and best practices, allowing anyone to set up a CiviCRM site in just a few minutes.

As a developer I’ve helped maintain the Drupal integration for CiviCRM Core over the years, including the updates for Drupal 10 and 11.

Skvare maintain several other Drupal modules including [CiviCRM Entity](https://drupal.org/project/civicrm_entity), [CiviCRM Form Builder Blocks](https://drupal.org/project/civicrm_form_builder_blocks), [CiviCRM Drush](https://drupal.org/project/civicrm_drush), and [CiviCRM Reroute Mail](https://drupal.org/project/civicrm_reroute_mail), as well as the [CiviCRM Extension Plugin](https://github.com/skvare/civicrm-extension-plugin/). All of these modules and more are included in this template.

## Need help?

Need help getting setup with CiviCRM Upsun infrastructure? [Contact us](https://skvare.com/contact) now.

[image1]: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAnAAAAD9CAYAAAA8okqMAABG70lEQVR4Xu2dh18Ux+P+f3/G95OqxgpGBRU1thgjoBK7UWwIYsGO2Huw98SGvYO9G3tX7A1779LL3YEVuOe35ercmXIh8Ryf9+v1jruzs7Nze7PLw+xd+H8gRGJMuXmUUkqpdP4/8QceITIhDnhKKaVUBhngiNSIA55SSimVQQY4IjXigKeUUkplkAGOSI044CmllFIZZIAjUiMOeEoppVQGGeCI1IgDnlJKKZVBBjgiNeKAp5RSSmWQAY5IjTjgKaWUUhlkgCNSIw54SimlVAYZ4IjUiAOeUkoplUEGOCI14oCnlFJKZZABjkiNOOAppZRSGWSAI1IjDnhKKaVUBhngiNSIA55SSimVwX89wPWIGSoW/WMKn23B5XyxlBBXxAFPKaWUyuC/GuC6RQ9BZL9BYrEL20d20P413t2G6NAewlZX3hfgDk7qKxb9A8wwPkgSC8lHhjjgKaWUUhn81wJc1/6D0aVvjFjsFluAu7MZ/btN1Zbv3UpRMpQBx2b0QL4Splp3/U35L5Bntga4AnSKWe3QCrCqvz38DQ4bgkLl37j+3bR/rczp0gbJ75SF/GQ0CJ+uLBSiRa8Ebdub5Hvav1FtJyr/fYeT0zsrW834sUUMCpSSqV27YfoVdWfysSAOeEoppVQG/7UA17xTJGKnzRKL3bJ9ZBu0Du+OH9rGYOqh507bcg9NVKLUK/TcmmorUwPc0dOLcDpbjXR27AHOjMYTTmhLpiOTke5QbU5kN8tSIZrMuqAtRYf+aq+gEBc1GI4BLmjILq1cXY/Za3CqS7wbccBTSimlMvivBTiVFp26Ytz038RiF6wzcGqoerRuEN6a09BrrTobZoZh3zglSr1Er+1ptvpqgNuXlYX2cy7aylRWRzsEuHHHtCXT4cnIcAxwXa2zgoUIXXRTW4ppOxNvryxE68jZep1u6mNfe4ALnpiolZ+aFYHo3TmW/cnHgDjgKaWUUhn8VwOcSqvO3cUiF9QZuCbtI9AkPAZDl52CGsD69IpBzC9x2LgzDupDyxs75ih1wrErudD2GbjXd9dj/RP7h+EMl+PRsutAzFM2Gm/uQOuIHvhl0w3bdpX3BTi8vocNEwchetQ4LB8zDAxwciAOeEoppVQG//UAR8iHRBzwlFJKqQwywBGpEQc8pZRSKoMMcERqxAHvDZ6Z0xGl63TF4iSjyzav0nATZcqUx8kMN9sczd6P//uqOFY8z3XZln1mImqVKI4vQ2a7bKOUUuq5DHBEasQB76nX5zTXQoqjLeOSXOr9Fa/Gx6BO65HYeNfksu2vaUKxr4vjVI5YXsQaH6Bu7fq4lO1mm6P/YYDbmbAZ2dqyAVf3bcHhs1eQqHkZRkudawe241aW676UUiqTDHBEasQB76l6gCuJLMv6L/VL4v++9tWW1ZDyfyUCkXV3L/zKlsZpS7BKu7YT9apVwte+1fF92xikW/aNDy+r7FsRPXZl6+3nPES7RrVRtkwpVPi+NS6k2oOQ4fk5NK1fHV+U9EWb6JnYftuIKWG1bSHysypDsM8hYLUqU0IrX/NUbyPn8kxt/fOAwcq6Eb+OjIJP2bL4skQ5NO051RZ61JDl8hqEYJb54CQ6Nm+g7Fsa9doOsL0ea734W0cwI6oJvixTGYtOJ9vOjXOAy8SN3bPh51sWpaoFYcfNTFvfr2ydDr/yPij2bQ3UadULl1OEQJh9H8sPP9CXjc9xbOMm5Dhut2pKx8INZ13LKaVUIhngiNSIA95TxQDXv6YS4IpV1Za1APdVCfxPsUZwM7wwKXXSDmihplrHsfhtTASqq8Gq+HdaYHIOcEaU+Lo4Krafji1nbmHloEbKNv04qzpXwmdKG8VqhSFuzjTU67YG9025OLZttB6sjifixNk7SFaPZ+lX8va+8C1WHN+EJWjrkwJLKcGsAWLP6Y9r24VEYv3u4zh+bDs+V47r03eXVq4FOPE1iDNrmSfRZUwcjiYeRTnlGJ/XGotjDkHv80rN0HfGUnSoXU5r667RNcDV/UYNmCUwZ88l7FvUU1u+ZlDaMN7W2ugwZz+2r1uKCdEdkOr0Hphw9/gOXLI+zs28he2rN2Lxyo1YsGIzDlx66lA3D+tXbrKFU0oplVEGOCI14oD3VHePUAfseqJt0wNccWxLs9Y34tS4+lrg0x/35SEnaZZW50COEOBSN2rlX5Ysg680S2vru7PztCCmLt8wOvfFcDtOK3f/CDUHR0fXVdr3UQKMEV8o9ZouvAuDZfuBhDj0iOqBzpFdUVZp/8vAaVq5HuAcX0Oea4AzpmDGuOGIiOyG6mWVIFayLRY+yLXVm3vH8kg456y2PirR6BzgjHf1c/d1CctrLaMExuIYe1oNl0YU/1oPke1HLcWe2xnOr8v4HEc3bkKqQ1h1NGn/Dhx9bH8kfXzzJqS8py6llMogAxyRGnHAe6otwCnh47NvfNC6/yzbDI81wF1RZ5K0shzsH1JdKSttC07Gh0u1OluznAOc8cEyvV3BnUqAUz/npi6/EPryxwFO6c+FqVoQepRzSau3/JHlEejlpVpgcjyOGODsryHPKcAZ0xIxpaW/cz+FALfM8thW/fKDuh5zMMc5wBkuO+9vcdQpfXbw0Oyetv79r1RN5wBmfIyD6zYhw83rVTU8PIsNF9Js78np7ZvxlAGOUiqxDHBEasQB76niI1RHrQHuqkP4SdnWG2qIuqCFLCOuz2+lrT8yCTNwORe1fbtve+HwyE8PQoGWUDX3ph5wclKe47nSnuHOAq38+HsCnPVLDmFRbWyPeVWHq499S/xoWw8o7hrgHF+DY4Db1qeCFq5C5t/VtnWv8I1LgPt5xUMtsGadm6KtL3uSKzxCzdYeCavnMc2lz3YXddAfHTdfZPm8m6opGSe3bMLz94SyrNuJ2Hk9x7Z+eMMm4REspZTKJQMckRpxwHvq3w1wqj+pIccyo6T6/fC9Wrn4JYZV3e1fStAtq5WnJk5FkI9DGyU7YIkSikymR5YgpFgqAmtSXPu0oYeftr3GL6dtZZfntNDKPi9REp99XQI/VCv5lwNcRuJ41Cmpf37tC3XfBpVdAlwJ7fNtlhm0cs1t58bxM3Bn53XAtyXs9f7vq2/0c+oyO1cChx0f5yqh9snZvTj5TA+3yRcPYMm6fUi8eAOJJ45jwerdTp95W7lyMz8DRymVWgY4IjXigPcGxQBH/6KmFCzaesW1XDTnMRbvvulaTimlEskAR6RGHPDe4PxWpfF/xfzQe7f9kR/9ay5fucOlTDT16hEcvGdwKaeUUplkgCNSIw74D6v+rVD1EaFPWDzuCN8upX+uMf0Jrj7/479gcer8bZcySimVTQY4IjXigKeUUkplkAGOSI044CmllFIZZIAjUiMOeEoppVQGGeCI1IgDnlJKKZVBBjgiNeKAp5RSSmWwCANcIcZ3bY+vv6yE4HajMGvDebGCM+ZsnFkdh+uv7UXq+vRZu2zrv9T4Fp/9zxdLnhXaKxHyNxAHPKWUUiqDRRPgCp9jSQt/fPaZP2LHT0FIQDV8XW2iWMuJ1NVd8c1nvlifY7aUFGrrn30d5VSPkH+COOAppZRSGSyaAPf2GPqXK4+vas/U182vkJJs0JcLstEp8Ed89U0tfBcyACY1rxXmoG7J8trsmuqXVSbi0tJBtnXVU++AhU0qacu73gLvDo/EF77DcXjWIDSt9T3KVm2LZ+9sPcD2idH45kt9xk7zq47KcbIR1jAQX31VFeWrtcaWK1n2HcgngTjgKaWUUhksmgCHPByO+UEJTuUxZt0Vpy3+X/gioPNyPL52CJNb1MTnxcOUNJaNySF6OJt+4jqSbqbgwZVES/DqgCtXriPP7Brg1OVqoVOxcM1G+Hzuiy98hmnHyL8wTdlWQekFEF5ODXHlkaHsP7luBXxRNgKXzxzDliWzsCGFj2I/NcQBTymllMpgEQU4nT1T+uBzNYR9FoDAsYlKsrqtha7i31RBSdUSfsp6RRQodVe3VZcdHqGaM/UA5/AI1TXAfYu3lm27o6oqYa+NuiMM63vis89rauWLmur7XHgHXJ7UTFv2/aEfJq5LsrVLPh3EAU8ppZTKYJEGOJ0ClFE/y/a/CsjPv6kFqL0OX1Sw4lmAU9q0bNvXu5olwKm8QvkvrI9ky+PrqgOsTeDNi/Oo8Y2+rWK/I7Zy8mkgDnhKKaVUBoskwBXcW4xGX5VH254TMCN2iD4L93kdbVuVL3zxVaUuuHjlGs4d249mjaZq5Xt6VtPq/dBnGeZN3qiUvLHM3lXG2nXrcent3whw705pX6BYtXYrNmz8Hb8fvaEVT/05EjuOXcGlHRMRVLw8iv+83rI3+VQQBzyllFIqg0UY4OxfQPjsswrwC9+ibTs8srm9XPGLSrFaeca2Afj2c0t5sX5QH4Xa1hW3vfwbAa4wHSW0WT+r5bEw6RXGVHP4UoNin9/5JYZPDXHAU0oppTJYJAHug/L2CsbVqgj/zmugfkUhN/kSfmtdDZ+XGyHWJJ8g4oCnlFJKZfCjD3CFL+LR8uvyqD1gr7Z+efNENC77LSr1PyrUJJ8i4oCnlFJKZfCjD3Aab58j9Mcf8cWXfqjfcgDGLE0Ua5BPFHHAU0oppTIoR4Aj5D2IA55SSimVQQY4IjXigKeUUkplkAGOSI044CmllFIZZIAjUiMOeEoppVQGGeCI1IgDnlJKKZVBBjgiNeKAp5RSSmWQAY5IjTjgKaWUUhlkgCNSIw54Tx1ZuyT+93VJ1GwZjVmHHrlsd9WAgMH73JS7OqblcJeyv2PKjmiczHEtNz5fg4UPcp3KMnf1w1k3db1Bw4PVmHvNiGNjvkelQQddtqv6BE1zLjPcQNiGDJd6jqZs64UtjwxINbhu+6taz9uMEF+XbX/X971f/5XNoja7lP2Z7s6hvR0D/IcecdmnyDQkIXzdU9dyF3PRZtEDGFzKdYNLFMf/faVaGiHz77hsf5+O16fL+PvL/svnyI1PV0dq50MsdzZXq/e+c9ambFuXe8hfNxV+XZbgZNIzdKhQG11XnMTFRyY39Zx9//0wExMuGLVl9Xo8/w+u5z9Xv3+nu5T/N+4c0Mb2Wv9IBjgiNeKA99SRdaroy4YrmBToC6NygTeffxbVfMqgVORGmNKv4fsq5VG91RBlm7qP/YY9MbwhKvr4osOkPdp61t29qFK+HL4uVxXnz8Xh82KlUapiKObd0m9uk4O/tbSRiwcrO+KiIRfdWjZA8XIBqNctTqsTWn0IejeqivFnjbab2fNj8+FXqbxW70RKrhbgpm6cjuKlfFCpcW+tTccAt2FMRxT3qYHDT5Xjpl/BysFt8HVJHwzZes/htbsee0bTRpjTtQGaLbij3PiV7SE14VO3HTKczpmwn3Lefl712LatVPAMW3/V7db+qj8s7AEuEy0Da+ObSj/ioUlv16fxePxY1Qd1w6djj/rDwBbg9H6UKeuLYRtu2PtheoJqvqVQyscP2eq5v7Mbfj7l0Kj3XG37sTE/2t7HFw79XzeyM0qXVc7Fltva+nsDXNYt1PIrjwZR8/TzqPRn7PYdqFi2LIr5BeKp0m+fWmP0utknMaxWZdv7pZ7H2MOJKKu8P+oP0AmRIShWvrZT3+JHdUDNSr5o0HupVhZafRBW7ZiEEqUrYPOtu6hVyQcN+q7BpUy9P+pYK1k52DbWKnZZjia1/FClxVAkXM/BjdU98L8SvigTPAWnckwIC66OYr41cTLD8b0zoUfT2igZ0Bhhk3e7nEO1jnM7BlQZsBQBFez9dOzLXaewasBPM/fAr2xpfFW+Dq5l5WnnTD0P1jH16PA8lC1TTjv+bXVfZXvElmyo7/Gz43HCe2xCn5bfo0Sl2tgwOBBflC6v9LMCsmzHsxtcNsJp3XEsHHyiv3eO74daJ/uC8/XpExyLwOoVUbXFEFs7TteRQ/uPjy+w9S0z136OipWrgTNpah19fPv6+KDtpAPaPtb3q1ipCtr7pZZN79oYVavVwP+U8Bkw+gRy7u/T7ifWc5t1axu+LVcWX5Xxw/Ikyw990zOU+aaEdj4qD95vuz8VU+osPpNq6+MW5Zyp9fRzpl+z1mtS3W4NcDl3N6LLuru28e7u9Tq+N8YnxzB/WCf4NWqPOWvm4OsytREc2kG7HsRxYb0fftd5idP90LFt1V8aV8HXZb9V+qpfQyvm9lZeTyXEX9PPkyk3Qzt3VZsPwpJzaU77ivdg9TwfXDbIdp4PDq+N8r13attyrv6GRfeztfu3Oo4c77WO14Y6NtV7Vmj1wega8h3K1ulgGzcVI5ahXmVfBPVbg5ndGyn3gzLoPPe0tu3sqiG2fqr3ZJfrPOMYvipWUnutEetSnO7LtqBtuc8wwBGpEW8CnmoNcIfndYFfxU5QfxB99cNE2/YOvg30ZeM9NJx9CzmWAJe5f6gtMD1d1QlXlR/cFaoOcGq7WjX7DwNVw835WKzcNA33lqKlb0uHbUZcmt5Y+WGg3FiVG48e8tz9NmqEb9/d2s0len+WXpZzER0Sku0BLnkj5t/Tb8BB5cJwfU5zlG4526kfztqPPSOkDFItZWcnBluCWyaqj0l084PTvl8j3/Zamfq65ty23/zV7db+Ogc4SxtKgGi7Oll7vaV9ulraWIJmZVvYApy9H3nY1qeyUz+Sfm2i/SadsTsGFSzn2vhiI0YlqrN9dZzeR9HIb5tp/74vwHWu2Eb7N+fabO08qv2pPeG8vt30HC2WPMTv0dW1/hwYVht+A/bZA5xyHisN0Gdp1b7tsYQox77dMeplV39rqr2+NmW+w8DDapjJU4JBf+3f/UO+Q7XRJx3GWq5trJX2idTqZJ0ci+rV1ZkNI76JtMycZe1B7+2us8mJsfXxzBKY0w8Mwc4M+zm013NoRxnrxVou0pat/XTsS4mQOVpfbHWbL7As56JM3fHaOVPPg3VMlYnYaDuOv3+0LcCp73HlwYe0cv09Nmp9fWzpq3q+m/3RDNw3aghVAkCFZph6yeg0FjpXqGfrh7if4/VpHX/q+Tzo5jpa8cw6W2VEqbAEe98czpG2rcd2p2MsDi1vGd/6+6WqvV85x9F7t/5+Hx9TV7uO/BtMtdTRz+3qsAp4bhknji5r76udD3XZdn9SnN/SV7k/Weop50ytJ54z232mXCgW3klC3WH6ebGOd1VtvNv2MQrvjVKWk4h++/RwVbFOLI7nuB8Xf3Y/tJm1C+MdZuASkvXy6jVGaO/F/JaV9Xo5JzG8tr9tP3f3YPU8J7zQ3yv9PJ/F2HpVtPVJQX7aL+jWAGe/1+rjzXptqGNTvWe1KV1dP1bmLky8qPevtG+U9u++wdXwxFJ/QgM/7edD+AZLgFb6GbUry+113r1CkOW1mtzfly33mSIJcGevPKe0SC0qXAa+h46sXQply/uiUkh/zDnxHOoN2bef/tucak3fnpZlA8opYUT9jVu9Adye3xIl1R8aqmV9kJhjQok2y5zadrlhKRd5yyUPcGdRG5T+WZ3RMGFQ52aoUaceqlQqp99Yy+rBQtUaCB6fXIY6depq9Ur12qndXObcsQalTNSbfMkWRLLPTlJ+i9b7VaxsKxiTE/FreF10Gb/auS9ujj0jxMeyLR0J4eX016ZYYcBeh+Dkut/8VhWVHxQm7XWpNyxrf9Xt1v46BThTKsJbBClt1EHrlc+0m2g5a9jKPoyYajVsAc6xHyXL+LgNcLfmtUCJ0OV6ueG6FgqPKT8UHd9Hq5un9EF1pe8lS/6krb8vwNUqUdpyXF/tPKr96bgu3bI9U3tUp4agg1l5iKleGwMPZTkEOB+0i0/R6qp9s84yOvbN+jruKudMDThtlGPMvau/p+Ua6I/z1PPlfqwpdepP1upkX5iKelUGQQxewf6V8Ou2K06vKb6zj+0HvPHpasy8bvzTAFcxRp9B0vtpcupL8foTtb5Y65Z3ON8/lOumnTPreVDH1A/Tk2zbf1bHuSXAqe/xF6V9Hd7jdMSHO4eRPwxwZUNx684dxYd4oV6HDmNhemMfGJ36Ydfx+iz3wyTtX/V87sl2vY7m3LReb8rrmHbF3jeHc6ReGyXDN9jHd+16+LZMWX18W94vVe39UsZ53z16CDquvM9Zyr5flvCxjXX13KZfWgmf+hEYumi/U78dA5z9/pSHo6PraNejtu4U4PRr1npN6veZFujV70ds12YMHce7/nrtx0sX3ps8twHOdVz8hfuhVSHAnbGMKfU8qe9FX7+Slr6VR4nS5W37ve+6cNxf+2V0UpA2C1+vUg9Yn6BoAc52r013ujbUsakFOOt5UN6rX87o/bO+j+q1ab2GZ4Qofcrej6+0WUS9nx0TUtxe5/YAl+f+vmy5zxRJgCPEW3Ea9P9A2yNUmwanWaLwCj/qy0r4ajT3lnJD1G8AGbsHYkuKc1u+AeoNw75evcpgoe08tK3UDs0rRWDVk1ykb+pu+QGYjb2Dq1turD/b6loDwTfqbIZWlm0LRPYZuHPosNY+A2d8tg5Djlm2Oan8YG61xLbu7tj2EKP/RnrPNstg191+xsdrEJe4SHtdah1rf9Xt7gLc/iE19B80ORdtAc42A3dnAUIcZuDe1w9Va/jIOjgUfpZzr866jD39ns/b5VxC+wT9EUyzMn8c4Dr41HHe1/a4T13XA5w6VqoO24dasae1G7U9wPnaPr+n9u33dL0Nx76JN3bHzyRZP49lDXDuxpq1jlOAC7fPcGmm7ceAg9bHUHk4OzlYe9SlLqvh8/fM98zA2dqxf1zA2k93fbHW/brJfMtyLkp9P8H2HlrbLRO+3lbfv/JA2zlV3+OS7VY4taXOSln7ajK9wE9xd/8gwDk/QnUcC50r1Bf6Ydfx+nQ8n2poeP91ZEBp5XXY+uZwjqwBzja+Fcf/qH4sw/kzdvr7lYcuVX1RNqAmouIStfUKfn3cHC9Pe2xab/JF2/qKDr7a+VCXbfenXH0GznaOlHOm1lPX7desfk3q95k2iLtvQoiyv9o/l/Fu0yi8N3luA5y7cfFX7oeaWbvxi/YY0/mpgzXAzW7qEOYddHdM9Tw77q+VK+9/5Ibj6LNb/QXMMcBZ77VGp2tDHZt6gGurb3cIcI7XplOAM97CjzOvOvXT3XUeVamB7bVaj63el+9aZ1ot1wQDHJEa+wXwz/yzAKd+NqR2JR9UazHQ5TNwU6Oao+q35eBbN1S7UWZc34qKZUvjyzKVcV25iRya1hHFKrXFnGv2C/b5xh7outUy1W56ihrKDbxhtznYt27AewPcngkd8N2PwVq9gN56INq8bQKKKb+N+oX0c/kM3KbxXfGV8ht16JSDuLVhCBp954di5WtgzwOHG4ebYzuHmFz0bVVP+e27kv3zN+/ZT61burif7XVZ+6tut/bXMcAZU0/Br9r3aDfhd7S1BLjq/dbhez9f1OsyC/stn1uyfgZO7YdPmVIIaBrt0D/n8JHz4IB27gOj9McSbgOcYo9GNfF9cDtMa/nHj1BNmbdQv9q3+KZKkHYe3Qc49fFJSVy0/MBwF+BUJ0U2wlc+3zn1Tbyx/1GAU5fVsfZlCV/bWHMNcMoP8MgfUTpwMk6knETFcmXgW6cN0izH0c1Fj59qKq+pIToo514tcw1wDu3kuAY4x744fXZHuS6qxyzRPhNUrOIPuKWORSE4PT25AKVKltGOL34G7unJxcJ7bERE45r4+tu62ufzejesiuKlfJGZcx4/TD7r1F8xwDmOhQNOY8n5dTpen2KAU5cdryN7YFPOxZ4ZDn1zDXDW8V2nQRNsGRP0ngBnRJUSJbQvX/yvmA9OpinHvr9fu59Yz+3vsW3xZclyKFWlAa5Z+qSadX2ddj78B+2x3Z++LO2Hhaftn4Gz1tPOmeWatV6T+n3GMt4Mt+Dfa7ttvFtfr2M7Lu+NIQnTT+n3hNBui23jXxwX1vthnag1TvfDh8va4YLt0bt+3kKq+eLrMtWQ4SbAmUzp+PnHAO0aahCpf4bPqngPdhvgFJuXLmm5V7kLcKr2a8P6Gbi/FeCUf8+tHmXrp/rZU3fX+b2do7XXGp7wyP19mQGOfAo4XsT/rQZUGX7MTTmln7LCLz5/RcN1RG6zhuJPS3XGx/ZxANMzNF1436WOrE4JaeVSRp1lgCNSIw74/8Ks9HRkpiVpX2YQt1H6aft3A5wR6XfXaF/qcN0mv4/XdkXC9Qxt1ujkqv5Os/SUMsARqREHPKWUUiqDDHBEasQBTymllMogAxyRGnHAU0oppTLIAEekRhzwlFJKqQwywBGpEQc8pZRSKoMfMMDl487aibiYZxY3/Ouox+0RnSAWEwkRB/y/7ZkJDexf+/9T/+438t6nERWiXf8EEKWUUnktogD3Bqd/G4jVBxKxetp4DIl/gLdilX+EGZF9N4qFf0rBg53Y8qRQXzHnouucy84ViPSIA/7flgGOUkrpf2GRBrikfGWxMB3hMVtxtwCI7DwWA8atwOUsM1YPikF479k4unsLImLWKxULcH3FaJxT9jk3fzRWHriKVWOHIqL/WrURRIUNxJ5Dx7Fr7VpkP7mBzr0W4/qNpw6HvI7uYzbizNGDiF+4RwtoEVEzkXTxlNbOlZdmnF45BQuP3MLTnFw8v34QXSbsxo37mdpxO3dZofUhPGIwNu4/jWGR0egy+gDMWafQ/7fjeHx8NQZ2jkFq3jt06fwLLp4/j5VHUmGJg8QD3r59h9jYXzFm9Axt3Ww2Y+GCNRgQ/YtQs+gQB7yntilbB5N3nMOzbPXPOC3H2L338ej4LIxJVP8HoyaUrt4dWTmpqO9TzhLgMlC9xyoY0m6gQvha3DMqbZQuj503UnFoeluse6L+3/QtAS7zFOqP2IYrL7KwrNf3SDLkoVYl/Y8hq22Xar0Uj7f2wQb1/wdlSIZf9YFOx0zaNBS+DHCUUvpJWaQBLqxTf4SFDcbtXP2xaGTYMMv2QkSEz8SuZD3+TIoYoEQne4DrG9Zf31dzIMyvL6J73FXLvipv0FmcgTO/Rp/waExffQI3s/KRf22DQxv9MfWICRn7Zttn4PJvI9IyA+cY4Dp3WayV3YmPVcLcQhSmHsHQlbfw8u4OjAyP0QLb4iGD0W/sanyAp71S8svYmRg9arr2PvXvN0bcXKSIA95THf+gscsfcM/ej8FHDNp2/Q9Ou/8j1/Y2MvH95Ivan9dRA5y7P2R+ZVYTPDPpf/NzycNchz/U/K3+h5odjqkGwW8Z4Cil9JOySAPc1gs38Djjta00MmyUZUkNcDOw44UepiYKAa5PWAweP3mOJ5ovACXA9Yi7ZmvHbYBTePXiOgZGRqNzz3lKgFuPcVvuWdp4jrTcwr8Y4NR/7QEOeIt+naOV/g7FsLnHLfsaMG/kCAxZcYshrgh4/fqNFt769hmFjIwscXORIg54T7X/Pbw0xHf2cf6jydn7MOSYHqbUP7itBbjTE7DB8sfJ7W00tyw7B7g7ca3wwCHAtVuTAsPN+Vjz1IjbC37WtvX1+865Tw7H5CNUSin99CzSAKc9QnXAHuCADcMHIrzXrzi6x/UR6sVFYzFp9TGcOrwfK3/bqW3rGjYQuw+exJ5Na7WwF955DE4cuWhrz2y6gl3K+vE1vyGq8wj9EWr4aCSeu6K1k/RWiWKX4jF4zgGcf/JWe7TbOeo3HD1+548DXMFT9Ixdj4MHTuLoSTVEFmL55mNIOnsIXUbtwzM+Q/2oEAe8pzr+QeOc64vw86yDyEh9iB1X1T9tY0Sp2v2QY0hHowq++iNUUypKNRiCtKwMrNuYiCdKCGtTqhx+v52B/ZNbY+tzh0eoORdRb8hWXEkxYFXferiq/ZHlXFTs0B0tK3fRjnl/fXeM3paEJ+lZ2Be/zemY13aM0h6hGu5vxKSTWS59p5RSKp9FFOA8oQBXl47EeSH0fWiOzRiKuwalU+Z8mG7vwJRDRrEK+YgQB/yH1DEE/hUnBPqh8/pkl3JKKaX0AwW4AnQPH4ioQXHwtieSr5+cRb9uMejWaxxGT9+g9JR8zIgD/kP6dwJcTuoF1Bh1HOlutlFKKaUfKMAR8t8gDvgP6V8PcDn4qlQlJKaqj1nFbZRSSikDHJEcccBTSimlMsgAR6RGHPCUUkqpDDLAEakRBzyllFIqgwxwRGrEAU8ppZTKIAMckRpxwFNKKaUyyABHpEYc8JRSSqkMMsARqREHPKWUUiqDRRLgOgdSWrQWFeKAp5RSSmWwSAIcId6KOOAppZRSGWSAI1IjDnhKKaVUBhngiNSIA55SSimVQQY4IjXigC9KDUYTHj99rv0rbqOUUkr/TRngiNSIA74oVAPbtDlxLor1KKWU0n9LBjgiNeKALwo37/zdJbyp7tx7wKWuzK7p0w3jDhpcyj+oxocufco6Ng9XDW7qeon9I965lFFK6Z/JAEekRhzw/9S45aucQtvDx089moWLi+iNaSe8LPz8TdUAN97DANe/02KXsr/j3vhDuJqR61KuBjixT38/wOVi/Ymnbsr/HT9sgHuJiRteuilXzHqNVRGF+nLmK9zMcFOHUvrBZIAjUiMO+H+qOOt25dpNp/Vbd++77ONOMcCdmTsEEeP3wZjxEO1HH9LKDpx9iOSsXKyI7gGDsj6i+QB0i56Ouw+fa6Gkz4yjyE67j98nDsBTk71tY8oBdBqxAZnJN9GqXQweZBiQfu8IRu5MgeHODkzeeRvPs7LxW68oZCr11/TtifHrz+Pa/ccw5dzB8PiryHx0DvN799SOa+t31j08SDMgce5Q7Xhr+kSiReeZSM/OQnTrGK2Otf3kWycQtfi60t5VzO3cR9/f9BTDtqfCqCxHdHQOcNkXV+GQFhBMaD3iAJ4p7Z84dBVGQwpajdivBTNrP5+kmZRzMQGbn+S69Emt59inOeeybQFOPMc5SWux9U4WjCYDjl965tAfIzr9dlk7j+0Hr0F2ViqS1k/FUccAY8pA6MD1yMp4hk6hM6GGvufbJ+OR5X1o33kFzufYz63aZ8fXO6ppIdKVPqVcfYOuaoAzvUSf6HfIzniJKwkFOPwkD89252P98Vd4kfoSd17kYUVHs23/nf3N2nmcGgJcePgSWcmvENWmEI+UPs5tb8a0HS9hfPgG8Sde4sX5t4i/pO/Xs4kZt5W2Do03o8fQN9pxrQHOcP81jp95BUPqK4xZ/Qqm7NeY11IPcMaUN9it9mlXPvq2K0Bm1kuMb633Qd3Wb6DSd6Ws78/5Tq+TUvrvyQBHpEYc8P9UMcClZ2Y5rT9PTnHZx51igOv2UwSat+yGVorNmsdCDQS/jRqL7hExCGsTiaxcNcCNRcJ9fdbJcVYp59p6nMyxt60Gjw2P9HptotZbyvVQsntUV1soMybvR/w9kxLEutr2fbg+Fi0t/WjVPBKXHWaush+dR5/IGER27KGHE2W/MXuytG2PN03AY1OWU/vDm4/5ywFO7V/ohJPIub4e+1P1vsdPm4IuXQahWdgKPcA59NMa4MQ+qfUc+9Ri0G7buXI5x6ZkdGzVHwOmbESO0BdrgLOeR1PORSxOMtrq5FyJx6EsffnCvBjl/XlPgHPos92XGLn8lW29txLgDJff4YSlPdVek15j4c/2wKbqNsA1KbDv002fyUuaV4joWa9xdBTQo5lZs9/U18hW60TqdQzX3mFE23ynAJd88S2WjSjA4M6F6DHhtdsAp/Zp+Vn9eNlH8nE1R9+286FetqS9ZcaOUvqv+8EDXFQHsYSQokMc8P/Ui1euOgW2tPRMp3Wx/vsUA9zoljGYcz7Htp65/1dbeEqc1c8S4MZhoyVQqKHkulHf7i7AabNTynLbns4B7tqy4Ui2hIzMU4u10OAYMjJPLMShNNf+Gp/sxmAlQKrLaftmWcJJJLovuaWVnZyh9tHo1H6ndgthMtzAoq499XZyLtkCXJf2i1yOEd+vN5ZG9bMdb90D/TW0+oMAJ/ZJrefYp/bTztkCnHiOHY1qOcth3R7grOdRDHCmtONYfEVf3ziwq/aa0nbPwF3tPcnVQuf7A5wS2sa9ti1rM3Bpb5Bw2bJdCVWxCS+xtRe0dq314iPsAW5ZO32bY4Dr3eOt9q81wF2PK9RmMp2Oa6njGODGr9MDXPfwd7huGXNRlgA3v5VzgNsVY0bsWr3+zcWFSDHZt6llDHCU/ncWWYA7Pdb+Z5CUXyb/MuNHiCX/LeYsIL1QLCWyIA74ojBh01ZbYNu2Z59tef3WnS5132dcRC+M3/MUT58l41laDhJ/jUGrqMXIyM7Gvv1XkX1pNXY+VgNCLka0t87A/fMAZ3ywFxN33MKLbCPm9IrS2nUKGdk3ED5uDzKz0vHwcqI9QGSexpTQaG19YXSU5fFgJJqHzUS2KRv9Wg3Wj21pP+3uSUQtvqE9atwf2xPPlR/0NzdNtwW4gc2GwWBwDlMP1sUiKswyM6ccb9qxNOQ8v/SHM3Bin9R6jn2af8H+CFU8x4Z75/Ek3QijMRMdw5Y59OUvBLjcLIQOWIvsrGQlqKqPUPO02cOEm9kwPD+PJn8S4IY3L0Smck5Sb7xBN+0zcC/Rp9875GS9xNV1BTiiBKInWwuwOfEVUjNeIul+Ho6NNdvCcd9Gfx7gDHffYuqq18hKf4nTt53r2AKcstxnxBtkKUF+cKsCHHich/Qrb/UZOMMrrI00a/20hrTkg/mIDi1AlnI+Jzo8QnUNcAb0mXLE5XVTSovOIg1wSfn2dXM6sPIIMKA5MHOZsp4BTPsJeGPZHt4UOJat/BuirBQAYxMUld8qewxXdwamRgK9I4BlW/X6k5V6u8YD3Vrr7al0U9qY31PZR9l24A4Q2x4YNhK4adC3n5gHdG0CHH+gNYkt3YALy/SyUbF6nZif9NB5UOlv/gugv9LmgJ56ffLv0T8UeJUnlhY94oAvKi9edp6Ju3zthksdSiml9N+ySAOcdQYu16wHuG5D9G1jld8W1Umu3MNKIDunhLjTSvA6pocka4DT/rWwuSvwUA2Dyk47ewF3leXJShvZyg6FT+ztdQ3U/1UJb6j/u1IJgZHKcc1pSkhbpZdFBwMLTuoB7nyuUqC0F98RyDTr/b6pHktZ3h+jhL2nlgbJv0a08h4tmKyPldg+4taiRRzwlFJKqQwWaYATZ+BGrdaXpzfWMppGRFtgyc/AW8u6NcBFxlgKFOb+BFifwl7/FThm0AOcGtbMOfb2ugbZ97EGQDWkqW3lXwDGrwSe3NdNM+rb1BBoDYYphQ4BzsK5BD0Mcgau6HmphOeYDsCiKfq6OgM3VnkfxvVzrleUiAOeUkoplcH/PMD1V4JYdCNbNbcBbnsU8MAyA7ejJ3DPMgP3dwKcOgPXf5p9u3WbGODOxgLXHPqtsqCNEjaci0gRkKXOyirh3OyQjl8pJ7p/W/t6USMOeEoppVQGizTAOX6J4X0B7u5CYPhy617uA5w6/TUlAugVBizeohf93QCncn65EhiU/SZMAZ7kuw9whUo/eyh1TiiB75LSty7BwMTp1lbJx4444CmllFIZLLIAR4g3Ig54SimlVAYZ4IjUiAOeUkoplUEGOCI14oCnlFJKZZABjkiNOOAppZRSGWSAI1IjDnhKKaVUBhngiNSIA55SSimVQQY4IjXigKeUUkplkAGOSI044CmllFIZZIAjUiMOeEoppVQGGeCI1IgDnlJKKZVBBjgiNeKAp5RSSmWQAY5IjTjgKaWUUhlkgCNSIw54SimlVAYZ4IjUiAOeUkoplUEGOCI14oCnlFJKZfCDBbjp45bhwLNCsZiQIkUc8JRSSqkMFk2AK3iOzcMH4kz8fHSNmoD09GvYMG0iuvefhXxlc6GyPmLACHSNGIyEcxnaLpFhY7DqZgGurxiN6yc3K9uG4PCTN87tEvIPEQc8pZRSKoNFGOAGYPD0HUiYOAq9eo3D5DVHMWtADI4ZzDDn3cTuY5dx6cJpdO62UNvFMcBFDV6Cw9tXosvoA3jBSTlShIgDnlJKKZXBIg1waWbAnHUcwzY9Q4FS/PbMciy/VoC3KUkYOXAs+vQagc5ho7RdHANc4kutEYRHLMSJPLNjy4T8I8QBTymllMpgkQa4bEuAG7n1hVOAGxcxQFtXtqKLmwB3Tn3OygBH/gXEAU8ppZTK4H8S4NLPbUZExBBEj12DOT0Y4Mh/hzjgKaWUUhksmgBHiJciDnivNucS2i247Fqem4V6fRKcynaOaYMbRrEepZS6OqFda2S7KacftwxwRGrEAf9fumVUO1y1hKyscwsw5mimS52/phLg+q51Kvs7Ae7BvVfo19aM9LSXLtsopR+3bZt2hNGyvH5YKG66uS94GuDmLV2BlWs3OpXNjFuM5NR0l7r0v5cBjkiNOOD/U9OOov3iazBlncWkTq2RqZRd2rUG1+5cR72mg7H8ngn3NwxFSOeh2HL8LjJyzqDlvEswGe/j93M3MbtfKL7vsgRqgKvzUxgSL13AttkxGHc80xbgerVug9Cpe3Ay4RfMupjj0odHD16icyAwZ3y+9m9GBkMcpTJ5beUA7EjOVZZzUb/5SK1s1+pNuHnjpHYPOZdjDXAmXF81ALuzlf2Md1F/zAEY7m3V7iHn793HT816ubSdnWPQAtyy+HXa+rQ5cXiRkupSj34YGeCI1IgD/r+2edMeODwtHPW6LtPW42eMRkhoZ3wfEo6JiQYtwK1/rt58lfqWAJd+Yy9+7hCGxi1/Rp3mE6HNwPWO1+sYrqF+7GFLgDOibkgbBLbphEZtOqDR1ESnY6el6uHNaNLX1Rk4dT0z07WflNKPVNMjNBi5G4/ubsDA31OgBrlpowaicbtw7R6yM9NdgLujBbiTsyO1e0gj5R7yY5OWyBLbtrgsYT3DmxfKAEekRhzw/7XnFvREo2YxWHzLpKwbULftRGSl3nEKcBuFADeve2vczDRiep9QW4CrHdIRJy+exaaZ/ZX97DNwPVuFot2Ubbh27TIO31eP4doHSqncxrRqp4SwNkhV1w3X8ePAjUi7f0K7h9gDXB5SD07FwE03cDJhrD4Dd3eLdg85cuU2juzZ6dIu9W4Z4IjUiAP+vzbn6kr80H8Dbls+lxLbNwLB4cMxqkPEewPcw6MLUa9pO8Rvm4/QFnqAazF9O5q1aIMf20cj2WT/DNzT85sQO7Anvm/eEZvvMMBR+im6M7YD6ii/FOrruegR1g7N+87U7iGOAc6U8xAtW7dBl8kb8KMS4NS66j2kcYvWaNl/pku71LtlgCNSIw54SimlVAYZ4IjUiAOeUkoplUEGOCI14oCnlFJKZZABjkiNOOAppZRSGWSAI1IjDnhKKaVUBhngiNSIA55SSimVQQY4IjXigKeUUkplkAGOSI044CmllFIZZIAjUiMOeEoppVQGGeCI1IgD3lMJIYQQb4IBjkiNGMQ8lRBCCPEmGOCI1IhBzFMJIYQQb4IBjkiNGMQ8lRBCCPEmGOCI1IhBzFMJIYQQb4IBjkiNGMQ8lRBCCPEmGOCI1IhBzFMJIYQQb4IBjkiNGMQ8lRBCCPEmGOCI1IhBzFMJIYQQb4IBjkiNGMQ8lRBCCPEmGOCI1IhBzFMJIYQQb4IBjkiNGMQ8lRBCCPEmGOCI1IhBzFMJIYQQb4IBjkiNGMQ8lRBCCPEmGOCI1IhBzFMJIcRb2TRsEMbvzbStX1s2Cq8ctovrr08txdX896+TjwMGOCI1YhDz1A9BYdpxjGjUEJ2GL8LsCeOwPcOslL6Cf53peHc5DhFrUmx1m/g3QqFl24l3SkH+M/hXCsHsxWvRv10PjDv2Erv7N8aENdswvnsnVKsUrN3Q1bL6AX1s7by9MA/VA4KgNuGMGYYzcahcJwrLFi9Hy+4bgHcXEPtDIFas3Yr+zZti6H4D1B628A/C6jWbsWbNVm294MYyhMTEY+2K5fiuUiC+77pJbFxrK6DvfuUwuahRuSNG7M/Q9mvcb7nSzmbsvZELszlLeX1jtOobezSFf4OpKLi1Ct81H4tFs+dizF79+IR8SgwPH4ARfQdjwMhpiBh7ECv6DMDoISMxos8gdI5Y6LJ+evZgDBs1HmOGjMDCS7nCOlPcxwQDHJEaMYh5qkfkXUGNFpNwbMdSdPshGKmFQGSVQHT6ZS2mR7aBv18rJbBkw7/+dL3+y9Oo1f8gtvdphq3pZgyrHYiAiK3ObVpCmhKLULlqtF707jqqddth26YGuM09GmO3wTnOqGFNC3eFL7CyY0NcztfL9swMx71Cvc7oH5pgRG3XAJd/cT4a+QUrR3XAEuBMyqLZuB+1R5zCW6gBriFSUjOQmpalVVODWKeVL/R98k5iWJ1AJFuOZ8MS4FoGNEKmpdvqfu3mXUeq0laupUMnf2mPXekpqNJsIS6/Ad6cmoWfp56zt0PIJ4Y5JwlT91/HllFDkKf9xpSBPvPPocfYvXioXpDiunJ1Rw3cjL694iwtiOvkY4EBjkiNGMQ81RNMe2Mx8ax2B8XduO7YlGHWApwa5AofJCC0shqIzKjl10ar//LoVAzZn6vcT3O19Q6Vg9BwylWHFlWsAQ5orc26KdUvxSFqk/r4xB7gZoQE4YEQktSwtutZBhJXx6KRErJeW8oeJC3BvNt6NPv+u5EYVsM1wBm2DUdApSbOhZYA9yA1HZtHR2LEYaNlBq4BKlVU9AvTqjkFuMKnWNauIS6Kv+grbVVpORB+342wFan7ae0ozrii71D4YieadRuIQXty9Nm2wkzU9gvEuBWnbfsR8ilRkHkbt16bkXf1AHLUa/5tOg4/KcCmhNN4qCY6cd38ChtPZeJYwi79GhLXyUcDAxyRGjGIeaon3JwTicmH7uH27fuamW/UGTh9FsuctRs9qwZBjSVHR7ZGYvYZjK4XrIUqKzE1AhGgzaw5Yg9wD5f0wpqHVzC1UTCytDuvPcAlRDTEAaHbalhbcPgMgvybo9vaZ7ayx4X5CGiyGEmp+7QAOdRNgHt3ehbq+zXUAqO9UA9we4+dQtWAnrZidQbOsZ5jgDMbDmHAd4HQngY7os7AdduJU+PDMPKI/ijUKfg50EpoXyXvzgbU7LcfOWK7hBAiKQxwRGrEIOapHvHyKvxr98L+/YexdUUc0rVHqK4BDm+u4If6rVE1ZKG2245+zbE93Yy3t9cjolYgeo5brn3G64g2MWcPcChMRrVqIfCvFauvOwQ4c14S/PyaY8HyDRg/aDQWXsi3PUItzDiCQfWDcO+dNcABvzYJRqWKgdrn4twFOGUvPNs6GgFB0Vi5Ih79Yvc7PULNPT0brWZew0u4/wxc4+hVWBE3D1UrBSOw326hbdg/A6fQvEoQGgw56voZOEvV1g4B7tLMXhg/cxWm9euCNnH39PNJCCGfAAxwRGrEIOaphBBCiDfBAEekRgxinkoIIYR4EwxwRGrEIOaphBBCiDfBAEekRgxinkoIIYR4EwxwRGrEIOaphBBCiDfBAEekRgxinkoIIYR4EwxwRGrEIOaphBBCiDfBAEekRgxinkoIIYR4EwxwRGrEIOaphBBCiDfBAEekRgxinkoIIYR4EwxwRGrEIOaphBBCiDfBAEekRgxinkoIIYR4EwxwRGrEIOaphBBCiDfBAEekRgxinkoIIYR4EwxwRGrEIEYppZTKIAMckRpxwFNKKaUyyABHpEYc8JRSSqkMMsARqREHPKWUUiqDDHBEasQBTymllMogAxyRGnHAeyohhBDiTTDAEakRg5inEkIIId4EAxyRGjGIeSohhBDiTTDAEakRg5inEkIIId4EAxyRGjGIeSohhBDiTTDAEakRg5inEkIIId4EAxyRGjGIeSohhBDiTTDAEakRg5inEkIIId4EAxyRGjGIeSohhBDiTTDAEakRg5inEkIIId4EAxyRGjGIeSohhBDiTTDAEakRg5inEkIIId4EAxyRGjGIeSohhBDiTTDAEakRg5inEkIIId4EAxyRGjGIeSohhHgrm4YNwvi9mbb1a8tG4ZXDdnH99amluJr//nXyccAAR6RGDGKe+qEoyLiGtkEtUDcwAnsfFyglr+BfZzouTO6A+OdmW71fmwTjSaG+7cQ7vezksumoFdAIrSLGY/7xdOzu3xiVKgaiXkhfDJxzXKujllUN22RrB+9uaHUsTTiQj+dHV6BOQEM0i5iEQqWkhX9DdFr5Qtv6+ukZtA1ugeqVG6J5xzFQfxaobQePOQODpZvzWgbjra09C+8uIKDvfpjU5YJUVPmur1YW+0Og0o8Gmqnn49By9m3bvj8px33npj+EfIqkpOTh0ORhmHv2LZJTTMhMzsKzrdOQb36LnOcZLut56anIv7kJTwsKkfGqUFi331OI98MAR6RGDGKe6im/9euB6nXCED5qi7YeGRCKpYN6oVrdCPSafRaFabtQf8xZS20lgNUYjiNjOuJQjhlHR7WBv39HIZzoIQ35txAQvtlSlo/KATG2bWqAS986Eq1nJDnuqAUqLdzl39PC1OV8vWzET41txzgVG4re9YNdAlz6+kGo6tfRqcwW4N7ehH/NaIi3frXtfg2CENB6mbb+hwHOnI/6/s3xxlKmBjgt1FloV7WhFuJeX5iHrgkv3PaHkE+Rt7k56Nd1MLrHxMP0ugD5r3MxqedgxF9OR07eW5d1c/5rrB05DBO23sM75cIX18nHAwMckRoxiHmqJ5j2xmLiWTWyFOBuXHdsyjAjskogUpWbZOGDBIRWDla2mFHLr41W/+XRqRiyP1cJMLnaeofKQWg45apDiyqWAKfQ2r+RFrzeXYpD1Cb18Yk9wM0ICcID4WasBqpdzzKQuDoWjZTw9dpS9iBpCebdVmf3gO+/G4lhNYJcAhwKM3F0chRqNBqIR3l6VLMGuOwtwzH0kPI685MwOShImzW7W6i3/Sw/GRt7NMfap4XvDXBVWg5EhBLYtmZYIqDTDFxD7TUWvtiJHt81RMPKrfSg6KY/hHyKFGTexq3XZuRdPYAc9WJ5m47DTwqwKeE0HqrXhrhufoWNpzJxLGGXfi2J6+SjgQGOSI0YxDzVE27OicTkQ/dw+/Z9zcw3UAKcGtqUe2bWbvSsGqQ9ajw6sjUSs89gdL1gLVRZiakRiIBuOxxKVOwB7uGSXljz8AqmNgpGlnbntQe4hIiGOCB0Ww1UCw6fQZB/c3Rb+8xW9rgwHwFNFiMpdZ8WIIe6C3A2zOhWOxA5ZnuAe3fmV7Sef99WY3mHhrYA91gLkW8RoITUxaEN3Qa4gG47kV6Yi8p+7fUfIG5m4FQKbi1H+6V6v+3Y+0MIIZ8SDHBEasQg5qke8fIq/Gv3wv79h7F1RZwSUtwHOLy5gh/qt0bVkIXabjv6Ncf2dDPe3l6PiFqB6DluORbNnosj2sScPcChMBnVqoXAv1asvu4Q4Mx5SfDza44Fyzdg/KDRWHgh3/YItTDjCAbVD8K9d/aQpX6GTv3sm/pBZ3cB7tLMXmjdbQKWrYhHTb/GWr/tn4EzI7hyIAZPXYUVqzaiY91AIcABxhMztfbdBjjLZ+DyLsShwZCjtgC3bM1mrFG07lNwZyU6LNMDnLv+EELIpwQDHJEaMYh5qqcsGRaNKv6NUadhb+Sa3xPglP/6VwxGizl3tbXDls/AqcEo785BNKrdGNXrdEKSNj3nEOCU7QGVAlF3iP6FBMcAp7Jh4nAE+AWhWfgUbL5XYP8MnLJf2q5f0HHxfVvIujozHJX92mn7uQtwKYcXoW9oJ1Su0gQjFp/Xyhy/xJB6ZhOCajaCv19DNO04Ctlm5wAHc7byGv84wKn9V2fqCoUvMVhn1xwDnLv+EELIpwQDHJEaMYh56qfGuzNzEVK7GWrV1LV+k/Qfk3cUQ+vZ200UkyIhhJC/BAMckRoxiHkqIYQQ4k0wwBGpEYOYpxJCCCHeBAMckRoxiHkqIYQQ4k0wwBGpEYOYpxJCCCHeBAMckRoxiHkqIYQQ4k0wwBGpEYOYpxJCCCHeBAMckRoxiHkqIYQQ4k0wwBGpEYOYpxJCCCHeBAMckRoxiHkqIYQQ4k0wwBGpEYOYpxJCCCHeBAMckRoxiHkqIYQQ4k0wwBGpEYOYpxJCCCHeBAMckRoxiHnqy5evxKYJIYSQDwYDHJEaMYhRSimlMsgAR6RGHPCUUkqpDDLAEakRBzyllFIqgwxwRGrEAU8ppZTKIAMckRpxwHsqv8RACCHEm2CAI1IjBjFPJYQQQrwJBjgiNWIQ81RCCCHEm2CAI1IjBjFPJYQQQrwJBjgiNWIQ81RCCCHEm2CAI1IjBjFPJYQQQrwJBjgiNWIQ81RCCCHEm2CAI1IjBjFPJYQQQrwJBjgiNWIQ81RCCCHEm2CAI1IjBjFPJYQQQrwJBjgiNWIQ81RCCCHEm2CAI1IjBjFPJYQQQrwJBjgiNWIQ81RCCCHEm2CAI1IjBjFPJYQQQrwJBjgiNWIQ81RCCCHEm2CAI1IjBjFP/VAUZFxD26AWqBsYgb2PC5SSV/CvMx0XJndA/HOzrd6vTYLxpFDfduKdXnZy2XTUCmiEVhHjMf94Onb3b4xKFQNRL6QvBs45rtVRy6qGbbK1g3c3tDqWJhzIx/OjK1AnoCGaRUxCoVLSwr8hOq18gd5VGyj72FXLYn8ItK0H9NorNqbtq7Zhzj6HgOZzkJhtVsqsbTREh2WPEeDXzlK7QFnuiAlnXjk2QQhRSEnJw6HJwzD37Fskp5iQmZyFZ1unId/8FjnPM1zW89JTkX9zE54WFCLjVaGwbr+nEO+HAY5IjRjEPNVTfuvXA9XrhCF81BZtPTIgFEsH9UK1uhHoNfssCtN2of6Ys5baSgCrMRxHxnTEoRwzjo5qA3//jlrQsaOHNOTfQkD4ZktZPioHxNi2qQEufetItJ6R5LijFta0cJd/D/NaBuNyvl424qfGtmOcig1F7/rBLgEuff0gVFVClCPWAKdS+HQDmv12G2rEVFEDnMle1QUtwBVmoGr1KFh/ZFhDnZXkjUMRe/Il7i6Mwvyb+Q5bCCFW3ubmoF/XwegeEw/T6wLkv87FpJ6DEX85HTl5b13WzfmvsXbkMEzYeg/vlAtOXCcfDwxwRGrEIOapnmDaG4uJym/F6gzS3bju2JRhRmSVQKQqN8nCBwkIrRysbDGjll8brf7Lo1MxZH8u8C5XW+9QOQgNp1x1aFHFEuAUWvs30gLPu0txiNqUadumhrQZIUF4INyM1bC261kGElfHopESll5byh4kLcG823r0+v67kRhWI8glwKEwE0cnR6FGo4F4lKdHrj8LcPbZtGeWUjst/IPRsHIgHjn00TYD5xeGGVfUwGZGff+2CKgx0F6JEOJEQeZt3HptRt7VA8hRr6e36Tj8pACbEk7joXqtiuvmV9h4KhPHEnbpvzyJ6+SjgQGOSI0YxDzVE27NjXR6tLj4fqES4NTQptwzs3ajZ9UgqDFlSJ0gvFZuokdHtsZRh0OFKgEu+A8C3KKfG+J5YT4uTu2IrRnqrdce4KY2DMJ9NwFOD0itET7d/gj18ZvbaDHnLgrMRtSOPoSh7gKcRj4WDOuNgKDR2tqfBbi9x87g2LGzuPxUjYrOqGEtsks4+m1PcygLxlF1n+NX8NCo/yhZFRaCZjNv2OoQQgjRYYAjUiMGMU/1BOPuX9BnW5ZTmbsA9zpxFibEzURg5Q56pXz9s17bejeFX5Vuwm/F9gBX+GQDuk2YhZaVm1nq2APco+V9EL70geOOtkeoB4a2hf936iNXS4BTgl7TKh0xeEQMjigv1V2AKyy092Jui2Btnz8LcH/6CFX5t121QDyzBE3xEapK6rqBltk4QgghjjDAEakRg5inesqSYdGo4t8YdRr2Rq7ZfYBTZ7b8KwZrs2Aqhy2fgVMfIebdOYhGtRujep1OSNImsuwBTt0eUCkQdYfos2mOAU5lw8ThCPALQrPwKdh8r8D+GThlv7Rdv6Dj4vu2AHd1ZjgqW7404C7ApRxehL6hnVC5ShOMWHxeK/uzAPdXvsSAd4/gX3MQEh4VCF9i0B+7MsARQoh7GOCI1IhBzFM/Nd6dmYuQ2s1Qq6au4R99OKYAdS3t1KrZCt3W6KGPEEKI5zDAEakRg5inEkIIId4EAxyRGjGIeSohhBDiTTDAEakRg5inEkIIId4EAxyRGjGIeSohhBDiTTDAEakRg5inEkIIId4EAxyRGjGIeSohhBDiTTDAEakRg5inEkIIId4EAxyRGjGIeSohhBDiTTDAEakRg5inEkIIId4EAxyRGjGIeSohhBDiTTDAEakRg5inEkIIId4EAxyRGjGIeSohhBDiTTDAEakRg5invnz5SmyaEEII+WAwwBGpEYMYpZRSKoP/H8bpLkkH4MZkAAAAAElFTkSuQmCC

[image2]: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAnAAAADlCAYAAADTJ8p6AABdDklEQVR4Xuych18U1/r/f/8LvVmj1yQ30ZtvesyNN9GIwC4sC6xUARsidrCgohLEGqyxRo0NVMReQETEggrSOyIgIlJ25/M7c2bL7CwqSUjiJs87ryfMPHPmzMyZ9p4zs/4/EARBEARBEHbF/1MmCIIgCIIgiLcbEjiCIAiCIAg7Y8AC97yzh4KCgoKCgoKC4i0IEjgKCgoKCgoKCjsLEjgKCgoKCgoKCjsLEjgKCgoKCgoKCjsLEjgKCgoKCgoKCjsLEjgKCgoKCgoKCjsLEjgKCgoKCgoKCjsLEjgKCgoKCgoKCjsLEjgKCgoKCgoKCjsLEjgKCgoKCgoKCjsLEjgKCgoKCgoKCjuLv07gnpQh5LsvMGb4cAx7fzw2nS5D+TZ/ODgORYeyrDHm/tsTzv9eZB4/vXkxn9/FdTgmhSahmeXWaH0w3GsIPIa+j9AF22Xzv4SroxuW3+g0556V72fL88I3PzyyWRYFBQUFBQUFxdsagy5wR4+ftsnZRPNVODKZ+mzqKmz9ORtHftqMyF01tuVeEws/HQIH59F8/jNnc7Ao1AfPWD7Qww1fzMvE9Us5+HKYB5z/swxX28V52vgyHT0mm+sIH+XBBM4d7sFHbOqnoKCgoKCgoHhbY1AFbuKkAB5vkrjUCV5w/nyNTb791lo4uPwXz5/dZWLlgadivu0a5n3oif+ll+HQ1GFwn3qcTS9h092Q/8y2blHgJm2u4MPl29RwcJ2Idfe72Dx3eG/b+y5u2F/TjeetN9iyPuS9cs6frrKph4KCgoKCgoLibY1BEzhR2kR5O3XmIv+rnC6PiCHuGDPnsk3eLHCdXXBmYnWdCVp7/mp8wqRrVWGXReCeZnHBa+2nbpPAtT1pQNh/hsD5g4XIecqmtV3hr2dXjffC/9aXoP7oDLh8uQbubDlOY+bZ1ENBQUFBQUFB8bbGoAjcz4dOWknbxYt5r5W4cC93/Cvuok3eInA9WPwfT/5tWtp3Q+Do6Il2ljMLXEvmawVO7J0Tw2mExvw9XUfNXjg4j8XzxtPs77/xpas7jjV0499MDh3cNTb1UFBQUFBQUFC8rTEoAqcLnW6Ty827jQcPy23yYlxP/JxJ1Ps2AiYXuPbCVDi4fgNXJ3e4TdzKc2aB63zBe+g0Ox7b1G1+hdr+kH/z9uPDLqm+/NWsvv/x4Qnu7nB0/54Pf+3KBM7lS5t6KCgoKCgoKCje1hgUgfv10Y2vh4k/ILD0ljn/e4GVwIllhju7welfM3hPmZizCFwPKs8stZpfjLNPrb+By5w5Do6uXyEp9zlas+Lg4O7P809KbuDKo2d82M+dzes0qp91pKCgoKCgoKB4O+MvEjgKCgoKCgoKCorfGiRwFBQUFBQUFBR2FiRwFBQUFBQUFBR2FiRwFBQUFBQUFBR2FiRwFBQUFBQUFBR2FiRwFBQUFBQUFBR2FiRwFBQUFBQUFBR2FiRwFBQUFBQUFBR2FiRwFBQUFBQUFBR2FiRwFBQUFBQUFBR2FiRwFBQUFBQUFBR2FgMWOIIgCIIgCOLtgASOIAiCIAjCziCBIwiCIAiCsDNI4AiCIAiCIOwMEjiCIAiCIAg7gwSOIAiCIAjCziCBIwiCIAiCsDNI4AiCIAiCIOyMQRG46upanDlz/rUhliEIgiAIgiB+P4MicKKgdXQ8f22IZQiCIAiCIIjfDwkcQRAEQfxGyhtfKFODjtD7XJki3hp6Udch8KE/41iQ84cKXErKBixevMoOBa4PyyJ84OY6BJPCkrAjtwkZ3kPgHnRYWRDoOA6dpzu+3VLJR4UX5Qj4+iO4eI7BzNQsQH8fGVMnwcvdE8Pe/RIZl+uk+XqvwcFpOAyyqq4u+Bie4ZmyjER37XX8b9x7cB8+DskH7yonEwRBvJ10N2BhTBh8/MOxN7deOXXAnNvyo3k4b+siLD7wgF1bq5FdpZeV+m20Fx1Bp3T/tWJBbBQme6sRu3B9v9MlejBtT5kyybGqt4vdB/KfWU3/NeSu1UK5pWI7vFTklAhNWVh7vUOegUadKht/mxGQduC2MvnrGKRjRE5nXjp2POy1JPruI72wD687FgaDpQnpULbJHyZwqambsXJlGmpq6u1O4D51c8fHUVvR3tmBMzs24WjpAA8AQx2cHN2ReKgAne0NWL/zOhO1K4gf44H513rxsvkuXJ3ccIo9TOkfb4KDoxuiTrZBOsf1fJrzR8lWVc5435OV88Duq4/xrKkMW7MbrKYTBEG8lQjP4TdrrzL7m/ghMFqZYtfWAmQUD/Da/BrqfpmP9n4EzU+3zTgkIEDzKul59U37VfX+FvoTuIHQW7ARMcER5vFnV9chym+mrMTbjAGqxBxl8tcxSMeInDjNCoRpVloSf5LASVi3yaAKnNjb9uBBCTZu3I6lS9fa5yvU55lwcH5XmUV+4sf4POU+kj/xxOzz4nNPBxydhsKgL0P6BC/MvdKL4jXfwOXbzdYzmgTuumTsU9zcsLJIj56zs+DmtwSOLv/Fmvt6tJ2Iwdj4xXDwCLXMa2hg8uaJcUkFlpxIbwkTRTeMGDGcresYqHeIB00fnFlu5Ltj4b29DrdSvoOj+xgMd3XHN6n32KFFEATx28jKOgvvKVplGhMnBSAzK1uZ5rTnrMBtWUeFiNCai7WhWtwsrcKeJeEo6WaXueoj2JlfhrryIvhE74HYufGycAv23axAfWkhf8D9ITCK3Uc60Nlj4DITuauE35w3FbTx+wurGHOPN/JlPGPLVcUf58MpOi3u1jQgOVwL8RYrzltcWY/GxlrEa0J43aJo1T7rYPVY92dZBA6YqloGUeSiVNGoqKvF/ewN+PGuWN5y0y6/X4bm+jJoYvaiRK+oV1+MtAK2YfoGBMzJwNmiCpzLWICTtaJc9CJk1WmrdRLaL2PF8btorn0EsQnF9b52vwIPL+/EsnNPeRmT1Il/H1Q14O6FnzBta5FplTlNJxahveUcdpeKWw+ER2RgT6xlPz4orUFjZSF0Gwohbp/ftM2ob2zA+thA6NZL9x35donkLA9FZkE5ahsakBoeyHOPDyRgX145LmfMwzVmreI+neWXgJqGRmydpUHq0RuoLb2GoHU3eHlxv8SmnUXl7ZOYdbDCZtlSz6UBfgsz+X6X1l5MNWBa2nm0NFXjXv4D1k7nsfuxJGg/hodZtduNu3XWx4hs/8WoY437z9j29VUI8Vbj3J0K3Dm+Gj9Xyd+Nyei5izXXX6B832xUm4r0I3CmY7yi+BrUsw+yRTdi3slmPm2xr0qS8d5CpIdMt9nXEnr4x23HldJGlBfd4plZalEardtkUAWurq6BS9ySJaut5M2eBE5fvgUOrt8p02aB68lLhPNna9CTmwjX77ayGSwClzNjNIZEKy5mRoETe9vEcHT/lO+8mgxfjI6/jPCRHnB6JxZfM9Gq7ymEg8s3lnn7brF5hsJ/7xNLjnEqehQ+Y+sismSsJ5O4f4uFmcB5Gp/SBLixZS1JXo3k5XPY9nyLtEeD+xRCEMQ/i1Onc/D9ZA2uXM3j46K8iblXUbE/DnWK++Av8RrM+cX0KrUX6rV5/GZ//rnUVbU7OhDJl19CX30C83deNs8n74GTC5y5d6U/gTPUYfYh6V8/EJpP4USTYNWT9eLiapQbRau/njLfyf7w9w/E977RqOsWpeo8tj2wXEdVMfshv2lf27ceU6dOQ4hvLHay661VvUaBe7gzBsbPpTiq0O0Q24FvDyzrhO6HCFt2yLyu8vX2iz3Ay8gFzjRtT4zG+EZH4n7GNH6jj9WsYA6RibNPBWQnas2f7hzesAK60FioNBsg3jdM4iuWTVAt5sPy7RLFwk/WA3RwliSDAZr1xkwfgjYWSQLHhUO8px7ElW5paqxqtXm/mNZhPl+O9bJPNotb0U8PnPAc6phUdJk3UoA6/hj/GzD/lE27yY8R+f7rurLGuP8sbX9llakduzHtp7J+ezxz101FlzhgqEb49oeScCkFzlAvO8aB2xvDIG7+VN0WiMtbePAYzrYJqD+6AJpVV23XmSMgSDMXG88UmzMmgbO0iX5wBU6MqqpaG3mzJ4GDvgKOjh5oUFx4TAIn7gBnRy8sGOeJbTUGK4HryomDo8t46xllPXAnosfB5ZOlVvX1FaXgUxc3OH+4mB8UDk6jZTNLvWrO/46X5QYmcK5sPuU2EARB/B5EYRPF7U3yJmKoOoTtD6y74I7MUQjcGmuBOxynRVKO6VsxA3YtCEU9u46laacZc3KBK0TGfeNtj93Ypx+o4oNygUs4XI6Wlqc8umTSI9J7Yz0eshHxRtrWj8CZeuDKDybgdqfABWBH0RNzfU/bxA/WjTftvkJ2E5e2NT04FjuYwFnVaxK4Ha8XONM6mTi3eS6utFmLZ0Dkbl6mP4HbN8Na4ExS0nEtFTN0s3gu/4cQntOX7sVF40d60wIVAse2NVE9z2a7uMAlX+HjImaB0200t0vr814rgTPUHjPv3zj1Cpv90vJU3N/Wyz5SK968+hE4I8VZaZimlqT+0iod9L3F2FNmaTix3fyDU62Okf73n6XtTe0i5kQ5k+0GI0wWJ/vBxzeAx/eTw7GxsKcfgavrV+Curw1FL2uXEr0AXVoBVmiTkPXEsrdM+9oKoRtLQ6Xe4z9F4F4VdiNwjJMzPjP3mDk4umNEVJZM4IDtU8RXl+9LJ4pM4ES8R1p62xxcJlgJnNj4I53dsIGd3FlRwzF5m/h0KKDt9nHkNooHbAfvcZPvwsd7QvGui7u5TucPlzBjL2aS6YZRo95h6/Ev+GSUwlrggIsLvuDrPuZfo7ns2R6MBEEQv42cnEvKVL+sDQ/A4UtFePzoLjb/ch9Cy1X++qzgcTX2Jkbg4UvxudVW4LpKrqC2+QnObZwD8RPkqyk63Cyvw5XbDRaBEzqhWXgQNWVFvDcnwi8apTX1uLFjLvyMMpAUxOYrqcHjO7n8utqfwOkrf0ZqzkMU5+Ubp0jIv4Gb6i/1EoUGzMaDyjrU1VTgIb/Z6qFK+BmC0IbA+fvwtPUplmskgbOq1/wKtQ4Bc7bh7B3xFepCHKsWb822Aie03kd5/RPczkzF8XrptfGrBS4Q+y/ex+NbpxGSctVYSuLE/EDj/UTAg3red4QHO6K5UKCrEDO3XEbr02aEvkrgFNslsptJ4oXiKtYGJZiu1vDcve2zcOByMWorHqHZIO3TVwocpP0St/kM6upqkF8uilR/AgfM8JuO6toqlJis19CIu5WNKM0/giSd9LoZhhpETIvibSFvtwj1IsUxYtl/9/NuGPff6wVu9dRQc7sLT3Ow+Y7lY6TGE4vhG7yBLz82Q3wFbTwWIL0iFo/xygfXoJqxT5qhqwBBwdP54NGEUCRmt/Kyyn0t0YfrD2rQ9KQZOxNC+P4ytae8TQZF4Ogf8iUIgiCIPx+53P3ZbAmLUab+AgRoF55SJv8RDIrAEQRBEATx5/NnC9yexbPh7e0PVfB03Go2/7zgL+FORiw0UYn/2B/pkcARBEEQBEHYGSRwBEEQBEEQdgYJHEEQBEEQhJ1BAkcQBEEQBGFnkMARBEEQBEHYGSRwBEEQBEEQdgYJHEEQBEEQhJ1BAkcQBEEQBGFnkMARBEEQBEHYGQMWuLv3HlFQUFBQUFBQULwFMWCBIwiCIAiCIN4OSOAIgiAIgiDsDBI4giAIgiAIO4MEjiAIgiAIws4ggSMIgiAIgrAzSOAIgiAIgiDsDBI4giAIgiAIO4MEjiAIgiAIws4YFIGrrq7FmTPnXxtiGYIgCIIgCOL3MygCJwpaR8fz14ZYhiAIgiAIgvj9/KECV1NTh8uXc/8WAndnUwACd5Yq04C+AvtCP0HqrZfKKW8dQd9+gTqDMksQBPH2khGuU6YsdNcgSqvB1OQc5ZTfRFp4BARl8lfQcioJjcYKooMXW098HcILzA0Phn/kJuWUX4fwBBEbC9DZz0b83m0j3j7+MIFraGjC4sWrsGbNRrsTuOIdOjg4uhnDE5+uvIvWm7uw906Hsig7YTpRfCgZuS3SqbFw/DvmeR2HhgG9VxA/xgOOzl5wcmJ55/fRJxZ89gsvc6PbUpV2mDtcJ2+zJGCAq1iXkwecnd15ed1Pj2TTfx1D2PJJ4AiC+DMQWs9iw9VKVFc8QvrcMJwo+20Pua8TuEOztb9bSiL805Sp34xc4EwMpP7ibdGQ3QoGTHfZCYQu3omSx49x9Mc3L4cjtMJPMwdrD17E45L7+GHLeb6v0i+WoabiIZZFalCrl4peWBGAtdct973WC6sRsvmueVxCjzC/MFy+/QhF104h99nv3SPEQBlUgTt48Bj/29zcwuWtoqLa/l6hCk1wdPRAlfEANpGf+DE+T7mP8a5uONQmHqAGuDm5o6WvDOkTvDD3Si96C5Lh6PKF9QXFKHDzr/fyUT83N6y8o0df/jI4eo2Ah89u1IhS1ZULR8/hcBwRJ5tZEjhX1R5ptLeErZs7WtkCbu9bjg9HDsew9/+HpMtdcGPlXrAizXsD4R6RxYsnBU2Ai8doLM1p4eskCtx/3h+Ff32mRZd5GQRBEK+nqqoGRUX3lGlkZmWjqalZmeaIUrC/0nIhXRscKF0bhRbMiwnHFHU49L152F0qlcn/IQTSkAGrZkXCRxOFJ2yGjLAAROuCEBS7wjjdQkaYCpO+98XUjGKkqKcbs73muirPbkJIQADUU+eCX7YZTwqPYl1CDFTaaRCfuyO8fXkdGcV6K1l8mLUVKlUwfrpWx8flda362SgxXXcQqFIjLGET3za5wM1Sr+R/zfXfq8K8k5a2itGsNQ/nrg3kZbxnHebjPfX5mKrRYMGGU3xc6LiP6aEh8NXK7w8CArTrZOMivYjcVcK2vQ/+q65JKUMtll98bt62n2ICbNrRal/pHyLxbDvfnl3TpiIlONpUCrqYn6BaIK2TicKNEWhWOpvQYdN+3WXZCNMGIiByCx/vqctFsL8GyfsK5HMSv4JBFbh16zZh6dI1XN6Ki0useuTsReD05Vvh4DpRmTYL3I0lH2NsIjvgui7C0c2bzWARuJyZozEk5qz1jDKBa6vMhyuTqOznQNvPOnhGZsLTyRMfLLiOXarh+OHuBTi4+cpmVggcY5yLGw4wgzMtU+jtRo9BsBE4fekmOI2STvYu3uUnCZx4jh4MfQ8fLL5hrpMgCOJNTJwUgLw8y81WlDcx9yqUAle+b5YkN/pipBVID7ToR+D0ZftxodM8m0WqDHWY80uDZYJ8GqM/gctdqzXKSh9Uyy6yOhoQs7sUPea5rHvITPUJ7ZeQlv+cD9cfX4wHfdZ1PdwZC6uOppe5OFxr6F/gZPWHan8wDvUg+qfH5rylbqBk9wz4xR/jw8KL20jKaYWh+gjOP1dYEhPhiB3KNzImgQNWaGbyzItrqajQW7YtxG+FrLyEeV8JfTiREot7xif8Vf5zYag/iV/qDOzeeBC5nQKCwrZbzbvKL9hqXGS5JsKm/dqyl6He+AbowY4Y+Mw+woc7rqzFPeM9ivh1DKrAibF6dTry8wttXqnai8Ch/SgcnMYos2aBQ08eE7z/IT/pU3y7ucJK4IqSv4TLBMU3DEaBGzl2PLyc3RByqJGni9dN4CJ4OWEcnJ2Gwdn5PQjsycfB5SPZzEqBE+DBJOwyu/aZlmnKiwInXvMsPXAGBIwdzrZlCM7WSZcG0yvU7qwYVude47wEQRADQxS2Sd9rkJ194bXyJqIUuOtrg8Ffor5B4ETObE1EROJu3gtkkTQ9An6w7q2xEjjV6wQO8I/czWTkBI41WH9HYitwAp6fX4kS04wvr/LeOXldvXlpeMhGbqZH4XRhGWoeHMWOR/o3Clzxthj+fZqh9hhuyN4oy+veGaXBsvOS/Ijb7JeY07/AMQlUrzb2spmxCFzr2RX87c7GUEnkTG01y3e2rLyEuK+2FTaiufYmZuwpMefj1ZLshYWkIzl4IR+OUaWYp4uIPaTWaybAL2qPTfvJBW5nlBpT1DoEalkEanGwir7t+S0MusBVVdXayJtdCZy+gr9CVZzjFoFjJ4izoxcWjPPENvHskAlcV04cHF3GW88o64E7ET0OLp8staqvrygFn7q4wfnDxeysrmbCNVo2s0Lgeh7yV6jtglLgAHdWrkmwfoWK3ieI+GIUhgYd5l3cJoHrOSUKnKVXjyAIYiCcOp3DxU0Mcfh1KAVuTZDxezUrgSvElrtS94tc4ETObZ6LK23CgAUuTRthHOpf4AKYwAnt57HTbBYSUTYCx2rIT8dNYzed0JTFBcNK4G6s5wKXrg2TEn2FrxQ4ef1i7+LFZwY8Pb0Mch+T131kjgZzfqk3jvVCvSbvFQLHRCk4XZGzCJzQfpH3Ck6dcYBPMW3b1tAAKHXJsq8ERKrizfkYtfSa98DMYGiTL/PhOJV0DzNxbU0InipWLUC7wab95AJ3OE6DhMPlaGl5yqPLepcQA2TQBe5VYTcCxzg54zPZjxjcMSIqSyZwwPYpw/mPEaSLkUXgRLxHeljmdZlgJXCikI10dsMGdqJnRQ3H5G3iv40noO32ceQ2ikd2B5tvqOxpRhI4R5cRGOrpyeuMPVzJpygFbtWXQ+DoNhqjhnhKr1AfpWPYe5/hwxGeGBl+nH/rQQJHEMRgkJNzSZmywfQjhpqKEqTHhyGzoluaIBc4sYcpZBmqautxcJEkMULrfZTXP8HtzFQcZ3f8gQpc5aEE7Lv+CNVl98x1KQVOvN6GqaKx/OB11FU94tfFLaFalNTU4WZlj6y+HqhDklBRVY7p/mH8mtyfwF1I1iG3rBGNFae5wHXnpeFk+TP+QzWTwMnrF5cfEj4dkcFrjDVJyOsWWq4iRadFweNq7E2MwMOX4rN9fwIHtN/ajuhVB/G4vBxnD2aw2i0CJzJVF40s4wdq5m3rrYFPyCJsPp6L8scPsevHM1ayLbRcQPLFVr7NQbofpVx3E1qNlSapFD14QhcCfKch7/5jFBdcxoUGA0r2z7VpP7nAGRpzkBSkw82SGjy+k6vowSMGyqAIHP1DvgRBEATxZjKmRWNzkVFmCeJ3MCgCRxAEQRDEqxEaz8DHPwL3xG9gCGIQIIEjCIIgCIKwM0jgCIIgCIIg7AwSOIIgCIIgCDuDBI4gCIIgCMLOIIEjCIIgCIKwM0jgCIIgCIIg7AwSOIIgCIIgCDuDBI4gCIIgCMLOIIEjCIIgCIKwM0jgCIIgCIIg7AwSOIIgCIIgCDuDBI4gCIIgCMLOIIEjCIIgCIKwM0jgCIIgCIIg7AwSOIIgCIIgCDuDBI4gCIIgCMLOIIEjCIIgCIKwM0jgCIIgCIIg7IxBEbi09ZuVKRsGUoYgCIIgCIJ4M4MicOtSNyhTNgykzNvMnU0BCNxZqkwD+grsC/0EqbdeKqf8dbB1GjbGV5klCIL4RxIdvFiZ4lQeWYCHvcrsX0NaeAQEZVJ4goiNBcrsW0/LqSSo5mUq078SPYJi9yqTr9yX/0RI4PqheIcODo5uxvDEpyvvovXmLuy906Esyk6wThQfSkZui3TqLRz/jnlex6FhQO8VxI/xgKOzF5ycWN75ffSJBZ/9wsvc6LZUpR3mDtfJ2ywJGOAq1uM6EiPfeZdHuV42WcbZ6aPgvb1WGmHrFLdwmzgANzb/C3lBgiCIPwGh9SwyCurR0NDI488ib+NM+GnmoOBBGfKyD6DRoCzRP4uDNci8fg8PCq/g6I9pEAXCZ+ER1NXW4NjG+dha1MnLRU3xw5RZhy0z9j7G9z6JlvFfQYS/uBxrfgiMRkbxKy70g4Ye9zKiUFLTgMd3byDKPwhPB9hOA+G3Cty5pVrYroYBqsQcZZIACZwtQhMcHT1QpTh/8hM/xucp9zHe1Q2H2kRZM8DNyR0tfWVIn+CFuVd60VuQDEeXL6yfoowCN/+69Jjn5+aGlXf06MtfBkevEfDw2Y0a8YjtyoWj53A4joiTzSwJnKtqjywH7IwLxTtDhmLYBxNRb1xPUeAkcRwKQV/GRPEDmAROyruj61E6W+ZUXr40fSJGzjhnqZQgCGIQEQVuf6XsQio8h2ZJtiRUQjsiNhexS1wj4qLCMEUdikMFTeaiLUXHoFEFYu2h23y8r/EGglX+iEiwXAt3LY+DeupcNMuv1ezaN31/BZT6M0u9kq1PDvZVWKYERu9DW/Yy1LP1ab+Ygisdyv4vPfxSco3DAnzDd/IhVfwvuLZvDpqNxY/Eh2KjLtxYzsLZrUuZSEbjXrtUMHXJXPhMUSM+7RRKOqVchLcvJn3vy4UtI1zHcz8E+PHcpO/V7A7Qi8hdJTxffGID/FQ6nHn8QrrHsPacGx4MtS7OSnp2xUcjUKVGWMImqVx3NaK0GgTFLJOVkgSuRzbuE76DD/3yQxJ82Xr6auPQd28bbvEeB2B7pLR+e5IX8Ol+2mhcqZHePOlLj0Llo8asNSf4eH8C11J4GGo/LbZfrpMSbN8nxEbCe0ogduU189S5pQF8232YsLULAmvr42JBePP28EVer7QvTSiPgZ3LZsObtVGhsX3/7pDAKXmeyeTnXWXWLHDJn3hi9nnxoO2Ao9NQGPQWgSte8w1cvlV866cQuCmiwBXp0XN2Ftz8ljDh+y/W3Nej7UQMxsYvhoNHqGzm/gUuwN0N7iP+DRcnN3y76TG/WIkC5/nuF/j8i29tBO6zL75m+f+iV3+f5d/jdRwIHI6pR9ut6iUIguiPqqoaFBXdU6aRmZWNpibp5qvERuAYP4SFIfnCU3Tkb8INUZj0xVh8qBj11Q8Rroo0PvwKiFZH42FlFZIjtXjOksfnafGgrgX38h9IJZ5eQ2zaWVTePolZByvM9Rtqj2FPmVLfjDd9Qz0WZrUYM3qEbCwyC1x+Wgik/jU5coHTw3f2LxDXTbX0PNpbzmF3qWQ24REZ2BOrNc8lFa9HQPx21JXfRACTVnE+v2mbUd/YgPWxgdCtl16LRvivRUdHB7rZKpsFLjAKmwraWP45GzMJXA9UwUmoqy1BgC4N15gUvizcgn03K1BfWmjVaVB+vwy1jS24tmM+Sli9pT/NxJXSRpQX3ZKVUgocayNfqfNgll8CW89G1FaU9ytw4vTahkbUlNyEWitJodBRg8YnLTi4JAxd6E/gBESpolFRV4sYdayUYvt+0aF7aKx9jCDVfJ46tzQQ7aw9Orp62RwWgfNbmMnbSVwVk8DZHAOGBkxLO4+Wpmo023bj/S0hgVOgL98CB9fvlGmzwPXkJcL5szXoyU2E63db+ROfSeByZozGkGjxZJVhFDjza1X3T7lw1WT4YnT8ZYSP9IDTO7H42tUd9T2FcHD5Rjaz8RWq+2i89/44vPfBJJ4VBe54l7SujiPn4FyP4hWqQuDkr1D/z8UNN5hLvu/ijup/yEFOEMTvZ+KkAOTlWb7HEuVNzL0K+SvUxieijPAkLq0KQ3DyJWmc3cTTCqSHW6E5i/eQCc8uYMcjo4Tpy7H4dCvy06NwrLBByhnqcDhOY+51mq+yfBPVdzcD52x60iw3/ShtKv9rqD+BS6ycSeCyFmpseu1EyZk8JRBqdQC8dYvwglerRzATP1EkYjUrIDRm4uxTAdmJ8ld/ejzYHg1jxxv2crkzyQj4PAnGdZa/QrUInPwVqiRwPfnpyDN+blO0ORxBbB301Scwf+dlYzkL1/atx8KZsZg2ayZ2snZsPr8aG88UK0rZCtxKP6OgyXq4+hU42fTOyym4w6b3Nd/G7GlRmDE9Cjd7bQVOaD+PbQ+kbeq6sgaPxUHZvi/cEMrb1PoVqkXg5K9QJRnv5xgQnkMdk4ou293/t4UETom+gr9CbVDIjUngxBPK2dELC8Z5Ypv47lMmcF05cXB0GW89o6wH7kT0OLh8stSqvr6iFHzKpMr5Q3YAGqrh4DRaNvOre+BEgROa9sHBIxpZ7Cw8N2sMJm6tlgqYBQ5c4J7J5i3fPBnvz9nKpNBPliUIgngzorBN+l6D7OwLr5U3kf564ITm81imm42ZmgQpIRe4ljPYVy4K3HkbgeP0PsU0dbT55t3S8lSKp7IrXO99zD5ca/VKUcQkHSW7Z6DL0ITj80N5r5VJ4FpOJyHP5rWbpQfu1OIQtPLJLzH9QCWXvY5rqZihm8Wn5/8QIhNASeDqTevXIq6/TOCYzCSq5/HhqH4ELk07DRn3bQXuWpOlvtbnpl9eGLBrQSjfBk5fIdILjdPYsLkdhW4sDdVK319zlAKnh0/ELj4kFzR9yR5cM4pjfwLXdXUtililUerVfFxfuveVArej6Il5n/H1kO17sb3EofPLf53A9XcMFGelYXOR9Gr37w4JXD+cnPGZ7EcM7hgRlSUTOHYgTxnOf4wgPZBZBE7Ee6Slt83BZYLiFaoBI53dsIGdVFlRwzF5m9hjxp4Cbx9HLv8wpEP6hs24HuYeONmPGNLZU0x/AvcyN5HJnwdGDxuOPpnATRvlAWev9zBm1AhU8HP5BRNQN+iOPDUvhSAIYqCcOp3zRnkTUf6IQXwpFh6+CTefCxA6b2NpTgu/iesW/4TqmgrEB5okSHrd9qiqCisjAyF2qN3Mvorm5nok6UL49dHQmIO4zWdQV1eD/HLrn2llJoXBJ2QR7pSUo/BKFsQ3qmbpMDQiLDIK4Vul18EmgROXGavS4lzBQ5Tcu4mzBzNYRv4KtQe+sftEA8WCrBbjNVrAg3rxhSETkB3RkP0ejV33KxCyaA9q6upwuVD85qt/gdvCpKqkpg43K3vMAnc1RQfNwoOoKSuC+Rs4oQvqiNUor63Hzav3+SvCrpIrqG1+gnMb56DU5HtCGwLn70NuWSMaK05zgau8no2mJ83YmRAiW0fjjxhqG/D4nvgjhmCjoFoLmvgr2IC5O1FbX4uVIUaB89Eh/1E1aiqLEaKey3Mb2HY8rH+K6ksbuMB156UhQLtSJowCQgNm40FlHe7n3ZBS/Qhcc1YSjt2pws1rxWgxfwMHzPCbjuraKpSwg8G0fjbHANu3dysbUZp/BMkX2yEwyQtJviAt62/KoAjcQP6Nt4GUIf5gBHaWG9rg7ORp1XVOEATxlyC7iRP2gZXgEX8pgyJwhH3w4mIS3DxGY/c94/coBEEQfyUkcHYHCdzbAwkcQRAEQRCEnUECRxAEQRAEYWeQwBEEQRAEQdgZJHAEQRAEQRB2BgkcQRAEQRCEnUECRxAEQRAEYWeQwBEEQRAEQdgZJHAEQRAEQRB2BgkcQRAEQRCEnTFggbt77xEFBQUFBQUFBcVbEAMWOIIgCIIgCOLtgASOIAiCIAjCziCBIwiCIAiCsDNI4AiCIAiCIOwMEjiCIAiCIAg7gwSOIAiCIAjCziCBIwiCIAiCsDNI4AiCIAiCIOyMQRG4+8UPsS51w2tDLEMQBEEQBEH8fgZF4NLWb1ambBhIGYIgCIIgCOLNDIrAiT1sb2IgZd5m7mwKQODOUmUa0FdgX+gnSL31Ujnlr4Ot07AxvsrsH0bR8R+xYkECVm+7gIb8X7A995myCEEQxG9Aj6DYvdaZqkOYoV5rlRtseot/wtFqgzL9h9NyKgmNgjKroLsGF7cmwXuK9s1lB4HeZ02ob+uG0NOhnPR2oC9GWkGvMvsWoEflkQV42M+qnV0ejs5B2HckcP1QvEMHB0c3Y3ji05V30XpzF/be6ecAFjpRfCgZuS3S3lg4/h3zvI5Dw9jRfwXxYzzg6OwFJyeWd34ffWLBZ7/wMje6LVVph7nDdfI2SwIGuIr1uI7EyHfe5VGul02WcXb6KHhvr5VG2DrFLdwmDsCNzf9CXvBVsPV0cB6nzL6RvsKVcBzmgxVn7uL67WqcjBgG312NymISfQVwcBmvzBIE8TdEaD2L9MvlqKl4iOToQDzuUZb4begrf8b0QRK4os0RaJLdSJf5R1pG/giEDsw6VItXqeFABO7QbC2Wnu/nXvRa9PBLyVUm30jH5bW40MQMxKDHtRQtXnH7Qd0v89Hez3qna/1wutky4dbGSKy6+vs7OyL805BnEqOBCJyx3f9IhOf3oZq2GvdKy3H+0JZXtpWSvI0zsfbgRTwuuY8ftpxnbV2NWTtvoa6mHPfzzsAnNI2Xu7AiAGuvW/Z764XVJHA2CE1wdPRAlaL18xM/xucp9zHe1Q2H2sQD0gA3J3e09JUhfYIX5l7pRW9BMhxdvoDVcWwUuPnXpQPMz80NK+/o0Ze/DI5eI+Dhsxs14tnclQtHz+FwHBEnm1kSOFfVHlkO2BkXineGDMWwDyai3rieosBJ4jgUgr6MydgHMAmclHdH16N0tsypvHxp+kSMnHHOUml/AveiFOPfH4WxE2OxLqeGp84tD4CHC5Na9RK+nQ27AuD8n0DMmpOAeXvuWglc0d7F8PIYiVlbctEkrqcocMb12VA20MObIAh7RBS4/ZXG89xQh/ijDai9vB3L42Ph7RME8b7eUnQMGlUg1h66zYsF6n7EHeO9uHh7NHrYVUYVf5yP11/fAz+fAKSkLcVUlSRwQlcFpmkDEZ8qlelrvIFglT+8VToUyro4as+shc8UNZbvKzTnOL13seh0izQsPMfUzXf5oKH6CM4/l+bftTwO6qlz0cw2pff2VuQbH7qFltPIfCKVWaedDnRXI0qrQVDMMhx+ZBEK0zpFJOzhIjHpe18ePok5WKKeaSzFtnPhaSuB66nLRbC/Bsn7Csx1iWSEqYx1qLgkKNuwuywbG5bOxZQpAcgzt0H/AiffNpFF00LhrY5AcYc0X0H6VDzrfIEXXb1WAnd261KrdhcFTlyn79WSbJiYq16J8OBU41gvpqZfQ+y+Cmm06w4CVWqEJWzi9xKhrRDRumD4aaNxpealdB9l+2RueDDUujgr6Y3wltpwkvc0LnBhcQvh4xOIXXnNfLq4v2N1QfALno0WcUZZu8tF89RirfF+bTrODFg1KxI+mijEbbzGp7QUHobaT4vtl+v4eGsRG/dV8+nG3c9JUE2zjHAEtGUvQ71BOq4l9AhOL0TuWmNbsnv19P0VlllEmMAtPPXUPHojNQji0bRr2lSkBEcbswJ0MT+RwCnRl2+Fg+tEZdoscDeWfIyxieyE6roIRzdvvgNMApczczSGxJy1nlEmcG2V+XB1ckP2c6DtZx08IzPh6eSJDxZcxy7VcPxw9wIc3OSvPiWBM/cGGgUrwN0Nx7uAks1+cPlmA0r0ih44hcBZeuD64MzkVHwQjh3pgZ/kj542AidgKBPUQnYiP96uwTBRVlnxnhddfGrCR55YmNvHBc4jaA9KK6tQ3dxlFjh9+Y9wGqnl9Xzj7g6n0XOoB44g7JSsrLP8lZ2SiZMCkJmVrUxzTAIn9HbicHI08p4J/MYVuatEKmBowLSdj/hg7+P9OMyeZI/PC0TC8SaeW+SfKNYi3ViZAE433vjlPXBB/sv4X6H5FA5UGbAxOIyPv4rKA3P4zVBOuGop//v86lrcN040CdyDHTHGh3kBgaHb+TrPz3zCb/rF26IRtUv8rEaA/7KLuJQc2G+vi9U6KXrgxPV5KlamL0H6rR6ZwPXBZ/YRXqbjylrc469tJDLCdZYep37aUJQGk/RaUApcn+22yZgauRPFekngTNtkEriuG+k4Y+xVM7X7q3rgQsK3o/3Cajxi69+YmcjuIXqo196wLvQyF4drDVbSfCYpGNp1N9B8cnG/PZKv6oE7Mkej6N3UQ5N609zuSpQCpy/bjwudsgLsuIvMKOaDRVui+L00WrVKVsCEHr5zjilyFoETj2suqS3ZyHoinQe8T+NuBnKMsmzGLHACetqrEeI/j6dX+c+Fof4kfqkzsPvrQeQyOSeBU9J+FA5OY5RZs8ChJ48J3v+Qn/Qpvt1cYSVwRclfwmXCJusZjQI3cux4eDm7IeSQ1DtVvG4CF8HLCePg7DQMzs7vQdA/ZILzkWzm/nvgTAInNO2Fg0c0snoGKnDA2q88sSS/iy1zqPWBrhQ44YnsNbIUl9k5EjVuqHk8/MRLLnCe0We4FIqYBK5k/bfW84viRgJHEHbLqdM5+H6yBleu5vFxUd7E3KsQBW7rjRo0tli+iZULnKH+BI6KdzdeuJndYGtgqD2KOP/l/IabcFy8Vko3VrHsMeOd3CJwvfjeV4tArY5FMBafaWXXmBbMCdEgIDbFStTi/SNQXNWAKxunQ3m/rNgfxyVhuWa2OWeSiZ1RamP9OkyZEs+nRQSn4wa7/s6L2Ia1wUnMaPJwiL9G6UHKDB1Sj95Hq9zkjOu0P7/RRuBgqGHr/RTtOckQX+yYBU5fiilqabmBgVocrLJcreUC118bDkjgWP0229bzCJEpJ9DYVI8QzQbc7O1f4G6uDzHPZ2r3/gWO7TsuNXoEJOUgNEa8jwnwm58F8TOfm+lROF1YhpoHR7Hjkd5K4Pru/IgQ1Tpeftey6Zi32bpj5FUCJ/baikPi/k48kIum+gr4Lb1gbnclp2164Jg8bk1EROJuXKp+ydvXT2PcVv8A3GMNYHhWilCVlk+3bLIAH3MvmyVnEjjxuM5uFXBppY7PYxI4Q80R7KtQaD8TuLk/l6K5uQrn1kaixjg5Xr2C/w0LSUdy8EI+TAJngwEjmGiNj9uLzq4u3DyxjZ14zy0Cx/jKxQ2eTu7StxMygUP3LTg6umPtqXvoetGGfRlnrHrghCenmBx6QezDuhD3HiZsKIP4g4PNE4dKdbMT0MFxmNW6vF7g9pkF7s6qrzBSd5glu2UCB4xi25JjfOXL/9/4Mxzdh8HDb7dVnTYCx8p7Orlhyy3xSUCPztoysRCcHD25rImi1p/AZceOwkdJBeyBciMcXT7BM3bw9rVXobyxh1+sHJyG87Kdg/Q9DEEQfx6isIni9iZ5E7F6hWrEugeuHtHG4d6y/fiZ/2hAQHNWIh6eWSH1TJlurIYGhG8u4mXlPXDa0M1SXTa8QPSecuOwgUlDJh9qPL7QRuAgtCBm9zUszJJev4mYZELsZWtVlL+XEQ1d+kX8kP8Szy6sxsWNUVY9b+IyuKQouLhC7KHrRdi2B1blVwbNRtrUBXz46ekkNPDl9SFwxSVZKQvWPXC2bTgggWP1K7dN/2gPLhmf9qcFvlrgXuSloeCFdaO056yQPgWywgDV0ot86NpaHS4aDc8vit3Pem8hLdDYM9lXaCNwualhCFh1VZrO0D/eh0vSyx9OnGo5sk3GKBO4B1zgpP0tvWBix48ocMZ2V3I/Y5rxeLAIHKf3NtLFnlN2z0o41mDJyxCnb7xt6Ro9kxiMctk37XKBE4cDFp2CNkk6Z8yvUMWeu6CVlllErF6hCkwepR6/sEDJoZ6wY2RDofQdIQlcfxjaEOn9FZydvfDfwLlIPVliJXBtmdPh/LFkw1YCB/EHQpfx9dgxcHYfjfCk3VYCJ7Jx4nCMjj6Nn4OGQr3XcsGQ6GYC6CU7uRWvUFmsuqvvV+DEJ4xvx46G55jx6JEJ3JOrG+Dl6gnXYeP4q1aRsS7Sa1wrRIGTLWfxjT4I7Xcx/t+j4TZ8LD6dLL17z9sShyFunhj+7mfIKOpFS9Zi+KTkWZ52X5bh248/4ttw/ce5fNn//ioAM/ZJ3fyH5/vD2WU4ki+1m+YgCMLOyMnpXy7kvFHgGM2FRxCg0mD1Afl3Xi/hHbbNOGy5sbY/OIMQf38Ehs/BwnVnpKkdJYgODoRaN5vfiA8vjcPkKRpoIuajVSYUNRe3w2+KClNj5kO69VmzKVRtlbfIhIDty+awOgOx9brxWzl9FQ7M9Ae/V7Prrt9CaV1u/ZQE78lqLNhwBiWy7+9M67TmsPR9XXZaAkLUakxfIUml0JCJxaeNN+yeSgRF7uCvTLuqLkHHtjdomvS9sQkrgYNtG75K4CYbvwET4zHfLcptE5A+X/w+UYuElFP8B3NygWvPTUfCfukemLUpyardxR612GANpsbJ7/PsXiW+vlQQFJDO/wrt9xEaEAB1cAwu1EuvUJM3JPPvIw/fbeO9lE1XfoQv22+xidaveFsL9yNxmg4BEYsh2AictL8Xx4TybyGXHpRegYrt7q0KQ5nsdbR4rM2PDMEU1VSk/HyX7dqzCPBlx8msFPx0Q3qV35B3gOXUiIhfz8dT4qIw2TeYT7eqinFu91qofVSIiFuFTkEucOIPOCJwxyh4FoED76FdPjsak1m7r9p5RSFw7DgoysAxVok6Ypc5Z2JQBI7+IV/7QH93LT741wg4vz9LOYkgCIL4k6lvacf2+DAbEfgnIu+BIwbGoAgcYR+8uJgEN4/R2H1P2f1GEARB/LkICFH5Y+ke61+Z/lMhgfv1kMARBEEQBEHYGSRwBEEQBEEQdgYJHEEQBEEQhJ1BAkcQBEEQBGFnkMARBEEQBEHYGSRwBEEQBEEQdgYJHEEQBEEQhJ1BAkcQBEEQBGFnkMARBEEQBEHYGSRwBEEQBEEQdgYJHEEQBEEQhJ1BAkcQBEEQBGFnkMARBEEQBEHYGSRwBEEQBEEQdgYJHEEQBEEQhJ1BAkcQBEEQBGFnkMARBEEQBEHYGSRwBEEQBEEQdsagCFza+s3KlA0DKUMQBEEQBEG8mUERuHWpG5QpGwZShrAH9Oy/PxBDtzLzWhob2pUpgiD+RuhfPlOmCDtB6GpBjzyh75KPcWzKvAZ9Rx26BGX2nwsJXL/0YVmED9xch2BSWBJ25DYhw3sI3IMOKwsCHceh83THt1sq+ajwohwBX38EF88xmJmaxY64+8iYOgle7p4Y9u6XyLhcJ83Xew0OTsNhkFV1dcHH8AzPlGUMcHV0g4MsGuUz/C5eYuyokXB09sLH301F3PpsZQEz4vY5OHpxcfNwckOdYh2+dnWD03uLrJNvIPyzD+Ho5I53xk7AnptPjFLYB2dHzwELYs+ZmXCdskuZJgjiLUDoLIROo8EU1VSkH76pnDxgtoRGKFNvpPfJPcwIDYYqeDrOV3Qhb+sidsXrhy52fc43CmJ3AxbGhMHHPxwxC9LQy1LbE6ZjircaYbOWo974bLknJgARGcXmKkQSVJFW4yaKt8fgxgvL+OX0OASHRyFIm8xWsg5q32BotSmWAoOKAXNXZCmTCvSYER6K76doMH/N7gGL1EBpOZWERplw5a7V2lzflWVeR1v2MtQP2j3Q/iGB64dP3dzxcdRWtHd24MyOTThaqjzkXoGhDk6O7kg8VIDO9gas33mdnaRXED/GA/Ov9eJl8124MgE69ZydNo83cSGLOtkG6djV82nOHyXLK+QC56raI8sNFi/Y8odwgWy/nYZJXu5YVtinLGTDYAncZy5uOC9eIbtrmbS5w5PLMQkcQfxdEFrPYn+ldDYbGjKx5a54wv96fq3A7YzRIHJjgTL9eoTn8Ju1V5nFYlWceXieUdKWqaIRGxPMBU9EaDqNmEiN8TouR0DAnCPwiz9mHNcjMO2WeWrBeh3efMX9o9HDLyXXOCxgXkCwVafC70UpZyRwgwsJnJLnmXBwfleZRX7ix/g85T6SP/HE7PPis1wHHJ2GwqAvQ/oEL8y90oviNd/A5VvFt34mgbsune5T3NywskiPnrOz4Oa3BI4u/8Wa+3q0nYjB2PjFcPAIlc3cv8CFvecJZ4/RcGTT1t6WnivFdXBiuaFeX3OxcXQeine8PLkkeo16D16u7hiill+gTAIn4MGxufiUTf+lWYD+0QY4jZnPS4hixryT1+3g/AHPmQROaL/Elu+O994dzZchCZyAj5n8jhr3KZvmgQq91G6OLsMx8t2x8N5u7H2EReCe1eTCyWkIPl91B3KBe3puPhycPDCErZfbJ4txqV08w19iKFu++4j34a7aaxa4SwvHw83JHQXPBdTsCoCj+3v4YtwYGO8dBEH8TrKyzsJ7ilaZxsRJAcjM6r/3Xi5weJGLtXndEJ5eQ4pOi7s1DUgO13KBEW/KFx9Vo/JeDnTr2cMvO9WF5vOYueEMqsvuIMw3jFfx+EAC9uWV43LGPATo0nhull8C6hsb0fDCZAA9UK28gk7jmAmTOGhDM8y5JP/FzF+KkVbQi/acFbjdj1/KBS5FE8z/RmvSkc8ePBOON0j54Dm4vSnMRsb0FQdxqkVA5kKNUfZ6MdlXC38mSYHxh3EtRSMNL8xkhRuY7GWgqvwuAgOTcLJWXNteBK86g8b6anad7kXIqtNsuAoh3mroFu9BHcvr/ObymnXaRDS1tKCwQtbdx67Hqvjj/K/ftM2snRqwPjaQt68FucCxO071EexjF25xn4jzNDbWo4OVnxq0yVj8EW8vsZzY9rUNjTiWOhuZfH2BB6U1aKwshG5DIcSXpUo5y10biP0X76HkZibWxWjRKsjK9NsGAqKYMD+oqsONuw1mgUubFoll2eL9RA//uO1oaWlESdsALfBvBAmcAn35Fji4fqdMmwWuJy8Rzp+tQU9uIly/28pmsAhczozRGBKtuJgZBc70CtTR/VN+IanJ8MXo+MsIH+kBp3dimSy5o76nEA4u38hmVrxCdRnPHOcGk6kP+VR96UY4ekXi6HNJssR1ELH0TL1kIiX1svFXti4TzDVLAueBKT5qfPKvYUxG3bCuoHPAAncyYgS+Xl9iLicKnDivo8d/kZy8GpHjh0O994m53ZQuJQrcl1PU+G78R0zUhuDDaeKFxiJwYp1H+ZsNAe5sma7eO/FkfzBcv7dcgMXtdBrxHltfHXY/ljr/S9ZPhPO7vihtVy6RIIjfw6nTOfh+sgZXrubxcVHexNyrEAXOxz8Yfj4qRK86wnOH4zSYfahWmt58CieaBKtelQTVYpxkD5JH5lh6tEw9cAGa9cZMH4o2h3NhmqVeacwZEVoQsbPE5npjErhzy4KN07oRs6fcLHAV++Ns3iyILPZVMcnSsu3WorBFmtM/dj/K2ODmsHAI+nL8cOMFqg/N5aIjJ4MJqpgSWrKRmieKVS9CZa9er6VYeqMe7owxz995KQWq0O0Qy0fukq6x8uErq7SI3VdhHhbrSNCE4XGbUiEtAif9ZUONmbx9LVgLHF5eQ3phH98npnlE+hU4WdurdNJ1+fCGFdCFxkKl2YCbvf0JnKwHTl+JBVkt5jL9tYHQcQG7Six7U1yvzYsiYXE1AUGauXjS/c+TNxESOCXtR5lQjFFmzSLCDI4J3v+Qn/Qpvt1cYSVwRclfwmWC8UA3YRS4kWPHw8vZDSGHGnm6eN0EjE0swOWEcXB2GgZn5/fYxeAhk6yPZDP30wPXc4Yvn/OMraubGjvYlad/geuFk/HbNfTdZnV/aaoF8leo6GvAsehx8NT+DH0JE7h/zeMlXidwe/yHMkFrNpcTBa6Pya38ez2xx+11AsdfobIT8FsPd7Zun0IucB+w6XnG69FI1m7OX65jcvYdPKPPmOvgPY1O7nAaFYgfHxi/cOkqwUgXlhv2FZ7/M89pgvjDEKVt0vcaZGdf4MOvQxS4bYWNaK69iRl7JPnYGaXGFLUOgVoWgVocrDJYCVyiah6O1BpYOY25HkngBPh4a6T5WPj7qXivlo3AoQfq1dd4748ckzi0nl2BGnFZ3UXYLX4aYxQ4cR3uKP0HYg/cTDQ3P8GWaC2kT+CYDM05BraKqDgwB7UFW1DC5ms+uRhWXsTQqZdLA0IrAlKu43UCd3O9zvxKtq9oK4L8xR7G/gXuRmowonaVmofFOl5UXoFaFYESK4vsR+Daz/H2tWDbA3egSuqBsxI47esFLkS1jjX9I0SmnEBjUz1CBiJwTLZnHKgyl+mvDQz1J3CswbK+4nqFa3RWslyffwg+QXPRqrzJ/AMggbPBgBFMGMbH7UVnVxduntiG/fnPLQLH+IrJhScThybxIJIJHLpv8deKa0/dQ9eLNuzLOGP1ClV4corJoRe/uFyIew8TNpSx+SuweeJQqW6hmYnPMKt1sRE4dDIp80Bxp4CTMz6Gp3oPF6qBCdwXsnosAtdVewkrJo7CkFB2wnadY+XG8Xn6E7jhTOCusg1o2h8Mp3c0fH7zN3A9N9n2DUOl+DOhnqd82hsFTt+GsS5i7+JXkATOgz9dLfvYE/9bdRP6lmtM0rwwPvUhu3akw9H1c4hvS160tJq3c8P37/BXtjVsIS+apNe0omAGHmy1WiZBEL8fsdftTfImIn+FeiMtkp+fxduiEbjiklU5K4FTSwJXsnsGHhvv5qYeuCX+s4xzWLAVOCBVp0HsdulabcIsDsJzzNhfjGs/REgPr0aBYxdnqOf9YjWPiPkVqtABVYIoNAaoll6UBILVNTlA+gFC99W1eCS/yHUVYNEvJaitreOxSCX2xr1a4LpubsS5FslKLq2aCu26G3iVwOX/EGI1LF/sNJX8BxH9Cdz51wicgISAEN5rqBS4JUxkOf0JHGuHgFVX2aQ9uGR8gzstUBK4p6eT0PAKgXt5fyd+rjaYy/TbBoYaxO4pM88vHSsC4jURWH25xZwX191v/pt+sPH3Y1AEbiD/xttAyrw1GNoQ6f0VnJ298N/AuUg9WWIlcG2Z0+H88QqprFzgGN01l/H12DFwdh+N8KTdVgInsnHicIyOPo2fgyw9WBa6mYgYhYvTn8CxA/3xKXw4cjg+918oXYTwWwTuJT4aM4rJkQf+9X+TEDhnIz9xRQ4tDGTb7omxX/ny79jkAvfgwDx4fS19f3J4aRjcXLzwn6/VCE08yXM159bzb+/eGfcdf9J9lcBFj/8ITkyCPUf+B0l78tFkfPrNTAzEBwvFC0ovYr0/g9foz3G53vJofDF9FjxdPPB/3smy7dSjancgnEZHIyc5GO5s+rhvI41PzARB/BVYfQPHHs58Y/aJWXRVXYLO3x9B05aYZUEpcCK/rE+Et7c/ZiX+KE3UP0VC1FT4aKIwa8UJnupP4MRlvKi6jmhdMHwDp+GXu21W4vBTjBqalGvSiEngGIb2x4iPCoO3KhQRcav4t2Lyb+DK9sWhtE+PgNSb5p4iE2KP0Q1TUujEtTU6q17AF3npONva80qBE8nJWA4fdRjOlD43XosHKnBMvCJ1mMLmvVAlv+oNTOCidSH43jsA81N2m7dLKXCG1iKEqNTw103HOXZhl76Bm43Y4EBMnfOD8T4kIH1+LLx9tEhIOYVyceN6KhEUucNcT2X2BgSq/BEcsxQbTxrbQlbGtg2AhrwDUPuy42DFScuxIjxDbmoEGvXPEM3WwS9oOkqsP+77RzAoAkcQBEEQxD8D5StU4q+BBI4gCIIgCMLOIIEjCIIgCIKwM0jgCIIgCIIg7AwSOIIgCIIgCDuDBI4gCIIgCMLOIIEjCIIgCIKwM0jgCIIgCIIg7AwSOIIgCIIgCDuDBI4gCIIgCMLOGLDA3b33iIKCgoKCgoKC4i2IAQscQRAEQRAE8XZAAkcQBEEQBGFnkMARBEEQBEHYGSRwBEEQBEEQdgYJHEEQBEEQhJ1BAkcQBEEQBGFnkMARBEEQBEHYGSRwBEEQBEEQdsagCNz94odYl7rhtSGWIQiCIAiCIH4/gyJwoqC9iYGUIf5ZvOhRZgiCIP5IelHXIfCh7tZqSEN/T4SuFgz+JdaAFwZl7u3mWWevMjUoVFT9uvbt6FYcbUIvnj97YZ37lZDA9UsflkX4wM11CCaFJWFHbhMyvIfAPeiwsiDbK8eh83THt1sq+ajwohwBX38EF88xmJmaBejvI2PqJHi5e2LYu18i43KdNF/vNTg4DYf8XLi64GN4hmfKMgK8v/oE/xo+HG5D3kPsmuOyaYPDkR0bB3wQfubiBgdHY7gHKycPAD2c2bw5bIGpX3th7pU/5sQiCOKvR+gshE6jwRTVVKQfvqmc/PvQVyO7Sq/Mvpm++0gv7OOD11K0UNZQeXk/tCp/ePuFsHUugr78BC409qd5BsxdkWUc1mN7cgK8p2iwbOtpPl6VlQK1rxr+uhk4++gZLyU0ZWHt9Q5zDSKtF1Nwvdsq9TuR1quSbVjLqST0u+qcbjw6uXlAAttedASdxoKG6iM4/3wgcw0iXewemi+2oR46VTjWrF6J3sYb2LfjlLJkP/Qgdl+FMvk7MO13Aap5ma9pXwXsuNtUJB13JsT9o1owkG14NSRw/fCpmzs+jtqK9s4OnNmxCUdLlaf5KzDUwcnRHYmHCtDZ3oD1O68zUbuC+DEemH+tFy+b78LVyQ2nnrND8fEmLkJRJ9uMJ5GeT3P+KFleIVxZGVe/n9jkDvi844H/ri+VTf+9CHBj9Q/0GUAUuKyB2t4bIIEjiL83QutZ7BdNgmFoyMSWu4N4vvcWIKN4gNdlOa8RuCc5K3G08tdf4OLVEQoR1ONeRpT5wfjWxii0COIqb0RMcISsnIDg6NnYU/YbtmMAvFbghA6cW6q16kB4FXW/zEf7XylwRoTmUzjZbFq2AT3dAzmeBlvgTJDAvZ0ITXB09IDy4S4/8WN8nnIf413dcKhN3GsGuDm5o6WvDOkTJBnpLUiGo8sX1k81JoG7Lh1sfm5uWHlHj778ZXD0GgEPn92oEc+irlw4eg6H44g42cxGgVPt4WPXF4yD+1SpF65o72J4eYzErC25aBLXlZ2QUX4T4OIyFEmXX7Kn3xJ88+G/8OGESPPT06noEfDeXgvxoHZ0HMJqlwRO6lVzly44L0ox/v1RGDsx1qZnzkbghKcI+G48PN2GYvhYb5zcksCGhyFuz30++dzyAHi4eOJT9RIcfNDJc0OYpNYZSOAI4u+OXOCgf4jEs+18sKcuF8H+GiTvK+Dj3WXZCNMGIiByizS9Ph9TNRos2CDd3PrubcMt471ve6ROGmACN+l7XxZqLiEthYeh9tNiu+kNhwmhldUVgMBpSeBXm9cI3E8xATY9ciZhWaKebc4FRu9DqZ7dwOPFa3E3/BaKvW5yrAXuWc4KiK7ZeWEVru2bA4uD1GF59iWbG/vZrUsxjbVHfKp0re96mMnbxy8kDnevHkCArxo+gbFoNK7sommh8GYSWcxfDUvrVW+QCVx3NaK0GgTFLDMvQxK4AN6GPok5PLVvVQL8gqajuN1a60SBE8t9r07j7TFzfhym+OkQtTDDXKb4xAb4qXQ489i6O6Cv8QaCVf6ISJDuYavnz4b3lAAs234OpUYRFLoqrLZXZA9bl1B2DETMFTsvipFW0MseAk7gx8u3UVh4l83TiId3KqTCwjMkRISw9dlqvveeWL8I4Wy/xyRtsRE4sX39NNGvbd9F2/PM7bsrPhrevsHIrngJU/v2J3D60qNQ+agxa80JY0ZAV8V5BPqpsSAtzbyfCw+ug4+PFunLZ8CPC5wBy+Nj4e0TxI8N+bEsdc4asGpWJHw0UXjCprcWHea9u3Ebr5HAKdGXb4WD60Rl2ixwN5Z8jLGJ7MLTdRGObt5sBovA5cwcjSExZ61nlAlcW2U+72XLfg60/ayDZ2QmPJ088cGC69ilGo4f7l6Ag5uvbGaLwPU+b4L3SA/8b2MZW8cf4TRSC/EA+cbdHU6j5/D1cHD+gM/VYxAwjC3nQPlLPNgeDKdR05HFHqFeJXCWU07AUCalhexC8Hi7Bp6KV8byV6jjUx/KltmDx1v84Dx2AcuJvZCeEA/VnhddfL6Ejzzh4PIfPkwCRxD2R1bWWXbjFa851kycFIDMrGxlmmMWOKEPJ1JicY9dDh7siIHP7CN8eseVtbjHLhRt2cu4cIiU7GY3tfhj0vwvbiMpp/WVAmfugWMiFJlRzAeLtkT1/0aBPWxygXyNwIX4rZCNSZgE7vGemeB+pK/C6qviEow38u7rSM1XXscsAmfobkWCVsfFonzfbCaRLxGSXgDxynhlddj/b+dMvKK48j3+x7AJAZVk4sRMXvTkZXkzSWYck7ixNlsjCAIiIhIXAhpQIRpEQIMbKm5M3BEhqCiyuBEEhSCL0Gxhky0C3f1999bSXdUs6oTxpd/5fc6p01W37r1163Z13U/9bgH0xg7E5feZSo6UpyFfMjwecTrZbFD0zxh8dstT0ePwTL4tFxMIDDmMyQTuRpLPBDG1jMDxfm+RMqUH+amCEFNF4Iz9RThcq2ffc5Fpajgn0ldVNt0/SLElyw93rnLs1op5/bxEsZTPty57DXTKBisELr9XrF3fdBprPHcK6wleQeIx9Y3YcqVH6MNiucEWEbiX7d/qrNUT+nenJhbmc5gocDLjVQcEYX90MBwem6UImxSB432VWclFUBmBG0PIkToxn8W1rEkpZcPsCVwT4x8CYR47TOskcJb0n4WN3TuWqSaBw2gZE7x/oiLhYyzObFQJXGXS3+CwKENdUBK4txZ8Bhd7RwSc6RCSa3YtEkSwOHYh7O3mwt7+XRjZU6qNwweKwqLA2boswII/ucDhr+IXV7dnsfldNL44fKYSOBh/ZelzxIva8JStz0XQ+d9EgTswjcAJ5cz12r2zUd4jMCECpzimQZcN29mR4Bc2r5O/sRC6cI6ivrlCPhI4grBO8q4UYslSDW7eKhO2ubzxtKngAnfgfge6Wu8g8pg4QB0O9cRyTy18mNT4+PjilGoA5fs12FY0KNWgh3t8IfQPD04rcIa2C3DXSHV6eeOhYvDvLtqBg9eq0dFcifU/tk0rcFFu5iibjElYxh9jV9kIOi7E4ZlwY5UGciYXmy53W5QSBU7X1YW689twjc+fMu6kaoXj5W3xR3RuEwLT7rGt3xB2vMFU8s6eAPE8hMWfyV2von/4Mc3RHY/os+xWXouQ5Avo6GxDgIaPsRMFjt/vkyO12H1WnBkRi6sFjve77CJPjkdBmGSSmErgYGhlgj2AwaLt8JLa7OXuIUY6Zca7sT5AgxMVfNwzCxzvo4YT69BjHMMSN1/V+SrbImadTuCMWLFMY+oz95Ry1odaIYAgoha4l+1fHjUV+tc4BM+1mWjt6EScd4SUZ3KBOxLui4raFtRd+Q53xsQ+/fa6NLpKAsf7Sn4jazKBs7yWl648KKTn74/HqvhsoV8Mz37BSg9f3Hj6GwncRAx4k4nWZ9HHMTQygjsXDrCLb9AscIxPmcg42zmhk/emQuDw/B4TIyd8l/cQI8N9yMnKV0XgjL/mMTl0EZ6+rkW/i0V7nwhPDZlfzhHrNnaZREdui3kKdRROTH5OtBqgr0uHrcNHeMYuuvH+ZjR0jKoFDjyS5ojTTc9RfzQQdm+F4xL7BT7JWAKnL/YIdYkCB7zNzrVQmhI2ssWZldt3rwf8B9Yqz71KTCtwbZYCNyZE4nj2i6vmThC4jMUucDvSZq6LIIg/PFzYuLi9SN44yinU8tQQIcJTcyAMPok3VPmUAvf4cATcN4gROIxU4purPayeQhyVRj2TwOm5UEk3I0MLYs+1i+sW/LRNjj4NmwRuz93JBa7pTCzy29TTmUphifTbjWhtmrTHLCOhbqvVwmExhRrjGSrsL4iXhGm0GvuDPdAuFBqHJpWLnMhwWSruDqtrUwuGLECiwOlrj+GG5AirfdQC13MlQTqGSMf5zeKYJTCG8t0BpvPn/d4qbWQEq6No/UxmhNd8YClwOiZwz2DsKUT2L9M/jF9P5N+Dov2jj3BQEjXflZmqvPwaaZfNkjOtwAHfeEUpMjMlvpuBi23ymakF7mX71yRwY/eQ/kA8tzR/tcC5x15Q9W+IZ7Lwqf/luCBwPKrptvaUuFOOwPXfwI5iMeI6mcBNdy1j7AFri/n6TPMPIoGbFEMfQpZ9Cnt7F/zdZwN2X6xTCVzfpTWw/1AKtysFjvG8pRifL3gH9k7zEJyQPeEduPQvXTEv7ApO+82B5/EusQ4Tz5lYuShuKup34PoK1sPW8Qth/fYPG+AyyxnvfeqNyJxaC4Fjl9ezh/jsvXn4y+dBYuhfQI+Qxf8N+1muWOS1Vvjx/Hprr1DPrLkLUccObOyvEso5ui7A/rviFKiM6q9QuQBOK3BA2b5ozHZ0huv8T/C5e7iQTxY4Q1cx5s/5s7lygiCshsJCtYRNhuodOCYqbuE5PBUjzTeg9fKC3+pvhHuQUuA4z1tL2X4Nvk6Vo03Aye3rsWS5N9Zv3W9K278xDG6+keDjcXuZ+O7Sqhj+gKpA34VIrS/cNKtwqIK/g2fExuBAxOf3Qt9+E367xGiiTNXlQ/Dx8MTSFb7YcfimSlj6rycjp1E+H6VMjSI9PhrLlnlj824+YKsFzthfgsTr/Tgd5aMSIxE93LcWqVIuZyQgzN8Hntp1wr17MsGQBY5/pm3k70/5IjaZy4BZ4DDaBL+QQ7h3NAHLlnpi0958+RAiz5sR4OmJNYnifz7IToqBu28EqnqV9sQwDiHCX4PA6L2TChyn8l9pcF/uiahE83fGyd0ajaXLNUjJrYIgPasSEci++8ikEyjvEMdE40Cd6nx5vgNb18Hfg3+faS8UOOh7EBsaKLwjVid5ZOmJ3YhZpcUKr2BkV/SKiRK8f5ct85q2f00Cx8j97mt2Dmyc3bxPlScveZ3QvzJD9fnC+24+wevQIF0m412VCGXn5uEfjut84GM0FGWza9UD2ogt2JHLp0sVAgf1tVzAzFnfXCDkD4xKFiKLydGhWOrmj6PlnTMjcPSPfAmCIAiCmBqlgBIzwYwIHEEQBEEQBPH6IIEjCIIgCIKwMkjgCIIgCIIgrAwSOIIgCIIgCCuDBI4gCIIgCMLKIIEjCIIgCIKwMkjgCIIgCIIgrAwSOIIgCIIgCCuDBI4gCIIgCMLKIIEjCIIgCIKwMkjgCIIgCIIgrAwSOIIgCIIgCCuDBI4gCIIgCMLKIIEjCIIgCIKwMkjgCIIgCIIgrAwSOIIgCIIgCCuDBI4gCIIgCMLKIIEjCIIgCIKwMkjgCIIgCIIgrIwZEbinT1uRn1807cLzEARBEARBEL+fGRE4LmgDA4PTLjwPQRAEQbwW9IPo1Vsm/t9hHBu0TCKI38V/VOBaWnQoLi61QoEbx7ZVK+A4aza+CkrAodJOZC2bDSe/XMuMwMB5aJ2dsHhfk7BpHG6A9+cfwMH5HazdfZndRKqRFfgVXJycMXf+35BVrBPLjZXAxs4VBkVVtzZ9COfgS6btloPusLF1VC0fba9C2iIXbLg5pihJEATxx8I4dB8BGg2We67E3tMllrtVlKZFIG7H98itHUNv5Tn0Gi1zvDr6ptO4Mcza0VmGxzMqcs9RezETL9PEn/b9YFov/c4XM9qMF7DTLwj1rR1oG3yZlpopP5MOTzdPrPAKxvHSNrQXpqJpsoYb+xF38pG0PoyU2DVY5h6AtNxKtv0rbqTFwm25B/xCvsbP3eNCtpHiZOR3qdtzLz0UPa/WRELiPyZw7e2diIvbgZSUdKsTuI8dnfBh6H70Dw0g/1AGzv4y2dU7CQYd7GydEH/mLob627Hn8G0majcR884b2Fgyht+6qjDLzhF57EFMX58hCFnoxT7pRqAX9tl/kGRRKWPgHGxmfWXaJIEjCOKPjrG3ACfkkV/fjRUhB1T7lXhEnDBvGGfm3iYLnL42G2UzU6WIcQA/bfVVPXxPxfc+Yab11ytwRnjEnLdMfCHlqatQM/SqNmWEjyZenWR4ilNRGpPkHo3wFs697sgaBGm2KzI+R2D4WjwQ/Y54RWZU4E6dOid8dnV1C/LW2PjU+qZQBy/Bxn6+ZSoq4j/E/yRXI+kjZ6wr+o2lDMDWbg4M+icmoapJ+QccFmeqC8oCd1u8gyx3dMT2Sj1GC6Lg6P4NbB3+jpRqPfouhGNBTBxs3lipLs+ZROBsHVzh7OAEV5+TaGV3Er3uHGuPMxb82RV28yOEfLOZELrOXwBbKXrn8va77NMJLZPkv2DxVEQQBCHT3NyCysqHlsm4dPkqOju7LJMFVAIHLjD+GBHWRuHhnwBdax28tak8J9y81iA+IRFl/Xp05yWgw8gd4F84XPEEuoZKrAg7JpSsPxmLnLIGRVkzDdVP0NX2BJrw46jTqwXuWs8AG4eGTMfmdRRnfY2SfnYgfQ22nKlBe0uDtP4QDa0dKDu5DT/ymyVr3+PmDjytykPitX5J4HzQP8DqHBmDsacEEakFaHpwEVGnGlVt+t4nlB13AEOjBkHgSqob8bj4MGI0AYLcTCw7hoAdV1DT3IYHZ3dAG3cMuran0LpvEOobqjyApLP30ahrRbineJ/X+sajs7sb9xuHTcflbXaPPiMce4wd6Ep8IAoqG/FT1iZcbOWdU4OsIF80t3WgsWvUVMbNf5+iDpG+q9vQxrphq1e0mGDQIenGIMs9hpAjdTC0nsOxJxZqaiFweVs0gsDdSPLFQHka7okXAppOxqC/Mw953TT+/DvMqMDt2pWBrVtTBHmrqalTReSsReD0DfuYLH1hmWwSuNGyeNh/koLR0njM+mI/K2AWuMLIeZgddlVdUBI4eQrU1ulj4UJuyXLDvJhiBL/1Buz+FIHPZzmhbfQ+bBz+oS7PmUTghAjc+D2W/xNsuz+OLe87Y3HkdiQl7YQ9kzSumFzgdOyHlx/+NpO42cITY+z8N7DrkX5CfpewfFP9BEEQlnz5lTfKyu6atrm88bSpsBS4hpwoQcxGK9JQ9lxMq8wMxjiPFkXJr6cYVQJXJE3/ZYf5CJ/emj1SPrmsmZKcPQgMXI0AtwgcrtVPGoFTHpu/KuOXXinITOpdKYNyne33z/iZfRqwP3EjAkPWwW3b9QkRuNxojWl9o0ectCYyVQRu+PpONOgnKytKkZjvOSJyGoW1mzvEsvEeq6XcwMjNFNSzxFhNEOr7LENYygicHu5br5n2eKw8KApcsNaUJqKHW8w5izSzwLX9uBHcs54VbRe+H7mt41VZ+GnAQsAEgfOEl7cflix1x8VHz4Tk01G+4G3zWn8WrQYj/NgnxipwqPb1xSb/PzGjAseXnTvTUFFxXyVv1iRw0Dcy2XkD7RbxcVng+EVrb+uCTQudcUAIZZkFbqQwGrYOn6kLKiJwF8IWwuGjrar6xiuT8bGDI+zfjxMuehu7eerynKkETl8LG/uFQt2b3uPTtPKTlIgscDe/fh92rM38J/Lth85IrNRPmp8gCGI6uLB9tUSDq1evTStvHEuBS/HzFSIyXKJKOnvQ3c2XXp7zhQKXGy2W9damS+XkshLj95F2XxSvNP8IQQhMAld3DKUKgTMfuwe9g/w+OpXA6eH9/V10nN8sCQtrJxch4yCKvlULnKlNPaKoyKT6moVLKXBj5XuE9/ImllUKnLjOqfg+QBK4KMX595gEdqilFN6b86Qtzr8jcECkmxjVUyILHAztSCjsQ5KfPF0qtW+sGutyLf7LhCICZ+y7jc0X24XkDO0q4bPqhzD4rt0gRuLYOJYszVARr8aMC9xUi9UIHONi5CeKPxxwwpuhlxUCBxxc7srE6S9ieFghcJxlb5mjbTYOiyymUA14y94Re9nN5XKoK5Ye4Be9EX0PzqO0g/9CBli5Oaaws4mXELjx+mzhmG/O/y/YuoQI+aYTOMv8Z+kPpAiCeAnyrhS+UN44XOD23mpCS2Md0mKCcKlRCn0ZR+C5aicaWttw5xa/p768wD08GIWTxTWKsnKxPvhszEFPbw++1YgCZ+wtxO7rOnYPfoiorNtoqCoxHZvX0dpYiy5+232BwI3/koPvrlSjt0sniZARXZcTcO7nZtwpqYGhoxDRmfnQ6VpQ0aCcxgRuJWtxp0GHmw/aJxW4iWWnF7j+0jTsOleOR006VJeVg7clv6IeHc018AjPkWrnqN+BuxSnRcHPfAp1M849HZ9S4AxdN+EdtRePnzSivrYKmT9WmwWOkegTip235MHC3L5LCUHIPF+KhvrHOPJD/oQp1B9jfTHMNpI81okJxiG01kjfn0GHzZe7MXwvC9mPSORehRkRuIKC6xOEzXLheQiCIAiCIIjfz4wIHP0jX4IgCIIgiNfHjAgcQRAEQRAE8foggSMIgiAIgrAySOAIgiAIgiCsDBI4giAIgiAIK4MEjiAIgiAIwsoggSMIgiAIgrAySOAIgiAIgiCsjP8FRqJbt3fciaEAAAAASUVORK5CYII=

[image3]: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAkUAAAKpCAYAAACy+Fg4AACAAElEQVR4Xuzdh1cUWcMu+u/8BXetu9a5a51z7jn3fOcdMwbEnHUMM6PjzDijoiiYyDmKiqgMKiYMY8465uyYc57BDII5IyIiIiISOtRzd1U30KG6aYLK2z6/b9X3vlZ37dq1a1ftp0Lz/geIiIiICP9hOYOIiIjoa8RQRERERASGIiIiIiIFQxERERER6iAUSZLEiRMnTpw4ceL0bz/VOBSZFqLX6ysmnU7HiRMnTpw4ceL0bzfVKBSZhqHCwiI8ffYST55mceLEiRMnTpw4/dtONQ5FciDSarVKIJL/k4iIiOjfWbVDUfldIvk2U1lZmZKsiIiIiP7d1SgUld8lKikpYSgiIiIip1DjUKTRaFBcXMxQRERERE6hRqGo/NHZx48fGYqIiIjIKTAUEREREYGhiIiIiEjBUEREREQEhiIiIiIiBUMRERERERiKiIiIiBQMRURERERgKCIiIiJSMBQRERERgaGIiIiISMFQRERERASGIiIiIiIFQ5EqCUU3t2JKZAjGLUxBmeXHDhPlpG9B7DhvhPxxCW8ky89tqelyn1M9qmNxOrb8PglBfkvwd6nlh0RERI75CkJRCW4sD8KQIR5wD9+GRzrLz9VIeHdiJoaLZYYn1yYU6fB4azTcRTlDRi/HNY3l57ZUfzlt7l2cO7IPW08/hgNfd5jtcqtfx1opfYXUM0ewc+ffeKE3/0gqOINEDw8M9liAiwxFRERUQ04fiqSCC5g9egQGi8F78NAgLLtZYvkVFXUVigB9Xhr2rFqFzRdfVquc6i0n4f2pWYb6zrkER7bQMfbLrV4da0ef9Rdih4kA5r0aqVrzzxiKiIioLtS7UHTq1HkcPXbKcnYNScg5mIDhQz0REB6JEUNHwGv2BRRU+ain7kLR52E/vNTcpyq3+hiKiIjoU6tXoUgOQ78NHqVMdRKMdE+wNcITg4dNwq57/2DB2BEYMmI6jlq9AKNHfvpfWDgxFF7DPTHCdwKmxAZhqGkoKn2EI8vmIi4qAr5jx2K4x1j4xszHtvNXcHTtLET5yvO84Re7CPvuFKJ8DZorS+A51APDphw1vHcjvcetPUuRODEavmNGY9gwT3iMCUfcH4dw531lvayWE0pfXMKGpAnw8RoFd3ldEdOx8VqBWFdleFHuiCnTCHj+cR0aOeBlHMbquQkI9/OGh7K+MMTvfgyd+Oz1hdWYHB4ELw9PDB0+Dr7R87Dpn1fGR2X2ylWvo/xYLV+sb9m0aIzzGg1P72hMXX4YGfmVzy11L85j1dxERAX7w1NZ71j4RM3GhkvZNh/9lYeiynp4YGjQJtzTmYSiob4ICAnAyOFe8BT7cNbW68g1e1yqF21xCIvjIzBmpKib73gkrj6Fh0XllZeQe3kbkhPiEBYYAK8RXvAYG4EpK47jnwu7sXCyWE7MGzEuCglr/8ZLs8pWVTYREdV39SYUmQaiugpGmjsbEeg+AsPjDuGVvhQ3lgdiyFAvTNiXDdPXUsoe7kD0CPkR2wgMGxUIn7GjMXSoYeAtD0WVA+9IjBgbBJ8xo0RZlUFhmJe/GAxHKu8uDfFejL8LDYOhVXDQv8SeWE9lGfeRvvD29cOIYYZ1j0o6gzzjGGq1XOltrA70FOscCU//8YiJiRbhKABLriu1qwgvQ7xCEB4xHhFimrjlNrQipNxdH6YEvCHuozHaNwhjPUcj/tAbJUzJd8RGjPSHf3AE/McatmnI8PHY9lhOE/bKVamj/P3rqxEyXGzPULlNfOAptm2I2LbhoeuQ+sG8TYYMHQXPcYEYN8rL0G7DorDxnvp9uYo7RcN8EGCsR9T0A3hiGorEeoZ4+MDbexzc5X0zdDRi92TCkIskFN5ca6zbaIwNioCPp7y/RLsnHEe20iHK20qUIwLiOF9/pf7lIUxuvzHe3himlD0KMTufV6NsIiKq7+pFKDINRCdOnMXZc5fEIDS6lsGoDKkrgsTAOxoJx/KUOzeajPUIcPeAe+ROPC2/gyB9wIW53mIAGwnf5AvIUa7+NcjcHa+8RGwVisof0ejycGa2r2Hgm3cRBfLg/P4qFvuPVO5YLL5mGNytgkN5KBoagBVpcrSQUHxvCyLl8OAxE8fz1cOU/sV+jJdDwdhluFb+iEhXilJlO+w95iof6D0Rvu2pYRCXNNCUP4IqK0Fp+aCte4vz8/zFNnkietcLERztlWtdR+geYVOYvG2jMX7zHbwX5eryU7E6QoSeoZ6I2ZWphFHr5d7g9Gw/ZR8ErLtrDBrmHHt8Ng9ni+Q5GrzYn4ARYh3uMXuRKa9U+xB/hoq6uQch+cIbZR1SYRpWKvMisPGBPKeyrSKMbVVyf6uybwYPm4itj0tFi4i+sXcqhstlT/zLEHgcKpuIiOq7Lx6KLANRuYuXLiuBpsbBqOQGlnjLj8tE0HhrvP2ivYd1QSK0DIvCpofGgUp7G6v8xKDnHoK1tyuSktU7RVahSHyn4GSS4TuzLkAZi0VsuDh3tBjcvTD1WL4hiFkGAKtQJOgeYEPwSLMB1Gq5j1exaKx8J2IswubuxLl7b03edbIXXqwHejNSCV7d/hvH9u/Fzt0HsHN+lAiDI+C7Wr4bZK9c6zrqM/ciRg4unvNxwdAgMLRlkhIihsUfRa5kvZz8ncLTsw3rSToH4w0lM46Fosp3ivQv/8IE+fvGX8ZV1M1jPOb9uQ2bNsvTFiRHyftrFBJOyI8hVdpKJ/pMoNxnIiv6jO7pTkTIZfmtQ7rW0bKJiKi++6Kh6MCBoxWB6PCRE5Yf4/Ll6yIYjVE+P3jwmOXHdhVfWYox8iMaDz8EGR+3REREw89LfhwyEkEb7imPgMQIjQUj5TsBk7BLuaUgcyQUAaWXFhi+k3ja+PK2BteX+CihKO5AjuOhSJ+JndHyvGCszrARikRp+Wk7kRgoD7Ty4xsv+EzZgqtvlPsSdsKLykBfTvMch6YHGh41GR8RlT8O9FmVXu1QpLu9Af7uHhjqvx4V+VLQ3lyh7Av5Dp38uMtyOaWsfxbBQ56XcALGm2VmqhuKpPwTSFDmLcI/msq6mW9n+eRlfJyo0la6p9gWKd/xCcW6u4aN0mcfxETlrt0K3NA6WjYREdV3XywUySHIXiAqd/16GtyHjVW+d+TIScuPbfiIlIXyoy3LAapyGhqwHhnyozLdbaxWHnn5Y3HFc6nqhqJTlaFoqbxeL0yqbiiKkecFiVBkmGe1XDltAR5d2oPkiHHKozvPpHN4Jz4vOjvX4q5VOZWB3qjs2jKMlsNKyApczCpEqbYMWfunYVhFKLJXrnUdq7xTNMXWnSIxL6UyFJXf2DMlvTqISSZBxOwzlX0j5Z80C0X657sRJS/vtRCXPpovX0mlrXTPKkLR2jvGUPTKPBQ5VjYREdV3XywUvX6dC/+AKLuBqFxaWgZGjwnC8+cvLD9SJRWlYL78t4mGTTS5+2NUcs3wGMo9GKvS5VT0EVf+kN+jGYERsVtx653hzku9C0X6QrzJK6m446C9vUF5P2posOEXWNrUVRg7VA57K3BNeclbQmlxmfrdD6OP5+cZwkrcIeQozSQh7+h0s1Bku1yVOmofYGOoHDBHI3bLPchf1xekY12U/AK3J6KMLyZbLSfPqyIUoegiZit39MZj033DPStdcYnNfWMZiqAxPjodOgqRq67gVWn5it8jK/u9sV1V2sqBUORY2UREVN99sVAkKyuz9QNsa5qKN4OrIqHo0iKMku+AhG+3/gvWyovVY5UQ5LsyXRlUddmnMGOc4VdG8q+OvP2DKn5JVl9CkXwXJnqYF7x8IxARMx4Boz2VbRg975KybulDivInB+RHX0NH+sF77Bh4TDqIbL3KQG+kzz6EOPlXdyKwjAmbioTpSYgPlV86rwxFtsu1rqMSJi8vQ4D8YvLQEfAY449RHoZfnw0LXo3rtn6RJ8+rKhRJb3Dsd3m/iX00bBzG+fhixMg5OCPKVNs3VqFIDnwXF8HP+Eu/IR7eogx/eA4fUfGuU41DkUNlExFRffdFQ9EnIRXhUrLh12T+a+8Y3hsy/wLenZylDMBD/dfiljGXlWZfwbb5UxA0ZhTch8k/FQ9D5OQ5WHrimTI4qg28nzMU6Z6dwIK4SIzz9MRQd1E/3xhMW34U94xBQ96ugvS9mBsThJHDRmKYVxBi5p9Cpp1QJIeA3Ou7kDwpAmNHipDl7oURY4IQOiEJy868NP7ZAlvlWtfRQIvcm/uxSPl7PaMwclwk4pf8hdS8yjWrLVdlKBJ0udewaUYMxo0QbSCCR8DENbj0xtFQJNPg9fU9WCD/vSF5e4eNxpigSUhcl4LXtQpFjpRNRET1nfOFIiIiIqIaYCgiIiIiAkMRERERkYKhiIiIiAgMRUREREQKhiIiIiIiMBQRERERKRiKiIiIiMBQRERERKRgKCIiIiICQxERERGRgqGIiIiICAxFRERERAqGIiIiIiIwFBEREREpGIqIiIiIwFBEREREpGAoIiIiIgJDEREREZGCoYiIiIgIDEVERERECoYiIiIiIjAUERERESkYioiIiIjAUERERESkYCgiIiIiAkMRERERkYKhiIiIiAgMRUREREQKhiIiIiIiMBQRERERKRiKiIiIiMBQRERERKRgKCIiIiICQxERERGRgqGIiIiICAxFRERERAqGIiIiIiIwFBEREREpGIqIiIiIwFBEREREpGAoIiIiIgJDEREREZGCoYiIiIgIDEVWdK9u4MDmtdjyTx70lh/SJyV9eIwL+zZj1ZGH0Fl+SERE9IkxFJmRULDbH02+aY6BSx7VaGDW3l2DYR074LuEC3gvWX6q4uMVzB7YEW1/W4LUUssPLeg+4vXjdFx7mA9HirZPQlnBC9y5mo4ss/XqkbkzGF1a90HEgZxPEwxtbIcubS56N2oKl7DjKDOZT0RE9Dk4fSjSPVyBn5s0xTdNBmPZo6piTu1DUdGxKLg2aIom7uuR6UCi0Odsh5eLqF/LIOx7Zz/qaC5OQYeGLugy7TK0lh9Wlz4b64e1wL+ajsbm16br1eJyQi80/MYFfeem16gNqmJrOxiKiIjoS3LyUFSMi/HfigG+Cf4lBvnuU1PEHHtqH4qgy8edM6dw7WVVt33KaZCTehqn0vOqXJ+tMFEjNkOR8THWsRQ8/Wg/pNWUre1gKCIioi/JqUORlLsX3q7N4OIxFbH9m6OBWyj+yrcIAAWp2Dh+BHq6uaKJax/80r+7CFHloUhC/oXF8Hf/GT06dYBLk1Zo3WsU4tdsQnLYMHR3ayWW6YVfx+/EXWPashzY9VnHkDjOHX27tIdLYxc0atEN/f3+wLkcYwTSnMP4Ns3QsFsiLisJQYPMY3Mx7ocuYn3N4dLuO7jPuYQP8idKmJADnnFq9D1mpemgf30Bi8JHoX/X9mjWWCzTtj/iThaKytzDer9B6NGxHZo2bgW3Xh6I3ZKBD3ITlIei8rLE1NRnH95Dj+erh6HxNy3hufWN8fGWhMKMXZjq1R/tWriiZaef4T3rMB6VJ0zdQ+wYPxY/9e6GVs1c0LBpO3QdFIXV1wpUH/PZ2o7ytmvQujs6t26Fxs274Ltx83E62zQuluDxoTkYK9qnuUsbdPjeGwl7HhjDbglurgnH8IHfoXMbNzRp2hZdB0/Asj+XI8bjB7Rp3hLNOw1C8OqbKKiomNi227sQP1L+XGxbl0HwnXcSmZqKFRIR0VfCiUORHs9WD0eThu0ReOAtXmzwQrMGrvD482XlezL6V9jl0xENGrjAte8o+Hh7oV+75vimIhSVB4RmaN1vFLy9PdCjRVMxkIuBu2VfDB4zFj92bIFvGrTEryufKHd6LENR+b8btvsJnt7+8OjXHg0biPL89iNXHpgtQpH++Qa4u4jy3X6Gb+wUxIaMg/cyw2MsQ5gQZX/ni/ET4hA7aQGOvNBXrqPtQHj5BmKMhz+W3xJL6J5iU5gnRgdEIDRgFPqIgPiNHEBS5RUZQ1Gj7hgSJsoS5U3ecFPECutQpHuyGZ5u8rId0HfYGPzavbXYZhd0Cjtqtg3fNO2Bn0YHYNzQvmghQk+DznE4W1Te2JXsb4dYzrUfhozxE23VQbRVU7Ty2QPDzSw9Xh+MQCe5fXuOREBYAH6W279Rb0y+KK+oEHt8WuFfDdzQY6g/vEf0h2tDw/5y6ToYXmOGoqto2381+g4zbxjuUZVvW4PW/eEVHI4x/TuKdbZE//npYC4iIvq6OG8o0t3DwgEuaNBxIk5/FPV+sxferZqi0cCluG+88aB7shqDGjdBw+/m4qZyq0F+fOZn8vjMMiDo8WL9CDQWgeCHBfeUoFKakojuYpBu5r0X8itBtkJRxSOhotOI7igChGsUjsrrtAhF2qszlPJa+e5BrsXztBo/dpJ0KCkuwZvdAXBp0AKD12RCb/PxmeU2l+JSfA8RFFrDffVjJShIH67g974u+Kax8T0ty7tdUh52jnMTYeVbJFyxftDn8HYUnUGM3FatjG2lu4Pk78V6W/ti0/1c5Oa+QfbFmejbqBncok+LQGcMRY0HYbG8k6V32B/QDt807I74S3LNdbi/eBAaif3726rnYktLcSGuBxo06oGIA8+V8nIzDyOyk9iWXrNhzE1ERPSVcNpQVHY1CT0buaDrlBQob/dI73EopIMYAL9H0k3DPYCy07FwbdAM7SZeMN4VsHynyDIgGAb09g2boZMoVwkIr7diZNMmaDxkLZ7rrQd2y39Dn4k1QwxhZJMcRiwDRfF1zOnvqtyJce3jg6kbUvDSmHQcDhNG0ocMbIoZhq4tRJD4pikaivaQyx2wSAQ6R0OR7hlW/tZcBI1hWPWs/B6bFld+7y2CkisCDxVbb4NoudTZPyifBx+xfrfK4e2waCupQATbpiaP3UymJl7bkStZhCJRj4zkAUo9gg4b6lF6JFwEQxf0mX1L9OPnWCVvm0p53zSPxFHVhElERM7KSUNRCc5P6oEGKoOd/MJ1l/h/xDcMoah1g6ZoHXXaEJwcCUX/JKCTCEUdJ/9tCEV5OzFKDNSNfl2NJ/ITqypDkTGMNPHCxmy9SqAQZRY+xJHFMfi1cysRYpqh7ZjteCbfkLk0BR1FmOg8NcV+mDDMReqs75VA8H30Rhw+cxEnFoxCi4pQ9AobhpuEswoqoejX6oeijOQf0fCbVgg8KLe0OYe3w6KtpHd7MFa0dYOOwVh95gLOnaucLtzKEfvDOhTdXfSzWT3KjkcrbdAr6Sa0uqdYMai58jgtZts5s/LOX7qHPAd+PUhERM7DOUNR0WlEtW+GBq0GYlz0BETHGKeosegtv6/TYQJOfZRvRKzHkKbi352icChXHgHrRyiqUJyOeT+KQbvJCKzLkt+5mYc+oqzmvvuVR3XlrNah+Ij9/iIgNBqI5NuG53Cac5PQpqExFIkAsVcEiG8a9cecNNMVW26z/IipOxo0aA2PDc+VR4YovoGZ37mI8PErljxUeXxWRShyeDss20qXjtl9XJQXs6dcMnmJW6+DTvlHNUORiMZnY7uIbWuFXxZmmPwyUZRn8eiSiIicn1OGovdHIuEmgkubyFMwe89Xeotd8rsuDTsi7Gih8u/j0T2Vl3mbdByE0QGhGDugMxp8wVCkvT4fvw0cjYCoyZgUMw69WzTFN61DcUD+uZQIe5HtDC88f+cVBB/PEUg8W2K9DoUOdxb8hEYNmsHtp3BMm7MAs4J/QrPyO0Xi/x4tH4zGYtubdRsGb38fuAdvwmOd9TZrH6zF0Fby33rqih/HBMCjTzsRJJqhQ/BBvJazZDVDkcPbYdlW8v7YMk7s2yb4pmkXDPAMgN+4UfixxyiseiqnmOqGIvHv20vxc/Om+FcDV3T+xRu+cjt8/y0Cdr9T/eUcERE5L+cLRdI7/BUov1zbEeHH5B+ym32IN7t84SKCgGvgQcNdipJnOJocikE9OsClcQu4tO6O3mJwnHkyVwzB1gHhU4eion8Ww/O7bmjRxAUNm7VHt19CMP9MtuEOjfj/r07Pg1efDmjSyAUuHX9B3NE30Fquo1zxA+yeMgZ9O7RGI/H9Ji07o8eAUZhyKBvKk6GPd7ApcjA6tpB/Rt8ePT3XIF0lFMnt9u7GJkz0+B5tmrdCi44DMWb6X7j/0bie6oYiR7fDsq1kUiFubZ0m2qiL2F/N4dKmB/oOHo8dj2sWiuTvvLm8FtHu36GNiwsat+iMrt97YtrRT/TXvImIqN5yvlBEREREVAMMRURERERgKCIiIiJSMBQRERERgaGIiIiISMFQRERERASGIiIiIiIFQxERERERnDQU3b5zD4uXrMTCRcs4carTSe5Xcv8iIiLn45ShSB643r0rsJxNVGtyv5L7FxEROR+nDEXyFT3Rp8L+RUTknBiKiKqJ/YuIyDkxFBFVE/sXEZFzYigiqib2LyIi58RQRFRN7F9ERM6JoYiomti/iIicE0MRUTWxfxEROSeGIqJqYv8iInJODEVE1cT+RUTknBiKiKqJ/YuIyDkxFBFVE/sXEZFzYigiqib2LyIi58RQRFRN7F9ERM6JoYiomti/iIicE0NRrZQh73EGHudLlh+QE/t8/YuIiD4nhqLa0KQgvnNnxJ7TWH5CTuyz9S8iIvqsGIrs0uHNje1I9BuM7m6uaNTYFW49fsO4KZtwNU9iKPpK1V3/IiKi+oShyCYtnuwMQTeXLvh14mrsP38dt9Ju4sKhPzEjbDaOvGUoqi9u3bptOcum6nzXlrrpX0REVN8wFNmgu78Sg1p0h9+uTBGPbGAo+uLS0jLw2+BR2LR5p+VHVuTvyN+Vl6mNuuhfRERU/zAUqSrGuYnd4eKxCS/0lp+ZUAlF2tQVGNG7M5o3cUGjFj0wMGQNrryrfBG7+NZWxI75Fd3btEbjxq3QulccjhUYPi95egLJAb+hS2tXuLT7DsNiN+LKG13FsqRuw8ZtStiR/9MWR77jqNr3LyIiqo8YitRoryOxZysMXZcFe5lILRRJ+Q9wNfUhMl9mI/PuWSzy7IpOsedQZPgUuVvHwKX3JOxLe4znmU9wR/yn/OM1fe4RhHVtg37hG3Aq7R7uXDmIuZ7d0OKnhbhZXFE82WAv9Nj7rCZq3b+IiKheYihSU3wYgS7tEHGyzPITcyqhyJLm72no0nMGrijP4AyhqPmvq/HE7AaQFqmzfoDLoJV4aDJfKjyPCd3aYvT21/bDGSnUwo/avNqqdf8iIqJ6iaFIjTEURZ6qfijSZJ3Hslhv/NS7Jzp17Yf+P/REc7dYGIqyEYp0T7B8kCsGrXgC84dlZTg/sQtahh4DbxY5ZuvW3UoI2rx5pzLJ/12eV5dq3b+IiKheYihSo72Cad1aYdiGbPt3aCxDUcl1JPVzQ6+gtTh54yGev3iC1M2h6Og23n4o0qZi5reuGLe7AOZ/BlKH9HkD4OK1Hbn8+5AOKw9GnyIQyWrdv4iIqF5iKFJViMMh7dF89A7k2EtFFqFIlzYXvVsEYK/xxenyeX2qCkW6x1hm705RCO8UVZf8uKwuH5mZqn3/IiKi+oihyIbiyzPwbdNvEXnUzvs8cijq0gkxZwyhSHtjNnq1CMS+wsqvOBSKoMX1mf3g8tsqPDKd/+ECJnVvA6+tObbrQJ9dXfQvIiKqfxiKbJE+4PrCYXBt9i28ZmzBsZRbyMi4hStn9mFFwmzseSbSi+4hlvzkiu8TzuJFkfj3h3OI7dIGAybvw/UnOXidk4X7+8aja5WhCNC/OoCgTm7oF74Rp9Pu487VQ5jn1R3NB8zDtY/m36Uvq076FxER1TsMRXaV4OnpVZjg9RO6uLmiYaNWcO38I4aHL8SJTDnV6PH6zGy4d++EUVvkuzkS3qdtxnj3vnBzcUHDJm5o030ghgT9iQwlBNkORbLix0cw2/cXdGrlCpc2fTE0eg3+zlX5In1Rdde/iIioPmEoIqom9i8iIufEUERUTexfRETOiaGIqJrYv4iInBNDEVE1sX8RETknhiKiamL/IiJyTgxFRNXE/kVE5JwYioiqif2LiMg5MRQRVRP7FxGRc2IoIqom9i8iIufEUERUTexfRETOiaGIqJrYv4iInBNDEVE1sX8RETknhiKiamL/IiJyTgxFRNXE/kVE5JwYioiqif2LiMg5MRQRVRP7FxGRc3LKULR4yUq8e1dgOZuo1uR+JfcvIiJyPk4Zim7fuacMXPIVPSdOdTnJ/UruX0RE5HycMhQRERERVRdDEREREREYioiIiIgUDEVEREREYCgiIiIiUjAUEREREYGhiIiIiEjBUERERESErzUUad8j++U7aCznk02a/Ke4//IjJMsPHPWVtnmt2+3fUhnyX7zCe2fcaGfux868bXY5cX+lavsqQ5Hu8XZEJRzFm/p0EEjvcXJGMJbdfIfTSf5YdLVuTk2lT45jwfgw+AWGIXTBeeTXaJsl5BxIQOzO59AZ5+hKSuycPPUoLSkzCwJfus11dzciZMphZN/djLCJ+5Glt/yGdZ1rz7rdnJFVX9DewvKABbhYajrz35Pltn3pflx3rPt7fdo2y3avDqnwDnYljUdAQBgCI9bhWon551Zlf7L+qsOjnfEIW3NLxC6ZdZtT/ePEoUiPgrtHsTwhGt6jfTBmXBDCEtbh4it9vTr4KxXj/NxIrL1dhEvJYViRpoV8UN3bHo8A32D4+ctTBMYnrcOh9DzIn1ZJeoMjCTFYefNDLQ9Ei8Fdcw2LAlfgho1KyAEkdPYFFJnO+8Jtrqx/xinkPdmJmGlHkWtRD7U6195XEIrU+sInG2Q+M5Vt+9L9uK6o9fd6s20q7e44HZ7umITYrY9hkYUM1Mr+ZP1VQknWLVx7ajj/qrU51T9OGookvL+xFuHBc7Dn5isUyz1SKkPew3t4If5Rbw5+M1rcWpuMv7LLkLF+LnY9l29laHB9aSBmXzAe3lIJcm8fxYKIMCSdyK56oNVmYFXQApQvXnOWoegqFgbYPmnp7mxESD074Up5xzF7+Q2U5Z/E7MVXYHn+U6tz7X0NoUilL3yyQeYzU9m2L92P64paf68326bS7o4rw9/JoViuXFSqUCv7M/VXtTan+sc5Q5HuKbZGRWBlWrHlJwr54I8YF4aI8AgE+gciYOJKnM2qvKGqy7uJbUkTEOAXDP+Imdj4T07l7VZNNi6un4Ew+c5N4ETM3nkL+cZHMfo317A+IQbBoVEICYvHpnTDTVOUZuL0ygSEBYUjMGwqlp15YbydakpcVeTmoEAnoVT8Z75y0FqEIiNd1kHE+SbjXIHh7KXNuYKNieMRFByOkNg/cPCh8R0W+WD38YaPqE9oWDTidzwQg7MWGZvjEBwsb3sYYpecg2HTdXiybRKmHsqtuKukvbkS/guviFpYh6IFXt7wU8qNwYwDmWaDvnzwB4wKFG0gPg+fgq13dVW2uc1t0D3HkXlxCA0OQ0BgMAJi/sCO/VswOzZSlBMAn4gFOPy0vDX1yE/bg9kxEaKcCEQl7cYtYxvJjydzXheL/iv+M8f6HR+1OkMqxpMTKxEXGgxf/whMWHQY9z5YLimz1aYm7Sb3yegp2Fv+3E7/EnsmTsCWx8aWk3JxaFocdjzTQXp9BvPCw8U2hMI/fBa2p78XJZXh2tIwzD5XWLl/bm9A2JwL+FD2EmeXT0VYiKh7aDQS9j21CGH29m0t+61aX5D7nW8AQqKjERQYBJ+QRKy/koeKJ5YOlau+Teptg2r2Ezv9zZTKtpV9ln5spxxTumfYlxCpfMc/MBZzDz42XgCW4NHhPxAbGinqHYmI5NPIsVhYrb/X+Bg1Ib1Jwar4aAQGyts5HmvTxDZJH/Dg0FJMCA1DUFAMpq6/glylg4qL1/TdmBkdIeoRKfrLaqQUSqrtbnlRYfscXYILc8dilL+8bBQiZh01f1SuVvYn668Scg9NR8w2Q99Va3PbbUNfilOGIn32X5gYtB4ZNi4WlCuiyfuRZQwer07MRUDSWbyTj3DdC+yNi0Ly6ZfK3QTN6xQsjZiIzQ/kw6AMdzfGInLlNbzRyOeeFzg+NxLxB16KTq/DvQ3iYDjyxnAAS2UoU47SEtxaG43I1TeRLz7QF9zEishp2G/9UosK9VAE6S2OTvPHwsuiTtqn2CFOrAvOv1bCy8f72xEbtQUP5G2zcQWkKS0zHPC6HBxNDMbcC/LtXXsDp3UosrraMqF2RWS3zR3ZBqUJJBT8sxh+YWtxo0A5zSDvTDICZp9XXpKUck7g9+BZOPhc3uAyZB6YgdClN6Aejc1Z11lC4dXlCJm0DRnyuqQiPNgzHcEihORZjgSw1aam7aZB6nI51BhupUuF55A0chQSjuUb2rs4BfMj1iNd3mZdGUo1yrdQlL4eYVE78ERUoeifPxAk9sdHZY16ZO2diqkHc1F6dRmCkv82vigqH5uWZ1V7+7aW/VatL8j7zH8OThXI3xVh/+k+xAUuw1VlHzpWbpmtbbLRNtXpJ3b7mymVbfsc/dhuOWa0KC01tIv0LgULAhNx6LXodQVnMCN8LcqvCbVlcinmrPt7LbbNsoypR0weT4tt/XsxguJ24l6RmKnLxdnkaMw68w6SuDDYGzcZ254Y4owkxhTlv6m0uxm752g5FIUaXz9QoVb2J+uv1qHI8hxjs20qvkOfm1OGIt39TQiN3YtMG7nD6jZx0XkkBa6BfBzpHm1DhNmLuBLyjkyH/8p0aDVpWOY/CyeVs4SB7ulOREfLJ2YxSO0TVwoLTuPJB5MVa25iiZ/pMjo82hKLxPLB0C4boUjMT1ngg+mn3kP7YIvy4vCL8lVKr3Fg6mTslB+/2QhFleRB+3eM3yEP2vYGzjoKRbbavDrbUHQBs4PW4pZx3VK+CEIRm3FftP+rv6YhZP29yvetii5idqgIx5YZQYVVncUV3LnZwVh0xaTtNfLjyEQctnwhyYxpm5q2mxjELy1CkAhp8qaUXl2B+DnJmLAoRQltmlvrELH4mvV7ENpULPVfhL/lC+6iK1gYuhQp8gJSAU7OjMO2p2LP3d+C8Og1+PtliY0+ZW/f1rLfqvUFy30m5eCv+InYKqcXB8uteptg1jZW67TZT6rob6ZUtu3T9+MqyrHpo+iv4Vglp+ri61gSMg2bUt9Y39Ewsurv8ryabpsJqzLEcXR2VhAWXa7s2ZqbqxC04DJKpXycnhWB6fvu4Z1p/1Fpd1N2z9E1DUWfpL9WEYrstU3FHPrcnDIU6V/sQ2zwety2MRhaHbia61jkuwSXxWWK5toyjJtz0ezugjJv1gV8EFf3M/1XIdXkgJIKz2KGr/Eg073FrQMrMFm+fbr2HJ58FFdtH8Qynv7ihBKPicYpNiIS0w9lV96etclGKCq/U3RFXFldX44xYyMQa1J+ZGg8tj3QWR/sMn0+0vYuw7TYCYiKnYzxwX6IUA5aewPnJwhFpm1enW2Qb3/7LsO18rv6H8XgErwO6VodHvwZiVGBkyrKmDhxAkLC1tmspymrOutfYV+cyeMtZV62mBeDTQ8tOpbNNjVvN6ngLJLCNyBDq0XGukRsTE/HuolrkKrR4eHmOMxT7i6Ja9Pn57Fu9lRER00SbTIePqPKt78MaavGY+6FQkjFKVgQK67UlaqUIfvqHvHvCEQkbcM/Ly2HQnv7Vv64Fv1WrS9Y7jOpEKeSIrHurs7xcm1sk822sVynzX5SRX8zpbJtn74fV1GOCanwAQ6vmIUJ0RMQMyEeod5BxjAg4eOzi9g0ewKCY//A7tQ8w3Frwqq/y/Nqum32yhDH0f5J4+AbWbncxPHRCFl4EfKTben9AxxfMxNhodOw9PB9w50WlXY3Ze8cXVQnoaiu+msVoaiKtqEvwylDEbT3sD40EmsyrK67FVYHrjj4//AzHPyqVyFH5auQW9Bq5CvT2Thp0mN1z3YhpvwWfjnNW9xcPwlBqzOg0aZhufyyc43erlMPReXvFJ0X9ZDrG6XyayqF5cEulFxZCr9pB5FZIi8g4c2R8oNWj+z90xCz41nFCdR2KLqOxYEmJ3QL8p26sKRzkF8PqJhXRZs7vA3ySc3PdDC5KK645cFEwuuDiYg2noCqy6rO5XeKrpo0nua2cqfokEVFbbepRbtJBeJkOwEbb9/BpmkbkK4pQ+qqKVh76xG2xy3AWXlEUN41isKyq++MbZ2OlUGV2697tB0xCcfw/MoKxK6/a/ErxDK8urQcYTE7zfuj3X1roib9Vq0vWO4zMcicFoPM2jtyOHCw3Aom26Sx0zaW67TZT6rob6ZUtu3T9+Mqyqmgw931kRi/+T4MN/hKcXGeZRiQw9FxEbZm4IhFYVb9XZ5X020zYVWGVITzcyJEvWycLIx0IhztmhqG5EviwkCl3U3ZPUdXGYpUyrbcN3XVX3UWociyzR1sG/q8nDMUyQfJxUUICF6Ag3feokzphDp8yH6KrEKVX5+ZHPzyC5G7xYl3wblXyq1n7ZurWBYRiz/vy/8qxe314xG1+gbeysdc6UucnBeJuP1ZygBYWvgepUqZerw7lwz/BfKjkWLcWBGFiZtvQ3l9QF6F5d/JsMny12elyL19DAuVX5/J7zEJ2kfYEh2L5ZffGMs0+VsYlge7UPLPH/CbdQZ5hlFanExmVhy0GvlKJnYb7n80NIxpKMo7OgMha+8Y7yw8xbaYSdjyWG4TPYqLzf/2hpR7DFND1+Cm/Jxc1Lm4tIo2r8422BlM9NmHMSVsIU5llRqWlcpQUlr1/TiZdZ31eH95KULiduBOoShD+ojH+2YgaNY5q3eKbLepRbuJfxecTUb45ARMXpOuzCtNXYPY+ATEJF80nCz1mdgZK4LTPeNteK0IYsGmJ+y3OJkUi+iYeGwyvtAhFb/He2N7aF+JNhDtYfk+nb19W6t+q9YXLPeZ6SDjYLmq21Rmp20s12mnn9jtb6ZUtk37Gfqx3XIq6JCxJhyT9700fqcMf883/ikPXREKPhgbt/QRNsfEYcdzs5Ss0t9rcYyasCpDfCP/3HyEJB7AI3ldMm0JSpT+qUFhQTGUI1QEhBvLI5Fw7C0klXY3W4/dc3QVoUitbMt9U1f9VWseiqzbXG+nbSS8Sz+O/Zdf1egij2rOSUORTINXV3djQVwExo31xZixAQiasAiHn2itD1zTg1/Qvr6KPxPHIyBQ/oVLIlaff1n5bL70Bc6s+h2hASHKLz6mb7mON0qv1eDO9qkICghDUHAYQiatwMnnhqWk4qc4vmwaQvxDEBAUgbApe3DfxjFrTlwNbp0EH+8A+Br/TlHMzHU4aPF3ijRZl7D292j4y+UHR2LC+lQoY5/lwS4TA8vJxfEICoxAaHgMwsInYv6pHOOJqQCpW2cixDdQbFuYKCsWCXseGg7o1xexKDIcC+QrOXmwT1mLWP8A+IlyYtenmb/MLH3ArS2JCPAJEmVMwOKL+fYHE/mfjm6DvcFE1PTN9R1IigqDn7wfQiZi8YW3ViduVSp1lkQQenB4KSaEiDoFhCNm3n5kqN3XttOm5u0mn/uvYIF3GNbeLt/w21gdGIjFV8tbUJwMU7cjMSIUAaHRCI+IRsSkbUg3OQuXXl8Bn5jdeGYMYR+urUd0YAgCRb8LEP117T+51idSm/u2tv1WpS9Y7jOzQcaRcm1tk522sVyn3X5ip7+Zsd62D5+lH9spx4QuJwWrp0SKNoxEWITod1FJ2P9YtFLueSyQ2yg4XHw2HjO2pRleljal0t9rfIyasDq3yqT3uL3/D8QGB4u+F47gyHk4Ir+cJMLNwemRyjz52IlJPoj7SjiwbnfLH0vYPkdXEYrUyrbcN3XYX01DkVqby7+GVW0bcYa/vSESvgv+MbubR5+eE4ciIieke4u/F0/C7DOOvKhPRETVwVBE9O9A9wS7E8YjPHwCEjffrPjbWEREVHcYioiIiIjAUERERESkYCgiIiIiAkMRERERkYKhiIiIiAgMRUREREQKhiIiIiIiMBQRERERKRiKiIiIiMBQRERERKRgKCIiIiICQxERERGRgqGIiIiICAxFRERERAqGIiIiIiIwFBEREREpGIqIiIiIwFBEREREpGAoIiIiIgJDEREREZGCoYiIiIgIDEVERERECoYiIiIiIjAUERERESkYioiIiIjAUERERESkYCgiIiIiAkMRERERkYKhiIiIiAhOGorGzHqG/9LtOv6j27UaTfKychlERET09XDKUFSbQGQajIiIiOjr4ZShyDLg1HQiIiKirwdDkZ3p34Xu7nZMmn8aeZLlJ5+B7in2z1yE46/1lp9QHfqi+7gufbyO1eNX4Uqp5Qf1BPsz0VeNoUhM/3JPR0Dyc6v59Y70AY/On0LqG/MTdtnxaLgN/xMvv8R5XJOC+O7DseqZzvITh+gerMGQTqOw/qkjyxfi1Pje6Bl/EcWWH5kqyUTKkavIqnV7SHh7+xTO3C2EaRapXp2ryUbdv+g+rkNS3k6Mcg3BAbs78Asy688W/U113zjYJ78SupybOHzpKTSmM7XXkdSvB4L+yjM7juo9G+fb2lJtI6o3vvpQ9D9/u4UXuWXKcqNmPq1+KBJXlit+64Dw44YyKmlwfmI3DFh0D3U2dOrSMeeHAZiVZl7iFx0waxmKpPwUrJ65EVffO3K61OLR/mTMO/TcbpvqX2yAe8eJOFPrs468D7tjyOpMmDZt9epcPbbq/kX3cR369wpF5v1Nfd841ie/FkX7A9HKZx/em87Uv8LJRXOw426J6dz6z8b5trZU24jqja86FP23X9LwJNtwHz/zdRn++6A0hqLqqmUo+hTUB6+aUA9Fn5Ktun/RfVyH/r1CkTlb+4YqOdWAb+N8W1tO1UZO6KsNRf91YCoevDAEotf5Wvwf93Sr7zjE0VBUfB87JgxHdzdXNGvRET1Hr8Od8mOt7AWOz/XH9x3c4OLaC4Oi/kRqgcpdCPkg7dccjVxaw6W5mNy8seWVXhkwW7X5DgN6d0bzpi3RSpzUJ+x8YHY7X5ebgmUhv6FTS1e06PQLAhb/jVy1AVYqxKkpA9G+ZUs0atoO3Ycl4nCmtvLz4kfYn+iNvu1bo2lzsX3jfPFjm2EVg4guYxOChg5Ap9auaNTEFe1+CMTCHduR5DdIrLsFGrfsiV8n7sdjY3OZD5I6PN07BSMG9Eab5mL9Tdqg408RWHuz/PGVFlcT+6F/8m27bSoPXkObuIj6Gdqp1aBluCvm6+5tR8Sw/ujYqpVSdq+Ev1Fqd3vlfdgZDZu6Gtq7eUeEHy1RGdhL8fjgLIzq11l8R5QxeDxWX3lbEaR0tzch2P1HdBH1bNxYff+Us1X3qvexhIK0zRg/tDdcxXLt+nkj6diLilv01d0vyjKO9BndQyz+uSuiT1feBdBemY6e/Rcgo2IsKcT+gM7w3VcAvdx2Ll3Rd2AfuIl93Exs08jpx/DCpIvZPR6KrmCxz1D07dQOzZo0R1M3leXNFOPB3kSM7NNRtGcH9Bw2FbsfmNyxsNufzfub+r6x6JOO1E/7CueWhOOXbuI7jVvApV1f/OK/AemqY6/9voXiG1gV6I5e7d3QpEkrtB60RKWcj7i3dwZGfdcFzZu1hlt3Dyy6IXqG9Bbnkv3xU/cOcJHr2s4bfz6XS7bXZnq83B2J3m1bo0njVnDr44PkC28q6iMP+E0btTIeL23Q8/fL0OoeY+mgHph00dAbqz4eJHy4vRtTvfqjXYsWaNSsHTp9PwqJx1+rX5yUZeJ4ciAGdGqLpi7iuz9Ox9kP8geinIwdmOTRT/Q1sd29R2HytgwUlp9a9bk4meSNn3p1QYtmzdG4eWd8570YF8o7uY3zbZXHWhXbp9pGxs/oy/sqQtGGo3noHf6g4t//94BU3HlmOMjffdChmddtq2XqNhTpkbVxFDqO/RP3C+XRuQhZT16hWDk4i3A5cSB6h2xDWp4G2vcPsCfyO3SfeF4MJRZsXLnIA2brAUk4/6IQGl0JXl1KxiC3wVj20Pg9zT0sHdwHo5ZdxqsSLT4+P4VpP/aA395clZOMOOBfvUSBRlROk4eU2YPR3m8f3sh1FQHifFxfdBq9Ev9kFaGsOA93jyWJdVWGIuWOxqDFSH+vgV5s54MtgWjfdCAmHriDvDI9Sl+dQXy/DvDZ81YJOuYBQx5g+qLPtEt4J9Yvad7i5sqxaNc7CdeUM47pAGS7TW1d0ZfXLaNI/n4JCgrlfWZne23cKTKvs4R3pyehexcfrLicjaLifNz9Kx4/tPfAqgeGU11Fm4h6SpLK/jFhr+729rH+xXaM6TEcs85kokhbipx//oB7pxFY86Rm+8XxPqPBP1N744fyUCD+/5OVQ8VANg5bc42jj+YKpvUSdcnUG9qu5QgsTstBkTiPfHx2HJO+64Ax23OM5do/HgzLj8OfWcVKH7Be3pSEvGMx6DUgHn/dfw+t6E+p6/zRtf98pCq7vqr+bB2KrPeN+Xeqrl8Jbsz5GW0HzcTRR4ViaR2KH6zEYLcoHLM8hTjQtwzrG4s/X5aKb4v2LPhgMcCKNjgajS7dArDmSjY+arX4kP0UL4vEvlHCSleEHngLjTiva96/x0d9FW0maN5m45V8DIm+nHU8Hn27xOGsccRXvQtiEYqqOh702fvg1/Fb+G+4jpwS0We0+TgW0xM/L3lk7GOmipDye3908FiEs0/FsaEtxusnWZAztD57L3w79UPo1nTkFov5qdsQ3KsbfHa/MuwLpV7dxPbnolTM0L0XF1nB36Jj5EnDudfG+dbhY83G9qm2EdUbTh+KghZkKvNKxIm/a9A9/F/f38SNBx+VeR+K9WjjfccqDNV9KNLh0dLB6Bh6BG/Lr1KMpPz98O3gj10mH+ierMavnSfjvOVtehsHqdWjFek99vm1w8jNr5UBruRsHDoPWYOnFYtJyN/lCzf/A1UemLpHKzCo+zT8LV9Yirr6uA3HauVq0sjicYNVXUrOIKqj6TI63Jn/M7pPM1wdWYcik6tuWekFxHYahEX3LAcp222qPnip1E2F6fY6FIr0WVg/vD08t5gOyiW4GN8b3aamQO4VVuu12D+mHK67WRk6pM0egL5JqSYDYglORXeD+7ospV5Wy1exX6rTZz4cDkc7UbbyArL0Fjt9fkT/H75F5HHDcaa7vxQ/i0H1ljyOWt1l0+PFWg+4hR5TrqSrOh6qWt6MPhNr3Hsi5rShHgrtTczoMxBzRGWq7s81DEX26ld4FCFtf0by7co9Jb3ehpFqociBvmW9Pgv6F1jn3gFjd76x6muWYUVRRZtZ0V5HYu9fsEC+nQkbA75aKLLTl+8u+gVtAw8iv6LCWqRM66MaiqSCA/B3G4oVxkBSSYeM5IFoH3ZMCUgGImQeDEPbH5dAOZ2obL8uLRn9uv+OFHn3qJ5va3CsWRzvqm1E9YbThyL5vaFHLw2PyYrEVcf1+4aDXaOV0D3kvlUQ+jShSJxrcs8h8Zeu6DJkEpYfu493xuNMlzoXvZu4wq1DF7SvmDqiVZsIHDI5Lxm+rHaQqhyE4nCVr94HLDTcpXq+ehiaNGtnUr6Y2raDm9dmq185ybeU/14Zi+Hf90SHjj3QvWc3tGxrGAjkuvbtnojLppeiVYUiXRqS+vZHUmp5nfV49ecouIWfVDmpq4Qi3T0sHPgt4pWUYjFI2WhT9cFLpW4yO9vrUCjSnMf4Dj9joXFQKFf0VxBaDt+krMt6vab7x5zjdTctoxB7vFuhiWtns33c1q09flp0R1mH1fJ290v1+oz0dg+82wdi7ztxyi86joj+CTi4xR99RMDSiLKyN47CtwlXIG+S2iBeciQMrUZsQY6+6uOhquXNaM5hfJsWaNHWtKzOcGvdB1MuaRzoz3URiiy2Twy6fbtOxSWTMmyGIgf6ltr6zMht0KH8osKCSiioqs3kY+LFyUUIHvw9OnXohs49e6Ndix8qzkmqA35VociiL+/zbYvhG413c4yf2wpFujTDPlRCjJlC7PVpixGbzO8g6rM2wl1uL/ncqrL90uutGOEaisPygwTV820NjjWL4121jajecPpQJE/yL8zkF6nL6fQSBsQ+tPqe5eQQcSW21r0t/JWjzFQpjod3wM9LH5sM8AW4e3QFYn7rgU4j1yC92Bg0Ok/BBYtBUJXqQap+EJo+ZpIHuJYBB1FkupAqCa93+aPdj9Nx6nmR4QC/txS/GAcC5QTUrfwuilGVoUjU+fvvMf16+VlLQu7WsWgddtzBUGR64lL73LpN9Vlqg5dK3arYXkMo6vFJQpHVdhg5XnfTMuQTdRu4b3hpVk9TVsvb3S/V6TOCPgebvboh+HAhSi5NQ//okyh8sREeP85HuuYtdnj3xYRzhsfVaoO4ad2qOh6qWt6MPMC3H4h5lS83mam6P1uEItV9U3UoMq2f9uZs9OlhHsQ+dSiKaV/NUGSvzR6vxm/tR2Dh5RyUyOsvvoxpffrXOhRVtKFUgF3j2sJzq+mdLTuhSAm2xjs7ZmoYikzbU/V8W4NjzaKPqLYR1RtfRSiSp/8cmo7sPI2oPzBs2hOrz9Umx5TgzPiu6JFwGWY/OC27iZl9OiL0qMqwormLBT92RuSpUkj5++Dj+iPm3rIxCpiSX2r9pQ+mWpwBqjoIS85MQoeu8ThnmdusaHHl9774bm56xcnH9OrYcKv6ZyRnmJ5Ev3AoKmfaprnb4eUWgSMWA4VV3arYXuXzhL4YuPiB2frM6mzjEcelKX3Qbap8p0R9vba2ozp1ryxDh9TZP8DN/y+rR4nlrJavYr843mdkeuRsGYvOEYdwctrPCBPhCPrnWOX+K+Zf2gO/3pXvnKgN4qZ1q+p4qGp5M/pMrB7SBkPXqf96sOr+bBF4VPdN9UKRUkZL80d2NkORA31LbX1mlDZojzE7HH98Zq/NlG1xX48Xpv3IJDiUHouEm+c2vDZdWXVCkXLM9Uan2HOo7Hq2Q5HcX7xbD8HyJ5af2H581s7O4zPzUKR2vq3BsWbRR1TbiOqNryYUyVNDjwyMtvhbRPYmR5Vcn4N+rX5A+J+X8fTte7x9dhWbowegRa8EXFQykYT3j1KRkVMsroS04r/vQ3j3bzElRU4ahTg7qQ9cf0nEgdu5+FhWgneZqUjPUhsUPuJEZGf0jTuNrCLxvad38PidVOVBiNI0zOnfFn2jduBm9geUlhYi+3Y6nsgvW5rR4+WmUWj98yycyypWToraxyvxW0VIKMbVpIFw6x+HHak5KBJ9oOjVQYR1/hKhyE6byu85fNsTQbseo7CkEC8yHiq/mrKqW5XbK+H1dm+4DZqPK7nFKH7zCHcyPxp+QVVRZ8PLsD26+GJFShYKi/JwZ/8U/NDOAytNX7S2t39MOVx38zJ0j9fDvXUv+KxOQWZBKcqKcnE/9WHFexlWy1exXxzvMwbS650Y0/E79O4XgYPKKKTDk1Ue+LZff/SKu1Dxvo/aIG5WtyqOhyqXNyPC2t5gtG/vhfmnHyO/uAzFb5/g+p3ykFFVf7bYT6r7pnqhSHwBR8J7oMPIJbjwQrTrxxzc3BqB7q4qociBvqW2PnOiDfYFo0NnHyy7+BzvSkpRmJWBu690qqGgqjbT3V2MAW1HYcm1XJTKu7n0Oqb3rbxTJL+T90u7sVid8Q4lRTm4c/eV1a/PrPeXeRtq7izFz24DELP7Nt4Wi/3/6AxmDW6Pn1RCkdxfzsX1QVv3eTj+4C2KS4vw+u5dZIr20GfvgY/yovUt5Hz4gJybW40vWmcb9r/K9pu3p/r5ttrHmuWxqtZG5V+lL+6rCkXVnRynQeaJ+fD9sQdaNHZBoxbd8MO4WTjwuPzekQ531vuhT1tXNGzUEi27/IbApSnIKz9oih/jr+ne+L5jazRq1AqtewxDwgn1v/6qebIPMT91QbNGLdC61xgsT9NUeRAqc7LOYH7Ar+jcsjkaNmmHzj+Nx26Vv8WC0sfYO3kkerq5oolLa7Rq1xsDxq2t/JmvLgcXlkXjtx7t0bSRC5q59UJ/zzk4bfzfn7CqSxWDb81Dkb02FSf2EzMwtKsbGjVui65D5uFCoVp4RNXbW3wb6wMHwK2pC5q2G4CgbY+htRqISvD4QBK85J9Nu7RD11+jsTIlr+JK23q9KttZwdG6W5ahR97lNYgYLAJFU7kPdsV33htw27gCq+Wr2C8yh/uMTCrAgaAOaBtxouJXk/oXG+HevB+mG346aPiaVdup1M3O8eDQ8qbEoJm+dQo8+nQSx4wLXNp9D4+FVypfyrbbn63b2HrfaKoXiuTvfLiDbXGe6OXWCk1a9MDP40T/ax0Nq9cSFfb7ltr6rChtEI9hvTqgaWNXuHUfjPhjoj1VQkHl9220mfQBtzZGY1DXdmja1BXNW3dFz1+iseOpsV9I75CyaBx6urZAo+bdMDDuKHI01QtF8r+zzy5GwMDuaN5U/tn/aIz6qTN+MX0VwVSJ6C+J3ujX3lX5+X7nAVHYofRT40/yh/eFW3Ox3d96YuKWdFT8zVWV7bdsT7XzbbWPNcvtU2sjtb5LXwRDkZ2JiOhT0z1eiUG9puMKbxfYUIITkV3hZfaeEdGn4ZSh6L90u24VcKo7yWUQEdUtPXIf3MKj3A/Q6PUoeZOBHRHfo3vcBcdeav8KSEWZyLibhXfFOui1hXh+fiHcO3tira27lER1yClD0ZhZz2oVjORl5TKIiOqU9B7nkjzwbXs3NG7UAs079MfIyduRXvFnlkn3YCsCB/RE62bN0ahZe3QbFIqFZ7LVH50R1TGnDEVERERE1cVQRERERASGIiIiIiIFQxERERERGIqIiIiIFAxFRERERGAoIiIiIlIwFBERERGBoYiIiIhIwVBEREREBIYiIiIiIgVDkZPT5D/F/Zcfa/y/Lq0vykVWXkmNl4f2PbJfvoPGcn5tSR+Rffcp3ta4YlSu1vu4mjQF2XjN/62vGipD/otXeP8VNt/n7qf0dWIoqsckbQlKa/W/gigh50ACYnc+r+H/mKKE3EPTEbPtqerymlvrETZhNx6pfWike7wdUQlH8aauz2Tam1jqtwj/1HnaqkPSe5ycEYxlN9/hdJI/Fl11rLKOtGuNSRqUlOpNZ9jdx3VPi9TlIViQ4lhbVNLh0c54hK25JWKBfY60X62PLat2dLx+1aErKTG/oNDewvKABbhYajrzM9Jcw8KxyTj//joWe8/CqU+Vzqza93P307ok4eq6u2gy/z2KLT+yq6bLUW0wFNUJPQruHsXyhGh4j/bBmHFBCEtYh4uvTA/qapIKxIAai00Pa3MK+LShSPrwFNfTXqLEznnxqw5F4lR2fm4k1t4uwqXkMKxI0yj7w3fxdauTnJR/Con+S3G52LF2rRk9svZMQfyBHJOrbfv7uO7VNBRJKMm6hWtPP1R5p6DK9qv1saXejo7Wz2EigCwKXIEbWpN5XzoUadOwPGgJUorTsTJI1MOyI9cJ9fati35a+PdzuPyWhv8xKA3/z4A0/MvvMeLOl6LE8ot17MPz9zjwQFvtvlHT5ajmGIpqTcL7G2sRHjwHe26+QrHce6Uy5D28hxfKP2pInLhP1OrELfu0ocgRX3co0uLW2mT8lV2GjPVzseu5HlLuMUz1X4YrZoOJhPyTsxCgEpbqlh4vdsd/ksHGcTUNRXWo1seWWjt+ApqrWBhQz0KR7il2zN6G+2WZ2JX0JzJq2oR2qbVv3fTT/CMP8f/Ofm+4m6fX42X6a/zinoHQm7W4gCWnwlBUW+IksTUqAivTbA1nIjTdOYj5seHw8wtGSPwanH5efl2iwd3dMxEdGo6gwBD4+EVjxs7bhvcF5BN34liMDoxCaFgUIhaeQ56kwYP9cxAdEoaAoDAEJR2HfDNKl3cT25ImIECU7x8xExv/yTHecrcRiuQ6R0/B3izjiUD/EnsmTsCWx8ZvSbk4NC0OO55pxYnod4wOiEFEaBj8fEMQNf8oHhnDnnngkVBw+y8kx4rvBYQhMGIpLryTlO9EjAtDRHgEAv0DETBxJc5mWQ+I0psUrIqPRmCg2LbA8VibJk5bUjGenFiJuNBg+PpHYMKiw7j3wXiatAxFpZk4vTIBYUHhCAybimVnXhhOfFIJHh3+A7GhkaIdIxGRfBo5ViOZet2l12cwL1zsm+BQ+IfPwvb094aTtO45jsyLQ1iwWFdAEHxCErH+Sh6sT6sSSnJzUKCTUCr+M18e3KS3OJ4YgkXyLaGKr+WLQToMS28YRjrzdtUjP20PZsdEiHpEICppN24VSNXYh6Z7Xh5s4uDpHa70qdCodbhaIg82tvexzfVbsNlWgib7b6ydFg0//xAERiZicrgv5iuhSELh9c2YEhmh9Gd//0hMW3cAu5clIiIkFL4+YZi8/jryjf2rclA0Lhcl18m6zqbtp39zDesTYhAcGoWQsHhsSpf7laPHlhYZm+MQHCz33TDELjkHQ9e11Y4mg7a9vuto/xGhaIGXN/xC5XrGYMaBTOjkUOQbgJDoaHHOUFnW1nEgzgh3ds1EVKh8fIXCL3gKlu05gDXTJyIkKATe/pOw9NyryvOEnXLyc/JQJmmR/yoPatnM9vnIzvnOjK32tdNPpQ94cGgpJojPgoJiMHX9FeSqpCezUKSQcOfPu2i4+IOonYTsq9n4aWw6/o97OlqMf4kT+YZv6XPy4R+Ygf8cko7/PeQ2Qq7o8ebSC3T3Ev8eegv/67cM9Fr4ColJ9+Ey7Bb+x8/p6PJHAV4ad8zTnffhuvoj5FNA7vVs9B+TjgYjMtBwzDPsKhAzNSVYP+seGg/LQCOPDHy72fBd0+Ug6XB9/zN0Hi7K/zUd7RJycOm9oXzoivHH5DtoLOr9n4PT8N+G3Uf4+TJjX9Thyq7HaOORjkZinS7xb/DIorO9uZSJTiPEdgy+hf9vcAY6T8/BBbleCglnlt/BN3LZv6WjzYw83Kk4heuReug5uotl//eQW/ifYtluawrx0bicrfaszxiKakmf/RcmBq1HhunVnAkp9wxmhiZh/2P5ZWcd3t3ajNiwVbhRJB/MJbgwNxTL0wwLSx/uYH1UFDbe1xlO3FZXs/L3Q7A81SRU6F5gb1wUkk+/VE5QmtcpWBoxEZsfyIe9jVAkDv/U5WGYfc5wq18qPIekkaOQcCzfMJAVp2B+xHqka+UTkRigNtwznPx0+UhZHIGJ+14qJ2HTwUfKPY0ZobPwl7Kd4t+if8i1VL4zeT+ylE3U4NWJuQhIOot3FidC5XtTjyC3Yr4Y+K4uR8ikbcgokNujCA/2TEfwnAtiAINFKCrBrbXRiFx9E/niq/qCm1gROQ37RWCQCs5gRvhalGdWbZl86jNnq+7QlaFUo8xBUfp6hEXtwBO5Icuv1pVsK4LP032IC1wmTtwmhdokAtiZufBfcNl44hBz8k4gMXQdbhnP1GbtmnMCvwfPwsHn8h4oQ+aBGQhdegPFDu9D40oUtq7Abe9j2+u3YLOtnmDb+Bgs/SdXaVOp5CUOTQ+oCEVykIguDxJlz7Fzoi8SDmWjVC6q+AH+jIk2HgPmochsOZv9Uod7G6KRcOSNcXAoQ5myWgePLUFTWmYIHLocHE0MxtwLcnvbakeT0Ga37zrYf2zdKfKfg1MFyt6xWNb2cVB+rllhPNfoxH5NHBuHrQ8NfV6TdRDx8qM6pRPYK6cKds9Hds53Zmy1r61+Ko6pvxcjKG4n7snnVV0uziZHY9aZdybLG6iFovQNd9Dgjw8ofZmLPu4PMP+xvJ16ZGy/j0YzCyDnDu29LLQMeY2nJk0gB5ZWq4yBpbQY03xT0XtHCT7KK/1YhOgxGYi5/f+zc59hUV2N2+jP5/PtfDrXuc553/ecf2giqIgxwRJNosYYY4yJvWFB6b0JWDDYGxIj9lhj710jFtTYCyD2gqIgYAOkTLvPWntmYNgzDDgKj/F//65rnjzO7Nl77bXX7HXPWmswlqAm3OgrMSPgJibeNu7IUKVXpu4qTj/Ef016gSLlaQMqlA+AxfvE/y/JfAgX/3wcl98S9DqcW3cbTokleCLfo3kDv/738Jfpg1l29xk69n+I3XI6/mUxeg3Pw5Fy42vV4pjqK1nnXLQaZCy/hf8ZW4w804aVlXrjZ0hbhT+istDvqHFK7+WZR3Dxe4xDpqmA6quP4ZxQgleQ39Pqr8+PGUPRe9LdXo+w+J14rG5lCmMoCV19y9jYFG9xZn4w5p6WXWLdG5XYG+6sj8OUA8Winuu7cVtuL95xbxMiE0ToqDm+ASUHpyFgWTZks7UdikTHdSYNwaJzkzeYqotLMWnOfPFt9pzS2Wmy/kTkokuQv/NQD1lrriyF/7yzyna1nY84zr7fELbmtuo4ltuYnig/hZlBK2FxCgqr7cQ3v5OzQ5B2waKn0ORgeXAKDsjkZBmKNFfxh/8s/F2TtHS491c8UmRAqLiMP0KTsf5acT0LYOsvex3aa1gckIazcifqKQxDIfZMSsBGJQU0zFB6FvOCFuK08gssUcfiekWuvV3TRmrrQo+CPcl120/5acwOEyFc19hraKm+zqa+a2zv+OYnbLCoK93djYhM2odnNe3TcvpMfWwd7m6IEyGmxFQ+HXJWRmLmcRlErEOR7TLXrb/8XVMQnpqBB2UWH9BGfrbqkp+l3xC3RX6WGqjHBttuI9tPfaGovvfa+xyoz0++b3IiNj80HVOfhy3xydglL5Td/dhn/36krmOL+515c0UD9Wt6puaai/o+MSsYaedr61tzdTmCxRcP9UhW3ekzHR5cLUSfATkIvSra3sZbcEkrq71PlL1A3yF5OK41haLw5zUhQaoziiPKd37JDXy73RSixb8zFmSj9wFjeKjZ1qDByvhs9NxQhgKL/K3JfgL30eIa5MnWXav2fVqsTcjC0FMWBdCUImDgbSwslP9fhqL72GiuAn0V5gTlIvG22Fv5a/gOvoW489XWX2ZM6p6LUP0G4wfcRmqB5VZG9zbfgveqCrGtDhuSsjDweG271Vx7DBclFBns1ufHjKHoPemf7EJ8yGrcsNlJiG+qa2MweX+RRUM3Pjdxj/zAq28S4ia+cwoStudD38gbt+ZSOsbOOV2nsSvPzcpEOeoLRbJfOIGZEWuQo9Ui588UrM3Oxp8JK3FNIzumJMxTvhFb34h0t9YjfHoGlBkcy2/k4pym1DlP0/bqsKO5jLTxf+B83S/k1tvpC7AryWI6SHnumXgu1lgnFqHIUHYSM0YEIDxhEhJMj/jIKEzb/0z5Fvn20Wmsnz0BIfG/Y/u1ElVd1F/2yrxT+HP2FMREJyI+IQ7jfE2dkVXHVIpjM6Pw5011LdenAhfFt9yZGa9hkOc5Mam2c0Lder2zLgq+QYk155WQMAGh4X8qHWXjrqGlxnU2tdfY/vEt1VdXSluce8aifdoLRXo8FuVL2lVg6ljkecRj6qEXqraofl997VK+8AJZe5diYlgMpq46iQfya3wjP1vQv8T1nelIjp+A6PiJiAvxR6RyzAbqscG228j206hQVPte+58DdSiSdRBTO0ojQtLeycbpVvv7sc/+/Uhdxxb3O4vt37md6gqwO3EsxkfVljchLgahC08r7cGSDEX/+3fX8b/6y6mebHhFPMRvZ6pEeDLgn8XZ+D8G5OIL/5umxw24DMvDAU3jQlHOmpvosKHSVD5jSOq2wxiSLLfVvypH+oI7aDHkFkZvKzONDulxJ/MZBvllwyM+H1tNB7IcYZoZeAMTblmckHwuwDQapQ5FIkStiMtB2HXj9q/vvkDshBtw8ruPlPOmkXALVqFI7HtWYA5i5L71GhxZ9xDf+N1Aa7+b8B50DR4WZUqwKJNlKLJXnx8zhqL3pb2F1WFRWJmjHvuWjKEkTHzTrr3dvcXZekeK9Hi6yxyKSpExM1Y1tKzeHra/mR2S38yy7IwUyc1ei5vpBKy9kYv1yWuQranGteWTsSrrHjYnpeKEcWGT9Y3otrwRHVN1Pno8252M8LV3rI5jFXZEKPrdvxGhyPxt+6LFdz3NDeXb9n71SJHyi5hUZJqGh22T4egIZodMx8HaOTrIOrdZdmWNTjTSL74yPq8x/dqmnlCUITqmVbnqs6+f5sZahCcfwrP7WxE/5UCddU6WI3DP96XUThOpNeoaWpLtKxlJu82hQ7J3jRs4vpmdutLdFe2zzkiq/VAkO8OkXebO1zhC0ahQZLNdml6UNC9wdXUiglfkQNPIz1blhcXwT96Hx8rP2AwoPmg+ZgP12GDbbWT7EZ+VRUHpuGT5WbH3XrufA9uhaE1NKHqOvVNEOJdr0Ozuxz779yN1HVvc78yb1zxvp35Nz9Rcc305Ts2JhPx1Z0Osp89qPdhsMYWk0phQdGNt3VB0YantUGSmfVWGqaFZ6P+35a/L9Lj790O4jX6KKzqL95lGioZlWhTANFKUamukSGy/UoSi0Gt17wGv7xbhp0G38btqBMiqfNoyhA+9hflPgbJTD/A/wgqRbUq6edtry7Q8Oguj/qktU20osl+fHzOGovcmPvSn0xAYkop9uS9QrbRBHcqePUR+qbiVFx3DtNBZ2PewAnJN0eucvxAfthSXlEWX9m4SWmQtj8CU/YXKh0xXIf9eiXp7+UIetosOKfVkgfJB1xZfRHpkPNbdNq4pKjk0HaGrcq2+GcjXXp+Yj4iJUzFxZbbyetW1lYifNBWx80/D+Lf17NyIVJ2PPn8fJgbNxr77b403Mk0FKjQ2OqjGhiJx7DfnFyM0aQtyS8UeDW9xf9d0BM+Si2LFy1rZyczAEWUVbgWuLI1GwoYbkEs4lP2Z/76Lrhyvy0xPVt3DhtgkZYjaks2yVz3G1ngROG6Z/licPF7IhwtF8rptiY/DlOQ4zDn52uKmqKrXZwcwOXwhjuXL77KCodri77c05hrW9fbMQgTOO62s6TJoKlGhs3+N7R/fRG+nrsR57kiMwIz9D6EsoxPt+qoIRZZripouFBlQVfrGuD5J7PHVyfkISJXTi437bFX+8zv8Zx1HiXIQ+VmaUXNM+/XYUNttZPvRPcSm2ET8dV9+lvWoqKgWfZ2999r5HKjPz14osrufBti9H6nruL5Q1FD9GlmG95cnFyA0ZS/uGRuZOHAlKm30xvZCke5xIboMu48Vj+T4siC+7JWZ/q7DhwtFepS81Bm3Meiwf3Y2uu2sFrcpLYpMFVydL8oxMA8ZmrrHKDr5AM4BT3FKftnR63Bpw218Fl9i/MJhLxSJ/vq5+QtSZTnix+Riyj3Tv03kcf7rt5d4onws9cjZeRefifOVC7LLjt/H/4gvxhNTxT/ZcaemTA933cH/CivAhTL5ih4P9t3D/z3BGIrs1afu+WXs2Z/1Uf7xXYaiD0KDgovbkZoUibFjxmP0mEAET0jDgQey2YibcdZOzI4NR0BQKEITl+DQfRmQJPs3CV3+caRGBsMvIByhk3fijk69vZH2+UWsS4lTflUSEJGCFaee1nzoDc9PIy0qAqln1FMp4rXyC0j1C8eqG6ZPo/g2uyIoCIsumge/7d2IoAoyOhRd3ISZ0WEYHxSJkIgZ2P1QZx12Gh2KBNGZ3DmwGBNCQxEYGIHYebuRUzMeXombW1MQkmD8I32Gioc4kp6M0ACxbXAkwifvwG1RTYaiU6IOw0RojRDPx2H6putWi7xtl12LV9c2I0W+NywGEZExiEzchGxZbrsdU2OJTvboTIwIWIlrFgMKkrpeiy9vEWUz/jIuODQBizJlSDBq+BqqVN3HHlFWv/GhCIqch0P5OrvXuKHjGxnqryu5h5Lr2DovCcGB4vWAYPiH/YatSmesbl8fOhRpkLt5ijhuuPIrtdDEpfg7z/jJaNRnq/ox/l40CcGiTYRFxCI8IgELjhUay9ZQPdpru41uP6KNnFuF+IBA+IsyxK++jooG3lvf58DqXmM3FNnbT8Pqvx+p67j+UNRg/ULVTg1vcGP374gPCRH32QiERM3DQWUFcl32QpGs77wzT/HjqCz8P/2z8F+DczHyqDHUfLBQpKvA/Ogc/M8B2fiv/tloO6kQZ0WgeHEmD20GZOH/G5SN/3fYbYQcrzKGDstjiBB1btsDtB8sfyEm3juxABnmX3PZCUX6ghIMHineI/c98Aa+X/5G+dWyJXmc/8v3FtoPE9v8moWW0fnY89zUXqsqsGzaTXwmjuk6PActhudi4N4q43nqNTiw4i48+8tfrmWjfUAO/s+JL6BkpHrr04Dy8+nwD16NrEYl7ebFUERERPTfmNX0WWPp5fyHiUGPa+tuo9Paitrn/oUYioiI6L+F/+2rS3zYeFiGIvVr9h5vL+ej08gcOA2Wf3fpBr6eXYxrpkFq9baWj48ZQxERERERGIqIiIiIFAxFRERERGAoIiIiIlIwFBERERGBoYiIiIhIwVBEREREBIYiIiIiIgVDEREREREYioiIiIgUDEVEREREYCgiIiIiUjAUEREREYGhiIiIiEjBUEREREQEhiIiIiIiBUMRERERERiKiIiIiBQMRURERERgKCIiIiJSMBQRERERgaGIiIiISMFQRERERASGIiIiIiLFJxmKZBn54IMPPvjggw8+3uXxSYUiyxPT6/U1D1lePvjggw8++OCDD3uPTyYUWYah0tJyPHz0VCkbH3zwwQcffPDBR2Men1QokoFIq9UqgUj+l4iIiKixPolQZB4lMpfrYygTERER/bt8MqHIPEpUWVn5UZSJiIiI/l0+qVCk0WhQUVHxUZSJiIiI/l0+mVD0sZWJiIiI/l0YioiIiIjAUERERESkYCgiIiIiAkMRERERkYKhiIiIiAgMRUREREQKhiIiIiIiMBQRERERKRiKiIiIiMBQRERERKRgKCIiIiICQxERERGRgqGoyWlwb9c0jPMNxfSDT6BTv2yTI+8hIiKi98FQ9N50eHX7ONbOn4JQvzEYMngkRoyLRtLctThw4yV0hiLsmzQS/QcMw5AZJ1FqUL/fBnvvMZTjUeZWpCXHidDki0GDR2NMyETMWLYXlws1ojgPsW92EsICxmP40OEYOHgURo6PRsLs1dh3vVjELQvabCwbNwz9B47C5AOFsC5aFbJWhGOgKMewef+IfxEREX26GIreSzUeHZyD8YNFsBgwVPUYgfC/7ovIZEDprUNYlb4OR++/tRE8bKnnPbpCnEqLxJCB6mOJx8AgpF8VsUWbhSV+xvIMGDgCQ4aOEP81bxOAqZYjT+WZmDnU+NrAkHXIrZOYRCleHMf0kcZ9DZ54AIWNKzwREdG/EkPRe6i6uR7hQ4wjLaEL9uLSoxcor3iL1wV3ceHAbmQ+0avf8h50yNs5CcNEwBkwJBTTN5/D3aJSVFS8wfMHV3F023HckaHGHIoGBmN5thYyYFW/fICMRdEYLN87ehHOVRj3qM/fjfjB5sDkjwVnyyxCmw6Ptycq7zGGpg24xXk8IiL6hDEUOcrwEsdmjMGAAcPgm3IUhfXmHx1urpZTUCMQuekhdJpcrAwcrozaLL5cXbvVo22IEgFlwNgluFSleo/coOISFilhZxTitz6sOw1mySIUrciRocjI8OIokoeIgDM4Bn/dN6Yb3c11CBwkjjl8tAhbwzB0ymE8N6eiqhtYETQcA4aNwlAZpkal41K9ByUiIvr3YyhyVMU/mDdCho/xSLtob7WNOuBU40p6oAhTIxC6/p5pKsuAkoMpGCKCycj5/6Dc6j1y+c8qjJPhZNgsHHttZx6rvlBUchiTTaFowz3jUTUXF2Ok2OeQ5NVYHjMCAwbHYdND+ZoBpWfSMHrgcAQt+RMzhon9DZ2LE+U1uyMiIvrkMBQ5SP9sLxLk1NPgJGy3O01mHXAqzv8hAsdQDIrfjXz5VkMpTswajQEDR2PG8TcikqjfI0LK8TkYIqexgtYi1940lioUGXTVKC24iSMLI43TZ37puKBMn5n3OQzDRBDLPzQNw0QICliRgypDMQ5NHSVCUiK23b+K9LFif0OmYl/NMBIREdGnh6HIQfqnezBBCUUiOLxjKMLbC0gdPQwDzEHj7XksGCX+PXwOMpRRIPV7RIDJmG0MRYGNDEXqhdhy4fXQCKRmFsFYWgOe70vGYBGKxi65Dk3pWcyTZRjzO07n7kDsYBGWfjuKEs0drA0ZLs4z3jSKRERE9GliKHJUeSZmyWklOX12vlL9qgV1wJHe4p/U8Rgw0BdTD7/A24uLMXrgMAyfeRLGmTHr92iuLlNGlwYMnYm/X9kZsakZKRqBUUGxiAwPxnC5WFqUc9aJl3UWUj/aMgGDBgxH0Opb4l9VuLYsBANFmfyDAsV//ZH6TxkMujxsiR6B/oNCseoGQxEREX26GIocpS/AroSRxoXWM0+gpN6cYh1wpIqL6RgrFzdP3YMDqf4iIPlhbmapKbRYv8fw+iSmDzcutE7a/bRmP1bUa4oML3EmNVj5W0ODwtcip8JcUOtj6O5tQrjp12gDA/9EllwHbijEnqSRYn9+WMSV1kRE9AljKHKYASXH58JXGYUZg+j0o8h++gYVVVUof1WAW2cO4O+bFTbWB5lU38CKwOEYMGgUhg0bZrHWR7LxHkM5Li2W4UaOFkVh3p6ryHv5FlVVFXhTeA8XDh7B1ZcG61Ak3/r6HFLHG0ePwtfeMv0RRi2upPsrC77jdz41TqmJoLc70Vd5rva4r3DkN18RlHwxO9PeiBgREdG/G0PR+9CX4Oyiev6YohxBWnAO5QYbAUehw4NNcRikvHc4gv+8afEze9vvMZRmYXWM/DMA6mPJYOaL5MMlMNgIReYAN0r59dok7HysTMjh3IJRYl8jMXF/kWmEyoDSu6dxYP8J5Lwwjyi9xclZxlA09ehri+k3IiKiTwtD0fsylOH+iU2YPykGfiNHYuDAERg2Jhyx05dh69knqKg3FIm3Fh/F1OHDMGDoROxUfoZmZuc9Ffn4Z+sSJEcFY+TQ4RgweBRGBcYjOW0zMu6W1hOKBN0T7EqUIWgYxi48j1J9GY7PNIedV3bCjghPqfJ9I5Cwp9C0SJuIiOjTw1BEREREBIYiIiIiIgVDEREREREYioiIiIgUDEVEREREYCgiIiIiUjAUEREREYGhiIiIiEjBUEREREQEhiIiIiIiBUMRERERERiKiIiIiBQMRURERERgKCIiIiJSMBQRERERgaGIiIiISMFQRERERASGIiIiIiIFQxERERERGIqIiIiIFAxFRERERGAoIiIiIlIwFBERERGBoYiIiIhIwVBEREREBIYiIiIiIgVDEREREREYioiIiIgUDEVEREREYCgiIiIiUjAUEREREYGhiIiIiEjBUEREREQEhiIiIiIiBUMRERERERiKiIiIiBQMRURERERgKCIiIiJSMBQRERERgaGIiIiISMFQRERERASGIiIiIiIFQxERERERGIqIiIiIFAxF1KR0BVewd8Mq/PVPCfTqF6lJGcruI3PXBiw/eBc69YtERGSFoagpvb2A2X188Pmvf+BalfpFNT0ebw1Bp7bdEbm38BMJEAa83h6AFk6e6PPHPYc6Zu3NlRjs8yV6Ts3EG4P6VRvepc51b/H8fjYu3X2JxuzaPgOqXz9B7sVs5Nc5bjNc13rOQ3d9Lrq5usMj/AiqLZ4nIiLbGIrek/5VNrbODMMv33aEp7sn3L2/Rm/fJCw7WwRt4WaM9HCHU+tg7HrVULerxfmp38DFyQM95mZbBIgqPD6xHPEjf0LHtm3g6uaN9t2HIGjmXtyuEOf+OgNTf+mFjt5t4ebqATdPH3Tu7YvI1IO4U24+pgHFm8aKcOIOz+Eb8ETVMxteHEBw+5b4zN0f217bL6fu7lL0bSHOqUV/pN9rKOa8fygqPxwNL2d3tBi0Go8bkSj071DnmtOT8aWLBzolnxe1/570z7B6cCtRh6Ow4bnlceu7rh9OfefBUERE9G4Yit6DvvAw4rq1gZNTCzi19EHX7/uiZ9cOcHdpC99Nz0Uk0KDwWgaOZZc0qjNUpjsOn8PDt+ZOtQLZS0fA28Udnzl7oFWHXuj1w/fwae0Bl69n4IJGvOf5Jgx3F8f36IJe/Yeif98f8IVHS1Gmlmjruwl5yoF1uLGgj+iYW+Az1x5IPldpcVQtchf2hauzeM3tZ6TdslfSCpye9K1xP6KT7zLlnHjGnvcPRdC9RO7xY7j0tKFhH7PG13l9YcIh9YYiW9f1w6rvPBiKiIjeDUORowwvsC+0I5xFOPAZuwpXXpi7YAMqnt7DkzLRAWpOIq5dS7h8lYLzmjfYE/g5nFy+QmKmuYOvwqmEznB26YwJp94ib8VguDm1xoiNxco0iDZ3EXrLURnPvph0KA8V5j5V+xJ37xcrnb45FLl8twBZpiLoCnYh4POW+KzFYKzIk8MrGpyc0EGUVYYZd7QZtwPmfttQmoEYH7GtfM2lExIyNaaDWDMU7YSfV0t4DJ2C+B884ewdhj0vVQHg9TWsjRuGr7290MKrO37+oYsIUeZQZMDLzEUIGNQXXTt8CY8WbdD2G19MWrke88MHo4t3G/Geb/BL3FbcNKUtdceuzz+MlLGD0KPTF/Bw84Brq6/wg//vOFloOnnLOlcSggaPD8/F2F6dxPE84dG+JwbNOYMy+YoSJmSdmB6u32PWdR30zzORFuGLHzp/gZZu4j2f/4Ckv0tFYW5htX8/dPVpD3e3NvD+Ziji/8qBvNQ1oci8L/FwH7cLb6C3uq6yjZTmbMOUkT+gfSsvtO7QF36zDuCeOWHq7mJL3Bj81O0rtGkpArB7e3TuF40Vl17bnOar7zzMdefctosyyujm2Qk9xy5AxjPLuFiJ+/vnYIyoH0+Pdvjyez9M3XHHFHYrcXVlBIb06YmO7bzRwv1zdO4/AenrliB2aC+082wNzw79ELLiKmoHGMW53diGScPl6+LcOvXD+Hl/43H9zYqI6KPBUOQgQ9FW+MppmjaB2F5sq6uCqoM2oHjrOHg4W0yj6LIxp4eHCBcxOFyu7jy1uJjS3TjtMut6vd/0bYUilB1HXAcRdNwGYMkD+WQZdvm3Ef/ug2FDO8PFrR/Sbsrn9chf5wsP1y4YPLw3XJ29ELD3rcXeLenxaMUQtHD5AkF7X+DJmpFoKbYfuu5p7ToZfQG2jfOBszhHrx6+GOc3Et+194RTTSgyn2NLtP3OF35+Q9G1lbsS1Jxb90D/0WPwo08rODm3xi/LHih1pA5F5n+7tP8JI/wCMPS7L+DiLPbnvxtF8jKoQpE+bw0Gievk7N0X4+MnIz50LPzSjfVvDBNi3z3HI25CEuITU3Hwib72GJ/3wcjxQRg9NABLZOXqHmJ9+AiMCoxEWKAvuouA6CQDyDV5IFMoEnU5IFzsS+xv4pqrIlaor6vYzYMNGOEt3/slegwejV+6tBXn7IEO4YfqnIOTe1f8NCoQYwf2QCsRepw7JuFEubmya9k/D/E+r+8wYLS/qKsvRV1ZhmI9nu+LRAdZv18PR2B4IPrK+nfthomn5YFKsWOcaDfO3ug6MAB+w36Alxy1FNfLo3N/jBw9EJ1F3X7m2hMzrhjHqMzn5tz2B4wMicDoH3zEMVvjhwXZYC4ioo8dQ5GDtJdmoavocFz7rYCSO2xRd9DP/sKwlu5w/Xkp5HIc3d0l6OMmOqmgfXhlUHWehpfYMqa16JC+QPSx+iJRbShy9voJftHxiAweh35ftVWmz7xHbDCWTZ+PVYPk1M54bDyzEL3cPNAxIRNvNdmY29MDrn0W4fQGueaoFQaveWZ7MbDuFhb2FgHOJwEZIjcZinfCr404lz6Lcds8QvVgBfq5iYDWcy6uKkMNcvrM32L6TB0Q9HiyehjcRCDolXpLCSpV51LQRXTSLf12Qi4Jqi8U1UwJlRtHupy8onFIHlNV59qL05X9tRm/A0Wq6+TwtJNBh8qKShRvDxQhtxX6r3wMfb3TZ+pzrsKZSV1FUGiLQSvuK0HBUHYBv4lw7ORmWqelHu0ylGDrWG8RVr7F1AvWE32NPo/y44iVddXGVFe6XMz/Xhy37Xisv12EoqJiPDs9Az1cRduJyRCBzhSKRIheJC+y4RV2B7aHk0sXTDojS67D7UX94Cqu76/L88SZViEzqSucXbsicm+esr+ixwcQJQK6yzezYcpNREQfLYYiB2kvzRSdrQhFfY0BxyZ156YvwLrhbeDUYhhWPdHi4fJBIhC0R+BeOS2iDkUvsGW0DEWfI/Jo/etpzKHIctpGrj/6JmqPxXTMTSzoJTq/1jE4UvkM60e0hXObAKzePAE+ru0wenMhKg6EoaV4X+80YzhRq744E1+7eqDz5HNQSmN4g/2hX4oO8HvMvGocA6jOiIeXc0u0F4HL+Ix6TZE6IBg79C9cWqKD2K8SEJ5vVM7HbcAqyJk/dceu/jf0j7FygDGMrJdhRF3nFZcx5wcvZSTGq/s4TFlzDk9NSafRYcLEUJaD9bGD0bmVqEsnd7iI+pD7VeqssaFI9wjLfvUUQWMwlj8yx08tLvzWTQQlLwTtr7A+B1Fz12b3Ul4POWjdFhp9Hqq6MrwWwVbddkyPFiM3o8igCkWiHDnzeyvlCD5gLEfVwQhl9LP77CzxGczDcnluNvbn5BmFQzYTJhHRx4OhyEH6gg0Y6u4Op1b+2Nqo6TP5hB7PNowS4aM1Bq06i2Wig5LrcvYpCzLUgUGDs5O6KmuWvp15td6ph7rTZ3o82eKPdi7ucPtuNi6YZ8K0FzClsxzlmYxMjQgqh2PQXnSi7h6t4SJHfspEUY8nwFs81+W3SzYWHVfiVKIsi3VnJxdcd5r0D+TSbRmK2jq7o210hjE4NSYU/TMVHUQo8pl41hiKSrbCV5yP6y/GETh1x67+d820VYuRWPtMb6POxT5L7+Lgolj80lEEUhHaPh+9GY/kgMyZyfAR59xxyjn7YcL4LK7N+l4JBN/HrMWB46dxNNUXrWpCUQHWDLEIZzVshKJf3j0U5cz/ES5ObRC0z3KRvFGjz0NVV4ZXOzBGjjL6hGDF8UycPFn7yMwqFNfDOhTdTOtbpxzVR2KUOvhGtFGt7iGW9vNUptNiN52ss79TZ26hxOYQJBHRx4OhyFHiW/fqIcYRiE6BG5FbWnvH15c/xVM592PVuclOfxfGyWmnrj3RxbUl2osAIRf9WnWe4pmKzMno5Cq+Zbfuj2nHCyw66GqU5D9XFsNarSnSPcb6EZ+LcrVBn7RcY5iqzkCklztcvpmFy7Ic1ZcxrZuHEmjk+ia5jfZ8CjqLDrRt7AnrKaPyDER/0RLObfpgbMwExMSaHtFj0E2u1/lyAo69lVWyGgNEUHTuEI39RbI+Po5QVKMiG/N+FJ12i2H4M1+uuZmH7mJfnuN3K1N1ZlbHULzF7gAREFz7YP4N41ia5mSiCKDm0bVS7BQBwsn1B8y5bnlg9TnLKaYucHZui6Fr8oyjchVXMKOnuB5uv+CPuzamzxoIRY0+D3Vd6bIxu7uHsjB78hmLRdx6HXTKP94xFIlofCK+kzi3Nvh5YY7FLxPF/mwNPxIRfWQYit5DZc5yDPKWv9wSQcCzM7r3/gW9v+8O75ae+G5eDnRWnZtUiqPRnYyjLq7fYvI/5k5O3XnKp4pwOLYH3OTP5Z1boW2XPujzU19069AOrl4hyt/hsQpFguaG8Vdrzt4B2FYoOr/yvRjfUmzzQxpylW10yNuVgsDA6diTbwxzuqwF6CECmHvgPquf2b85GAVvEVzaRR1DnXW+hhfYJte6uPgg/FCp8u8jMV8ri3lb+PTDqMAwjOktf6H3nwtF2ssL8GufUQiMnojE2LHo1sodTm3DsFeOzomwF9XeuOC558hgjBsxDCknKq2PodAhN/UnuDq3hPdPEUiek4pZIT9ZTDnqcG9Jf3Gt3NHyq8HwCxiHQSHrcV9nfc7aO6swsI38W0+d8ePoQAzt3l4EiZb4MmQfnsvLYdVu7IeiRp+Huq7k9fhrrLi2Ini7d0LvEYHwH+uLH7v6YvlD2VDeNRSJf99YjL6e8k9IeKHjz34YL+vh+28RuP1VbegiIvpIMRS9p4oHR7EwagR6+LRT/niiu1cX9BgUgVn77qPKqnMz0lybKwKIO9z6LsWdmm/Q1p2nQleCSxtS4Nf3W3h7eMClhTfadf0VoxNX43yx3mYoguE1jsZ0Uabeesy6hqrnGzGshVwUvrzeReHyjzL+5GZeS2LxguEV9gTJxbU+iDhsHNOyeBHF28bDQwQBL2WxuHiq8hEOzQ9Dv65fwsOtFTzadkE30TnO+LtInKH1OTZ1KCr/ZxFG9PwKrVqIumv5Bb76ORQLjj8zjtCI/y3ImIeR3b9EC3HtPHx+RtKhYmjVxzCruIPtk0ejx5dt4Sq2b9G6I7r29sXk/abF6W9zsT6qP3xayZ/Rf4GvR6xEto1QJOvt1ZX1SBj6Pdp5tkErnz4YPW0PbpunO63aTQOhqLHnoa4ryVCKrI3Joo46ievlCY92XdGjfxy23HcsFMltis+vQsygnmgn2qtbq47o/P0IJB9qor/mTUT0ATEUEREREYGhiIiIiEjBUEREREQEhiIiIiIiBUMRERERERiKiIiIiBQMRURERERgKCIiIiJSMBQ56EbuLSz6YxkWpqXzwccHfch2JdsXERE1L4YiB8mO69Wr1+qnid6bbFeyfRERUfNiKHKQ/EZP1FTYvoiImh9DkYPYaVFTYvsiImp+DEUOYqdFTYnti4io+TEUOYidFjUlti8ioubHUOQgdlrUlNi+iIiaH0ORg9hpUVNi+yIian4MRQ5ip0VNie2LiKj5MRQ5iJ0WNSW2LyKi5sdQ5CB2WtSU2L6IiJofQ5GD2GlRU2L7IiJqfgxFDmKnRU2J7YuIqPkxFDmInRY1JbYvIqLmx1DkIHZa1JTYvoiImh9DkYPYaVFTYvsiImp+DEUOar5Oqxol93Nw/6VB/QJ9wpqvfRERkRlDkYOardPSnMOkjh0Rf1KjfoU+Yc3WvoiIqAZDkYM+XKelQ/GVzUjx748u3l5wdfOCd9dfMXbyelwsMTAU/Tf14doXERE1FkORgz5Mp6XFg62h+MqjE35JWIHdpy4j6/pVZO5fh+nhs3HwBUPRxyIr64b6qXq9y7b1+TDti4iI3gVDkYM+RKelu70M/Vp1gf+2xyIe1YOh6D/u+vUc/NrfF+s3bFW/ZEVuI7eV73kfH6J9ERHRu2EoctD7d1oVOJnQBR5D1+OJXv2aBRuhSHttKYZ16wjPFh5wbdUVfUJX4sKr2oXYFVkbET/6F3Rp1xZubm3Q9pskHH5tfL3y4VHMD/wVndp6waN9TwyOX4sLxbqa95Jta9ZuUsKO/G99GrNNY71/+yIionfFUOSg9+60tJeR8nUbDPwzH/Yyka1QZHh5Bxev3cXjp8/w+OYJpI3ojA7xJ1FufBVFG0fDo1sidl2/j7zHD5Ar/it/vKYvOojwzu3wXcQaHLt+C7kX9mHuiK/Q6qeFuFpRs3uqh73QY+81R7x3+yIionfGUOSg9+60Kg4gyKM9Iv+uVr9Sl41QpKY5m4xOX0/HBWUOzhiKPH9ZgQd1BoC0uDarFzz6LcNdi+cNpacw4avPMWrzc/vhjBS2wo+t597Xe7cvIiJ6ZwxFDnrvTssUiqKOvXso0uSfQnq8H37q9jU6dP4OP/T6Gp7e8TDuqp5QpHuAJf280G/pA9SdLKvGqYROaB12GBwsapyNG7crIWjDhq3KQ/5/+dyH9N7ti4iI3hlDkYPeu9PSXkDyV20weM0z+yM06lBUeRkzv/PGN8Gr8PeVu8h78gDXNoTBxzvOfijSXsOMb70wdvtr1K4+knTIntcbHiM3o6juC2SHORg1RSCS3rt9ERHRO2MoctD7d1qlOBD6BTxHbUGhvVSkCkW663PRrVUgdpoWTpuf695QKNLdR7q9kaJQjhS9Kzld9iGnzCy9f/siIqJ3xVDkoA/RaVWcn45v3b9F1CE763lkKOrUAbHHjaFIe2U2vmkVhF2ltZs0KhRBi8szvoPHr8txz/L5skwkdmmHkRsL6y8DNbsP0b6IiOjdMBQ56IN0WoYyXF44GF4tv8XI6X/h8Lks5ORk4cLxXVg6dTZ2PBLpRXcXf/zkhe+nnsCTcvHvspOI79QOvSfuwuUHhXhemI/bu+LQucFQBOgL9iK4gze+i1iLjOu3kXtxP+aN7ALP3vNw6W3dbek/64O0LyIieicMRQ76cJ1WJR5mLMeEkT+hk7cXXFzbwKvjjxgSsRBHH8tUo8fz47MxqEsH+P4lR3MMeHN9A+IG9YC3hwdcWnijXZc+GBC8DjlKCKo/FEkV9w9i9vif0aGNFzza9cDAmJU4W2RjQ/qP+nDti4iIGouhyEHstKgpsX0RETU/hiIHsdOipsT2RUTU/BiKHMROi5oS2xcRUfNjKHIQOy1qSmxfRETNj6HIQey0qCmxfRERNT+GIgex06KmxPZFRNT8GIocxE6LmhLbFxFR82MochA7LWpKbF9ERM2PochB7LSoKbF9ERE1P4YiB7HToqbE9kVE1PwYihzETouaEtsXEVHzYyhyEDstakpsX0REzY+hyEHstKgpsX0RETU/hiIHsdOipsT2RUTU/BiKHMROi5oS2xcRUfNjKHIQOy1qSmxfRETNj6HIQYv+WIZXr16rnyZ6b7JdyfZFRETNi6HIQTdybykdl/xGzwcfH/Ih25VsX0RE1LwYioiIiIjAUERERESkYCgiIiIiAkMRERERkYKhiIiIiAgMRUREREQKhiIiIiIiMBQRERERKRiKmor2DZ49fQWN+vmPTjVePinAG4P6efo30rx+huelvJgN0eftQHzyQTzXlqGw4PUH+5xqiu8gK68MTXkFeI2Jmg5DURPR3d+M6KmHUPyR3bsM2kpU6Sye0GZhSWAqTldZPPcfVPXgCFLjwuEfFI6w1FN42YT1p8lajfAJ23HPsj5UDG/+QWrYTBx8ple/9BHS4tqSUKSee8cuXl+IQ9OisOD0mwY780bVmbqNvSuDBpVVlvWtw72tkxC+MktE+A9Bjzyxv8n7nkP7QT+nBhTtn4bYTQ/xPqdvn4PXmIgahaHovejx+uYhLJkaA79R4zB6bDDCp/6J0wX6jzMUGV7j7+nxWH/X4pb9MYUiQzEOTo3Fsqsf8pt2/dfIUPYQl68/RaW9g+lf487FXBTV9EF29leSiYURoRjvHwL/gBAEhE3G3L/OId9ct+L8Dkweh0n7C2AVsSpvYFVYOFbdeJ/u1NEOU4OiG5dw+6VVqaw0WGe22tg70SN/x2RM2lto0QYMqMzPwqWHH6hd6J9gW8Jv2Fto+MCfU4Yion87hiKHGfDmyipEhMzBjqsFqJA3VUM1Su7ewpOKD32z/UBEh3VU3WF9TKFIm4PlwanIrFS/4Cj71+jd2d+fvmAfJkZvrhlF0ZXl4XhaNMLX3jJOz+juY0PEGAwLWYqL5ZbH16NgfwpGDfPDvDPvcyE+gg7TVht7J3o82T5JFYo+LP3jnUiYtB8Fhg89ostQRPRvx1DkKN1DbIyOxLLrFepXFPJmGzk2HJERkQgKCEJgwjKcyK+9kelKrmLTzAkI9A9BQOQMrP2nsHZdg+YZTq+ejvCAEPgHJWD21iyYv8Triy9h9dRYhIRFIzR8EtZnmyYUqh4jY9lUhAdHICh8CtKPP7GeapAdVsoYjAqKRlh4NCIXnkSJRoSi8YEIjYlBcFAwxoWmYPWFktqRjHr3q0HuthmIDgtHYFAY/EMmI33HXqycloDQ4FD4BSRi8cmC2s6h3v1YkAFtnB/GhcnyxWDSljvK++uvKw3u7J6DmFBRhuBwBM88goI6sy4NXyOlQ9TewdqIFOwvMveMBrw+NhfR6+9BZxkaG9ifOhRJuhurETzlIJRda69hcUgaNqyaIDp9i9GiymysiE/F+mUTMOVAsVUYMDw/jnkREQgOCUNAxCxszq6d5tI8O4tVyTHwDwhFUFQKJkaMxwKlwzSg9PIGTI6KVOomICAKyX/uxfb0FESGhmH8uHBMXH3ZND1Zicy5YVh6XVv7PnGewSHh8B8fiugFh3DPFCItQ4TNtmirjRlsXSctcjYkISREfj7CEf/HSRg/HjIUJWGEX4Ty/rDoP3GxUhU2DBV4cHQZksJCMD4gEhPSDuBWmbF8huenkZ4Uq5Q90D/Q6nMn9/9YhK6Ju431r3xOgyYiOT5S1FEwAuPSsPumeUTKgLLzKxApyhgcFIqQSWtwvth81UQbubEH8+NFHQWGIyhyMTJf6euUs+r+bkyJX4bzSiXr8fL6DsyOlfUaieiZ25H1unFlrv8aWxKfxy3i2orPXmCQ2E/oRMzbeg0lprZorw3pX1zHltmJ4hzDEBgYiuD4xcgwf5AMZbizfzEmiM95cHAspqy+gCK5T0Ml7h34HfFhUeI6RSFyfgYK1Q2X6F+IochB+md7kBC8GjmyH7FB6Twm7ka+8roGBUfnInDmCbySNw7dE+xMisb8jKeQfa3m+TksjkzAhjsyJlTj5tp4RC27hGKNvPc8wZG5UaITfSputDrcWhODqQeLTZ1DNaqVe2MlslbFIGrFVbzUyRmfq1galYzd+arpEFvf4mWnHzAHx17LbQ2ofLgLSUHpoiOSL9rbr2VHKk6p8ChSxiRh4923ys1Wk78Pk4KW4ooy8GFvPxZsjVrZrStZhlAsuabuIIwadY2UDr4aV5dEYm6muTOswoVFsVgq92tRpob2pw5FuvInOLU4FuFrbxtDXMVpzIlYj9wCUVdRYj/KeRpQcnQOJvx1F89kh7rlkfUog64aVRpZMgPKs1cjPHoLHsiNtA+wKS4Wi/8pUvZvqHyK/dMCa0KR7KBjzEGiOg9bE8Zj6v5nqJK7qriDdbExprZQNxTVeZ/uJc4tikTCrqc1IcJYZ/W0RVttrJ7rpKmqNgZDXSEOpYSY6t/WSJFlKBKh7eIShCZuQs5rcQxDOe7smIaQOZkifJnKl3zIGELVnztJn4/tCcnYZVojJrePil6Da3Jf4tilt7djUuginDUHluoqY32Jz+WDrZMQuCzLWNdFGZgeNgt77hvbu0HcezQW5ax+nonUhAU4ago3BvH5+C1kFvblyYtejcd7pyNs8RXIeG23zHavsSXjNVxi+jzqy+9j7/RwJOx8bLqO9bQh3VPsmRSJ2Ycfm0Y+X+HItDjT9RPB7+wiBCdtxS05sqkrwon5MZh1/JX4DB/H9IhVMH8/0FbLsyf692MocpDu9nqExe/EY1W/bmY1LF9+CjODVkLes3T3NiEyQQSmmveKjvHgNAQsy4ZWcx3pAbPwd81dXGz/cCtiYuRNTI/8XVMQnpqBB2UWB9ZcxR/+lu/R4d5f8Ug5/LLujcpWh6UOIoZCcZNMwEZ5x7S737qhSHnf5ERsfmjatz4PW+JNnY/d/VhQlwUN1JW6DCrvco0qLqQjNO2C0klBk41lMUuMwdCiTA3tT4aixOHjERgejdCQQAwfHIppW6+i0NR/GYoPITlBvF9XgStLYjHn5GsYdKLTS5yDIyV6lJ+Yh5BVudahyJIcbQpIw1mRCXV3NyIyaR9q14BbTq2op3J0uLshToSYElOd65CzMhIzj8sgYh2KLKeANFeWwn/e2doOXKmzetqirTbWwHWSxyzc+xvituSJYzYQigxlODk7BGkXLOZYNXLaNQUHimxMW1t87iR9/m4kJO3BU1ORrbYXgfh8WjBmnyq36uR1dzch6rcjInyJ8u77DWFrbquulbGc0enbsSRpJnbeM5dRj4I9yQhdfQs1NVB+GrPDRDDW2SiD5b3C7jW2ZF3HugdbES1C+n11g7JsQ/LY8TuQZ96/5fUTdX1iVjDSztfWtebqcgSnnkdVxWX8EZqM9deKrUd8if7FGIocpH+yC/Ehq1HfulirG53mMtLG/4Hz4l6muZSOsXNOGztg88vyuVmZKCs9iRkBy3HNoipURwMAADtLSURBVP8wlJ7A9PFLcUU+p3uBrL1LMTFMfEtfdRIP3hrEvUu8Z0QAwhMmIcH0iI+MwrT9z2qnaJQd2eiw1EHEUIpjM6Pw501dA/tVhyK57xisvW3atwhJeycnYcujhvZjQV0W2K+rcnUZVN7pGlVcRFp4Oi5UyD52DWIXXTIe03KkqIH91RkpEvVxJjUSE3c/qek4jT8DN44I6MT/n5C0G7cvLEPc0qvKsTTnF2Hc75etfh5emXcKf86egpjoRMQnxGGcr7E8Sj3MPWNRN/ZCkXHaKGmXedpOhqR4TD30osFQpLu1HuHTMyAHT+rUmY22aLON2bpO+pe4vjMdyfETRKc8EXEh/ohUjtlAKNIXYFfSBPxl2dPrn4nnYpVj2vvcyTqQi7gTdxpHvSSr7UUJbq+NwcQ98vgaFJzfjPmTEhEdm4QJMaHwnWIaJRPbTNlfpApOspwpGBsUjnFx63DdNNok93lnXRR8gxJr2n9CwgSEhv+pfKatyqC+V9R7jS1Z17FB3kvEfeOy9h3akOX1E3W9O3EsxkfVfm4T4mIQuvC0aAsGvH10GutnT0BI/O/Yfq3Efpgn+pdgKHKU9hZWh0VhZY7tVcG2bnS/+xtvdDZHPw7J0Y8saDXyW9xs/F1zQxXbP9qGWPNwt5nmBa6uTkTwihxotNexRC5QLrd43RYReDJmxtYGF0kdRJRtorAqV2xjd7+2Q9GamlD0HHunJGHzo4b2Y0FdFjRQV+oyqL3TNarElSVxSDv3EtdWJGGJcd6vbpka2J96+sxQdAzTgmbhiGmtkhxpCp95AsqfmDG8FPUciYCgSTWja9rrKxAwOxNvTftT6J9iR0I00i++MnY6chQr2DRydVfUTZ2RK/uhSIaNpF3mIGocrWtUKJLlnn7MOhSZWbZFW23MxnWqvLAY/sn78Fj5GZsBxQfNx9Tj6a5kJJnW/BjZGCm6aJmcbygjRXJNmFX5LD53Sl0mTcYOi2lbq+0N5Tg9LwhzM9+KS5SB6UELkGEa6pMjtrGmUbJnu5MRvta45q2WuZy38OjIfIQmbsUt45wUnu9LqZ2SVLEqg+W9wu41tmRdx3JUbELUJtzT2GlDN9chdNL+2vVAdUaKynFqTqTYp/pYlmQ4OoLZIdNxsGZNHtG/F0ORw0TnfDoNgSGp2Jf7AtXK/UCHsmcPkV/awM1Zl4ft4iaVerJAGXrWFl9EemQ81t2W/6rCjdVxiF5xBS/k/a3qKf6eFyU6iXzI9RRVpW9Maxz0eHVyPgJSz4lveRW4sjQaCRtuQFkaIQ9RWWk14iBvqFnLI8Q33ELl5qirENuog4hlKLK733cIRXb3Y0FdFsluXVl3BHW92zXSiA4ieso8pMSvxQ1z4eqUyf7+1KFIvvZoWxKC069ALslQQs+8s8raKKnq5h4sXHteWQujbH1zPcJ+O4oXln2L/jG2xk/A2luVxlEJrQgAIabyiLrZkRiBGfsfKvuX1/eq6DAt1xQ1XSiqry3aaGM2rlPlP7/Df9Zx00JgGXRn1Bzz7ZmFCJx3WllTY9BUokJXd03Rm/OLEZq0Bbml4kwMb3F/13QEz5ILui3LZzqQxedOn78HiQm76kx/KttbrOcpuvAnouWvA8sMMLyQ64CW4ILpDyXKLydxpn3r88W1DpqNffffGutTIz6FGstyVuLu1qmI+P28sphd/+wAJocvxLH8KuN1NFTX/C0me2W2f40tyToOxPTDBcZroinCmUUxiN3yEFp7bagqF6vCY7D4XLEytacvu4X18cZRN3ldXp5cgNCUvbhn/rWkthKVckNdOV6XmVpI1T1siE3CljwddM8vY8/+rLptmOhfhKHovWhQcHE7UpMiMXbMeIweE4jgCWk48EBr/0YnaJ9fxLqUOOWXWwERKVhx6mnt3HzVExxf/hvCAkMREBSPaX9dRrFy/9Egd/MUBAeGK79UCU1cir/zjO8yVDzEkfRkhAaEIjA4EuGTd+C2jaygyz+O1Mhg+AWI90/eiTtV9kKRvf2+Syiytx8LtkKRfLreurLubK29wzXSP8H2uFGI3WpanCpZlan+/VmHInHeZReQFjQVe5/pjdNjaZesw6CJsnbMYr2LkQGvrm1GSmQYAsNiEBEZg8jETcg27URXch1b54ngFSheDwiGf9hv2KpcA3W4+dChqP62aNXGdDauU/Vj/L1oEoKDIhEWEYvwiAQsOFZoLFvVfewRbdBvfCiCIufhUL6ubplEELpzYDEmhIq2FBiB2Hm7kWMaWbW6pjWfOz2e7pyC+G1PLEagRK0UnkRabDjGy3Yp6jAieRWOPTSFB3Gc23tSER0chhBRxkjxiF9+QakHWX9FFzdhZnQYxotzCImYgd0PtXXLqSvEwZQozMuUa+d0KL68RWxv/LVacGgCFmXKurdXZuM/67/GlmQdj0dY0lREhshfG0Zj8srTeKrsw14bkj+uyEC6aM+yDoKipyIueAI2mYelDW9wY/fviA8JEfeiCIREzcPBJ3oYik6Jayz2FxIhPs9xmL7pugixBpSfT4d/8Gpk1dfIiT5yDEVE9OlT1h1NxNaaFcWfGhvBs1EM0Otrh3V0Ly9gcXw6ztWZwyX674OhiIg+efpne5EUvx2mgctPkIOhSF+Av1MTER4WiZDQKIQnLMCWay/rjKYR/XfCUEREREQEhiIiIiIiBUMRERERERiKiIiIiBQMRURERERgKCIiIiJSMBQRERERgaGIiIiISMFQRERERASGIiIiIiIFQxERERERGIqIiIiIFAxFRERERGAoIiIiIlIwFBERERGBoYiIiIhIwVBEREREBIYiIiIiIgVDEREREREYioiIiIgUDEVEREREYCgiIiIiUjAUEREREYGhiIiIiEjBUEREREQEhiIiIiIiBUMRERERERiKiIiIiBQMRdRMdCi4sh8blm/G2SK9+kWFoeQqtqXPR8rGbLF106h8chF7/1qFndfL1S8REdF/cwxFTentBczu44PPf/0D16rUL6rp8XhrCDq17Y7IvYWwHRv+zUqxY1wbfObWD4tu24482suz8LWrOzzCj6BaPvFO9VeXvvIFHmVfRG6dAKZH3orBcHNqjREbi2GweIWIiIih6D3pX2Vj68ww/PJtR3i6e8Ld+2v09k3CsrNF0BZuxkgPdzi1DsauVw11wVqcn/oNXJw80GOu5UhJFR6fWI74kT+hY9s2cHXzRvvuQxA0cy9uV4hzf52Bqb/0QkfvtnBz9YCbpw869/ZFZOpB3Ck3H9OA4k1j0cLJHZ7DN+CJKnEZXhxAcPuW+MzdH9te2yin/gm2Rf6Mrj5fwMPNAy4tvPF5118xOmkVMvOV+NII7x6K9O9Uf5Z0yJn/I1ycvRByyLJ8DEVERFQ/hqL3oC88jLhubeDk1AJOLX3Q9fu+6Nm1A9xd2sJ303PR6WpQeC0Dx7JLGjUdZCi7j8zD5/Dwrbm7rkD20hHwdnHHZ84eaNWhF3r98D18Wotg8vUMXNCI9zzfhOHu4vgeXdCr/1D07/sDvvBoKcrUEm19NyFPObAONxb0EYGrBT5z7YHkc5UWR9Uid2FfuDqL19x+RtotGyXV3Ubaj574zMUbnX8cgoH9f0YX71biGO5w+SoBR180Jl68eyjCO9ZfLYYiIiJ6dwxFjjK8wL7QjnB28oDP2FW48sLcbRtQ8fQenpSJLldzEnHtWorgkILzmjfYE/g5nFy+QmKmeS6oCqcSOsPZpTMmnHpr1WFrcxehdwt3OHn2xaRDeagw9+Lal7h7v1gJCuZQ5PLdAmSZiqAr2IWAz1visxaDsSJPDgtpcHJCB1FWEXxEkGkzbgeem/ZlKM1AjI/YVr7m0gkJmRrTQSyYQ1GLoVhlHmaqvItlg9vCSQSPsdtfiv3swbiWLeD64x8w5iotziV/DRdxbomn5T5NocjlS/To+6MIdl5o5dMX4+Zn4InWuEurUGRZf6ZtoCvE6WVxGPBNB3i08IL310Mx9+xb04tmplCknK/x4dwuAcc15lDUEq19usLbwxMt2/XE0OS9uG8xPad/cQmrYoeiS1svtPTuhn7hS3GmyFy5d7Elbgx+7vENPm/TBm6tuuDHkEVYtzwZvr06w9PdC+17+mPBqWKLKdBK3N8/B2N6dYKnRzt8+b0fpu64IyIvERF9TBiKHGQo2gpfObXTJhDbi+sZc6jTqRtQvHUcPJwtpsd02ZjTwwPO3jE4XK4exdDiYkp343TarOumkRNrtkIRyo4jroMIOm4DsOSBfLIMu/zlKE0fDBvaGS5u/ZB2Uz6vR/46X3i4dsHg4b3hKgJOwF51wIDtUCTKd3l6D1E+T/Rb9hC6xoYiZxFIvhmCMf5+6P1lKxGq2qDP7zchM0/DoagcF2b8CHdnd7i1/xFDxo7D0J/HIj1XPY5kHinyQNcRCYifkIQJv+0Q5TLXsTs8v+qPkWPH1JTh1+UPjNekMhsLf/aCk2tH9B4biaDh36O1iztaDV2HR3IDU5mc3Lui39hAjOzd0TjK5twaX/QehdGDvkMrFxHCvkzAMWUttx7P90Wigzyvr4cjMDwQfX3EMV27YeJpLvYmIvqYMBQ5SHtpFrq6ihDQbwWU3GGLqlPXP/sLw1q6w/Xnpbink4MOS9DHzR1tgvbhlUEVigwvsWVMa9HZfoHoY/VFotpQ5Oz1E/yi4xEZPA79vmqrTJ95j9hgLJs+H6sGtcJn7uOx8cxC9HLzQMeETLzVZGNuTw+49lmE0xvkmqNWGLzmmfUi7zqhSAd91Rs8ubwJIV084OTig8gjIkg1NhSJQPa7afpM93g9hnq6w6XLNFzQNhyKlDVGcvsO0ThQzy/YjBo/fVZ9ZTa6i2O2GLkZRaIdvdobhjYyuP52Gk+LilFUdA/rx7aHkwiYS2VlqoNaxWkkdhQhqVUY9smMoy/E+hFtROjpiZnX5EXOxfzvRT21HY/1t4vE/orx7PQM9HAV1ycmA5YTmURE9J/FUOQg7aWZ6CJDUV9jwLFJ3YHqC7BuuOgwWwwT4UKLh8sHwc25PQL3vhYdtDoUvcCW0TIUfY7Io/X/9MociszTRMpDdOrfRO3BPfP8jO4mFvQSHXPrGBypfCY67bZwbhOA1ZsnwMe1HUZvLkTFgTC0FO/rnXbLev2OORRZHsN0nPYj1+OOknkaH4pq1hSZ9+s+FpuKDQ2GIs3xBHi7iDARexz114jU+FCE0t3wk+XuLcutxdWZPetMu9U8XL9BslII9TV9itWDReBs4Yv1hTKoifOe0lWctw/iTmhgeL0TfurrY3oYg5hF8YiI6D+KochB+oINGOruDqdW/tjaqOkz+YQezzaMEuGjNQatOotlA1rB2TsM+5RffKk7bA3OTuqqrFn6duZV2Fjpo6g7fabHky3+aOfiDrfvZuOCeSZMewFTOnvA2WcyMjUGvD4cg/YuHnD3aA0XnwRklJkDhwe6/HZJmcqqo2ahdXt0GzgKI8cEISxhDpbvy0axeeO3+xAgwoVLr4W40ehQlIO533mIUOSHzS8aDkXVGfFo6yxCUdzJeqcTjUwLy2UoOmgZn9R1LFTsR6BS7jTkilB0ZYZxSvCnlAM4cTITJ82PUxdx743BqkzKyNBwGYpGYu0zYyi6mNJNHPsLRGdUw/BqB8bIkTyfEKw4brE/8cjMKqz3uhIRUfNjKHKU/jFWD/GCk7MHOgVuRG5p7XSOvvwpnsqfkKs7UMFQsgvj2rjDtWtPdHFtifbRGSgzvsuqw67InIxOri3g1Lo/ph0vsAgC1SjJf64s1LVaU6R7jPUjPjeu1UnLNXa61RmI9HKHyzezcFmWo/oypnUTYcT083+5jfZ8CjqLQNI29oR14LC5pkhFcw6TOrSEk1cQdim/Rms4FJVfnI2e4pgu3edCmWm6Ngffin+7j90B5Rf46umzx39iQAs53TYRx+3+RF/U5cohoi5bof/KxxbTgdZ1XDcUGfByZyBaieDlNXI9HlgkFtm+FOpr2kAokuvGZncXde36PSafkSOCJnoddPZOgYiImh1D0XuozFmOQd7yl1vucPbsjO69f0Hv77vDu6UnvpuXA526A1WU4mh0J+MvwVy/xeR/zKtKbHTY+iIcju0BN2Uhbyu07dIHfX7qi24d2sHVK0T52z1WoUjQ3DD+as3ZOwDb5JRO+V6Mlx3/D7Ljl1vokLcrBYGB07En3xgZdFkL0EMEMPfAfda/impMKBLn9XdMZ3FeLdG6+0j4BwXi1y5t4KQORS6fo9uwEASNG4IurdzFv30wetMTJbgYnpv+LpFbFwyY/w/eVKvqz1CCA+FdROBwRwufvhjmF4hRg35BzO5XVj+vl2u+vhbn49y6J4b4B2PkgETsKtFZ13GdUCT+XXYOU7vLxdfiPL4egtH+gfAd0AvfJJwwTtmpr2lDoUhe17/GwttFhFv3Tug9IhD+Y33xY1dfLH9oNVFJRET/QQxF76niwVEsjBqBHj7tlD+e6O7VBT0GRWDWvvuoUnegJpprc0UAcYdb36W4U9Mv2ghFkq4ElzakwK/vt/D2MP7hxHbyDycmrsb5Yr3NUATDaxyN6aJMvfWYdQ1VzzdiWAu5KHx5vYvCdXeX4ie3eta5NCoUicO+vISlYf3RsbUnnF1bo9UXPdB72ARsvisPWonLy4Lxa8+v4e3ZCq4t26PjjwFI2X4T8q8XGHdQjqw1UejT8XP4JGSi2lb9VdzDrmnj0cvHG66unmjVoS8itz+2XgdleIUL6cH4/gsvuLh64fOeEdj8UGNdx+pQJGjyT2BhyAB0adsaLu6f44uufTFy/lnI2bN3D0WyLKXI2piMET07wcPNEx7tuqJH/zhsuW9VaiIi+g9iKCIiIiICQxERERGRgqGIiIiICAxFRERERAqGIiIiIiIwFBEREREpGIqIiIiIwFBEREREpGAoctCN3FtY9McyLExL54OPD/qQ7Uq2LyIial4MRQ6SHderV6/VTxO9N9muZPsiIqLmxVDkIPmNnqipsH0RETU/hiIHsdOipsT2RUTU/BiKHMROi5oS2xcRUfNjKHIQOy1qSmxfRETNj6HIQey0qCmxfRERNT+GIgex06KmxPZFRNT8GIocxE6LmhLbFxFR82MochA7LWpKbF9ERM2PochB7LSoKbF90f/f3p3AR1XeewO/tmpvt0/73nvb69u39729n/ZtXUBELIq2BYxiEdzFWkVFRciekAVCiCAYILJoRCCAgIggW0GUfd+VLTvZyL5vkz1kMss5v/c858wkk5nJJJkhkY6/7+fzb+HMOc8858wDz4/nnIlENPAYitzESYv6E8cXEdHAYyhyEyct6k8cX0REA4+hyE2ctKg/cXwREQ08hiI3cdKi/sTxRUQ08BiK3MRJi/oTxxcR0cBjKHLTd27SMjWiKD0X1Wb7F9wnGxpRXa+330z4Do4vIqIbAEORm27MSUtC7blVCHhqFO6+YxDuHPYE5n/dbr+TW8xZH+Hxu/2xu9n+FXcZcDD0j3g4Lhkm+5foBh1fRETejaHITZ5PWmZkfxqAcSMfwt13DsL/+8NQDH1oPF4Mfg+fnSuDO+snsm4vAob/Ga8uO4bU/GLkZ6ajoFG2380tDqHInIPtb8/Bluwelo663U+EovsYirrh+fgiIqK+Yihyk+eTlgnn547GXRPXICW3EAX5OUj9+hA2xvnjkSF/xLjZx1BlnyN60HYoAvf6LEJSP6QMh1BkOI7wYY9g3sUe3qzb/f65QlFaWob9pm71Zd/ueD6+iIiorxiK3OT5pKWFokGBB+xWhWS0pCbgb0OH4+VPi9D7XCSjdutkDH5uLQp6f1CvfZdDUWrqFTw/YRI2bd5h/5IDsY/YVxzjCc/HFxER9RVDkZs8n7S6C0WCGdnLn8OdI2Nx3tC5VV9wAHGTn8IDQ4ZiyEPPwvf94yjtSBQyara8gTt+dwd+a607X8fmahloOYu45x7FsMGD8fs7h2PkC9HYktEK64014zfz8Kfh0ThhtLalMCUidvQIRBzXOuA0FA29s/O9fjcYT67Icwxx3e4nQtEw3P3IC3jG5yEMvmOIek7+y79GjdS1CdfnbUbW1mhMemYMhg8Zgt//YSjue/RNxO7+BkcSZuBFnxG48/YhuGfk3xG1PQdttg1Ldbi4PgovjLofgwaPgM9Ls7E5tbnjutj6dONWNeyI/+9Ob/bpLc/HFxER9RVDkZs8n7RchSLxKE4CnrjrKXyQqcUMqWovgh4chr9GbsXXVwuRdXo9fEcOw5MfZULLMlooGvT0cqTo6lFfr1RDCwxihpeqkXEhHXklFSgrTMf++X/DsDFLkGIJFm6HomEPY9bxGu296hvQpHeIRC7200LRfa/GY//5TOQX5uLylwvw7L33Y/KOKlhzUc/nrbUzwn8TLmYVoLgwG2c+9sOIPwzCg68uxvZzou0cnF3njwcHPYflHc826ZEa/zwGPzAJ7x9KR35+Mr6cNwFDR4Rjv85ZLHIdely95g7PxxcREfUVQ5GbPJ+0XIciXNsLv0EjMENNKkZcmj8Gdz61Etk2K0MNe0Iw7M/v4hs1HWihqFe3z64dQMC9E7AyT9vR/VDk7LaYnW73c3b7zIjLC8Zg8ORdqFNzSW/O20k75mx8OH4YJm2r61z1MV/FR08OxUsbK9XAJVfvwOtD/ozQA/Wd+5gy8f64YZi4qTOU2XMWfpxt85Tn44uIiPqKochNnk9avQxFJ5WZ35yPhGeG4im721NS2Ua8OPhlrC9Vp/nuQ1FbPva/H4mXx4/BQw/54NEnx2HEXY9hgeWJ7BsnFAHNX/hj0F/jcUWcQ6/O21k7bdjjPwxj38+0OU7b9uiidHWb/kgkht4biUNd7qcZcSbmL7g/+oxlFcq5LVt2qiFo8+Ydaolfi23Xk+fji4iI+oqhyE2eT1quQ5E5ZyXGD3oaH2YpU7gpBQt9BuH2ux/AsPtGdNawYbj99mewTL0l1E0okptwbPpoDBk/C5tOiVtoJci9tBqvDB2D+YlajDB98y7+9McbIxQZDkXgntFxuCw29uq8nbVjwJGw4fCJS3HYNjI2Udkmo2GnL+78w1DcY9uuUvcMGoRBwYdg8yiXU9Zg1B+BSPB8fBERUV8xFLnJ80nLVSgyIWvZM7hz1EJcFEHFsmLywsorqKisQqVtVdWhVQ1B3YQi4ynM+OOfEHXS5oc4im33P9YZipIXwWdICPbZrpr0GIpOIvI+H8y9YB927HS7n7Mwo2w9HImh1lDUq/N21o4BR8Pvd7pNC0XaStG9I2ZiX6ldu0pVN/buB16K22XX85aZLc/HFxER9RVDkZs8n7S6C0UymlNX4IWh9+PVTSWWZ1uMuDjvUQyb8gXEl8mc6yYUGU4gYtifMPO0zdqHXSiSa7bhtcHjsDjVJp44hKLlGD/YDzsbbV4f9QCmHXKMdF10u5+zMGMXinp13s7a6TkUSVXKOQ8Zj0UpvQtAA83z8UVERH3FUOQmzyctyw9vfHk1kvOKUJifg7RvDmHjQj88MmQ4nph3AtU2T/uai7fh9eEj8EzMZhxLvor8glyknjuAo1esXyHvJhTJNdg19QEMe3EpDqSVoKq6CiWZm/DWsM7bZ5DK8fmk4bj3+fnY+U0W8grykHHhM/iNeKAjFGnByQdhX+SjSb1b14S9QUq7L32IY1fykZt2Bl+dLnT8Sn63+zkLM/ahqDfn7aydnkMR5BZ8Ezsed4/yx4dfXUBGXgHyMhNxbO95lDqcxMDzfHwREVFfMRS5yfNJy4ysT3wx5sH7MUj9z3zcg3vEf+YjMA4bz5XBcf1CRmvWF4id/DQevOdu/P72ezH80VcwZ3+FZTWpm1CkkGrPIyFkAv48VPwcn3sw5IExGP9yDHYVdu5orj6DD/2exojBlr6MGItn35yNHbmWfeRmXFwxBT7DJ2CZeM5JYSrejzkvPoJ77hiEu/74OF6JP49mJys6zvdzFmYcQ1HP5+2snV6EIsFchTOrpuMFnwcx6A+DcMe9o/HElHW4ERaPPB9fRETUVwxFbuKkRf2J44uIaOAxFLmJkxb1J44vIqKBx1DkJk5a1J84voiIBh5DkZs4aVF/4vgiIhp4DEVu4qRF/Ynji4ho4DEUuYmTFvUnji8iooHHUOQmTlrUnzi+iIgGHkORmzhpUX/i+CIiGngMRW7ipEX9ieOLiGjgMRS5iZMW9SeOLyKigcdQ5CZOWtSfOL6IiAYeQ5GbOGlRf+L4IiIaeAxFbuKkRf2J44uIaOAxFLmJkxb1J44vIqKBx1DkJk5a1J84voiIBh5DkZs4aVF/4vgiIhp4DEVuWr5iDRoaGu03E3lMjCsxvoiIaGAxFLkpIzNbnbjEv+hZrOtZYlyJ8UVERAOLoYiIiIgIDEVEREREKoYiIiIiIjAUEREREakYioiIiIjAUERERESkYigiIiIiAkMRERERkYqhqL+YmlBR3gCj/fYbjgH1pZVoku23E10fxsYKVDdzgBHRjY+hqJ+Y87chYt5B1N5gc4Fs0qPdbLPBlIZV/vE4226z7VvUXnAY8TNC4RsQipD406jvx+tnTNuA0Jk7kWd7PezITd8gPiQOByok+5cGjlyPyxvnI8Q/GP5Bs7El20WH3SKhXW9A/1xqE1JWBSP+/I3/zwMiIoYij0hozDqIVfMi8dbrU/DG5ECEzvsEZyulGzMUyY04uiAKm3JtJtUbKRTJtTgwbzrWJLdcxwm6+89IbilEYmo59K7eTGrE1UuZqOmY0120pzuDD6cFY6pvEHz9guAXMgdLPj+PMuu1Vc5v/5wpmL2vEg4RS5+B9SGhWJ/hGHiM6Z8gZN4BVPRTrjBnbUTIojNotX/humAoIqJ/HgxFbpPRlLQe04IWY1dyJdrExCoboMvNRqnymxs1FB25kUOR6Qo+DozHGb39C+5y/Rn1nev2pMq9eDtiW8fKk7mlGCeWRSB0Y7Z2G9Wcj83T3sTEoNW41Gr7/hIq98Xi9YlvYek5+w9Chu7gQkRuKYBjXLo+zJkbEcxQRETEUOQ2cyG2RIRhTWqb/SsqEYrCJocibFoYAvwC4B+9BifLOicGsy4ZW+Nmwt83CH5hC7Hxm6rO54+MFTi7YQFC/YLgGxCNRTvSUG9ZWpBqL2PDvOkIColAcOhsbEo3aC+0l+D4mnkIDZyGgNB3kHCiFJZXOolQFPsmXg+IQEhoBMI+PAWdUQlFU/0RHBmJwIBATAmOxYaLus6VjG7bNSLzHwsRERIK/4AQ+AbNQcKuPVg3PxrBgcF4y28WVp6q7JzIu23HhghoU97ClBDRv0jM3n5VPb77a2XE1S8XIzJY6UNgKALjDqPSdgmmF5+RGlxNV7FxWiz21ViDiozGY0sQsSkPZtvQ2EN79qFIMGdsQOA7B6A2bUrByqBl2Lx+JmbvsVkt0qdjbVQ8Nq2ZiXf219qtksmo2fcuXn0zVP3MQsITcLrB4Py8ux03MpoTN2OO0vfAoFD4Tg1GxAcHkWcJhiIU+U8KUMaT0v60OdiSJU5AQn3qLiyaLo4JQ0TcTqQ1avvL1WeREDNdbcvf199hbBsrvsb6uZHw9QtGQHgs3p42FR84hCJl/GyPRZgyVvwDlHaC38bSHSnQWa6dXH0CS6dNU94jBH7T3sO29KaO6yLVpWL7olnKeA2Bv38wAqNW4rj1g+9unMl65O3/CFEh4cp1DEfY+8dR5U4uJiKvxlDkJqniK0QHbsAVk/0rGnXCfftLlKmvG1F5ZAn8406iQfxFbC7FFzEReP94OcRca6w+j5Vh0dh8Vfz1bUDWxiiEr7mMWqP4u7wUh5eEK5NouRIQzMj+NBLzDtRqYUM2wKDONXqkrY9E+Npk1JvFHZ9krA6fiy/L7G7SdLdS5LcYxxrFvjL0hbsRE5CAS+pqjat29TizJASrU7ULYK46gtg3Y7Al95o6eRnL9mJ2wGokqQsfrtqx4WzVyuW1En0IxqoU+wlX06vPSF3NMyB5VRiWnLHetmvHxeXTsVq0a9OnntqzD0Xm1lKcXjkdoRtztBDXdhaLp21CZqVyrcKVdtTzlKE7shgzP89Fxb75mL69yG5FSIQiZfvWQpvtzs7b1bjR2oi0tmGux/nlYYjeXa4GM2crRbLyeb4b9B72FotOGlCyZwFCViZBxEH1us09qAU9+7FtKsDWGdOx8psa9ZxlfTn2zfd3Eoq08bPKMn6k1nzsWRCK6C9KLH00oN0oGpTRmr4BoRHbUaAm5HJ8NTsMiw6VWFbqGnB4/gzLmO5+nMmNJ7Bg2npY86xJ+YPDTERE9hiK3GTO2YSQqC9Q4vBwiMbh9lnracQFrIOYA8x5WxEWrQSmjmOVifHAfPitSYfJmIoEv/dwVJ1hNObCHYiMFJOChLLd7yA0/jgKWmze2JiMFb62x5iR93kUYg/Vd/2Lv7tQZBtE5Cpl0onGFjEDuWy3ayhSj5szC9sKLW1LxdgeNRe7xQPKLtuxYd8X9HCt7Ptgpy+fUdvFBAQvu6hO+jCmY03kKi0Y2vSpp/ZEKJr1ylT4h0YgOMgfr/w9GPN3JKPKkgfk2oOYG60cb25D0qrpWHyqEbJZCRGzFuOwTkLryaUIWp/Zy1Bkd94ux41jG8ak1fBd+rUWchxCkYTKr+YieEM2Ot6h9SwWhShBztzD2M7dgrCYveh8Lr2722eO52Au2IEIJVTmd70A2gqb3zJ8bbC8d9QuFFvbtx3TrsZZWyJWBM/FppRaxxVKIiILhiI3SaW7ERW0AU6ei1U5TBzGRCybugIXlLnBeDkBkxef1SZg68ti23tn0NJ8Cgv9PkaKzXwnN5/EgqmrkSS2meuQtmc13g6JxLz1p1BwTYbcohzzqh9Co2cj2lJRYeGYv6+i6wO9vQpFzTgWF45Pssw9tGsfikTbkdiYY2lbCUl75sRge1FP7diw7wtcX6tW+z7Y6dNn1HYJy0ITcFF5I+OVTzF9+WXtPW1Xinpor8tKkXI9zsWH4e0vSzuCiFS8C1GWFRaz8uuZMV8i5+IazFidrL6X8cJyTPko0e7HODgGGmeBQnY5bhzbMGdvQuiC4xB3xBxDkRlXPwvHpIBZHZ9XdPRMBId+oo7BHsf2knM2n1fvQ5F6Dkp/E5VN+uLT+GTRO4iMmIWo6BmYMkn7DBzatxnTrseZjGtFZ7Fp0UwERX2EnSk6u/BJRMRQ5D5TNjaEhGPdFedPBTubOD7y1SYOp6sfB8XqRxpMRvGv4kU4anl+QzAX/QPTrbcPrIx1SN4wC4Frr8BoSsUq8YByT0/KKoHneNz0zuAi2AcRdZ9wrM9U9nHZrvNQ9GlHKKrGnndisK2op3Zs2PcFPVwr+z7Y69NnpEfSqhlYdr4eKWtjsEq779e1Tz20Z3/7TK45hvkB7+Gw5VklsdIUGncS6o/skeuV6xwGv4DZHatrptS18FPCyTVLexrHQONw7QWX48axDbUvC45poUjt1ymtXyoZ1XtjO2+32XE5tnOVz6vLalrvQ5FU9iVmhm9FnrEcu6IjkHCpQXt/sXIXaFmty/oMwbP3dT4PZBv0ezXORDg6jEVBC3Cg4xkyIiINQ5HblMn57DL4B8Vjb2YdDOrfr2a0VBSirNnJt89sJg6Yi7FT+Us//lSlupRvqr2EhLAofJYjfteOjA0zELE2CXVivmgvx9Gl4Yj5sgzi2ZD25ia0q21KaDj1Pvzizyv/am5D0uoIRG/OQKNlFjPr9U5+cKQJaR9Pwzv7qtTJxtym7GMfRGxDkct2+xCKXLZjw74vgstr5TixdtW3z8ioTLgR7yxFbNRGZFg716VPrtuzD0XitaJ/xCAwIQniy2Zq6Fn6tfpslNCe9RU+3HgBOsv7m7M2IeTdI6jrMlc7Bhrn5+163Ni3YRuK5JpDeCdkHZJFJ+V2tCkDTKrYjzmhH+JYWbt2i1M2QN+uJR3762Y/tnfNmoaF+wrVcxZjLlkJRc6fKfLHgkOV2ng21uDc8khM314Ik1SCHVEzsTFbr723KQMfB1k+g/ZMrA+NxMrzteqtPaklG5uipltWP12MM3MrGlssG9vzsHl6DLYXm2GuTsRX+9LsrjkRfVcxFHnEiMpLOxEfE4bJb07FG2/6I3DmMuwvMLmeOBSm6kv4LHaG+s0tv2mxWHu6vPNZh/ZSnPj4XfWH9fkFRGH+54mo1f7JjMxt7yDQP1T95k/wrNU4WqwdJbcV4nDCXAT7BcM/MAyhc3Yhx0lWMJedQHxYIN7yU46f8wWutrsKRa7a7UsoctWODWehSGzu9lo5Cwf2+vAZSaXYOeN1TN9hedhXcOhT9+05hiLlvFsuYlnAPOypkLTbY8suO4ZBC/UZoJivUN71nqdDoOn2vLsdN45t2IYipZNI+zwW/lMClcA3E8vPime9zKhN3I64iFD4ivEWHI3lZ+rUkOJw3ezGtlmXih1LlTDoHwJ/v0D4hryLHbarkypxDlMREjMPYcpY9vOLwJx1Z1GutiGjIWUbYsOU40MiMS0sEmGztiLd8pq+8DgSlOs/VXy7LWIeZgTOxFbLMmp340yuOa2Me6W9oGnK9hlYsDUVDcrfG60XEuAbuAFp3X0oRPSdwlBERN+CboJdj2RIUueyjrn+IlZGJeB813uORERuYSgiom+Bm6FIqsTR+FkIDQlDUHA4QqM/wPaU+q4P7BMRuYmhiIiIiAgMRUREREQqhiIiIiIiMBQRERERqRiKiIiIiMBQRERERKRiKCIiIiICQxERERGRiqGIiIiICAxFRERERCqGIiIiIiIwFBERERGpGIqIiIiIwFBEREREpGIoIiIiIgJDEREREZGKoYiIiIgIDEVEREREKoYiIiIiIjAUEREREakYioiIiIjAUERERESkYigiIiIiAkMRERERkYqhiIiIiAgMRUREREQqhiIiIiIiMBQRERERqRiKiIiIiOBFoUiSJBiNRrVPhUXlMJlM9rsRERERdcvrQlFbWxsaG5vVYCT6xmKxWCwWi9Wb8qpQJFaH9Ho9WlpalGDUiLq6Ouh0OtTW1rJYLBaLxWK5LK8JRbb9EqtFIhg1NTWp4chaDQ0NLBaLxWKxWE7LK0KRYLtaJPomVoxEOBJ9ZLFYLBaLxeqpvCoUWYOR6J8IR+IZI9FPFovFYrFYrJ7Ka0KRYA1G1nBkLdFfFovFYrFYLFflVaHIyjYcsVgsFovFYvWmvDIUEREREfUVQxERERERGIqIiIiIVAxFRERERGAoIiIiIlIxFBERERGBoYiIiIhIxVBEREREBIYiIiIiIhVDEREREREYioiIiIhUDEVEREREYCgiIiIiUjEUEREREYGhiIiIiEjFUEREREQEhiIiIiIiFUMRERERERiKiIiIiFQMRURERERgKCIiIiJSMRQRERERgaGIiIiISMVQRERERASGIiIiIiKV14Ui0T9JktQ+mkwmFsvrS4x1MebF2CciIvd5VSgSfROTxJqvqvCLJ1PwL3+5zGJ5fYmxLsa8GPsMRkRE7vOqUCT+tSz6xEDE+q6VGPNi7Is/A0RE5B6vCkWiXw0NDQ4TBov1XSgx9sWfASIico9XhSJx+0Cn0zlMFizWd6HE2Bd/BoiIyD0MRSyWlxRDERGRZxiKWCwvKYYiIiLPMBSxWF5SDEVERJ5hKGKxvKQYioiIPMNQxGJ5STEUERF5hqGIxfKSYigiIvIMQxGL5SXFUERE5BmGIhbLS4qhiIjIMwxFLJaXFEMREZFnGIpYLC8phiIiIs8wFLFYXlIMRUREnmEoYrG8pBiKiIg8w1DEYnlJMRQREXmGoYjlefmkYmhkAd5YXITX3s7B7x/Xtt88Jhk/Hu1k/xu1Rl3BW6fb0Vjfgtl+SY6v3+DFUERE5BmGInfLJx3j1uhwosiIJoOM9lYjstPqsXRxFv5jpJP9vbS+PyEf64slyNYPQTLi44gk/KtfBVL0QFtxNXz+6njct1m3+RbAb3UFAkNScJPta2MLsLtdnISM8wnp+L6TY2/kYigiIvIMQ5E7NTIFzxw0wGRJAmajDIMkplKg5etC/Od3JhQl44kDRiinjsYcHaIWF2HKhwUYPvYy/tfcBjQrF0TWN2HKs/bHfZuViCcPmZXPSsbpZWn4nu1rI5MxZGEV1u0qxain7I+78YuhiIjIMwxFbtT3ni/BCaPyhpIBn8em48ejlO2jk/HbwAK84JvcdfXBm2t0Ft4rkdXrsCw40e61VDwwtwgTA9Nwq/1x32q5CEX/5MVQRETkGYYiN+rmyRXIMIs3bEXkS3ZhwKb+591anCkyotGgXDOjGWW5jXhvdjr+Vbzuk4OPqkSgMGH9jM7nV25+owJpSttSgw7jx2jbfvC3XMw53oqiFgltLQYkna3Cy6+5fubl1glXEX2kBflNknJdJFQXN+O9SOvtokT8KqQUa5P0qLomoblej+N7SzH6WZtzGZOFwH2NOFdgQG2bDJNZRmP1Nez8JBf/ZX1OSDmHlbVQQ9EX64oweZFScXm4d/xl3DQ+E8/GFeHNudn43yI0qu0m4Y45ldiR2Y66dhn6VhOKS67h+IkqvPCi9t63LWmCuIOlP12An1j60rHtRD5+KLaNTMbwRVXYmtSGIuX8jKJvtdewNFy5Jo9mY9YFZVw2SDBIMq41tuP0/hI89IS1D9ZQZEvGgfeUazPqCqKzxWdixOqwzmtx018z8NLmBlyuMuOa3oSi7AbEzc3AT21WBH8TU4ltl6/hqs6MNpMMo7JfdlIN3po8cCGZoYiIyDMMRW7UTePysb1Ze8+mgjpEzcrAfzzsuJ+YzMUkWlzejmJl8pbF7SRjG959S0y4SRi7T9x6kpHzeRZuthzzX/HNUPICGpUA8PO/iGd2CvCPWlm97i117SiolyCJeVtXj7897fieor73bD42V4m1EOX9zBJ09SZcMxmwPESb6H8RVYurYqVL2cHQakazSbv1115Sg8fGW87xqSIcVPdRwkuLEeX1ZhjVBiWcX3VFe97GGopsmdsw943EznBXW4OHfUSbibj9gyboxL02pc26ijYkFyjhSF1xM2KFpW+9CkXW8CIONZhRWWtEk74NsZOVNh7OwbIqCY06A3LLjWgW4VWhO1mAX6ohpjMUter0uFLQptQ1rIpJdh6KfDIwLcmk3iIU17JeCaZmcbASZo/EX8Etah8T8aftBoi3kpUAWqszKqFPu6ZSrQ5PWq5pfxdDERGRZxiK3KpE/OYdHTL1ne/dVt2Ctcuv4v+qAcBSjyZpt9bEr0enYeJJMbnKSF6XoYaKn86qU0OCMbsMd4j9Rqbg1XMiPEnYu1Cs6iRj/H4lOCnXPHv3VfxSvU2XhpdPaNvOJ1jCSZdKgs9ubYJuzqjE6Ke1yf2Wx1PwcxHcHs5CXLFIZxIub87BL5Q2b3kmF8sLtOCVZOlbRygyNOBFdcUqCXcltKBVOdSYU467RF9sVop2rCrExNgCTJyXi7vH2ax4WUPRX/OwsUHsa8LhjzLwI9HXURmYnauFELdCkU14ucknCT9Qr3UifvxYYsfqzE+mVCBJOQ+5tR7Pqefh4vaZk3b/c34DGpVN5tp6vDkxSfmMknD3sibUKJ+b1FiH58dpbWqhSMaVTzPVgPv9p/KwrlJcZzM+j3G9qne9iqGIiMgzDEUe1A8n5MB3RyOymrVVGfE/NZdKcJc1GI1Kxu+CC+CXUI7ZH5dh9nE9xJRV9kWO9pzN2HxsaRKrRy2Y9jft91ubld/rG/GGeNBXXfUQk7QZFw5VIW5zpVrvn2tX22k5mqeFBNt6OBsfiMlYmdjXTXecjL//WjmSxMpQWwNesnx1XtRti5ugVw4zpJbgv0c5C0XKsRPLcEEc26zDOHGO1lBkuoaY17reRrQPRTdPrUSO+H2TDk88atnvOoYi27r16Uw8sbAEM9eVY+bKapxqVQ42NsNffeC7L6EoCc8e1fbN2KiFHXU/n2zEW67xmnCxn2MoEsc+YXmfbwbom2wMRUREnmEoug5105h0jNvQjCpxj0Uy4dOZShh5JAMhF4wd31CzVbH7quXh42Q8f9QESZZwdGkafhZdh1rJ5htsPnnYYrMaZc82OHSU9RgnQUXULcHVKFbew1xdjZE2t/xujdSpq1amggoMHe08FN30bDGOqtvq8XwfQ9EtAdUoEKsruho80hEaXYein1ra6ksoui2qBunOrpkSigKfF/v0IRSNTMXUS+IDlHFkaWrns0Gj0hGeLrZL2DlXBE9noSgRo3dp21LWa6tvtv3sj2IoIiLyDEPR9arRmZhXoE2g51ak48dROtSJkFGmw4uvpOBHPkm4PaEFBtiGosv46UwdqpX92hLLEKwGJDN2zrM8EP1wDpbXKAdIBqwIdQw4TqvjGCNWOVlF6XGlKKX7lSJPQtFNzxThsEg2UjvWTE/RwsjDmYgV18wmFP0stgEi07RfLsavLA8y9zoUKdtnZMrqLauTa7Px67GJuPXxPKyvQ5dQNG6/SQ1FXyufk8tQ1IuVIm0/56Fo1M7OUNRxbD8WQxERkWcYitwpZfKcsKIIY15LxY8sz7H80r8cp8VtGlnC7tgU/FxM7iJkpJfit5bnin79QbNDKPqXR3OwQjwULUloVWZ+qV6Hp8Za3ysZzxzWHvJtTK/EmOcsAWBkEn41MR3/5uznIY1MxnMiXCnH1CeX4y9PWY7xScEvH1d+7ZOFxaUiOEi4+Fk2/n2UeP7lKuLztWeKrBP49Q5F4nmppw8a1IeUZWX8lBS0IUtnfWi5MxTd4l+FPLGi1NIE/7/brR71FIpGZ2GheF5KvXWYbDlvSx9tQtF9n2m3MevOFuLX6rNcSfjpY4lO271tYSOalE3mmnpM+rtYFUrCHUsb1SArNdVjQjfPFDEUERH982EocqNumVqJbMu3mmRJht4oAoX2e2N5DR5TJsrvv1yKs2ImV17QFbfg6IUmnC4xq2GlSyhSJs97P22z3GaTkf+PbO0r+9b3eqUER5us7yWhvs4InZK2ZH0DXuoIT13r1kmlWkATx5gl1NWb0KL08eJq7cHs22J0KFK/KgW0NZlQb1B/CUN5LcZZvrp+3UOR2D4mAy9vbURyjVm5ZhIqC1qRKc5N6vxmnAht88VD36J7RjMqqg2oadN+32MoUkLk2L3aD5OU9AYkJTfh4OVrKBd97ghFl/HD4GoUql8nE+dvRHWrhKtbsnCLs3YfycTMdO3barLJjJpGy7fwJDNOLM+w+/YZQxER0T8zhiI36uZnszH183qcKTaiSZkhJSWsNFS34fCeUjzyvHWSTsR/z6jA9ox21OjFPjJalQk4O6sJaxd2/dbY9yYU44hehIBWRL3SNVyI+slrBYhTUk5hswSz0k5zfTsunK3AYy5+6vLPJxch/utrKGmV1WMaatqw8wPr5JyI30SW4bO0dtTqJbQ0tOPUgTKM6eh7P4Ui+3o4C0vKRAhpx2LfzuNvfTEPcefaUH7Net0MyMhoxCdLMrUQ4iy8WPs9NhNTdjchrdaMduVYo8GM6oo2nD5djkfUVZ3L2s85itfhfJVZ/VlGrfV6HFydhR900+5Nj2fije2NSFHCXFu7GaW5jVi6IBM/61ipYygiIvIGDEWsAaufTczCYOvtPCU0/J9ZtchVgpP4tt2kJx33Z/WtGIqIiDzDUMQaoErE2H0mdeWnvtaAIp0yhtR7UjLyv7yKnzt7PorVp2IoIiLyDEMRa2BqZDJGrWnA2UIDaq7JMIrnhYqbsfHjXPymu9trrD4VQxERkWcYilgsLymGIiIizzAUsVheUgxFRESeYShisbykGIqIiDzDUMRieUkxFBEReYahiMXykmIoIiLyDEMRi+UlxVBEROQZhiIWy0uKoYiIyDMMRSyWlxRDERGRZxiKWCwvKYYiIiLPMBSxWF5SDEVERJ5hKGKxvKQYioiIPMNQxGJ5STEUERF5hqGIxfKSYigiIvKMV4aiXzyZ4jBhsFjeXGLMMxQREXnGq0KR6FdDQwM+2JLPYMT6zpQY62LMi7Ev/gwQEZF7vCoUSZKk9qmiogI5OTm4cuUK0tLSWCyvrfT0dHWsizEvxr74M0BERO7xqlAk+iZuH4h+iX81i9sJLJa3lxjrYsyLsS/+DBARkXu8KhQJon/iX8uij2KSYLG8vcRYF2OegYiIyDNeF4qIiIiI3MFQRERERASGIiIiIiIVQxERERERGIqIiIiIVAxFRERERGAoIiIiIlIxFBERERGBoYiIiIhIxVBEREREBIYiIiIiIhVDEREREREYioiIiIhUDEVEREREYCgiIiIiUjEUEREREYGhiIiIiEjFUERERESk+P/WuVyOYGizngAAAABJRU5ErkJggg==


# CiviCRM with WordPress Bedrock on Upsun
Source: https://developer.upsun.com/posts/hands-on/civicrm-with-wordpress-bedrock-on-upsun

A guide to deploying CiviCRM on top of a Bedrock-based WordPress installation on Upsun, utilizing an optimized Composer template and MariaDB schemas.


<PostMeta />

Recently I published the [CiviCRM with Drupal 11 on Upsun](/posts/hands-on/civicrm-drupal-11-on-upsun) guide, and a common follow-up question I got was: "Does the same approach work for WordPress?" The answer is yes — and arguably the [WordPress](https://wordpress.org/) side is even tidier when you start from [Roots Bedrock](https://roots.io/bedrock/) instead of stock WordPress.

This guide walks through deploying CiviCRM on top of a Bedrock-based WordPress install on Upsun, using a public Composer template I developed at [github.com/Skvare/upsun-wordpress-bedrock-civicrm-template](https://github.com/Skvare/upsun-wordpress-bedrock-civicrm-template). The template encodes all the small but important decisions — read-only filesystem layout, separate CiviCRM database, mounted persistent directories, nginx rules to block direct PHP execution in upload paths, and crons for both WordPress and CiviCRM — so you don't have to rediscover them.

The hosting platform's strengths are secure and powerful: Upsun's [**PHP container profile**](/docs/configure-apps/image-properties/container_profile), secure Nginx configuration, separate [**persistent mounts**](/docs/configure-apps/image-properties/mounts), MariaDB with multiple schemas, and [**source operations**](/docs/configure-apps/source-operations) for auto-update all map cleanly onto how a healthy CiviCRM install should be maintained.

## Why Bedrock?

Stock WordPress puts everything — core, plugins, uploads, `wp-config.php`, and your application code — in one big bucket at the web root. That works on shared hosting but fights you on a PaaS, where you want a clear split between immutable build artifacts (deployed via Git) and writable persistent data ([**mounts**](/docs/configure-apps/image-properties/mounts)). Additionally, the modern method of managing a web application’s codebase and its dependencies is Composer.

Bedrock fixes this by:

* Moving the WordPress core into `web/wp/` so it can be managed entirely by Composer.
* Putting plugins, themes, and uploads under `web/app/` (the equivalent of `wp-content/`).
* Loading config from environment variables via `vlucas/phpdotenv`, which Upsun fills in for you.
* Generating salts and DB credentials at runtime instead of committing them.

Drop CiviCRM on top of that, and you get a layout where the immutable parts (core, plugins, civi-core, civi extensions installed via Composer) deploy cleanly, and the writable parts (uploads, cache, civi `templates_c`, civi custom dirs) live on Upsun [**mounts**](/docs/configure-apps/image-properties/mounts).

## Prerequisites

Before pushing anything, you'll want:

1. An Upsun account and a project created in the console.
2. The [**Upsun CLI**](/cli/install) installed locally.
3. PHP 8.1+ and Composer 2.x for local development.
4. Four CiviCRM environment variables generated and ready to set in the Upsun console:
   * `CIVICRM_SITE_KEY`
   * `CIVICRM_CRED_KEYS`
   * `CIVICRM_SIGN_KEYS`
   * `CIVICRM_DEPLOY_ID`

<Warning>
  Always keep your encryption keys (like `CIVICRM_CRED_KEYS` and `CIVICRM_SIGN_KEYS`) and site keys secure. Never commit them to your repository or expose them in public configurations. Refer to the CiviCRM documentation on encryption keys to generate `CRED_KEYS` and `SIGN_KEYS`. `SITE_KEY` is a long random string of your own choosing. `DEPLOY_ID` is used to invalidate caches and asset URLs across deploys — set it to anything stable per environment (a UUID works well).
</Warning>

Set these in the Upsun console under Variables, marked **Visible at runtime**. The application config declares them as empty placeholders so Upsun knows to inject them:

```yaml theme={null}
variables:
  env:
    CIVICRM_CRED_KEYS: ''
    CIVICRM_SIGN_KEYS: ''
    CIVICRM_SITE_KEY: ''
    CIVICRM_DEPLOY_ID: ''
```

## Quick start

Use these commands to create a new Upsun project using a clone of my [Skvare/upsun-wordpress-bedrock-civicrm-template](https://github.com/Skvare/upsun-wordpress-bedrock-civicrm-template):

````bash theme={null}
git clone https://github.com/Skvare/upsun-wordpress-bedrock-civicrm-template.git my-civicrm-site
cd my-civicrm-site
upsun project:create
upsun push
Once the build finishes, open the project URL (run `upsun url --primary` to open it in your browser), run through the standard WordPress installer, and then activate the CiviCRM plugin. The rest of this article explains why the template is structured the way it is, so you can adapt it to your own needs.

## Local development

For local work, the template uses a conventional `.env` file:

```bash
composer install
cp .env.example .env
# edit .env — set DB credentials, WP_HOME, AUTH_KEY/SALT pairs, and CIVICRM_* keys
````

`.env` is only read when not on Upsun; in production, the `.environment` shell file (covered below) builds the same variables from Upsun's relationship and route data. Commit Bedrock's `.env.example` so collaborators have a starting point, but never commit `.env` itself.

## The Upsun configuration

Everything Upsun needs to build and deploy the site live is a single file: `.upsun/config.yaml`. Let's walk through it section by section.

### Application stack

```yaml theme={null}
applications:
  wordpress:
    type: 'php:8.3'
    dependencies:
      php:
        composer/composer: '^2.1'
    runtime:
      extensions:
        - opcache
        - redis
        - sodium
        - apcu
        - blackfire
        - imagick
        - mbstring
```

PHP 8.3 with the extensions CiviCRM actually uses: `opcache` and `apcu` for performance, `redis` if you choose to add a Redis service for caching, `sodium` for modern crypto, `imagick` for receipt/contact photo handling, `mbstring` for multi-byte string operations, and `blackfire` for production profiling when you need it.

This only matters on Upsun Fixed: if you don't have a Blackfire subscription, drop that line, since listing an unlicensed extension fails the build. Upsun Flexible bundles a Blackfire license, so you can keep the extension as-is.

### Database: one service, two schemas

I recommend installing CiviCRM in its own database. On Upsun you don't need to provision two separate services — MariaDB supports multiple schemas in one instance, with separate endpoints per schema:

```yaml theme={null}
services:
  db:
    type: mariadb:11.8
    configuration:
      properties:
        max_allowed_packet: 64
        max_heap_table_size: 32
        table_definition_cache: 2000
        table_open_cache: 2000
        default_charset: utf8mb4
        default_collation: utf8mb4_unicode_ci
        innodb_adaptive_hash_index: 0
        optimizer_use_condition_selectivity: 4
      schemas:
        - main
        - civicrm
      endpoints:
        mysql:
          default_schema: main
          privileges:
            main: admin
            civicrm: admin
        civicrm:
          default_schema: civicrm
          privileges:
            main: admin
            civicrm: admin
```

A few things worth flagging:

* `max_allowed_packet: 64` (MB) gives CiviCRM enough headroom for bulk imports and large mailings; the default is too small.
* `default_charset: utf8mb4` and the matching collation are non-negotiable for international data and emoji.
* `innodb_adaptive_hash_index: 0` is a CiviCRM-specific tuning hint — the AHI tends to hurt more than help on CiviCRM's query patterns, especially under contention.
* Two endpoints (`mysql` and `civicrm`) let you give each connection a different default schema while still allowing CiviCRM to reach into the WordPress (`main`) schema for user lookups via the UF (User Framework) tables.

The [**relationship**](/docs/configure-apps/image-properties/relationships) is wired in the application block:

```yaml theme={null}
relationships:
  database: 'db:mysql'
```

### Mounts: where writable data lives

Bedrock plus CiviCRM has four directories that absolutely need to be writable at runtime, and they need to not be in your Git repo:

```yaml theme={null}
mounts:
  '/web/app/uploads':
    source: storage
    source_path: 'uploads'
  '/web/app/wp-content/cache':
    source: storage
    source_path: 'cache'
  '/tmp':
    source: tmp
    source_path: 'tmp'
```

`web/app/uploads` holds both WordPress media library files and CiviCRM's persist, custom, and upload directories — the latter three are subdirectories created by CiviCRM on first run. Putting them all under a single [**mount**](/docs/configure-apps/image-properties/mounts) keeps backups simple and avoids cross-mount permission surprises.

`web/app/wp-content/cache` is a separate [**mount**](/docs/configure-apps/image-properties/mounts) because page cache plugins churn it constantly; isolating it from media uploads keeps backup snapshots small.

`/tmp` uses the `tmp` source rather than `storage`, so it doesn't count against your persistent disk and is safe to wipe between containers.

Note what's not mounted: `web/app/civicrm-ext/`, where Composer-managed extensions get installed. That directory is part of the build artifact, so extensions are versioned in `composer.json` and not editable through the CiviCRM UI in production. This is the right tradeoff for a PaaS — predictable deploys, no drift.

### Build hook

```yaml theme={null}
build:
  flavor: composer
hooks:
  build: |
    set -e
    echo "Installing Upsun CLI"
    curl -fsSL https://raw.githubusercontent.com/platformsh/cli/main/installer.sh | VENDOR=upsun bash
```

The composer flavor handles `composer install` for you. The added CLI install gives you the Upsun CLI inside the container, which is occasionally useful for source operations and scheduled tasks that need to talk back to the Upsun API.

### Deploy hook

```yaml theme={null}
deploy: |
  set -e
  wp cache flush
  wp core update-db
```

`wp cache flush` clears any stale object cache between releases. `wp core update-db` runs WordPress's own DB migrations on core upgrades — it's idempotent and cheap when there's nothing to do.

### Web locations: serve statically, block PHP everywhere it shouldn't run

This is the longest section of the config and the most security-critical. The high-level rule is: PHP only executes from places we explicitly trust. Everything in uploads, cache, and the various civi data dirs serves static assets but blocks `*.php` execution.

The root [**web location**](/docs/configure-apps/image-properties/web) handles WordPress requests:

```yaml theme={null}
"/":
  root: "web"
  passthru: "/wp/index.php"
  index:
    - "index.php"
  expires: 300s
  scripts: true
  allow: true
  rules:
    '\.': { allow: false }
    ^/composer\.json:
      allow: false
    ^/license\.txt$:
      allow: false
    ^/readme\.html$:
      allow: false
```

Bedrock's Composer-managed layout lives at `web/wp/`, so `passthru` points there. The rules block hidden files, the Composer manifest, and the standard WordPress info pages that leak version data.

Uploads are explicitly hardened:

```yaml theme={null}
"/wp/wp-content/uploads":
  root: "web/app/uploads"
  scripts: false
  allow: false
  rules:
    '\.(jpe?g|gif|png|svg|...|3g[p2])$':
      allow: true
      expires: 1w
    '\.(?i:php|phtml|php3|php4|php5|php7|php8|phar|pl|cgi|asp|aspx|jsp|cfm|shtml|shtm|htaccess|sh|bash|exe|dll)$':
      allow: false
    '/\.':
      allow: false
```

This pattern repeats for `/app/civicrm-ext`, `/app/uploads/civicrm/persist`, `/app/uploads/civicrm/custom`, and `/app/uploads/civicrm/upload`. Every path that accepts user-uploaded data has the same allowlist of safe extensions and an explicit denylist of every PHP-ish extension that could be exploited. If you add a new mount that takes uploads, copy this block.

The one exception that legitimately needs PHP execution under uploads is KCFinder, the file browser bundled with CiviCRM:

```yaml theme={null}
"/app/plugins/civicrm/civicrm/packages/kcfinder":
  root: "web/app/plugins/civicrm/civicrm/packages/kcfinder"
  allow: true
  scripts: true
  expires: 15m
  passthru: true
```

Locking that down further is on the roadmap but works as-is for now.

### Routes and cache cookies

```yaml theme={null}
routes:
  "https://{default}/":
    type: upstream
    upstream: "wordpress:http"
    cache:
      enabled: true
      default_ttl: 300
      cookies:
        - '/^wordpress_logged_in_/'
        - '/^wordpress_sec_/'
        - 'wordpress_test_cookie'
        - '/^wp-settings-/'
        - '/^wp-postpass/'
        - '/^wp-resetpass-/'
        - '/^PHPSESSID$/'
        - '/^simple_wp_membership_sec_/'
```

Two things matter here. First, upstream must match the application name in the application configuration block exactly — `wordpress:http` here. Mismatched names produce a deploy that succeeds but serves only 502s.

Second, the cookies allowlist is the difference between Upsun's edge cache being useful and being a security concern. By naming only the cookies that actually distinguish users, anonymous visitors get cached responses while logged-in users (and members, in the case of `simple_wp_membership_sec_`) bypass the cache cleanly. CiviCRM contribution and event pages are mostly anonymous traffic; this configuration lets them be served from cache, which matters during big campaigns.

### Crons

Two scheduled [**crons**](/docs/configure-apps/image-properties/crons) cover both WordPress and CiviCRM:

```yaml theme={null}
crons:
  wp:
    spec: '*/30 * * * *'
    commands:
      start: |
        wp cron event run --due-now
  civi-cron:
    spec: '*/30 * * * *'
    commands:
      start: |
        wp --user=cronuser civicrm api job.execute auth=0
```

The `wp` cron handles WordPress core scheduled events. The `civi-cron` job runs CiviCRM scheduled jobs through the WP-CLI integration, executing as a dedicated `cronuser` account that you'll create after the initial install (covered below).

For sites that send a lot of mail, you may want to split out CiviCRM mailing processing onto a faster cadence (e.g. every 5 minutes) by adding a third cron that runs `wp --user=cronuser civicrm api job.process_mailing auth=0` — the same separation we use on the Drupal side.

### Source operations: auto-update

```yaml theme={null}
source:
  operations:
    auto-update:
      command: |
        curl -fsS https://raw.githubusercontent.com/platformsh/source-operations/main/setup.sh | { bash /dev/fd/3 sop-autoupdate; } 3<&0
```

This wires up Upsun [**source operations**](/docs/configure-apps/source-operations) so you can run `upsun source-operation:run auto-update` (or schedule it) and have Upsun open a merge request or branch with `composer update` results applied. For CiviCRM sites, this is how you keep up with security releases without doing a manual composer update push every time.

## The Composer template

The `composer.json` is where the WordPress + CiviCRM marriage actually happens. The interesting parts:

### Repositories and packages

```json theme={null}
"repositories": [
  { "type": "vcs", "name": "skvare/wordpress-bedrock-civicrm-settings",
    "url": "https://github.com/Skvare/wordpress-bedrock-civicrm-settings.git" },
  { "type": "vcs", "name": "civicrm/civicrm-extension-plugin",
    "url": "https://github.com/Skvare/civicrm-extension-plugin" },
  { "type": "vcs", "name": "civicrm/civicrm-wordpress",
    "url": "https://github.com/civicrm/civicrm-wordpress.git" },
  { "type": "composer", "url": "https://wpackagist.org",
    "only": ["wpackagist-plugin/*", "wpackagist-theme/*"] }
]
```

`wpackagist.org` provides Composer-flavored access to the WordPress.org plugin and theme directories. The CiviCRM repos point to specific upstream sources, including a Skvare fork of `civicrm-extension-plugin`.

The `require` block pins CiviCRM at `6.13.*` and pulls in `civicrm-asset-plugin`, `civicrm-extension-plugin`, `civicrm-core`, `civicrm-packages`, and `civicrm-wordpress` together. It also pulls in `skvare/wordpress-bedrock-civicrm-settings` — a small package that ships a pre-configured `civicrm.settings.php` tailored to the Bedrock + Upsun layout. Doing this as a Composer package instead of an in-repo file makes upgrading the settings template across multiple sites a single version bump.

### CiviCRM extensions via Composer

Out of the box, CiviCRM extensions are installed and updated through the CiviCRM admin UI — which on a read-only filesystem like Upsun is a non-starter. The `civicrm/civicrm-extension-plugin` (Skvare fork) lets you declare extensions in `composer.json` instead:

```json theme={null}
"civicrm": {
  "cms_type": "wordpress",
  "extensions_install_path": "./web/app/civicrm-ext/contrib",
  "extensions": {
    "uk.co.vedaconsulting.mosaico": {
      "url": "https://download.civicrm.org/extension/uk.co.vedaconsulting.mosaico/3.12.1773937815/uk.co.vedaconsulting.mosaico-3.12.1773937815.zip"
    },
    "org.civicrm.cividiscount": {
      "url": "https://lab.civicrm.org/extensions/cividiscount/-/archive/3.10.2/cividiscount-3.10.2.zip"
    },
    "org.civicrm.contactlayout": {
      "url": "https://lab.civicrm.org/extensions/contactlayout/-/archive/3.0.4/contactlayout-3.0.4.zip"
    }
  }
}
```

Each extension is fetched from a URL (typically the CiviCRM extension directory or a GitLab archive), unpacked into `web/app/civicrm-ext/contrib`, and made available to CiviCRM. Pinning the URL means deploys are reproducible — the same Git SHA always produces the same extension set.

To add an extension, find its `.zip` URL on `civicrm.org`, add it to this list, run `composer update`, and push.

### Patches

```json theme={null}
"patches": {
  "civicrm/civicrm-core": {
    "WIP composer support": "https://patch-diff.githubusercontent.com/raw/civicrm/civicrm-core/pull/32945.patch"
  },
  "civicrm/civicrm-wordpress": {
    "Composer and PaaS support": "https://patch-diff.githubusercontent.com/raw/civicrm/civicrm-wordpress/pull/362.patch"
  },
  "civicrm/civicrm-extension-plugin": {
    "WP location of settings file in config file": "./patches/civi-wp-composer-config.patch"
  }
}
```

Two upstream PRs and one local patch. The `civi-core` and `civi-wordpress` patches make necessary changes for discovering CiviCRM Core in composer's `vendor` directory, and relax assumptions about being able to write `civicrm.settings.php` at runtime — exactly the assumption a read-only PaaS filesystem violates. These will go away once the upstream PRs merge; in the meantime, `cweagans/composer-patches` applies them at install time.

### Post-install scripts

```json theme={null}
"post-install-cmd": [
  "cp web/app/plugins/civicrm/wordpress-bedrock-civicrm-settings/civicrm.settings.php web/app/plugins/civicrm/",
  "composer civicrm:publish"
]
```

The first line copies the pre-configured `civicrm.settings.php` from the Skvare settings package into the location CiviCRM looks for it. The second line runs `civicrm:publish`, which copies CiviCRM's static assets into the location declared earlier (`web/app/plugins/civicrm/civicrm`). Both run during build, so the artifact that ships to Upsun has settings and assets already in place.

## The .environment shell file

Bedrock expects WordPress configuration to come from environment variables. On Upsun, you don't write a literal `.env` file in production — instead, `.environment` runs at container start and exports the same names from Upsun's built-in variables:

```bash theme={null}
# Database environment variables — injected from Service Environment Variable, see https://developer.upsun.com/docs/development/variables/set-variables#service-environment-variables
export DB_HOST="$DATABASE_HOST"
export DB_PORT="$DATABASE_PORT"
export DB_PATH="$DATABASE_PATH"
export DB_DATABASE="$DB_PATH"
export DB_USERNAME="$DATABASE_USERNAME"
export DB_PASSWORD="$DATABASE_PASSWORD"
export DB_SCHEME="$DATABASE_SCHEME"
export DATABASE_URL="${DB_SCHEME}://${DB_USERNAME}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT}/${DB_PATH}"

# Routes, URLs, primary domain — derived from PLATFORM_ROUTES
export SITE_ROUTES="$(echo "$PLATFORM_ROUTES" | base64 --decode)"
export DOMAIN_CURRENT_SITE="$(
  echo "$SITE_ROUTES" | jq -r --arg app "$PLATFORM_APPLICATION_NAME" \
    'map_values(select(.primary == true and .type == "upstream" and .upstream == $app))
      | keys | .[0]
      | if (.[-1:] == "/") then (.[0:-1]) else . end'
)"

export WP_HOME="${DOMAIN_CURRENT_SITE}"
export WP_SITEURL="${WP_HOME}/wp"
export WP_DEBUG_LOG="/var/log/app.log"

# Salts derived from PLATFORM_PROJECT_ENTROPY — stable per project, never committed
export AUTH_KEY="${PLATFORM_PROJECT_ENTROPY}AUTH_KEY"
export SECURE_AUTH_KEY="${PLATFORM_PROJECT_ENTROPY}SECURE_AUTH_KEY"
# ...one line per Bedrock salt
```

The clever bit is the `PLATFORM_ROUTES` parse: rather than hard-coding `WP_HOME` per environment, we ask Upsun what the primary route for this application is and trim the trailing slash. Branch environments automatically get the right URL; production gets the production URL. Bedrock reads `WP_HOME` and `WP_SITEURL` from these exports through `phpdotenv`-style loading.

`PLATFORM_PROJECT_ENTROPY` is per-project secret entropy that Upsun guarantees is stable and unique. Concatenating it with each salt name gives you eight different, deterministic, project-scoped values — no need to commit secrets, no need to rotate them on every deploy.

## First-time WordPress + CiviCRM install

After `git push upsun main` succeeds, follow this order:

### 1. Run the WordPress installer

Open the project URL (run `upsun url --primary` to open it in your browser). You'll see the standard WordPress 5-minute install. Set the site title, admin user, and admin password. The DB connection is already wired up via `.environment`, so you won't see a database setup step.

### 2. Activate the CiviCRM plugin

Go to **Plugins** in the WordPress admin. CiviCRM is already installed as a Composer plugin under `web/app/plugins/civicrm/`. Click **Activate**.

The plugin will detect the pre-shipped `civicrm.settings.php` and the configured `civicrm` database endpoint, run its install routine, and finish without prompting for DB credentials.

Visit `/wp-admin/admin.php?page=CiviCRM` to confirm CiviCRM loaded correctly.

### 3. Create the cron user

CiviCRM's API runs as a WordPress user. The `civi-cron` job runs `wp --user=cronuser ...`, so create a user with that exact username:

1. Navigate to **Users** → **Add New**.
2. Username: `cronuser`.
3. Role: **Administrator**.

<Warning>
  Make sure to set a strong, secure password for the `cronuser` account. While you won't log in with this account directly (the cron executes commands locally), it still holds Administrator privileges.
</Warning>

Once that user exists, the cron job at `*/30 * * * *` starts succeeding silently. Tail the cron log via `upsun log cron` to confirm.

### 4. Activate any extensions you declared

Extensions you listed in `composer.json` are installed (their files are on disk) but not enabled. Go to **CiviCRM** → **Administer** → **Extensions** and click **Enable** on each one. This is the only ongoing UI step CiviCRM extensions require — once enabled, the state lives in the database, so subsequent deploys keep them on.

## Things to know once you're running

* **UI warnings**: The CiviCRM admin UI will warn about extension installs being unavailable. That's expected — you're managing extensions through Composer, not the UI. Document this in your runbook so future developers don't think it's a bug.
* **Mailings**: If you do significant outbound email, add a dedicated mailing cron at `*/5 * * * *` running `wp --user=cronuser civicrm api job.process_mailing auth=0` and let the half-hourly cron handle everything else. Don't try to send mailings synchronously from web requests.
* **Caching**: CiviCRM defaults to a database-backed cache. For larger sites, add a Redis service to the project, expose it as a [**relationship**](/docs/configure-apps/image-properties/relationships), and set `CIVICRM_CACHING_TYPE=Redis` as an Upsun variable. The PHP redis extension is already in the runtime list.
* **Backups**: Upsun's automatic snapshots cover both the database and persistent mounts, so the uploads mount and CiviCRM's persist directory are included in restores. You don't need a separate backup strategy unless you want offsite copies.
* **Branch environments**: Because `WP_HOME` and `WP_SITEURL` are derived from `PLATFORM_ROUTES`, every branch environment gets the right URL automatically. CiviCRM's `CIVICRM_DEPLOY_ID` is a single env var across environments, though — if you want per-environment deploy IDs to invalidate asset caches independently, set the variable per environment in the Upsun console rather than at the project level.

## Wrapping up

The combination of Bedrock's Composer-first layout and Upsun's PaaS primitives gives CiviCRM a much better home than traditional shared hosting: predictable, reproducible deploys; sensible filesystem boundaries between code and data; and a database service that scales without you having to think about it.

The template is open source and MIT-licensed. If you find a rough edge or want to add a configuration option (Redis, multisite, a particular extension), pull requests are welcome at [github.com/Skvare/upsun-wordpress-bedrock-civicrm-template](https://github.com/Skvare/upsun-wordpress-bedrock-civicrm-template).

***

**Author experience and approach**

[Mark Hanna](https://github.com/jackrabbithanna) is CTO of Skvare. He's the author of the Drupal 11 + CiviCRM on Upsun guide and maintains several CiviCRM-adjacent open source modules including CiviCRM Entity, CiviCRM Form Builder Blocks, CiviCRM Drush, and CiviCRM Reroute Mail. If your organization needs help architecting a CiviCRM install — WordPress, Drupal, or Joomla — [Skvare](https://skvare.com) does this professionally.


# Connect multiple projects applications or services together
Source: https://developer.upsun.com/posts/hands-on/connect-multiple-projects-applications-or-services-together

Learn how to use Chisel to securely connect applications and services across different Upsun projects, with a practical MariaDB replication example.

<PostMeta />

Upsun's [mesh networking](/posts/how-it-works/how-upsun-built-stateless-mesh-networking-for-high-density-containers) provides excellent isolation and security between projects by design, preventing unauthorized cross-project communication. While this isolation is a security feature, there are legitimate scenarios where you need controlled connectivity between projects.

This tutorial demonstrates how to use [**Chisel**](https://github.com/jpillora/chisel), a fast, secure TCP/UDP tunnel transported over HTTP, to create encrypted connections between services running on different Upsun projects. We'll walk through setting up MariaDB replication between two projects as a practical example.

## Prerequisites

Before starting, ensure you have:

* Two Upsun projects (we'll call them `primary-db` and `replica-db`)
* Basic understanding of Upsun project configuration
* Access to the [Upsun CLI](https://docs.upsun.com/administration/cli.html) (`upsun` command)
* Familiarity with MariaDB or MySQL databases

## Understanding Upsun project isolation

Upsun's architecture intentionally isolates projects from each other.

* **Isolated projects**: Projects containers cannot directly communicate with another container in another project
* **Secure ingress**: Only designated routes are publicly accessible
* **Internal service discovery**: Applications can only be linked to services within their own project

While project isolation is recommended, this can prevent some legitimate use-cases like sharing a database or a service between multiple applications on different projects.

## Use cases for cross-project connectivity

### Database replication scenarios

* **Cross-region backup**: Replicate data to different geographical regions
* **Disaster recovery**: Maintain standby databases in separate projects
* **Data warehousing**: Extract data from production to analytics projects

In case of an incident, having a cloned database on another region will allow you to optimize the **Recovery Time Objective** (RTO) & **Recovery Point Objective** (RPO) by switching the production instance to the second project through DNS.

### Service integration patterns

* **Legacy system integration**: Connect modern applications with legacy services
* **Microservices architecture**: Bridge services temporarily or permanently
* **Multi-tenant isolation**: Connect tenant-specific services across projects

It's important to note that both projects could be running on different Upsun regions and even different cloud providers. However, a connection between two isolated regions can introduce some latency due to the network usage between the endpoints.

## What is Chisel?

[Chisel](https://github.com/jpillora/chisel) is an open-source tunneling solution that creates secure, encrypted connections over HTTP/HTTPS. Key features include:

* **SSH-encrypted tunnels**: All traffic is encrypted using SSH protocol
* **HTTP transport**: Tunnels work through firewalls and proxy servers
* **Reverse port forwarding**: Services can expose ports securely across networks
* **Single binary**: Easy to deploy with no external dependencies
* **Auto-reconnection**: Maintains stable connections with exponential backoff

### How Chisel works

Chisel operates with a client-server model:

1. **Chisel Server**: Runs on the target project and listens for connections
2. **Chisel Client**: Connects to the server and creates local tunnel endpoints
3. **Encrypted Tunnel**: All traffic flows through SSH-encrypted HTTP connections

## Setting up the MariaDB replication example

Now let's implement a practical example: setting up MariaDB replication between two Upsun projects using Chisel tunnels.

### Architecture overview

Our setup includes:

* **Primary Project** (`primary-db`): Hosts the primary MariaDB instance
* **Replica Project** (`replica-db`): Hosts the replica MariaDB instance
* **Chisel Server**: Runs alongside the primary database
* **Chisel Client**: Runs alongside the replica database
* **Encrypted Tunnel**: Connects replica to primary for replication traffic

```mermaid theme={null}
graph LR
    subgraph "Upsun Replica Project"
        CC[Chisel Client<br/>Port 3306]
        RDB[(Replica<br/>MariaDB)]
        CC --> RDB
    end
    
    subgraph "Encrypted HTTPS Tunnel"
        TUNNEL[SSH over HTTPS<br/>Secure Connection]
    end
    
    subgraph "Upsun Primary Project"
        CS[Chisel Server<br/>Port 443]
        PDB[(Primary<br/>MariaDB)]
        CS --> PDB
    end
    
    CC -.-> TUNNEL
    TUNNEL -.-> CS
    RDB -->|Replication Traffic| CC
    
    classDef replica fill:#6046FF,stroke:#000,stroke-width:2px,color:#fff
    classDef tunnel fill:#fff,stroke:#D0F302,stroke-width:3px,color:#000
    classDef primary fill:#D0F302,stroke:#000,stroke-width:2px,color:#000
    classDef database fill:#000,stroke:#D0F302,stroke-width:2px,color:#D0F302
    
    class CC,RDB replica
    class TUNNEL tunnel
    class CS primary
    class PDB database
```

### Step 1: Configure the primary database project

First, let's set up the primary database with MariaDB and Chisel server.

Create `.upsun/config.yaml` in your primary project:

```yaml {filename=".upsun/config.yaml"} theme={null}
services:
  maindb:
    type: mariadb:11.8
    configuration:
      rotate_passwords: false
      schemas:
        - main
      endpoints:
        mysql:
          default_schema: main
          privileges:
            main: admin
        replicator:
          privileges:
            main: replication

applications:
  app:
    type: golang:1.24
    relationships:
      db:
        service: maindb
        endpoint: mysql
      replication:
        service: maindb
        endpoint: replicator
    hooks:
      build: go install github.com/jpillora/chisel@latest
    web:
      commands:
        start: chisel server
      locations:
        "/":
          passthru: true
          request_buffering:
            enabled: false

routes:
  https://{default}/:
    type: upstream
    upstream: app:http
    cache:
      enabled: false
```

#### Configuration breakdown

**Services section:**

* `maindb`: MariaDB 11.4 service with two endpoints:
  * `mysql`: Standard admin endpoint for general database operations
  * `replicator`: Dedicated endpoint with `replication` privileges for replica connections
* `rotate_passwords: false`: Keeps passwords stable for replication connections

**Application section:**

* `type: golang:1.24`: Uses Go runtime (Chisel is a golang application)
* `relationships`: Creates two database connections:
  * `db`: Admin access to the database
  * `replication`: Replication-only access for the replica to connect to
* `hooks.build`: Installs Chisel during the build phase
* `web.commands.start`: Runs Chisel server as the web process
* `locations`: Configures HTTP handling with passthrough and disabled request buffering

**Routes section:**

* Exposes the Chisel server publicly via HTTPS
* Disables caching for real-time tunnel connections to be made over WebSockets

#### Deploy the primary project

Once added to your project, push the updated configuration to deploy the project:

```bash {filename="Terminal"} theme={null}
git add .upsun/config.yaml
git commit -m "Setup Chisel server on primary project"
upsun push
```

Once deployed, you will be able to see the newly created endpoint for the chisel server:

```bash {filename="Terminal"} theme={null}
Environment configuration
    app (type: golang:1.24, cpu: 0.1, memory: 64, disk: 0)
    maindb (type: mariadb:11.4, cpu: 1.0, memory: 2432, disk: 512)

  Environment routes
    http://main-bvxea6i-qwoo2yqnr6vgq.eu-3.platformsh.site/ redirects to https://main-bvxea6i-qwoo2yqnr6vgq.eu-3.platformsh.site/
    https://main-bvxea6i-qwoo2yqnr6vgq.eu-3.platformsh.site/ is served by application `app`
```

You're going to need to keep 2 bits of information on the replica project:

* The URL of this environment, here `https://main-bvxea6i-qwoo2yqnr6vgq.eu-3.platformsh.site/`
* The password needed for the `replication.internal` relationship

You can grab the password as such:

```{filename="Terminal"} theme={null}
# SSH into primary project
upsun ssh -A app

# Grab the password from the relationships
echo $PLATFORM_RELATIONSHIPS | base64 -d | jq -r '.replication[0].password'
```

### Step 2: Configure the replica database project

The `replicator` endpoint in the primary configuration automatically creates the replication user with proper privileges, no manual SQL setup required!

Create `.upsun/config.yaml` in your replica project:

```yaml {filename=".upsun/config.yaml"} theme={null}
services:
  replicadb:
    type: mariadb:11.4
    configuration:
      schemas:
        - main
      endpoints:
        replica-admin:
          default_schema: main
          privileges:
            main: replication-admin
    relationships:
      primary: app:http

applications:
  app:
    type: golang:1.24
    hooks:
      build: go install github.com/jpillora/chisel@latest
    web:
      commands:
        start: chisel client https://main-bvxea6i-qwoo2yqnr6vgq.eu-3.platformsh.site/ 0.0.0.0:3306:replication.internal:3306
  admin:
    type: golang:1.24
    relationships:
      db: replicadb:replica-admin

routes:
  https://{default}/:
    type: upstream
    upstream: admin:http
```

<Note>While we are hardcoding the endpoint in this example, you could also use the Upsun CLI in the environment to dynamically retrieve the correct route of the other project.</Note>

**Configuration breakdown:**

**Services section:**

* `replicadb`: Local MariaDB instance that will serve as the replica
* Single `replica-admin` endpoint with `replication-admin` privileges for managing the replica
* A relationship from that MariaDB instance to the application

**Applications section:**

* `app`: Chisel client application that creates the tunnel
  * `hooks.build`: Installs Chisel during build
  * `web.commands.start`: Runs Chisel client with specific tunnel configuration:
    * Connects to the primary server at `https://main-bvxea6i-qwoo2yqnr6vgq.eu-3.platformsh.site/`. This is the URI generated at the previous step.
    * Creates tunnel: `0.0.0.0:3306:replication.internal:3306`
    * This forwards local port 3306 to the primary's replication endpoint
* `admin`: Application managing the local MariaDB instance (circular relationships are not allowed, so a separate application is needed)

<Note>⚠︎ Because both projects are independent, the endpoint route might change based on the other project configuration.</Note>

**Tunnel configuration explained:**

* `0.0.0.0:3306`: Binds to all interfaces on port 3306 (MySQL default)
* `replication.internal:3306`: Connects to the primary's replication endpoint
* The `replication.internal` hostname corresponds to the `replication` relationship defined in the primary project

With this setup, when the local MariaDB instance will connect to the `app` application via the relationship, it will be tunneled to the remote MariaDB instance.

**Routes section:**

* Routes traffic to the admin application for managing/querying the replica

#### Deploy the replica project

Once added to your project, push the updated configuration to deploy the project:

```bash {filename="Terminal"} theme={null}
git add .upsun/config.yaml
git commit -m "Setup Chisel client on replica project"
upsun push
```

Once deployed, you need to configure your local MariaDB instance as a replica of the remote one:

```{filename="Terminal"} theme={null}
# SSH into replica project
upsun ssh -A replica-db

# Set the local MariaDB instance as a replica of the remote one
mysql -u main -p -h database.internal -e "CHANGE MASTER TO MASTER_HOST = 'primary.internal', MASTER_PASSWORD='<previously saved password>';"

# Start the replication on the local MariaDB instance
mysql -u main -p -h database.internal -e "START REPLICA;"
```

From there on, the replica should automatically connect to the primary project Chisel server endpoint, retrying as necessary.

### Step 3: Verify replication is working

Connect to your replica database and check replication status:

```bash {filename="Terminal"} theme={null}
# SSH into replica project
upsun ssh -A replica-db

# Check slave status
mysql -u main -p -h database.internal -e "SHOW REPLICA STATUS\G"
```

You should see output indicating the replica is connected and replicating from the primary.

Test data synchronization:

```bash {filename="Terminal"} theme={null}
# SSH into primary project
upsun ssh -A primary-db

# Add test data
mysql -u main -p -h database.internal sample_db -e "INSERT INTO users (name, email) VALUES ('Test User', 'test@example.com');"

# SSH into replica and verify data appears
upsun ssh -A replica-db
mysql -u main -p -h database.internal sample_db -e "SELECT * FROM users;"
```

## Key advantages of this setup

* **Secure tunnel**: All replication traffic flows through encrypted Chisel tunnel
* **Minimal configuration**: No custom scripts needed. Chisel handles everything
* **Runtime agnostic**: Works with any Upsun runtime (Go, Python, Node.js, PHP, etc.)
* **Production ready**: Built-in auto-reconnection and error handling
* **Cost effective**: Because the Chisel application is mostly a proxy, it can work with 0.1 CPU

## Alternative approaches

While Chisel provides excellent flexibility, consider these alternatives:

### Upsun-native patterns

* **Data export/import**: Use regular data dumps and imports for less critical scenarios
* **Message queues**: Use RabbitMQ or Redis for event-driven data synchronization
* **API-based sync**: Build REST/GraphQL APIs for controlled data access
* **Shared storage**: Use external object storage for file-based data sharing

### When to avoid cross-project connectivity

* **Simple data sharing**: Use APIs instead of direct database access
* **Occasional data sync**: Manual export/import may be simpler
* **High-security environments**: Additional network paths increase attack surface
* **Performance-critical paths**: Direct database connections may introduce latency

## Conclusion

Chisel provides a powerful solution for creating secure, encrypted tunnels between Upsun projects when legitimate connectivity requirements arise.

Remember that project isolation is a valuable security feature. Use cross-project connectivity with caution and always implement appropriate security controls including strong authentication, encrypted connections, and comprehensive monitoring.

For additional help with networking and connectivity patterns, join the [Upsun Community Forum](https://community.upsun.com/) or [schedule a consultation](https://upsun.com/contact-us/) with our technical team.

## Additional resources

* [Chisel project documentation](https://github.com/jpillora/chisel)
* [Upsun documentation](https://docs.upsun.com/)
* [MariaDB replication guide](https://docs.upsun.com/add-services/mysql.html#replication)
* [Upsun multi-application projects](https://docs.upsun.com/create-apps.html#use-multiple-apps)


# Build and deploy AI-Native Applications with MCP Servers on Upsun
Source: https://developer.upsun.com/posts/hands-on/deploy-mcp-servers-on-upsun

Learn how Model Context Protocol servers work with different transports and deploy them to Upsun for scalable AI-powered applications


<PostMeta />

The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is transforming how AI assistants interact with external tools and data sources. As AI becomes central to how users discover and interact with digital services, providing an MCP server is no longer optional – it's a strategic imperative for SaaS products and digital services.

<Note>
  The full code of this tutorial, ready to deploy, [is available on Github](https://github.com/upsun/tutorial-mcp-deployment)!
</Note>

## Why your product and company needs an MCP strategy

Consider how users increasingly rely on AI assistants for daily tasks. When they ask about your product, search for documentation, or need to interact with your API, they expect their AI assistant to have direct access to accurate, real-time information. Without an MCP server, your company becomes invisible to this growing segment of users.

MCP servers enable companies to:

**Control the AI Narrative**: Rather than letting AI assistants guess about your product based on outdated training data, provide authoritative, current information directly. Your MCP server becomes the single source of truth for AI interactions with your brand.

**Enhance Developer Experience**: Developers using AI assistants for coding can access your API documentation, code examples, and best practices instantly. An MCP wrapper around your product API transforms complex integrations into conversational experiences.

**Reduce Support Burden**: When AI assistants can query your documentation and knowledge base directly through MCP, they provide accurate answers to user questions, reducing support tickets and improving customer satisfaction.

**Enable New Use Cases**: MCP servers unlock possibilities you haven't imagined yet. From automated workflows to intelligent integrations, providing programmatic access to your services through MCP opens doors for innovation.

But deploying MCP servers presents unique challenges - from handling concurrent connections to managing different transport protocols. This article explores two MCP transport implementations and demonstrates how Upsun makes deploying these servers straightforward, allowing you to focus on building AI-powered features rather than managing infrastructure.

## Why HTTP transports beat stdio for SaaS apps

While MCP supports stdio transport for local development, HTTP-based transports like SSE and Streamable are the clear choice for SaaS businesses. Unlike stdio, which requires users to download and run servers locally, HTTP transports enable instant access through any AI assistant without installation friction.

### The power of hosted MCP servers

Hosting your MCP server as a service transforms it from a developer tool into a business asset:

**Zero Installation Barrier**: Users connect instantly without downloading binaries, managing dependencies, or dealing with compatibility issues. Your MCP server works everywhere the internet does.

**Integration Opportunities**: Hosted MCP servers can seamlessly connect to your internal systems, databases, and APIs without exposing them directly to end users.

**Continuous Updates**: Deploy improvements immediately to all users. When you enhance your API wrapper or update documentation access, everyone benefits instantly without manual updates.

**Built-in Observability**: Track usage patterns, monitor performance, and understand how AI assistants interact with your services. This data drives product decisions and identifies new opportunities.

**Security and Compliance**: Centralized hosting enables proper authentication, rate limiting, and audit trails. You maintain control over data access and can enforce your security policies consistently.

For SaaS businesses, the choice is clear: HTTP-based MCP servers deployed on platforms like Upsun provide the reliability, scalability, and control necessary to make MCP a core part of your product strategy.

## Understanding MCP transports: SSE vs Streamable

MCP servers communicate with AI assistants through transport protocols that handle the exchange of messages. While the [MCP specification](https://modelcontextprotocol.io/introduction) supports various transports, two HTTP-based approaches dominate the landscape: Server-Sent Events (SSE) and the newer Streamable transport.

### Server-Sent Events: The current standard

SSE represents the current default standard for MCP implementations. This transport uses traditional HTTP endpoints combined with event streams, providing a reliable way to maintain persistent connections between clients and servers. Despite being marked as deprecated in favor of newer approaches, SSE remains widely supported and battle-tested in production environments.

The SSE transport excels at:

* Maintaining persistent connections for real-time communication
* Supporting multiple concurrent clients through session management
* Providing clear separation between event streams and message handling
* Working seamlessly with existing web infrastructure

### Streamable: The future of MCP transports

The Streamable transport represents the next evolution in MCP communication. Built directly into the MCP SDK, it consolidates all communication through a single endpoint while maintaining the benefits of event-driven architecture. This streamlined approach reduces complexity and improves maintainability.

Streamable offers several advantages:

* Simplified architecture with a single `/mcp` endpoint
* Stateless operation that scales effortlessly
* Built-in SDK support reducing implementation complexity
* Automatic handling of connection lifecycle

While Streamable is positioned as the future standard, the transition is gradual. Many existing MCP implementations still rely on SSE, making it important to understand both approaches.

## Implementing an SSE-Based MCP Server

Let's examine how the SSE transport works by exploring our domain information server implementation. This server provides domain search capabilities through the domainsdb.info API, demonstrating real-world MCP usage.

### Core Architecture

The SSE implementation creates a stateful server that manages multiple client connections simultaneously using the [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk):

```typescript {filename="mcp-domains-sse/src/index.ts"} theme={null}
class DomainsServer {
  private server: Server;
  
  constructor() {
    this.server = new Server({
      name: "domains-server",
      version: "1.0.0",
    }, {
      capabilities: {
        tools: {},
      },
    });
  }
}
```

### Session Management

One key aspect of the SSE transport is session management. Each client connection receives a unique session ID, enabling the server to route messages correctly:

```typescript {filename="mcp-domains-sse/src/index.ts"} theme={null}
app.get('/sse', (req, res) => {
  const sessionId = crypto.randomUUID();
  const transport = new SSEServerTransport('/messages', res);
  
  sessions.set(sessionId, { transport, server: domainsServer });
  
  // Send endpoint information to client
  res.write(`event: endpoint\ndata: ${JSON.stringify({ 
    url: `/messages?sessionId=${sessionId}`,
    sessionId 
  })}\n\n`);
});
```

### Message Handling

Messages from clients arrive at a dedicated endpoint, where they're routed to the appropriate session:

```typescript {filename="mcp-domains-sse/src/index.ts"} theme={null}
app.post('/messages', async (req, res) => {
  const sessionId = req.query.sessionId as string;
  const session = sessions.get(sessionId);
  
  if (!session) {
    return res.status(404).json({ error: 'Session not found' });
  }
  
  await session.transport.handleMessage(req.body);
  res.status(200).json({ ok: true });
});
```

This architecture provides excellent control over connection management and enables sophisticated features like connection pooling and custom routing logic.

## Implementing a Streamable MCP Server

The Streamable transport takes a different approach, leveraging the MCP SDK's built-in capabilities to reduce implementation complexity:

### Simplified Setup

With Streamable, the entire server setup becomes remarkably concise:

```typescript {filename="mcp-domains-streamable/src/index.ts"} theme={null}
const transport = new StreamableHTTPServerTransport(
  new URL('/mcp', `http://localhost:${PORT}`),
  {}
);

const domainsServer = new DomainsServer();
await domainsServer.run(transport);
```

### Stateless operation

Unlike SSE, Streamable operates in a stateless mode. Each request creates a new server instance, eliminating session management complexity:

```typescript {filename="mcp-domains-streamable/src/index.ts"} theme={null}
class DomainsServer {
  async run(transport: StreamableHTTPServerTransport): Promise<void> {
    await this.server.connect(transport);
    
    transport.handleRequestClose = () => {
      process.exit(0);  // Clean shutdown after each request
    };
  }
}
```

### Unified endpoint

All communication flows through a single `/mcp` endpoint, which handles both POST and GET requests:

```bash theme={null}
# Client request with proper headers
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"method": "initialize", "params": {"capabilities": {}}}'
```

This unified approach aligns with modern API design principles and simplifies client implementation.

## Deploying MCP Servers on Upsun

Upsun transforms MCP server deployment from a complex infrastructure challenge into a straightforward Git push. The platform's multi-app architecture perfectly suits MCP deployments, where you might need different transports for different use cases.

### Multi-App configuration

Upsun's ability to run multiple applications within a single project shines when deploying both MCP transport variants. Here's how our configuration handles both servers:

```yaml {filename=".upsun/config.yaml"} theme={null}
applications:
  mcp-domains-streamable:
    source:
      root: "mcp-domains-streamable"
    type: nodejs:22
    web:
      commands:
        start: "npm run start -- -p $PORT"
    hooks:
      build: |
        npm install
        npm run build
        
  mcp-domains-sse:
    source:
      root: "mcp-domains-sse"
    type: nodejs:22
    web:
      commands:
        start: "npm run start -- -p $PORT"
    hooks:
      build: |
        npm install
        npm run build
```

### Intelligent routing

Upsun's routing layer enables sophisticated traffic management without additional infrastructure:

```yaml {filename=".upsun/config.yaml"} theme={null}
routes:
  "https://sse.{all}/": 
    type: upstream
    upstream: "mcp-domains-sse:http"
    
  "https://streamable.{all}/": 
    type: upstream
    upstream: "mcp-domains-streamable:http"
    
  "https://{all}/": 
    type: redirect
    to: "https://streamable.{all}/"
```

This configuration provides separate endpoints for each transport while maintaining a clean URL structure. The default route redirects to the Streamable implementation, acknowledging its position as the future standard.

### Preview environments for MCP development

One of Upsun's most powerful features for MCP development is preview environments. When you create a new Git branch, Upsun automatically provisions a complete environment - including both MCP servers:

```bash theme={null}
# Create a feature branch
git checkout -b add-domain-filtering

# Make your changes to the MCP server
# ... edit code ...

# Push to create a preview environment
git push -u origin add-domain-filtering
```

Within minutes, you have a fully functional preview environment at `https://streamable.add-domain-filtering-abc123.preview.platformsh.site/`. This environment includes:

* Both MCP servers running with your changes
* Isolated from production
* Complete with all routing and configuration
* Ready for testing with your AI assistant

### Scaling and performance

Upsun handles scaling based on your resource allocation. For MCP servers, this means:

* **SSE deployments**: Can handle numerous persistent connections thanks to Node.js's event-driven architecture
* **Streamable deployments**: Scale effortlessly due to their stateless nature
* **Automatic resource optimization**: Upsun manages memory and CPU allocation based on actual usage

### Observability and monitoring

Deploying on Upsun provides built-in observability through Blackfire integration:

```yaml {filename=".upsun/config.yaml"} theme={null}
applications:
  mcp-domains-streamable:
    runtime:
      extensions:
        - blackfire
```

This gives you:

* Performance profiling of MCP tool executions
* Resource usage tracking
* Response time analysis
* Bottleneck identification

## Best practices for MCP deployment

Successfully deploying MCP servers requires attention to several key areas:

### Security considerations

1. **API Key Management**: Store sensitive credentials in environment variables:
   ```bash theme={null}
   upsun variable:create DOMAINS_API_KEY --level project --value "your-api-key"
   ```

2. **CORS Configuration**: Both implementations include proper CORS headers for browser-based clients

3. **Rate Limiting**: Implement appropriate rate limiting to prevent abuse

### Performance optimization

1. **Connection Pooling**: For SSE implementations, reuse HTTP connections where possible
2. **Caching**: Cache frequently requested data to reduce API calls
3. **Timeout Management**: Set appropriate timeouts for long-running operations

### Error handling

Both implementations include comprehensive error handling:

```typescript {filename="mcp-domains-streamable/src/index.ts"} theme={null}
try {
  const response = await fetch(url.toString());
  if (!response.ok) {
    throw new Error(`API error: ${response.statusText}`);
  }
} catch (error) {
  return {
    content: [{
      type: "text",
      text: `Error: ${error.message}`
    }],
    isError: true,
  };
}
```

## Conclusion

The Model Context Protocol represents a shift in how AI assistants interact with external systems. Whether you choose the current SSE transport or embrace the new Streamable approach, Upsun provides the perfect platform for deploying MCP servers.

With Upsun's Git-driven infrastructure, preview environments, and multi-app support, you can focus on building innovative AI integrations rather than managing deployment complexity. The platform handles scaling, monitoring, and infrastructure management, letting you iterate rapidly and deploy with confidence.

Ready to deploy your own MCP servers? [Create a free Upsun account](https://upsun.com) and have your first server running in minutes. For production deployments and enterprise features, [contact our team](https://upsun.com/contact-us/) to explore how Upsun can accelerate your AI integration journey.

**The future of AI-powered applications is here. Deploy it on Upsun.**


# Experiment with Chainlit AI interface with RAG on Upsun
Source: https://developer.upsun.com/posts/hands-on/deploying-chainlit-with-rag

Learn to deploy production-ready RAG applications with Chainlit and Python on Upsun. Tutorial covers OpenAI Assistants integration, llama_index implementation, and secure authentication.
  


<PostMeta />

## What is Chainlit?

Chainlit is an open-source async Python framework which allows developers to build scalable Conversational AI or agentic applications. While providing the base framework, Chainlit gives you full flexibility to implement any external API, logic or local models you want to run.

<img alt="Test assistant" />

In this tutorial we will be implementing RAG (Retrieval Augmented Generation) in two ways:

* The first will leverage **OpenAI assistants** with uploaded documents
* The second will be using `llama_index` with a **local folder** of documents

## Setting up Chainlit locally

### Virtualenv

Let's start by creating our `virtualenv`:

```bash {filename="Terminal"} theme={null}
mkdir chainlit && cd chainlit
python3 -m venv venv
source venv/bin/activate
```

### Install dependencies

We are now adding our dependencies and freeze them:

```bash {filename="Terminal"} theme={null}
pip install chainlit
pip install llama_index # Useful only for case #2
pip install openai
pip freeze > requirements.txt
```

### Test Chainlit

Let's start chainlit:

```bash {filename="Terminal"} theme={null}
chainlit hello
```

You should now see a placeholder on <a href="http://localhost:8000/">[http://localhost:8000/](http://localhost:8000/)</a>

<img alt="Chainlit demo" />

## Let's deploy it on Upsun

### Init the git repository

```bash {filename="Terminal"} theme={null}
git init .
```

Don't forget to add a `.gitignore` file. Some folders will be used later on.

```txt {filename=".gitignore"} theme={null}
.env
database/**
data/**
storage/**
.chainlit
venv
__pycache__
```

### Create an Upsun project

```bash {filename="Terminal"} theme={null}
upsun project:create # follow the prompts
```

The Upsun CLI will automatically set the `upsun` remote on your local git repository.

### Let's add the configuration

Here is an example configuration to run Chainlit:

```yaml {filename=".upsun/config.yaml"} theme={null}
applications:
  chainlit:
    source:
      root: "/"

    type: "python:3.11"

    mounts:
      "/database":
        source: "storage"
        source_path: "database"
      ".files":
        source: "storage"
        source_path: "files"
      "__pycache__":
        source: "storage"
        source_path: "pycache"
      ".chainlit":
        source: "storage"
        source_path: ".chainlit"

    web:
      commands:
        start: "chainlit run app.py --port $PORT --host 0.0.0.0"
      upstream:
        socket_family: tcp
      locations:
        "/":
          root: ""
          passthru: true
        "/public":
          passthru: true

    build:
      flavor: none

    hooks:
      build: |
        set -eux
        pip install -r requirements.txt
      deploy: |
        set -eux
      # post_deploy: |

routes:
  "https://{default}/":
    type: upstream
    upstream: "chainlit:http"
  "https://www.{default}":
    type: redirect
    to: "https://{default}/"
```

Nothing out of the ordinary there! We install all dependencies in the `build` hook and then start the app with `chainlit` directly and we specify the port it should run on.

<Note>
  💡 You will need to add your `OPENAI_API_KEY` to either the configuration or your environment variables on the Upsun console or through the CLI. You can get the key by generating it on the [OpenAI Platform site](https://platform.openai.com).
</Note>

To add it as an environment variable through the CLI, you can use:

```bash {filename="Terminal"} theme={null}
upsun variable:create env:OPENAI_API_KEY --value=sk-proj[...]
```

### Let's deploy!

Commit the files and configuration to deploy!

```bash {filename="Terminal"} theme={null}
git add .
git commit -m "First chainlit example"
upsun push
```

### Review the deployment

If everything goes well, you should have Chainlit deployed and working correctly on your `main` environment:

<img alt="First push" />

## First implementation: OpenAI Assistant & uploaded files

The goal here is to make Chainlit work with an OpenAI assistant. Our content will be loaded directly in the assistant on OpenAI.

### Create the assistant

Go to the [Platform Assistants](https://platform.openai.com/assistants) page and create a new one.

<img alt="Assistant" />

Set the system instructions and select the model you want to use. Make sure the `Response Format` is set to `text`. I like to keep the temperature low, around `0.10` to avoid hallucinations.

Copy your assistant ID `asst_[xxx]` and add it to your environment variables:

```bash {filename="Terminal"} theme={null}
upsun variable:create env:OPENAI_ASSISTANT_ID --value=asst_[...]
```

### Upload your content

Enable the `File search` toggle and click `+ Files`. Upload your content. While OpenAI is capable of ingesting a lot of different file formats, I like to upload only Markdown as it is faster and easier to parse, removing potential issues with PDF for example.

<img alt="Upload" />

After a few seconds, the content is ingested and transformed into a vector store, ready to be used:

<img alt="Vector store" />

<Note>
  💡 You can reuse an existing vector store on a different assistant if you want!
</Note>

Everything is now ready on the OpenAI side and we can implement the logic in Chainlit.

### Adding the assistant logic.

Open `app.py` and replace the content with the code below:

```python {filename="app.py",linenos=table,hl_lines=["120-127"],linenostart=1} theme={null}
import os
from io import BytesIO
from pathlib import Path
from typing import List
from typing import Optional

from openai import AsyncAssistantEventHandler, AsyncOpenAI, OpenAI

from literalai.helper import utc_now

import chainlit as cl
from chainlit.config import config
from chainlit.element import Element

async_openai_client = AsyncOpenAI(api_key=os.environ.get("OPENAI_API_KEY"))
sync_openai_client = OpenAI(api_key=os.environ.get("OPENAI_API_KEY"))

assistant = sync_openai_client.beta.assistants.retrieve(
    os.environ.get("OPENAI_ASSISTANT_ID")
)

config.ui.name = assistant.name

class EventHandler(AsyncAssistantEventHandler):

    def __init__(self, assistant_name: str) -> None:
        super().__init__()
        self.current_message: cl.Message = None
        self.current_step: cl.Step = None
        self.current_tool_call = None
        self.assistant_name = assistant_name

    async def on_text_created(self, text) -> None:
        self.current_message = await cl.Message(author=self.assistant_name, content="").send()

    async def on_text_delta(self, delta, snapshot):
        await self.current_message.stream_token(delta.value)

    async def on_text_done(self, text):
        await self.current_message.update()

    async def on_tool_call_created(self, tool_call):
        self.current_tool_call = tool_call.id
        self.current_step = cl.Step(name=tool_call.type, type="tool")
        self.current_step.language = "python"
        self.current_step.created_at = utc_now()
        await self.current_step.send()

    async def on_tool_call_delta(self, delta, snapshot): 
        if snapshot.id != self.current_tool_call:
            self.current_tool_call = snapshot.id
            self.current_step = cl.Step(name=delta.type, type="tool")
            self.current_step.language = "python"
            self.current_step.start = utc_now()
            await self.current_step.send()  
                 
        if delta.type == "code_interpreter":
            if delta.code_interpreter.outputs:
                for output in delta.code_interpreter.outputs:
                    if output.type == "logs":
                        error_step = cl.Step(
                            name=delta.type,
                            type="tool"
                        )
                        error_step.is_error = True
                        error_step.output = output.logs
                        error_step.language = "markdown"
                        error_step.start = self.current_step.start
                        error_step.end = utc_now()
                        await error_step.send()
            else:
                if delta.code_interpreter.input:
                    await self.current_step.stream_token(delta.code_interpreter.input)

    async def on_tool_call_done(self, tool_call):
        self.current_step.end = utc_now()
        await self.current_step.update()

    async def on_image_file_done(self, image_file):
        image_id = image_file.file_id
        response = await async_openai_client.files.with_raw_response.content(image_id)
        image_element = cl.Image(
            name=image_id,
            content=response.content,
            display="inline",
            size="large"
        )
        if not self.current_message.elements:
            self.current_message.elements = []
        self.current_message.elements.append(image_element)
        await self.current_message.update()

async def upload_files(files: List[Element]):
    file_ids = []
    for file in files:
        uploaded_file = await async_openai_client.files.create(
            file=Path(file.path), purpose="assistants"
        )
        file_ids.append(uploaded_file.id)
    return file_ids

async def process_files(files: List[Element]):
    # Upload files if any and get file_ids
    file_ids = []
    if len(files) > 0:
        file_ids = await upload_files(files)

    return [
        {
            "file_id": file_id,
            "tools": [{"type": "code_interpreter"}, {"type": "file_search"}],
        }
        for file_id in file_ids
    ]

@cl.on_chat_start
async def start_chat():
    # Create a Thread
    thread = await async_openai_client.beta.threads.create()
    # Store thread ID in user session for later use
    cl.user_session.set("thread_id", thread.id)
    # await cl.Avatar(name=assistant.name, path="./public/logo.png").send()
    await cl.Message(content=f"Hello, I'm {assistant.name}!").send()
    

@cl.on_message
async def main(message: cl.Message):
    thread_id = cl.user_session.get("thread_id")

    attachments = await process_files(message.elements)

    # Add a Message to the Thread
    oai_message = await async_openai_client.beta.threads.messages.create(
        thread_id=thread_id,
        role="user",
        content=message.content,
        attachments=attachments,
    )

    # Create and Stream a Run
    async with async_openai_client.beta.threads.runs.stream(
        thread_id=thread_id,
        assistant_id=assistant.id,
        event_handler=EventHandler(assistant_name=assistant.name),
    ) as stream:
        await stream.until_done()
```

Feel free to review the whole code but let's focus on the important parts:

```python {filename="app.py",linenos=table,hl_lines=["1-8"],linenostart=120} theme={null}
@cl.on_chat_start
async def start_chat():
    # Create a Thread
    thread = await async_openai_client.beta.threads.create()
    # Store thread ID in user session for later use
    cl.user_session.set("thread_id", thread.id)
    # await cl.Avatar(name=assistant.name, path="./public/logo.png").send()
    await cl.Message(content=f"Hello, I'm {assistant.name}!").send()
```

`on_chat_start` is called when a new chat is created. It creates a new thread on OpenAI to handle the conversation and start it with a new welcome message.

```python {filename="app.py",linenos=table,hl_lines=["1-21"],linenostart=130} theme={null}
@cl.on_message
async def main(message: cl.Message):
    thread_id = cl.user_session.get("thread_id")

    attachments = await process_files(message.elements)

    # Add a Message to the Thread
    oai_message = await async_openai_client.beta.threads.messages.create(
        thread_id=thread_id,
        role="user",
        content=message.content,
        attachments=attachments,
    )

    # Create and Stream a Run
    async with async_openai_client.beta.threads.runs.stream(
        thread_id=thread_id,
        assistant_id=assistant.id,
        event_handler=EventHandler(assistant_name=assistant.name),
    ) as stream:
        await stream.until_done()
```

`on_message` is triggered whenever the user is submitting a new message. It sends the content to the OpenAI API on the thread and then launches a stream. You can find more information on how they work on [the official documentation](https://platform.openai.com/docs/api-reference/threads).

To summarize, instead of getting the answer as part of the HTTP response of the Message request, we have to poll the Threads API to find new messages that would have been created. It's a bit more cumbersone but allows OpenAI to perform multiple operations asynchronously and add the results into the thread.

### Commit the changes and deploy

Let's state and commit the changes:

```bash {filename="Terminal"} theme={null}
git add .upsun/config.yaml
git add app.py
git commit -m "OpenAI assistant version"
```

And we can now deploy:

```bash {filename="Terminal"} theme={null}
upsun push
```

### Test the Assistant

Go to the deployed Chainlit instance and ask any question related to the content you uploaded:

<img alt="Test assistant" />

You should get an appropriate answer! It might be a bit slow due to the polling process especially on the first message. But it works! OpenAI gives you the indications where in your documents it sourced some of the information

## Second implementation: OpenAI + llama\_index

So the goal for this version will be to build the knowledge locally and then rely on OpenAI to output the final form.

### Create a new branch

Let's kickstart this by working on a new environment/branch:

```bash {filename="Terminal"} theme={null}
git checkout -b llama-index
```

### Add two new folders and mounts to store our data

Create the folders first on your machine:

```bash {filename="Terminal"} theme={null}
mkdir data
mkdir storage
```

And now add the mount to our Upsun configuration:

```yaml {filename=".upsun/config.yaml"} theme={null}
    mounts:
      "/data":
        source: "storage"
        source_path: "data"
      "/storage":
        source: "storage"
        source_path: "storage"
```

`data` will be used for our source documents and `storage` will handle the cached `VectorStore`.

### Let's update our app

We will not be using the OpenAI assistant there so the code will be a lot simpler:

```python {filename="app.py",linenos=table,hl_lines=["39","41","43-44"]} theme={null}
import os
import openai
import chainlit as cl

from llama_index.core import (
    Settings,
    StorageContext,
    VectorStoreIndex,
    SimpleDirectoryReader,
    load_index_from_storage,
)
from llama_index.llms.openai import OpenAI
from llama_index.embeddings.openai import OpenAIEmbedding
from llama_index.core.query_engine.retriever_query_engine import RetrieverQueryEngine
from llama_index.core.node_parser import SentenceSplitter
from llama_index.core.service_context import ServiceContext
from llama_index.core.callbacks import CallbackManager

openai.api_key = os.environ.get("OPENAI_API_KEY")

try:
    # rebuild storage context
    storage_context = StorageContext.from_defaults(persist_dir="./storage")
    # load index
    index = load_index_from_storage(storage_context)
except:
    documents = SimpleDirectoryReader("./data").load_data(show_progress=True)
    index = VectorStoreIndex.from_documents(documents)
    index.storage_context.persist()

@cl.on_chat_start
async def start():
    Settings.llm = OpenAI(
        model="gpt-4o", temperature=0.1, max_tokens=2048, streaming=True
    )
    Settings.context_window = 2048

    Settings.embed_model = OpenAIEmbedding(model="text-embedding-3-small")
    Settings.node_parser = SentenceSplitter(chunk_size=256, chunk_overlap=20)
    Settings.num_output = 1024
    
    query_engine = index.as_query_engine(streaming=True, similarity_top_k=2)
    cl.user_session.set("query_engine", query_engine)

    await cl.Message(
        author="Assistant", content="Hello! Im an AI assistant. How may I help you?"
    ).send()

@cl.on_message
async def main(message: cl.Message):
    query_engine = cl.user_session.get("query_engine") # type: RetrieverQueryEngine

    msg = cl.Message(content="", author="Assistant")

    res = await cl.make_async(query_engine.query)(message.content)

    for token in res.response_gen:
        await msg.stream_token(token)
    await msg.send()

```

Let's break down the important parts.

When the application is starting, we use the `text-embedding-3-small` (line 39) to embed our documents into our `VectorStore`.

```bash {filename="Terminal"} theme={null}
$ chainlit run app.py -w --port 8000
2025-01-07 17:06:59 - Loaded .env file
Loading files: 100%|██████████████████████████████████████████████████████████████████████████| 3/3 [00:00<00:00, 17.52file/s]
```

And whenever the user creates a new chat, we define a `query_engine` (lines 43-44). It will be passed alongside every message and will contain the result from the k-search of our vector store. You can note that we are using a `similarity_top_k` param to define how many documents should be matched when searching.

<Note>
  ⚠️ I carefully set the `Settings.num_output` (line 41) so llama does not give me a bigger context window than what OpenAI can take. You can get a lot of context in the query and longer answers by increasing these values but this will obviously consume more tokens and generate higher bills so be mindful!
</Note>

### Deploy the new environment

As usual, commit and push!

```bash {filename="Terminal"} theme={null}
git add .
git commit -m "Switch to llama_index"
upsun push
```

Upsun CLI will confirm you want to create a new environment:

```bash {filename="Terminal"} theme={null}
$ upsun push
Selected project: Chainlit Dev Center tutorial (545vnfflc3n4u)

Enter the target branch name (default: llama-index): 

Create llama-index as an active environment? [Y/n]  

Pushing HEAD to the branch llama-index of project Chainlit Dev Center tutorial (545vnfflc3n4u)
It will be created as an active environment.
```

Hit `Yes` and the new app will be deployed in a new isolated environment.

### Push some data

In order to have some documents to work with on the Upsun environment, you can automatically upload your `data` folder:

```bash {filename="Terminal"} theme={null}
$ upsun mount:upload
Enter a number to choose a mount to upload to:
  [0] data: storage
  [1] database: storage
  [2] .files: storage
  [3] __pycache__: storage
  [4] .chainlit: storage
 > 0

Source directory [data]: 

Uploading files from data to the remote mount data
Are you sure you want to continue? [Y/n] 

  building file list ...   done
  ./
  developer_themes.md
  intro.md

  sent 27.83K bytes  received 92 bytes  11.17K bytes/sec
  total size is 90.92K  speedup is 3.26
```

### Test llama\_index

Once deployed, head over to your environment (`llama-index-sukwicq-[project id].[region].platformsh.site`) and test a prompt:

<img alt="llama test" />

As contrary to the OpenAI `file_search`, the response does not give you the source of the data as it was passed directly from `llama_index` to OpenAI.

<Note>
  💡 While most of our system relies on local data, we are still generating the final answer through OpenAI. If you wanted to run everything locally, you could rely on Chainlit being capable of querying model like [SmolLM](https://huggingface.co/blog/smollm) running locally.
</Note>

## Bonus: Adding authentification to Chainlit

Now that our Chainlit application is deployed and available, it would be great to add some form of authentication to make sure only you and your folks can access it. While Chainlit has many capabilities for this, we will go for the simpler route of using a `sqlite` database for this.

### Create the database folder

```bash {filename="Terminal"} theme={null}
mkdir database
```

And add the mount in the Upsun configuration:

```yaml {filename=".upsun/config.yaml"} theme={null}
    mounts:
      "/database":
        source: "storage"
        source_path: "database"
```

### Add the auth logic to our application

First let's add a new environment variable:

```bash {filename="Terminal"} theme={null}
upsun variable:create env:DB_PATH --value="database/auth.db"
```

We can now add the logic into `app.py`:

```python {filename="app.py",linenos=table,hl_lines=["19"]} theme={null}
import sqlite3
[...]

db_path = os.environ.get("DB_PATH")

# Create the database if it doesn't exist
con = sqlite3.connect(db_path)
cur = con.cursor()
cur.execute("""
    CREATE TABLE IF NOT EXISTS users (
        id INTEGER PRIMARY KEY,
        username TEXT NOT NULL,
        password TEXT NOT NULL
    )
""")
con.commit()
con.close()

@cl.password_auth_callback
def auth_callback(username: str, password: str):
    if not os.path.exists(db_path):
        with open(db_path, 'w') as file:
            file.write('')

    con = sqlite3.connect(db_path)
    cur = con.cursor()
    hashed_password = hashlib.sha256(password.encode()).hexdigest()

    cur.execute("SELECT * FROM users WHERE username = ? AND password = ?", (username, hashed_password))
    user = cur.fetchone()
    if user:
        return cl.User(
            identifier=user[1], metadata={"role": "admin", "provider": "credentials"}
        )
    else:
        return None
```

When the script is run, it first check that it can open the database or create it if it doesn't exist.

Adding `@cl.password_auth_callback` will automagically add a login form to our app. The logic in `auth_callback` is pretty simple right there. Feel free to change it the way you want.

We are hashing the form password and looking up for a user that matches both `username` and `password`. If so we return the user with the `admin` privileges.

### Create a simple script to generate hashed passwords

```python {filename="create_password.py"} theme={null}
import hashlib
import random
import string

def generate_password(length=12):
    # Define character sets for password generation
    chars = string.ascii_letters + string.digits + string.punctuation
    # Generate random password
    password = ''.join(random.choice(chars) for _ in range(length))
    # Hash the password
    hashed_password = hashlib.sha256(password.encode()).hexdigest()
    
    return password, hashed_password

def main():
    # Generate password and get its hash
    password, hashed_password = generate_password()
    
    # Display both the password and its hash
    print(f"Generated Password: {password}")
    print(f"Hashed Password: {hashed_password}")

if __name__ == "__main__":
    main()
```

You can invoke it and it will output the password and the hash:

```bash {filename="Terminal"} theme={null}
$ python create_password.py
Generated Password: F\7r\pQ-jmP$
Hashed Password: 67f4db1ae09453ff6ce68e5d3c138259f80b5b3b6c595226435323d0004d99f7
```

### Adding users

Now it's just a matter of creating new records in the `users` table of our `auth.db`. Don't forget you need to put the **hashed** version of the password in the database! You can either run queries through the CLI or use GUI:

<img alt="Creating users" />

And we should now be ready to go!

### Deploy the authentication

As usual, commit and push:

```bash {filename="Terminal"} theme={null}
git add .
git commit -m "Add auth"
upsun push
```

In order for our authentication to work, let's upload our `sqlite` database:

```bash {filename="Terminal"} theme={null}
upsun mount:upload
```

### Login now!

You now need to input your credentials to login to your Chainlit interface:

<img alt="Login form" />

## Conclusion

In this tutorial, we've successfully deployed a Chainlit application on Upsun with two different RAG implementations, each offering unique advantages. The OpenAI Assistant approach provides built-in file handling and clear source attribution, while the llama\_index implementation offers more control over the embedding process and local vector store management. We've also added a layer of security through SQLite-based authentication, making the application production-ready.

By leveraging Upsun's platform capabilities, particularly its storage mounts and environment management, we've created a scalable and secure conversational AI interface that can be adapted for various use cases. Whether you're building a document-aware chatbot, a knowledge base assistant, or any other RAG-powered application, this setup provides a solid foundation for further development.

Remember that while we used OpenAI's models for generation in both implementations, the architecture we've built could be adapted to work with other language models, including local ones, depending on your specific needs and requirements.

***


# How to enable custom maintenance page in Fastly
Source: https://developer.upsun.com/posts/hands-on/fastly-maintenance

Configure GitLab CI/CD to deploy to Upsun from private air-gapped GitLab instances using push-based workflows and API automation.


<PostMeta />

This step-by-step guide outlines how to create and maintain a custom maintenance page
in [Fastly](https://www.fastly.com/), and how to enable and disable it either manually
or during [Upsun](https://www.upsun.com) deployments.

We need to add a dictionary in Fastly which we will use as an on / off switch to enable and disable the maintenance page
as well as the content of maintenance page.

We are going to use official Fastly CLI tool which you can download
from [Fastly CLI](https://www.fastly.com/documentation/reference/tools/cli/). You will need a Fastly API token with
permissions to perform changes.

We are going to use these two environment variables:

* `FASTLY_SERVICE_ID`: Contains our Fastly service ID.
* `FASTLY_API_TOKEN`: Contains our Fastly API token.

## Create Fastly configuration

<Note>
  Please define these two local environment variables before starting, using the following command lines:

  ```bash {filename="Terminal"} theme={null}
  export FASTLY_SERVICE_ID=<YOUR-FASTLY-SERVICE-ID>
  export FASTLY_API_TOKEN=<YOUR-FASTLY-API-TOKEN>
  ```
</Note>

Let’s start with cloning the active configuration version:

```bash {filename="Terminal"} theme={null}
fastly service-version clone -t $FASTLY_API_TOKEN -s $FASTLY_SERVICE_ID --version active

SUCCESS: Cloned service $FASTLY_SERVICE_ID version X to version Y
```

From now on, we will work on our cloned version by referring to it with `--version latest`.

Let’s create a dictionary which will be used as on & off switch to enable and disable the maintenance page:

```bash {filename="Terminal"} theme={null}
fastly dictionary create -t $FASTLY_API_TOKEN -s $FASTLY_SERVICE_ID --version latest --name maintenance

SUCCESS: Created dictionary maintenance (id zHpEamIhKjDt7B28bSyRw4, service $FASTLY_SERVICE_ID, version Y)
```

Make a note of the given dictionary ID and let’s store it on a variable:

```bash {filename="Terminal"} theme={null}
export FASTLY_MAINTENANCE_DICT=zHpEamIhKjDt7B28bSyRw4
```

Let’s add an entry in the new dictionary which will be the actual on/off switch:

```bash {filename="Terminal"} theme={null}
fastly dictionary-entry create -t $FASTLY_API_TOKEN -s $FASTLY_SERVICE_ID --dictionary-id $FASTLY_MAINTENANCE_DICT --key maintenance --value=false

SUCCESS: Created dictionary item maintenance (service $FASTLY_SERVICE_ID, dictionary $FASTLY_MAINTENANCE_DICT)
```

We need a VCL to check for the key in the dictionary to know whether to return the maintenance page or not.
Save the following VCL snippet in `maintenance_recv.vcl`:

```vcl {filename="maintenance_recv.vcl"} theme={null}
if (table.lookup(maintenance, "maintenance", "false") == "true") {
   error 653 "maintenance";
}
```

Let’s upload this `maintenance_recv.vcl` VCL to Fastly:

```bash {filename="Terminal"} theme={null}
fastly vcl snippet create -t $FASTLY_API_TOKEN -s $FASTLY_SERVICE_ID --version latest --name maintenance_recv --type recv --priority 50 --content maintenance_recv.vcl

SUCCESS: Created VCL snippet 'maintenance_recv' (service: $FASTLY_SERVICE_ID, version: Y, dynamic: false, snippet id: KdpZbSaxdj4bqP3kwKHt41, type: recv, priority: 50)
```

Save the maintenance page inside a VCL called `maintenance_error.vcl` like below. Note maintenance page goes within HTML
tags:

```vcl {filename="maintenance_error.vcl"} theme={null}
if (obj.status == 653) {
  set obj.status = 200;
  set obj.response = "OK";
  synthetic {"
    <html>
      <head>
      </head>
      <body>
        <h1>This site is under maintenance</h1>
      </body>
    </html>
  "};
  return(deliver);
}
```

Let’s create the `maintenance_error.vcl` VCL with the maintenance page in Fastly:

```bash {filename="Terminal"} theme={null}
fastly vcl snippet create -t $FASTLY_API_TOKEN -s $FASTLY_SERVICE_ID --version latest --name maintenance_error --type error --content maintenance_error.vcl

SUCCESS: Created VCL snippet 'maintenance_error' (service: $FASTLY_SERVICE_ID, version: Y, dynamic: false, snippet id: 3BcskRs1Z2Fo9GqidDwDf0, type: error, priority: 100)
```

We can now activate our changes:

```bash {filename="Terminal"} theme={null}
fastly service-version activate -t $FASTLY_API_TOKEN -s $FASTLY_SERVICE_ID --version latest

SUCCESS: Activated service $FASTLY_SERVICE_ID version Y
```

## Testing

From now on, we can enable and disable our maintenance page in Fastly on demand by altering the key in the dictionary.
We can enable it by setting the key value to true:

```bash {filename="Terminal"} theme={null}
fastly dictionary-entry update -t $FASTLY_API_TOKEN -s $FASTLY_SERVICE_ID --dictionary-id $FASTLY_MAINTENANCE_DICT --key maintenance --value=true

SUCCESS: Updated dictionary item (service $FASTLY_SERVICE_ID)

Dictionary ID: $FASTLY_MAINTENANCE_DICT
Item Key: maintenance
Item Value: true
```

Bear in mind it will take several seconds for Fastly to propagate the key value among their edge servers. You can browse
to our website and check how the maintenance page is being served by Fastly.

We can disable the maintenance page by altering the key to false in the dictionary:

```bash {filename="Terminal"} theme={null}
fastly dictionary-entry update -t $FASTLY_API_TOKEN -s $FASTLY_SERVICE_ID --dictionary-id $FASTLY_MAINTENANCE_DICT --key maintenance --value=false

SUCCESS: Updated dictionary item (service $FASTLY_SERVICE_ID)

Dictionary ID: $FASTLY_MAINTENANCE_DICT
Item Key: maintenance
Item Value: false
Maintenance page will disappear and the website will be live again.
```

## Enable maintenance during deployment

If we want to display the maintenance page during deployment, we can do so by adding the variables and enable followed
disable the page in the deployment hooks.

We can add the variables to our project like below:

```bash {filename="Terminal"} theme={null}
upsun variable:create -p <PROJECT_ID> -e <PROD_ENVIRONMENT> --level environment --inheritable false --visible-build true --prefix env --no-wait --name FASTLY_SERVICE_ID --value $FASTLY_SERVICE_ID
upsun variable:create -p <PROJECT_ID> -e <PROD_ENVIRONMENT> --level environment --inheritable false --visible-build true --prefix env --no-wait --sensitive true --name FASTLY_API_TOKEN --value $ FASTLY_API_TOKEN
upsun variable:create -p <PROJECT_ID> -e <PROD_ENVIRONMENT> --level environment --inheritable false --visible-build true --prefix env --no-wait --name FASTLY_MAINTENANCE_DICT --value $FASTLY_MAINTENANCE_DICT
```

<Note>
  **Note:** Replace `<PROJECT_ID>` and `<PROD_ENVIRONMENT>` with your Upsun project info.

  Example:

  * `<PROJECT_ID>` = `azertyuiop1234`
  * `<PROD_ENVIRONMENT>` = `main`
</Note>

We add enable and disable maintenance commands at the end of [build and deploy hooks](https://docs.upsun.com/create-apps/app-reference/single-runtime-image.html#hooks) respectively:

```yaml {filename=".upsun/config.yaml",hl_lines=["7-8", "13"],linenostart=1} theme={null}
applications:
  app:
    hooks:
      build: |
        set -e
        #...
        brew install fastly/tap/fastly
        fastly dictionary-entry update -t $FASTLY_API_TOKEN -s $FASTLY_SERVICE_ID --dictionary-id $FASTLY_MAINTENANCE_DICT --key maintenance --value=true
    
      deploy: |
        set -e
        #...
        fastly dictionary-entry update -t $FASTLY_API_TOKEN -s $FASTLY_SERVICE_ID --dictionary-id $FASTLY_MAINTENANCE_DICT --key maintenance --value=false
```

<Note>
  **Please note**:

  The above commands can also be applied to [Platform.sh](https://platform.sh) projects by replacing `upsun` CLI by `platform` CLI in the call.
</Note>

## Updating maintenance page

What if we want to update the maintenance page in the future?

For doing so, we update `maintenance_error.vcl` with our updated maintenance page within HTML tags. We create a new
version, upload it and activate in Fastly:

```bash {filename="Terminal"} theme={null}
fastly service-version clone -t $FASTLY_API_TOKEN -s $FASTLY_SERVICE_ID --version active
fastly vcl snippet update -t $FASTLY_API_TOKEN -s $FASTLY_SERVICE_ID --version latest --name maintenance_error --type error --content maintenance_error.vcl
fastly service-version activate -t $FASTLY_API_TOKEN -s $FASTLY_SERVICE_ID --version latest
```

## Adding allowed IPs while maintenance enabled

Let's say that we want to allow some IP ranges to allow to reach the website when the maintenance page is enabled. This is useful when we need to perform tests and other tasks during mainteance window. In order to accomplish this, we will need to create an ACL with the excluded IP ranges and exclude this list when maintenance is enabled.

Create a new version to make changes:

```bash {filename="Terminal"} theme={null}
fastly service-version clone -t $FASTLY_API_TOKEN -s $FASTLY_SERVICE_ID --version active
```

Create the ACL:

```bash {filename="Terminal"} theme={null}
$ fastly acl create -t $FASTLY_API_TOKEN -s $FASTLY_SERVICE_ID --version latest --name maintenance_ips
SUCCESS: Created ACL 'maintenance_ips' (id: yQImb1Ab1cIWaqBV42VWC2, service: $FASTLY_SERVICE_ID, version: 41)
```

Make a note of the given ACL ID and let’s store it on a variable:

```bash {filename="Terminal"} theme={null}
export FASTLY_MAINTENANCE_ACL=yQImb1Ab1cIWaqBV42VWC2
```

Let's add an IP address and a network to it (these IP addresses are examples and add IP ranges you own instead):

```bash {filename="Terminal"} theme={null}
fastly acl-entry create -t $FASTLY_API_TOKEN -s $FASTLY_SERVICE_ID --acl-id $FASTLY_MAINTENANCE_ACL --ip 101.101.101.101 --comment VPN_IP
fastly acl-entry create -t $FASTLY_API_TOKEN -s $FASTLY_SERVICE_ID --acl-id $FASTLY_MAINTENANCE_ACL --ip 101.201.201.0 --subnet 24 --comment Office
```

Edit `maintenance_recv.vcl` VCL snippet like below:

```vcl {filename="maintenance_recv.vcl"} theme={null}
if (table.lookup(maintenance, "maintenance", "false") == "true") {
   if (!req.http.Fastly-Client-IP ~ maintenance_ips) {
      error 653 "maintenance";
   }
}
```

And upload it to Fastly:

```bash {filename="Terminal"} theme={null}
fastly vcl snippet update -t $FASTLY_API_TOKEN -s $FASTLY_SERVICE_ID --version latest --name maintenance_recv --type recv --content maintenance_recv.vcl
```

Active the new version to activate the changes:

```bash {filename="Terminal"} theme={null}
fastly service-version activate -t $FASTLY_API_TOKEN -s $FASTLY_SERVICE_ID --version latest
```

We will be able to browse to the website from IPs listed in the `maintenance_ips` ACL even after enabling the maintenance page.

### Updating maintenance ACL IPs

We can add additional IPs to the maintenance ACL in the future without cloning the version. Just add them like this:

```bash {filename="Terminal"} theme={null}
fastly acl-entry create -t $FASTLY_API_TOKEN -s $FASTLY_SERVICE_ID --acl-id $FASTLY_MAINTENANCE_ACL --ip 55.55.55.55 --comment another_location
```

## Summary

With your Fastly maintenance page configured, you can now automatically enable maintenance page in Fastly during
deployments to Upsun. This setup provides:

* [Create Fastly configuration to enable custom maintenance page](#create-fastly-configuration)
* [Automatically enable maintenance page during deployments](#enable-maintenance-during-deployment)
* [Maintain custom maintenance page](#updating-maintenance-page)

For more advanced configurations, explore [Upsun's API documentation](https://docs.upsun.com/api/) to customize
environment settings, manage resources, and integrate with your existing DevOps tools.

***

[Create your Upsun account](https://upsun.com) today.


# Synchronize your air-gapped GitLab with Upsun
Source: https://developer.upsun.com/posts/hands-on/gitlab-push-solution

Configure GitLab CI/CD to deploy to Upsun from private air-gapped GitLab instances using push-based workflows and API automation


<PostMeta />

When your GitLab instance isn't accessible from the internet, you can't use Upsun's standard GitLab integration. Instead, you can create a GitLab CI/CD pipeline that pushes code to Upsun and manages environments through API calls.

This approach gives you full control over your deployment process while maintaining the security of your private GitLab instance.

## Why the standard GitLab integration won't work

The standard Upsun GitLab integration relies on a webhook-based architecture:

1. **GitLab sends webhooks** - When you push code, create branches, or open Merge Requests, GitLab sends HTTP webhooks to Upsun's servers
2. **Upsun pulls your code** - Upon receiving the webhook, Upsun attempts to connect back to your GitLab instance to pull the repository
3. **The connection fails** - Since your GitLab instance isn't accessible from the internet, Upsun can't reach it to pull the code

This webhook-pull pattern requires bidirectional connectivity between GitLab and Upsun. When your GitLab instance sits behind a firewall or on a private network, Upsun's servers can't establish the return connection needed to fetch your code.

### The push-based solution

Instead of relying on Upsun pulling from GitLab, you can implement a push-based workflow where your GitLab CI/CD pipeline actively pushes code to Upsun. This approach works because:

* Your GitLab runners can reach external services (including Upsun)
* No inbound connections to your GitLab instance are required
* You maintain full control over when and how deployments occur
* Your GitLab instance remains completely isolated from the internet

This CI/CD pipeline approach effectively reverses the flow: instead of Upsun pulling from GitLab, your pipeline pushes to Upsun, bypassing the connectivity requirements of the standard integration.

**The pipeline will take care of pushing to the `main` production environment when the branch is updated and will create preview environments whenever a new merge request is created.**

## Prerequisites

Before setting up your pipeline, you'll need:

* A GitLab runner with internet access to reach Upsun
* An Upsun project
* An [Upsun API token](https://docs.upsun.com/administration/cli/api-tokens.html#2-create-an-api-token) for environment management
* SSH keys configured on Upsun for Git operations

## Setting up authentication

### Generate an SSH key pair

Create a dedicated SSH key for your GitLab CI/CD pipeline:

```bash theme={null}
ssh-keygen -t ed25519 -C "gitlab-ci@example.com" -f upsun_deploy_key
```

Grab the content of the public key:

```bash theme={null}
cat upsun_deploy_key.pub | pbcopy
```

In the [Upsun interface](https://console.upsun.com/), create a new SSH key for your user:

<img alt="Add SSH Key" />

### Configure GitLab CI/CD variables

Add these variables to your GitLab project's CI/CD settings:

* `UPSUN_PROJECT_ID`: Your Upsun project ID (e.g., `abcdefgh1234567`)
* `UPSUN_API_TOKEN`: Your Upsun API token (masked variable)
* `UPSUN_SSH_PRIVATE_KEY`: Contents of your private SSH key (It unfortunately can't be a masked variable due to the key format)
* `UPSUN_GIT_REMOTE`: Your Upsun Git remote URL
* `UPSUN_REGION`: The Upsun region the project is hosted on (`us-3.platform.sh`, `fr-1.platform.sh`, etc.)

<img alt="Gitlab Variables" />

## Creating the GitLab CI/CD pipeline

<Note>
  The full `.gitlab-ci.yml` file [can be found in our GitHub snippets repository](https://github.com/upsun/snippets/blob/main/examples/gitlab-ci/push-solution.yaml).
</Note>

Create a `.gitlab-ci.yml` file in your repository root.

Start by creating two scripts that will be referenced in the different jobs.

The first one sets up your private SSH key on the container and whitelists the Upsun git endpoint:

```yaml {filename=".gitlab-ci.yml"} theme={null}
.setup_ssh: &setup_ssh
  - echo "Setup SSH"
  - mkdir -p ~/.ssh
  - echo "$UPSUN_SSH_PRIVATE_KEY" | tr -d '\r' > ~/.ssh/id_rsa
  - chmod 600 ~/.ssh/id_rsa
  - ssh-keyscan -H git.$UPSUN_REGION >> ~/.ssh/known_hosts
```

The second is a function that will be called when we need to exchange our API token for a valid access token to actually query the API:

```yaml {filename=".gitlab-ci.yml"} theme={null}
.access_token: &access_token
  - |
    export UPSUN_ACCESS_TOKEN=$(curl -u platform-api-user: \
      -d "grant_type=api_token&api_token=$UPSUN_API_TOKEN" \
      https://auth.upsun.com/oauth2/token | jq -r .access_token)
```

### Deploying to production

Once done, you can create the first job, deploying the main branch to Upsun:

```yaml {filename=".gitlab-ci.yml"} theme={null}
# Deploy to production
deploy_production:
  stage: deploy
  image: alpine:latest
  before_script:
    - apk add --no-cache curl jq git openssh
    - *setup_ssh
  script:
    - |
      git config --global user.email "gitlab-ci@example.com"
      git config --global user.name "GitLab CI"
      git remote add upsun $UPSUN_GIT_REMOTE || git remote set-url upsun $UPSUN_GIT_REMOTE
      git push upsun main
  only:
    - main  # Adjust based on your default branch
```

The job is straightforward: It sets up our Git identity, sets the remote and pushes to the main branch. Since the `main` environment on Upsun is always enabled, no additional checks are required. This job will be triggered any time something happens on the main branch (merge, commit, etc.).

### Deploying preview environments for Merge Requests

For preview environments based on Merge Requests, the job will follow the same logic with some extra steps to enable the environment:

```yaml {filename=".gitlab-ci.yml"} theme={null}
# Deploy on push to branches and new Merge Requests
deploy_to_upsun:
  stage: deploy
  image: alpine:latest
  before_script:
    [..]
    - *access_token
  script:
    - |
      [...]
      
      echo "Checkout branch and push to Upsun"
      git checkout -B $CI_COMMIT_REF_NAME
      git push upsun $CI_COMMIT_REF_NAME

      echo "Activate environment"
      echo "UPSUN_ACCESS_TOKEN: $UPSUN_ACCESS_TOKEN"
      curl -s -X POST \
        -H "Authorization: Bearer $UPSUN_ACCESS_TOKEN" \
        -H "Content-Type: application/json" \
        "https://api.upsun.com/projects/$UPSUN_PROJECT_ID/environments/main/activate"

  only:
    - merge_requests
  except:
    - main  # Adjust based on your default branch
```

The script first trades our `API_TOKEN` for an `access_token`, checks out the correct branch and then pushes it. The last step is to call the Upsun API to activate the environment.

With the above job in place, every new Merge Request created on your GitLab will trigger an environment creation on the Upsun side. Please note that the API call might throw a graceful error if the environment is already activated.

<Note>
  While the configuration triggers this job on a new Merge Request, you can change this to follow branches by switching the `only:` flag to `branches` instead. This can be done if your workflow does not rely on Merge Requests.
</Note>

### Cleaning up unused environments

In order to not be running environments and resources for nothing, you can add a new job to clean up environments when a Merge Request is closed or merged.

GitLab does not allow the CI script to detect exactly what happened on the Merge Request. It can only detect that *something* happened. That's why the script uses a `manual` flag to trigger the job. A more robust solution would be to set up webhooks that call a script to handle the cleanup.

The cleanup script includes more actions as we need to complete the following tasks:

* Delete the Upsun remote branch
* Deactivate the Upsun environment
* Delete the Upsun environment

```yaml {filename=".gitlab-ci.yml"} theme={null}
# Cleanup environments when branches are deleted or MRs are merged
cleanup_environment:
  stage: cleanup
  image: alpine:latest
  before_script:
    [...]
    - *access_token
  script:
    - |
      # Get the source branch name from the merge request
      BRANCH_NAME="${CI_MERGE_REQUEST_SOURCE_BRANCH_NAME}"
      
      [...]
      
      # Delete the branch from Upsun remote
      git push upsun --delete "$BRANCH_NAME" || echo "Branch already deleted from remote"
      
      # Deactivate the environment via API
      curl -s -X POST \
        -H "Authorization: Bearer $UPSUN_ACCESS_TOKEN" \
        -H "Content-Type: application/json" \
        "https://api.upsun.com/projects/$UPSUN_PROJECT_ID/environments/$BRANCH_NAME/deactivate" || echo "Environment deactivation failed"
      
      # Optionally delete the environment completely
      curl -s -X DELETE \
        -H "Authorization: Bearer $UPSUN_ACCESS_TOKEN" \
        "https://api.upsun.com/projects/$UPSUN_PROJECT_ID/environments/$BRANCH_NAME" || echo "Environment deletion failed"
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
      when: manual
  allow_failure: true
```

You can trigger this script any time by going into your GitLab pipelines view:

<img alt="Trigger cleanup" />

### Deploying the script

Now that you have created the whole [.gitlab-ci.yml](https://github.com/upsun/snippets/blob/main/examples/gitlab-ci/push-solution.yaml) file, add it to your repository:

```bash theme={null}
git add .gitlab-ci.yml
git commit -m "Add GitLab CI configuration"
git push origin main
```

Congratulations! That push should trigger your first pipeline.

<img alt="First pipeline" />

## Branch name conflicts

If your branch names contain special characters, Upsun recommends converting them to safe strings:

```yaml theme={null}
script:
  - SAFE_BRANCH_NAME=$(echo $CI_COMMIT_REF_NAME | sed 's/[^a-zA-Z0-9-]/-/g')
  - git push upsun HEAD:$SAFE_BRANCH_NAME
```

## Security best practices

1. **Rotate API tokens regularly** - As API tokens have no expiration, it is recommended to rotate them periodically
2. **Use protected variables** - Mark sensitive variables as protected in GitLab
3. **Limit runner access** - Use specific runner tags for deployment jobs
4. **Audit deployments** - Enable GitLab's deployment tracking

## Summary

With your GitLab CI/CD pipeline configured, you can now deploy to Upsun from your private air-gapped GitLab instance. This setup provides:

* Automatic deployments on every push
* Preview environments for Merge Requests
* Cleanup of unused environments
* Full control over your deployment process

For more advanced configurations, explore [Upsun's API documentation](https://api.upsun.com/docs) to customize environment settings, manage resources, and integrate with your existing DevOps tools.

***

[Create your Upsun account](https://upsun.com) to get started with GitLab CI/CD deployments today.


# Limit deployments to Platform.sh only with tags: part one
Source: https://developer.upsun.com/posts/hands-on/guide-to-limit-deployments-to-platformsh-only-with-tags-part-one



<PostMeta />

Throughout the years, many users have asked us if it’s possible to only deploy to Platform.sh when a tag is pushed using
a [source code integration](https://docs.platform.sh/integrations/source.html). The answer is: with our current source
integrations, it's not—but that doesn’t mean it’s impossible.

Platform.sh is based on Git and because of this, acts as a remote for your code repository. This means there’s no reason
you can’t take advantage of your source code management system’s CI/CD platforms—for example, through GitHub or
GitLab—to enable you to only deploy to Platform. sh using tags, whenever needed.

In this article, I'll walk you through the steps of creating a GitHub workflow that only pushes your codebase to
Platform.sh to deploy changes when a particular tag is pushed. But, before we get started, there are some assumptions to
consider.

### **The assumptions**

For the purpose of this article and the steps detailed, I will assume that you have:

* A GitHub account and a repository with working code
* Administrative rights on the GitHub repository so you can add [repository secrets](https://docs.github.com/en/codespaces/managing-codespaces-for-your-organization/managing-secrets-for-your-repository-and-organization-for-github-codespaces)
* A Platform.sh account and a project for your code base with working code
* A default branch in GitHub which is the same branch as your production branch in Platform.sh
* A default branch in Platform.sh which is also your production branch
* You do *not* have a source code integration created between Platform.sh and GitHub.

The last assumption might surprise you but with a source code integration, Platform.sh becomes a mirror of your
repository and we don't want every new commit to be mirrored.

#### **1. The workflow file**

To start, we'll need to create a YAML file in the directory `workflows` within a `.github` directory at the root of our
repository as shown in the image below.
[Find out more details on why this step is necessary](https://docs.github.com/en/actions/using-workflows/about-workflows#about-workflows).
The file's name doesn't matter, but it *has* to be inside `./.github/workflows`. For this demonstration, I'll name mine
`push-tags.yml`

<img alt="push-tags.yml" />

#### **2. The event**

For this next step, go ahead and open up the file you just created. The first thing we need to do is instruct the GitHub
Actions platform on when this workflow should be triggered via a
[defined event](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows).

To trigger this workflow when a new tag is added, we'll use the
[push event](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#push) with an
[event filter](https://docs.github.com/en/actions/using-workflows/triggering-a-workflow#using-filters) of
[tags](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#onpushbranchestagsbranches-ignoretags-ignore).
If needed, we could also filter for only tags that match a certain pattern, but for this demonstration, we'll allow the
workflow to be triggered when any tag ( `‘*’` ) is added. I'm also going to add a name property so that this workflow
will be easier to identify in the repository's Actions tab.

```yaml {filename=".github/workflows/push-tags.yml"} theme={null}
name: Push to Platform.sh when tagged
    on:
      push:
        tags:
          - '*'
```

#### **3. The jobs**

Next, we need to define the [jobs](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobs)
this workflow should run. While unlikely, you don't want to push tags that reference commits that are older than commits
that have already been pushed or on a branch other than our production branch[^1].

To avoid this, create two jobs `should-we-push` which will determine if the tag that was just created references a newer
commit on the correct branch, and a second job `we-should-push` which will handle pushing the new commits to Platform.sh.
All jobs require a `runs-on`
[property](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on) to
designate the OS of the
[runner](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners),
so for both, you can set them to use `ubuntu-latest`.

```yaml {filename=".github/workflows/push-tags.yml"} theme={null}
jobs:
      should-we-push:
        runs-on: ubuntu-latest
      we-should-push:
        runs-on: ubuntu-latest
```

By default, jobs run concurrently, but in this case, you want the `we-should-push` job to only run if the
`should-we-push` job determines this tag contains new commits.

To build dependency between the jobs, you need to add a `needs` property to the `we-should-push` job, and an `outputs`
property to the `should-we-push` job so that it can pass information to the `we-should-push` job. Set the
`should-we-push` job to output a value named `push` that is set by the `do-push` step—a step that doesn't exist yet, but
don’t worry, we'll create it shortly.

```yaml {filename=".github/workflows/push-tags.yml"} theme={null}
jobs:
      should-we-push:
        runs-on: ubuntu-latest
        outputs:
          push: ${{ steps.do-push.outputs.push }}
      we-should-push:
        runs-on: ubuntu-latest
        needs: should-we-push
```

#### **4. Making sure we need to Push**

Now let's start building out the steps in our `should-we-push` job. By default, your runner's workspace does not contain
the contents of your repository. Before we can evaluate what tags exist, we'll need to checkout our repository into the
workspace on our
[runner](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners).
We can use the [actions/checkout action](https://github.com/actions/checkout) to do this task for us.

However, this action’s default is to only fetch a single commit: the ref/SHA that triggered the workflow. We need the
tag history so we can evaluate if the tag triggering the workflow is from newer commits and on the correct branch. To
alter the behavior of this action, we'll use the `with` property and instruct it to instead checkout all history for
tags. We'll also instruct it to checkout the default (production) branch with the `ref` property. We can retrieve that
branch name with the `github` [context](https://docs.github.com/en/actions/learn-github-actions/contexts#github-context).

```yaml {filename=".github/workflows/push-tags.yml"} theme={null}
jobs:
      should-we-push:
        runs-on: ubuntu-latest
        outputs:
          push: ${{ steps.do-push.outputs.push }}
        steps:
          - uses: actions/checkout@v4
            with:
              fetch-depth: 0
              ref: ${{ github.event.repository.default_branch }}
```

Now that we have our repository checked out into our runner's workspace, we can check to see if the current tag is the
tag nearest to the most recent commit in the production branch. To do that, we'll use the git command
[describe](https://git-scm.com/docs/git-describe). This allows us to ensure we're not pushing a tag that has been added
to an old commit, or on another branch and pushing unnecessary commits over to Platform.sh.

<Note>
  **Note**: to keep the sample code short, I'm `<snip>`ing the code we've already covered. The complete workflow file is
  available at the end of this article.
</Note>

```yaml {filename=".github/workflows/push-tags.yml"} theme={null}
    <snip>
        steps:
          - uses: actions/checkout@v4
            with:
              fetch-depth: 0
              ref: ${{ github.event.repository.default_branch }}
          - id: get-latest-tag
            run: |
              latestTag=$(git describe --abbrev=0 --tags)
              echo "latest_tag=${latestTag}" >> $GITHUB_OUTPUT
```

We'll store that value in the `outputs` object of the
[steps context](https://docs.github.com/en/actions/learn-github-actions/contexts#steps-context) so we can reference it
in the next step. Now we'll create the step that we referenced earlier in the job's `outputs` property. This step will
compare the tag that triggered the workflow with the tag we just retrieved to see if they match. If they do, we'll set
the output value to true so that the `we-should-push` job can determine if it should run.

```yaml {filename=".github/workflows/push-tags.yml"} theme={null}
    steps:
          <snip>
          - id: do-push
            run: |
              push="false"
              if [[ "${{ github.ref_name }}" = "${{ steps.get-latest-tag.outputs.latest_tag }}" ]]; then
                echo "::notice::We have a new tag to push to platform"
                push="true"          
              fi
              echo "push=${push}" >> $GITHUB_OUTPUT
```

This completes the `should-we-push` and now we can move to building out the rest of the `we-should-push` job.

#### **5. Pushing to Platform.sh**

We only want this job to run if the should-we-push job determines the new tag is one we need to push. To set a
conditional on the job, we'll use the `if` property and reference the output we set in the `should-we-push` job:

```yaml {filename=".github/workflows/push-tags.yml"} theme={null}
  we-should-push:
        runs-on: ubuntu-latest
        needs: should-we-push
        if: needs.should-we-push.outputs.push == 'true'
```

Many of the steps in this job will rely on the
[Platform.sh command line interface](https://docs.platform.sh/administration/cli.html) (CLI). For us to use it in an
automated fashion, we'll need to set an environment variable
[PLATFORMSH\_CLI\_TOKEN](https://docs.platform.sh/administration/cli/api-tokens.html) at the job level so it's available
for all steps in the job.

```yaml {filename=".github/workflows/push-tags.yml"} theme={null}
  we-should-push:
        runs-on: ubuntu-latest
        needs: should-we-push
        if: needs.should-we-push.outputs.push == 'true'
        env:
          PLATFORMSH_CLI_TOKEN: ${{ secrets.PSH_TOKEN }}
```

You'll notice that we’re setting the value of this environment variable to the value of the `PSH_TOKEN` in the `secrets`
[context object](https://docs.github.com/en/actions/learn-github-actions/contexts#secrets-context). For this, we're
going to need to:

* [Create a Platform.sh API token](https://docs.upsun.com/administration/cli/api-tokens.html#2-create-an-api-token)
* Add that token as a [repository secret in GitHub](https://docs.github.com/en/codespaces/managing-codespaces-for-your-organization/managing-secrets-for-your-repository-and-organization-for-github-codespaces#adding-secrets-for-a-repository)

For step 1 above, follow
[this documentation](https://docs.upsun.com/administration/cli/api-tokens.html#2-create-an-api-token) from Platform.sh on how to generate an API token. Once you have that value, follow [this documentation](https://docs.github.com/en/codespaces/managing-codespaces-for-your-organization/managing-secrets-for-your-repository-and-organization-for-github-codespaces#adding-secrets-for-a-repository) from GitHub on how to add a repository secret. You can name the secret anything you want; I've named it `PSH_TOKEN` in the sample code above, so make sure to update the name in the workflow if you decide to name it something else.

<img alt="Add GitHub Repo Secret" />

Please note, at a later step in the `we-should-push` job you will need to reference the Platform.sh project ID
associated with this repository.

While you are in the repository secrets area of GitHub, go ahead and add another secret for the project ID. To locate
your project's ID, if you are logged into the Platform.sh
[console](https://console.platform.sh/?_utm_medium=Email&_utm_campaign=2022-09-newsletter&_utm_source=devrelcareers),
you can locate your project's ID under the title of your project, to the right of the project's region when viewing the
project's page in the console, as seen below:

<img alt="Getting the PRoject ID in console" />

Alternatively, from the command line, when in the local copy of your project, you can run the following command:

```bash {filename="Terminal"} theme={null}
❯ platform project:info id
    ropxcgtns2wgy
```

In GitHub, add a repository secret of `PROJID`  and type/paste in your project ID.

Similar to the first step in the `should-we-push` job, we need to check out our repository into the runner workspace, as
seen below:

```yaml {filename=".github/workflows/push-tags.yml"} theme={null}
  we-should-push:
        runs-on: ubuntu-latest
        needs: should-we-push
        env:
          PLATFORMSH_CLI_TOKEN: ${{ secrets.PSH_TOKEN }}
        if: needs.should-we-push.outputs.push == 'true'
        steps:
          - uses: actions/checkout@v4
            with:
              fetch-depth: 0
```

Since `should-we-push` determined we're on the correct branch in the code snippet above, we don't need to include the
`ref` property this time. Now you need to install the Platform.sh CLI.

**Please note**: to keep the sample code below short, we’re `<snip>`ing the code we've already covered. The complete
workflow file is available at the end of this article.

```yaml {filename=".github/workflows/push-tags.yml"} theme={null}
  we-should-push:
        <snip>
        steps:
          - uses: actions/checkout@v4
            with:
              fetch-depth: 0
          - run: |
              echo "setting up the platform.sh cli"
              curl -fsSL https://raw.githubusercontent.com/platformsh/cli/main/installer.sh | bash
```

Next, we need to associate the copy of the repository with a Platform project (referencing the name of the repository
secret we created earlier):

```yaml {filename=".github/workflows/push-tags.yml"} theme={null}
    steps:
          <snip>
          - run: |
              echo "setting up the platform.sh cli"
              curl -fsSL https://raw.githubusercontent.com/platformsh/cli/main/installer.sh | bash
          - run: |
              echo "setting the remote project"
              platform project:set-remote "${{ secrets.PROJID }}"
```

This will add a `platform` remote to our checked-out copy of the repository which includes the Git address for our
mirror of the repository on Platform.sh. However, we won't be able to push until we generate a Secure Shell (SSH)
certificate to authenticate us when we push, so let's add a step to do that:

```yaml {filename=".github/workflows/push-tags.yml"} theme={null}
steps:
        <snip>
          - run: |
              echo "setting the remote project"
              platform project:set-remote "${{ secrets.PROJID }}"
          - run: |
              echo "set up a new ssh cert"
              platform ssh-cert:load --new –no-interaction
```

This command checks if a valid SSH certificate is present, and generates a new one if necessary. Certificates allow you
to make SSH connections without having previously uploaded a public key. As we've never connected to this server
location before from this runner, when we push, the SSH will not recognize the server fingerprint and prompt you to
confirm that you want to continue with connecting
([StrictHostKeyChecking](https://man.openbsd.org/ssh_config#StrictHostKeyChecking)). This will cause your step and job
to fail.

Instead, what you can do is use [ssh-keyscan](https://man.openbsd.org/ssh-keyscan.1)[^2] to retrieve the public SSH hostkey
of our Platform.sh location and add it to our known hosts before we attempt to connect. But before you can do that
you'll need to get the server address.

Since we know it has already been added as a remote Git address, we can retrieve the Platform remote address directly
from Git and then use bash [parameter substitution](https://tldp.org/LDP/abs/html/parameter-substitution.html)[^3] to
retrieve just the server location[^4]. From there we can then pass the server name to ssh-keyscan to retrieve the public
SSH key and add it into our `known_hosts` file:

```yaml {filename=".github/workflows/push-tags.yml"} theme={null}
    steps:
          <snip>
          - run: |
              echo "set up a new ssh cert"
              platform ssh-cert:load --new --no-interaction
          - run: |
              pshWholeGitAddress=$(git remote get-url platform --push)
              pshGitAddress=$(TMP=${pshWholeGitAddress#*@};echo ${TMP%:*})
              echo "Adding psh git address ${pshGitAddress} to known hosts"
              ssh-keyscan -t rsa "${pshGitAddress}" >> ~/.ssh/known_hosts
```

And now we can finally push our changes to Platform.sh. The only thing left before we push is to ensure we're pushing to
the correct production branch name on Platform.sh. Luckily, we can get that information from the Platform.sh CLI. Once
we know that information we can instruct Git to push the tag to that default branch on Platform.sh:

```yaml {filename=".github/workflows/push-tags.yml"} theme={null}
    steps:
        <snip>
          - run: |
              pshWholeGitAddress=$(git remote get-url platform --push)
              pshGitAddress=$(TMP=${pshWholeGitAddress#*@};echo ${TMP%:*})
              echo "Adding psh git address ${pshGitAddress} to known hosts"
              ssh-keyscan -t rsa "${pshGitAddress}" >> ~/.ssh/known_hosts
          - run: |
              echo "Pushing tag ${{ github.ref_name }} to Platform.sh..."
              pshDefaultBranch=$(platform project:info default_branch)
              git push platform refs/tags/${{ github.ref_name }}^{commit}:refs/heads/${pshDefaultBranch}
```

Your workflow file is now ready to commit to your repository and push to GitHub. You'll need to follow whatever workflow
path you use to get the file into your production branch, be it pushing directly, if allowed, or through a pull request
process.

### **All done!**

Now that the workflow file is committed into your production branch, any future tags that are pushed to GitHub, or
created on GitHub when creating a release will trigger the workflow.  If the tag is newer than any other tags (closest
to the current commit), it will trigger our second job, push that tag to Platform.sh, and deploy your new code base. And
just like that, you’ve limited deployment to Platform.sh only when pushing tags!

**Stay tuned for part two of our limit deployment series featuring GitLab coming soon!**

### **Additional resources**

#### **Complete workflow file**

The complete workflow file, as mentioned above, is available
[on GitHub as a gist](https://gist.github.com/platformsh-devrel/c9591a7007f46b380b8cfd183b69b69d).

#### **Bash parameter substitution explanation**

I personally do not like when an article or blog post uses something without an explanation of what is happening or
without linking to a good explanation. While I did include a link to the documentation on parameter substitution, it
might not be immediately obvious what I'm doing with the substitution I used. Since I also believe you should *never*
copy and paste something online without understanding what it does, I wanted to include a fuller explanation so you have
a clear idea of what is occurring.

The value we receive from running `git remote get-url platform --push` is going to look something like this:

```bash {filename="Terminal"} theme={null}
ah242jeyfwteo@git.ca-1.platform.sh:ah242jeyfwteo.git
```

What we need is the value that starts *after* the `@` and ends *before* the `:`. So let's break this down:

```bash {filename="Terminal"} theme={null}
pshWholeGitAddress=$(git remote get-url platform --push)
pshGitAddress=$(TMP=${pshWholeGitAddress#*@};echo ${TMP%:*})
```

We store the value returned from the Git command as `pshWholeGitAddress`. Then in the next line, we run it through
**two** parameter substitutions:

```bash {filename="Terminal"} theme={null}
TMP=${pshWholeGitAddress#*@}
${TMP%:*}
```

The first uses a substitution which we'll remove from our string (contained in the variable `pshWholeGitAddress`), the
part that matches a pattern (`*@`) from the beginning of our string, up to *and including* the pattern (indicated by the
use of the `#` after the variable). So in the case of the string returned from Git, what we match and remove will be
what is highlighted:

```bash {filename="Terminal"} theme={null}
ah242jeyfwteo@git.ca-1.platform.sh:ah242jeyfwteo.git
```

And we're left with `git.ca-1.platform.sh:ah242jeyfwteo.git` which is assigned to the variable `TMP`.  This is good, but
we don't want anything starting at `:` until going to the end of the string. To address this, the next substitution is
going to remove from our string above (stored in the variable `TMP`), the part that matches the pattern `:*` from the
*end of our string* back to and including the pattern itself (indicated by the `%` after the variable). What we match
and remove is highlighted:

```bash {filename="Terminal"} theme={null}
git.ca-1.platform.sh:ah242jeyfwteo.git
```

And what we're left with is `git.ca-1.platform.sh` which is assigned to `pshGitAddress` for us to use with ssh-keyscan.

***

[^1]: We can add a 'branches' filter to the 'push' event but this creates a logical OR between them so any push to the
    branch will trigger the workflow. This means we would still need the 'should-we-push' job to verify the event is one
    where we need to push to Platform.sh. Pushing/creating a tag happens less frequently than pushing to the default branch,
    which is why I've suggested only using the tags filter.

[^2]: We could potential alter the SSH config to set StrictHostKeyChecking to accept-new or do a quick ssh connection
    with '-o StrictHostKeyChecking=accept-new' but using ssh-keyscan with the confirmed address seems more succinct.

[^3]: Bash parameter substitution is just ONE method out of many to retrieve the server address. You could also use sed,
    grep, awk or several other methods.

[^4]: See full explanation at the end of this article [Bash Parameter Substitution Explained](#bash-parameter-explanation)


# Limit deployments to Platform.sh only with tags: part three
Source: https://developer.upsun.com/posts/hands-on/guide-to-limit-deployments-to-platformsh-only-with-tags-part-three



<PostMeta />

In parts [one](/posts/hands-on/guide-to-limit-deployments-to-platformsh-only-with-tags-part-one) and
[two](/posts/hands-on/guide-to-limit-deployments-to-platformsh-only-with-tags-part-two) of this series, we covered how to limit
deployments to Platform.sh when a tag is pushed or created. Focusing first on using GitHub and the GitHub Actions
platform, and then progressing onto Gitlab and pipelines to accomplish this goal. But in the spirit of being a
[polyglot PaaS](https://platform.sh/marketplace/), let’s look at how we can accomplish the same goal—limiting deployment
to Platform.sh only when adding a git tag—using Bitbucket and their CI/CD system.

### **The assumptions**

Just as in the previous articles, for this article and the steps detailed within it, I will assume that you have:

* A Bitbucket account and repository with working code
* Administrative rights on the Bitbucket repository (so you can add [CI/CD variables](https://support.atlassian.com/bitbucket-cloud/docs/variables-and-secrets/))
* A Platform.sh account and a project for your code base with working code
* A default branch in BitBucket which is the same branch as your production branch in Platform.sh
* A default branch in Platform.sh which is also your production branch
* You do *not* have a source code integration created between Platform.sh and BitBucket.

### **The `bitbucket-pipelines.yml` file**

While GitHub has a `.github/workflows` directory where any `*.yaml` file can be a workflow definition, Bitbucket has
[a similar approach to GitLab](https://docs.gitlab.com/ee/ci/#the-gitlab-ciyml-file) and consolidates your
[CI/CD configurations into a single file](https://support.atlassian.com/bitbucket-cloud/docs/bitbucket-pipelines-configuration-reference/)
named `bitbucket-pipelines.yml`. This file must be in the root of your repository, have a .yml extension, and contain
everything needed to run your Bitbucket [pipeline](https://docs.gitlab.com/ee/ci/pipelines/).

<img alt="Bitbucket bitbucket-pipelines.yml pipeline file" />

### **Start your engines!**

Similar to GitHub Events, Bitbucket pipelines are triggered by
[start conditions](https://support.atlassian.com/bitbucket-cloud/docs/pipeline-start-conditions/), which allows you to
control the scenario when a pipeline should be triggered—and lucky for us, one of those conditions is focused on
[start conditions involving tags](https://support.atlassian.com/bitbucket-cloud/docs/pipeline-start-conditions/#Tags).
In the tags property, we can define all tag-specific build pipelines, where the name or expression in this section is
matched against tags in your repository. Glob patterns can also be used for matching tags. Following along with our
previous examples, I'll use a wildcard for all tags[^1].

```yaml {filename="bitbucket-pipelines.yaml"} theme={null}
pipelines:
  tags:
    '*':
```

### **The steps to limiting deployments**

Now that we have our event defined, we need to define our first `step` and despite sharing the same name, it is not at
all like GitHub's `step`. Instead, it is much closer to a `job` in GitHub as each BitBucket `step` in a pipeline will
start a separate Docker container to run the commands configured in the `script` option. Much like GitLab, Bitbucket
will clone your repository into the runner's file system. However, Bitbucket limits the clone to the last 50 commits.
For purposes of this tutorial, I will set the depth to full to ensure we have the commit associated with the tag in this
step.

```yaml {filename="bitbucket-pipelines.yaml"} theme={null}
pipelines:
  tags:
    '*':
      - step:
        clone:
          depth: full
```

Next, we need to define the series of steps we want to perform in this `step`. In Bitbucket, these go under the `script`
property, which is very similar to `steps` in GitHub: each one executes a shell command or script and is executed in
sequential order. The first step we'll execute is to make sure we have all the tags in our repository:

```yaml {filename="bitbucket-pipelines.yaml"} theme={null}
pipelines:
  tags:
    '*':
      - step:
        clone:
          depth: full
        name: Push tag to Platform.sh
        script:
          - git fetch --tags
```

I've also added an optional `name` property to the step to make it more easily identifiable when viewing my pipeline in
Bitbucket's pipelines interface.

Now that we have our repository checked out into our runner's workspace, we can check to see if the tag that triggered
this pipeline is the tag nearest to the most recent commit in the production branch. To do that, we'll use the Git
command [describe](https://git-scm.com/docs/git-describe) and will compare this to the predefined CI/CD variable
`BITBUCKET_TAG` that contains the commit tag name that triggered the pipeline. This allows us to ensure we're not
pushing a tag that has been added to an old commit, or on another branch and pushing unnecessary commits over to
Platform.sh.

<Note>
  **Please note**: to keep the sample code short, I'm `<snip>`ing the code we've already covered. The
  [complete workflow file](https://gist.github.com/platformsh-devrel/9662f8f82c18ec0c2168185f9f8ccd1d) is available at the
  [end of this article](https://platform.sh/blog/guide-to-limit-deployments-to-platformsh-only-with-tags-part-three/#file).
  I've also unindented the lines and reduced the font size for it to fit this page.
</Note>

```yaml {filename="bitbucket-pipelines.yaml"} theme={null}
<snip>
script:
  - git fetch --tags
  - |
    if [ "${BITBUCKET_TAG}" == "$(git describe --abbrev=0 --tags)" ]; then
      echo "We need to push this tag. Setting up the Platform CLI Tool..."
    else
      echo "Not a tag, or not the latest, so nothing to push. Exiting."
    fi
```

Before we can build out the rest of the steps—just like we did with GitHub and GitLab—we'll need to create a couple of
repository variables that we can access in our steps. Make sure you've
[generated a Platform.sh API token](https://docs.upsun.com/administration/cli/api-tokens.html#2-create-an-api-token),
and have the ID of your Platform.sh project handy.

There are two ways you can locate your project's ID. The first is under the title of your project and to the right of
the project's region when viewing the project's page in the Platform.sh
[console](https://console.platform.sh/?_utm_medium=Email&_utm_campaign=2022-09-newsletter&_utm_source=devrelcareers):

<img alt="Locate project id in console" />

Or from the command line, when in the local copy of your project, you can run the following command:

```bash {filename="Terminal"} theme={null}
❯ platform project:info id
    ropxcgtns2wgy
```

From there, follow the
[Bitbucket directions](https://support.atlassian.com/bitbucket-cloud/docs/variables-and-secrets/#Repository-variables)
for adding a repository variable in the UI, adding one for `PLATFORMSH_CLI_TOKEN`[^2] and one for `PROJID`, setting the
values as appropriate.

From here the rest of the steps are almost identical to the steps we used in the GitHub Actions and Gitlab pipelines
articles:

* Set up the Platform.sh CLI tool
* Associate our Project ID with the repository in our runner workspace
* Determine the default branch in our Platform.sh project
* Push the tag to Platform.sh targeting the default branch

```yaml {filename="bitbucket-pipelines.yaml"} theme={null}
- |
  if [ "${BITBUCKET_TAG}" == "$(git describe --abbrev=0 --tags)" ]; then
    echo "We need to push this tag. Setting up the Platform CLI Tool..."
    curl -fsSL https://raw.githubusercontent.com/platformsh/cli/main/installer.sh | bash
    platform project:set-remote "${PROJID}"
    echo "Pushing tag ${BITBUCKET_TAG} to Platform.sh..."
    pshDefaultBranch=$(platform project:info default_branch)
    platform push "refs/tags/${BITBUCKET_TAG}^{commit}" --target "${pshDefaultBranch}"
  else
    echo "Not a tag, or not the latest, so nothing to push. Exiting."
  fi
```

Your `bitbucket-pipelines.yml` file is now ready to commit to your repository and push to Bitbucket. You'll need to
follow whatever workflow path you use to get the file into your production branch, be it pushing directly, if allowed,
or through a pull request process.

### **All set to deploy**

Now that the `bitbucket-pipelines.yml` file is committed into your default branch, any future tags that are pushed to
Bitbucket, or created on Bitbucket when creating a release will trigger the pipeline. If the tag is newer than any other
tags (closest to the current commit), your pipeline will run and push that tag to Platform.sh and deploy your new code
base.

### **Wait a second, something’s different!**

Eagle-eyed readers may have noticed that the specific steps taken during the push to Platform.sh are distinctly
different from what I showed in parts one and two for Github and Gitlab, respectively.  While building out the pipeline
on Bitbucket, I discovered that the version of SSH on the public runner is 6.6.1p1 which is roughly 10 years old. As it
turns out, to use the SSH certificates our CLI supports, it needs version 7.3 of OpenSSH or above. Despite numerous
attempts, I was unable to find a way to easily update the runner to a newer version and use that version between
individual script calls.

While trying to resolve the issue, the amazing [Patrick Dawkins](https://github.com/pjcdawkins), developer and
maintainer of the Platform.sh CLI tool pointed out that the CLI can
[push](https://docs.platform.sh/administration/cli/reference.html#environmentpush) *any* Git reference, commit, or tag
to Platform.sh, not just a specific branch.

Despite using the CLI for over 5 years, I never noticed it would actually accept a source, always assuming it would push
the current commit of the branch you are on which it defaults to doing if no specific source is given. This method has
one big advantage over the methods I showed previously: you don't have to set up the SSH certificates as it will handle
authentication automatically for you via the `PLATFORMSH_CLI_TOKEN` we set up. This means we don't need to determine the
Git address, create the SSH certificates, or add the Platform.sh endpoint to the known\_hosts file, giving us a much
more streamlined process when performing the push.

It’s true that no matter how much you know or how deeply you know something, there's *always* more to learn!

### **Complete `bitbucket-pipelines.yml` file**

The complete Bitbucket pipeline file is [available on GitHub as a gist](https://gist.github.com/platformsh-devrel/9662f8f82c18ec0c2168185f9f8ccd1d).

***

[^1]: Free accounts on bitbucket are limited to 50 build minutes per month. If you regularly create tags that you do not
    want to trigger a push to Platform.sh, I strongly suggest using a pattern to limit how often your pipeline is triggered.

[^2]: You can use a different name for the CI/CD variable but if so, then you will need to add a
    [variables property](https://support.atlassian.com/bitbucket-cloud/docs/variables-and-secrets/#Secured-variables) to the
    job, mapping `PLATFORMSH_CLI_TOKEN` to the name you used.


# Limit deployments to Platform.sh only when Git tagged: part two
Source: https://developer.upsun.com/posts/hands-on/guide-to-limit-deployments-to-platformsh-only-with-tags-part-two



<PostMeta />

In [part one of this series](https://platform.sh/blog/guide-to-limit-deployments-to-platformsh-only-with-tags-part-one/),
we covered how you could limit deployments to Platform.sh only when a tag is pushed/created, focusing primarily on using
GitHub and the GitHub Actions platform to accomplish this goal. But we’re a
[polyglot PaaS](https://platform.sh/marketplace/) and strive to be agnostic in our users’ source code management terms
of the service. With that in mind, let’s look at how we can accomplish the same goal using GitLab and your CI/CD system.

Just like last time, there are some assumptions to consider:

### **The assumptions**

For the purpose of this article and the steps detailed, I will assume that you have:

* A GitLab account and a repository with working code
* Administrative rights on the GitLab repository (so you can add [CI/CD variables](https://docs.gitlab.com/ee/ci/variables/index.html#define-a-cicd-variable-in-the-ui))
* A Platform.sh account and a project for your code base with working code
* A default branch in GitLab which is the same branch as your production branch in Platform.sh
* A default branch in Platform.sh which is also your production branch
* You do *not* have a source code integration created between Platform.sh and GitLab.

### **The `.gitlab-ci.yaml` file**

While GitHub has a `.github/workflows` directory where any `*.yaml` file can be a workflow definition, GitLab
consolidates the [CI/CD configuration into a single file](https://docs.gitlab.com/ee/ci/#the-gitlab-ciyml-file) named
`.gitlab-ci.yml`. This file must be in the root of your repository and contain everything needed to run your GitLab
[pipeline](https://docs.gitlab.com/ee/ci/pipelines/).

<img alt="The .gitlab-ci.yml pipeline file" />

### **The event**

Unlike GitHub workflows, GitLab pipelines are triggered[^1] when *any* commit is pushed to your repository. In our case,
we only want the pipeline to run when a tag is pushed or created. Instead of defining the specific event we want to
trigger our pipeline, we'll build a set of rules to define which type of push should trigger our pipeline. To build
these rules we'll utilize the `workflow` [property](https://docs.gitlab.com/ee/ci/yaml/workflow.html) which controls
when pipelines are run.

```yaml {filename=".gitlab-ci.yml"} theme={null}
workflow:
name: Deploy to Platform.sh on tag
rules:
  - if: $CI_COMMIT_TAG && $CI_PIPELINE_SOURCE == "push"
```

The predefined CI/CD variable `$CI_COMMIT_TAG` contains the commit tag name and, most importantly, is only set in tag
pipelines. The `$CI_PIPELINE_SOURCE` variable contains how the pipeline was triggered. Since we want a tag push, we want
to only run this pipeline if the trigger is a `push` event. I've also added a `name` property so this pipeline is easier
to identify in the repository's pipelines area.

### **The stages**

Like with GitHub, we'll need to define a series of jobs that perform the tasks. And also just like with GitHub, jobs run
in parallel by default. However, unlike GitHub Actions, GitLab gives us a way to control the order in which jobs run
with [stages](https://docs.gitlab.com/ee/ci/yaml/#stages). The stages are executed in order[^2], and later stages can
only start at earlier stages that have been completed.

Before we define our jobs, we'll define the stages that should occur, and then we'll attach jobs[^3] to their relevant
stage.

```yaml {filename=".gitlab-ci.yml"} theme={null}
stages:         
  - setup
  - perform
```

I've defined a `setup` stage, where I'll add the jobs that check to see if the tag that was pushed is one we want to
deploy to Platform.sh, and a `perform` stage where I'll add the jobs to perform the push.

### **Caching**

You might be wondering, "Why is there a section on caching when we just want to see if we need to push, and why is it
before we've defined any jobs?" Unlike GitHub and its
[outputs](https://docs.github.com/en/actions/using-jobs/defining-outputs-for-jobs), GitLab does not provide a
straightforward way to share small bits of data between jobs and stages.  To facilitate data sharing they instead
utilize [artifacts](https://docs.gitlab.com/ee/ci/caching/#artifacts) and
[cache](https://docs.gitlab.com/ee/ci/caching/#cache).

In either case, we have to use a file to store the data we want to share. Since
[job artifacts](https://docs.gitlab.com/ee/ci/jobs/job_artifacts.html) were specifically designed for sharing
intermediate build results between stages, in the case of just needing to pass a small bit of data to the next stage,
it's overkill. Instead, for this pipeline, we'll set up caching and cache a single file to share data between our stages.

Caching needs to be set up on a per-job basis but since we want both stages and their jobs to access the same cache,
we'll define our cache instead in the [default](https://docs.gitlab.com/ee/ci/yaml/#default) area of our pipeline.

```yaml {filename=".gitlab-ci.yml"} theme={null}
default:
  cache: &global_cache
    key: push-to-psh
    paths:
      - "push.txt"
    when: always
```

Here I'm using a [yaml anchor](https://yaml.org/spec/1.2.2/#3222-anchors-and-aliases) ( `&global_cache`) to set up a
reusable cache definition at the global level that I then reference in each job, but with the ability to override any
properties as needed. A cache is required to have a [unique](https://docs.gitlab.com/ee/ci/yaml/index.html#cachekey)
`key`, and jobs that use the same cache key will use the same cache. Perfect for what we need!

We then define the file we want to cache (`push.txt`) using the `paths`
[property](https://docs.gitlab.com/ee/ci/yaml/index.html#cachepaths) and instruct GitLab to `always` save the cache with
`when`.

### **The jobs**

Now I'll define my jobs and attach them to the stage where they should run. To make things easy to read, I'll define the
job in the `setup` stage first and attach it to `setup` using the `stage` property:

```yaml {filename=".gitlab-ci.yml"} theme={null}
should_we_push:
  stage: setup
```

By default, GitLab checks out a
[shallow clone](https://docs.gitlab.com/ee/ci/pipelines/settings.html#limit-the-number-of-changes-fetched-during-clone)
of your repository based on the commit that was pushed. In our case, we want to see if the tag that was pushed is the
closest tag to the latest commit on our default branch so we'll instruct GitLab instead to checkout the default branch.

We can do so by using the `before_script` property. Any steps defined in `before_script` are executed before the job is
started which allows us to alter the default behavior:

```yaml {filename=".gitlab-ci.yml"} theme={null}
should_we_push:
  stage: setup
  before_script:
    - git fetch origin "${CI_DEFAULT_BRANCH}"
    - git fetch --tags
    - git checkout "${CI_DEFAULT_BRANCH}"
```

Now before the `should_we_push` job begins, we'll fetch any changes from GitLab, then fetch all the tags, and finally
checkout the default branch. This is fairly similar to what we accomplished in the GitHub Actions article when we used
the actions/checkout action to checkout our repository using the default branch with a depth of 0. The `script` section
seen below contains the commands we want our runner to execute.

<Note>
  **Note:** to keep the sample code short, I'm `<snip>`ing the code we've already covered. The complete workflow file is
  available at the end of this article.
</Note>

```yaml {filename=".gitlab-ci.yml"} theme={null}
should_we_push:
  stage: setup
  before_script:
    <snip>
  script: |
    pushToPSH="no"
    if [ "${CI_COMMIT_TAG}" == "$(git describe --abbrev=0 --tags)" ]; then
      pushToPSH="yes"
    fi
    
    echo "${pushToPSH}" >> push.txt
```

Now, we check to see if the pushed tag is the most recent from the latest commit in our default branch (`git describe`),
exactly the same as we did in the GitHub workflow. If so, we set the value of `pushToPSH` to `yes` and save that value
in the push.txt that we'll save in our cache.

Last we need to set up the `cache` configuration for the job:

```yaml {filename=".gitlab-ci.yml"} theme={null}
should_we_push:
  stage: setup
  before_script:
    <snip>
  script: |
    <snip>
  cache:
    <<: *global_cache
    policy: push
```

Here I'm referencing the YAML block I set up earlier for cache ( `*global_cache`) which tells the YAML parser to grab
that named section and reuse it. The `<<:` informs the YAML parser that I'm going to add value or override existing ones
to the section.

Since we never want this job to reuse the cache from a previous run, I'll override the
[default](https://docs.gitlab.com/ee/ci/yaml/index.html#cachepolicy) `policy` of `pull-push` to only `push` for this job
(i.e. only upload a cache when the job is complete, never download cache when the job starts).

I'll next define our second job and attach it to the perform stage:

```yaml {filename=".gitlab-ci.yml"} theme={null}
we_should_push:
  stage: perform
```

Since this job will utilize the data stored in the cache, it’s time to go ahead and set up the cache configuration[^4]:

```yaml {filename=".gitlab-ci.yml"} theme={null}
we_should_push:
  stage: perform
  cache:
    <<: *global_cache
    policy: pull
```

Similar to the `should_we_push` job, I'm reusing the cache configuration I created in the default section
(`*global_cache`), but this time I'm changing the policy to `pull`. This ensures the cache will always be downloaded
before the job begins, but never uploads the cache when the job completes.

Before we can build out the rest of the steps, just like we did with GitHub, we'll need to create a couple of repository
variables that we can access in our steps. Make sure you've
[generated a Platform.sh API token](https://docs.upsun.com/administration/cli/api-tokens.html#2-create-an-api-token),
and have the Platform.sh ID of your project.

To locate your project's ID, if you are logged into the
[console](https://console.platform.sh/?_utm_medium=Email&_utm_campaign=2022-09-newsletter&_utm_source=devrelcareers),
you can locate your project's ID under the title of your project, to the right of the project's region when viewing the
project's page:

<img alt="Locate project id in console" />

Or to locate your project’s ID from the command line, when in the local copy of your project, you can run the following
command:

```bash {filename="Terminal"} theme={null}
❯ platform project:info id
ropxcgtns2wgy
```

From there, follow the
[GitLab directions](https://docs.gitlab.com/ee/ci/variables/index.html#define-a-cicd-variable-in-the-ui) for adding a
CI/CD variable in the UI, adding one for `PLATFORM_CLI_TOKEN`[^5] and one for `PROJID`, setting the values as appropriate.

<img alt="Add CICD variable to GitLab repository" />

<Note>
  **Note:** [Take a look at the GitLab CI/CD documentation for more information](https://docs.gitlab.com/ee/ci/variables/index.html)
</Note>

And finally, we’ve arrived at the steps for pushing our new code to Platform.sh—if the `should_we_push` job determined
this was a tag we want to deploy to Platform.sh, that is.

```yaml {filename=".gitlab-ci.yml"} theme={null}
we_should_push:
  <snip>
  script: |
    if [ $(cat push.txt | grep yes) ]; then
      echo "setting up the platform.sh cli"
      curl -fsSL https://raw.githubusercontent.com/platformsh/cli/main/installer.sh | bash
      platform project:set-remote "${PROJID}"
      echo "set up a new ssh cert"
      platform ssh-cert:load --new --no-interaction
      pshWholeGitAddress=$(git remote get-url platform --push)
      pshGitAddress=$(TMP=${pshWholeGitAddress#*@};echo ${TMP%:*})
      echo "Adding psh git address ${pshGitAddress} to known hosts"
      ssh-keyscan -t rsa "${pshGitAddress}" >> ~/.ssh/known_hosts
      echo "Pushing tag ${CI_COMMIT_TAG} to Platform.sh..."
      pshDefaultBranch=$(platform project:info default_branch)
      git push platform "refs/tags/${CI_COMMIT_TAG}^{commit}:refs/heads/${pshDefaultBranch}"
    else
      echo "no changes to push. exiting"
    fi
```

Beyond checking to make sure "`yes`" is contained in our cached `push.txt` file, the rest of the steps are identical to
the steps we used in the GitHub Actions article for the `we_should_push` job.

Your `.gitlab-ci.yml` file is now ready to commit to your repository and push it to GitLab. You'll need to follow
whatever workflow path you use to get the file into your production branch, be it pushing directly, if allowed, or
through a pull request process.

### **You’re all set**

Now that the `.gitlab-ci.yml` file is committed into your default branch, any future tags that are pushed to GitLab, or
created on GitLab when creating a release will trigger the pipeline.  If the tag is newer than any other tags (closest
to the current commit), our `we_shou` job will run and push that tag to Platform.sh and deploy your new code base!

[Take a look at the complete GitLab pipeline file](https://gist.github.com/platformsh-devrel/1ee70770c045cbbfe1f11f373e863871).

***

[^1]: They can also be triggered by other pipelines, an API call, on a schedule, etc.

[^2]: Jobs within stages are still executed in parallel.

[^3]: Jobs that are in the same stage then run in parallel.

[^4]: The order of where you define the cache strategy is irrelevant as long as it is a property of the job.

[^5]: You can use a different name for the CI/CD variable but if so, then you will need to add a
    [variables property](https://docs.gitlab.com/ee/ci/yaml/#variables) to the job, mapping `PLATFORMSH_CLI_TOKEN` to the
    name you used.


# Harnessing the power of Embeddings: a real-world example of a watch recommendation app using a vector database.
Source: https://developer.upsun.com/posts/hands-on/harnessing-power-embeddings

Learn how to build a real-world watch recommendation application using embeddings and a vector database. This tutorial covers using Postgres with pgvector, Laravel, React, OpenAI, and Groq, deployed on Upsun.


<PostMeta />

Given the increasing integration of Machine Learning and AI/LLM models in all applications, it is crucial to explore the potential of a robust cloud application platform like [Upsun](https://upsun.com) for conducting these experiments.

As a watch enthusiast, what would be better than a recommendation engine to find the right watch for you? Here is the app we are going to build from scratch here:

<img alt="Watch Recommendation App" />

### Source

You can find the full example repository on Github: [https://github.com/gmoigneu/upsun-embeddings-watches](https://github.com/gmoigneu/upsun-embeddings-watches)

### Architecture

Let's review the architecture we are going to create and deploy:

<img alt="Watch Recommendation Architecture" />

Our application will be composed of 3 main components:

* A static React frontend is used to present the UI to the user.
* An API built with Laravel 11 will handle the search requests and populate our database.
* A Postgres instance to store our watches records and vectors for the embeddings of our content.

For speed and cost efficiency reasons, we will leverage both OpenAI for creating embeddings and Groq for the LLM part. We will use `llama3–8b-8192` as a model on Groq, but `mixtral` or any other would also work.

## Bootstrapping our apps

You will need `php8.x` and `composer` installed locally for this to work. As we deploy our app on Upsun, you can grab the upsun cli by following the steps [here](https://docs.upsun.com/administration/cli.html#1-install).

First, create a new folder for your project:

```bash {filename="Terminal"} theme={null}
mkdir watches && cd watches
```

Let's start by installing Laravel 11 with the API components:

```bash {filename="Terminal"} theme={null}
composer create-project laravel/laravel watches
cd watches
php artisan api:install
```

You will need a few extra packages:

```bash {filename="Terminal"} theme={null}
# required 
composer require openai-php/client
composer require pgvector/pgvector

# optional
composer require laravel/telescope # for debugging requests
composer require spatie/laravel-ray # amazing little debugging helper
```

Let's now create a new React app. We are using Vite here with the `react-ts` template but feel free to use any other variant. We will set up `shacdn/ui` for the UI to speed up building our interface.

```bash {filename="Terminal"} theme={null}
cd ..
npm create vite@latest frontend -- --template react-ts
cd frontend

# Install shacdn/ui
npm create vite@latest
npm install -D tailwindcss postcss autoprefixer

npx tailwindcss init -p

# (so you can import "path" without error)
npm i -D @types/node
```

Add the following code to the `tsconfig.json` file to resolve paths:

```json {filename="tsconfig.json"} theme={null}
{
  "compilerOptions": {
    // ...
    "baseUrl": ".",
    "paths": {
      "@/*": [
        "./src/*"
      ]
    }
    // ...
  }
}
```

Add the following code to the `vite.config.ts` so your app can resolve paths without error

```typescript {filename="vite.config.ts"} theme={null}
// vite.config.ts

import path from "path"
import react from "@vitejs/plugin-react"
import { defineConfig } from "vite"

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "./src"),
    },
  },
})
```

Now run the `shacdn` init with the following settings:

```bash {filename="Terminal"} theme={null}
npx shadcn-ui@latest init

Would you like to use TypeScript (recommended)? yes
Which style would you like to use? › Default
Which color would you like to use as base color? › Slate
Where is your global CSS file? › › src/index.css
Do you want to use CSS variables for colors? › yes
Where is your tailwind.config.js located? › tailwind.config.js
Configure the import alias for components: › @/components
Configure the import alias for utils: › @/lib/utils
Are you using React Server Components? › no (no)
```

Add the needed components for our UI:

```bash {filename="Terminal"} theme={null}
npx shadcn-ui@latest add button
npx shadcn-ui@latest add textarea
```

Our React app will use two extra packages:

```bash {filename="Terminal"} theme={null}
npm i @microsoft/fetch-event-source # AJAX requests with EventStream support
npm i axios # for making API requests
```

Our two apps are now bootstrapped. Time to initialize our git repo:

```bash {filename="Terminal"} theme={null}
cd ..
git init .
git add watches 
git commit -m "Add Laravel API to the repo"

git add frontend 
git commit -m "Add React frontend to the repo"
```

## Setting up our local development environment & infrastructure

While you could use [Laravel Sail](https://laravel.com/docs/11.x/sail) or any other Docker-based local setup to develop the project, I find relying on the [Upsun tethering feature](https://docs.upsun.com/get-started/here/local/tethered.html) always way quicker. It maps the remote services (database, Redis, etc.) to local ports, so you only need to run the runtimes (PHP, JS, …) locally.

To do that, we first need to go through the Upsun configuration. While you can use the `upsun ify` CLI command to generate an automatic configuration, here is the complete configuration explained. Create a new `.upsun/config.yaml` and paste the following:

```yaml {filename=".upsun/config.yaml"} theme={null}
# Routing for the frontend and API
routes:
  "https://frontend.{all}/": { type: upstream, upstream: "frontend:http" }
  "https://api.{all}/": { type: upstream, upstream: "app:http" }
  "http://{all}/": { type: redirect, to: "https://frontend.{all}/" }

services: 
  database:
    type: postgresql:15 # We will use Postgres with the vector extension
    configuration:
      extensions:
        - vector
  redis: # Redis is used for the Laravel cache
    type: redis:7.0
 
applications:
  # Our react frontend
  frontend:
    source:
      root: "frontend" # folder where the app is
    type: nodejs:20
    build:
      flavor: none
    web:
      locations:
        "/":
          root: "dist" # Customize if your build outputs the app somewhere else
          expires: 1h
          passthru: "/index.html"
      commands:
        start: sleep infinity # needed as we serve static files

    hooks: # customize if you use another build tool
      build: |
        set -x -e
        npm install 
        npm run build
  app:
    source:
      root: "watches"

    type: php:8.3

    dependencies:
      php:
        composer/composer: "^2"

    runtime:
      extensions:
        - apcu
        - redis
        - blackfire
        - ctype
        - iconv
        - mbstring
        - pdo_pgsql
        - pdo_pgsql
        - sodium
        - xsl
    build:
      flavor: none
    web:
      locations:
        "/":
          root: "public"
          expires: 1h
          passthru: "/index.php"
    mounts: # Where Laravel needs write access
      "/.config":
        source: "storage"
        source_path: "config"
        
      "bootstrap/cache":
        source: "storage"
        source_path: "cache"
        
      "storage":
        source: "storage"
        source_path: "storage"
    relationships:
      # link our services
      database: "database:postgresql"
      redis: "redis:redis"
    hooks:
      build: |
        set -eux
        composer --no-ansi --no-interaction install --no-progress --prefer-dist --optimize-autoloader --no-dev
      deploy: |
        # customize if needed but should be ok for Laravel
        set -eux
        mkdir -p storage/framework/sessions
        mkdir -p storage/framework/cache
        mkdir -p storage/framework/views
        php artisan migrate --force
        php artisan optimize:clear
```

Once done, we must inject some variables into our Laravel app to grab the proper credentials. Create the `watches/.environment` file with the following:

```bash {filename="watches/.environment"} theme={null}
# Set database environment variables
export DB_HOST="$DATABASE_HOST"
export DB_PORT="$DATABASE_PORT"
export DB_PATH="$DATABASE_PATH"
export DB_USERNAME="$DATABASE_USERNAME"
export DB_PASSWORD="$DATABASE_PASSWORD"
export DB_SCHEME="postgresql"
export DATABASE_URL="${DB_SCHEME}://${DB_USERNAME}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT}/${DB_PATH}"

# Set Laravel-specific environment variables
export DB_CONNECTION="pgsql"
export DB_DATABASE="$DB_PATH"

# Set Cache environment variables
export CACHE_STORE="redis"
export CACHE_HOST="$REDIS_HOST"
export CACHE_PORT="$REDIS_PORT"
export CACHE_SCHEME="$REDIS_SCHEME"
export CACHE_URL="${CACHE_SCHEME}://${CACHE_HOST}:${CACHE_PORT}"

# Set Redis environment variables
export REDIS_URL="$CACHE_URL"
```

You can customize any other environment variable this way. Remember they will always be the same value as this is committed to our repo.

Let's add the configuration to our git repo:

```bash {filename="Terminal"} theme={null}
git add .upsun
git add .environment
git commit -m "Add Upsun configuration"
```

## Our first deploy

Let's create an Upsun project for our application:

```bash {filename="Terminal"} theme={null}
upsun project:create

* Project title (--title)
Default: Untitled Project
> Watch finder

* Region (--region)
The region where the project will be hosted.
Get a 3% discount on resources for regions with a carbon intensity of less than 100 gCO2eq/kWh.
  [au.platform.sh  ] Sydney, Australia (AWS)  [545 gC02eq/kWh]
  [au-2.platform.sh] Sydney, Australia (AZURE)  [545 gC02eq/kWh]
  [ca-1.platform.sh] Montreal, Canada (AWS)  [31 gC02eq/kWh]
  [ch-1.platform.sh] Zurich, Switzerland (GCP)  [91 gC02eq/kWh]
  [de-2.platform.sh] Frankfurt, Germany (GCP)  [416 gC02eq/kWh]
  [eu.platform.sh  ] Dublin, Ireland (AWS)  [386 gC02eq/kWh]
  [eu-2.platform.sh] Dublin, Ireland (AWS)  [386 gC02eq/kWh]
  [eu-4.platform.sh] Dublin, Ireland (AWS)  [386 gC02eq/kWh]
  [eu-5.platform.sh] Stockholm, Sweden (AWS)  [23 gC02eq/kWh]
  [fr-3.platform.sh] Gravelines, France (OVH)  [59 gC02eq/kWh]
  [fr-4.platform.sh] Paris, France (AZURE)  [59 gC02eq/kWh]
  [uk-1.platform.sh] London, United Kingdom (GCP)  [200 gC02eq/kWh]
  [us.platform.sh  ] Washington, United States (AWS)  [396 gC02eq/kWh]
  [us-2.platform.sh] Washington, United States (AWS)  [396 gC02eq/kWh]
  [us-3.platform.sh] Moses Lake, United States (AZURE)  [56 gC02eq/kWh]
  [us-4.platform.sh] Charleston, United States (GCP)  [647 gC02eq/kWh]
> us-3.platform.sh

Default branch (--default-branch)
The default Git branch name for the project (the production environment)
Default: main
>

Are you sure you want to continue? [Y/n]
```

The Upsun bot will then provide an empty project for you and set the remote in your local git repository. Once done, you are ready to deploy:

```bash {filename="Terminal"} theme={null}
upsun push
```

The pipeline will build and deploy both apps. After a couple of minutes, the boilerplate apps will be available on:
`https://frontend.<branch>.<project>.<region>.platformsh.site`
`https://app.<branch>.<project>.<region>.platformsh.site`

You should be directed to the default pages for both the React and Laravel applications.

We can now connect to our remote database and cache services:

```bash {filename="Terminal"} theme={null}
upsun tunnel:open
Enter a number to choose an app:
  [0] app
  [1] frontend
 > 0

Are you sure you want to open SSH tunnel(s) to the environment main (type: production)? [Y/n]

SSH tunnel opened to database at: pgsql://main:main@127.0.0.1:30000/main
SSH tunnel opened to redis at: redis://127.0.0.1:30001
```

You can now edit your local `watches/.env` to use these services:

```ini {filename="watches/.env"} theme={null}
DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=3000
DB_DATABASE=main
DB_USERNAME=main
DB_PASSWORD=main

SESSION_DRIVER=redis
SESSION_LIFETIME=120
SESSION_ENCRYPT=false
SESSION_PATH=/
SESSION_DOMAIN=null

BROADCAST_CONNECTION=redis
FILESYSTEM_DISK=local
QUEUE_CONNECTION=redis

CACHE_STORE=redis
CACHE_PREFIX=

REDIS_CLIENT=phpredis
REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=30001
```

You will need your local PHP runtime to have the `phpredis` extension loaded. Please refer to the following [documentation on the Laravel site](https://laravel.com/docs/11.x/redis#phpredis).

If you want to use test hostnames for your applications, edit `/etc/hosts` or your Windows host file with the following or any other names you like:
`127.0.0.1 watches.test frontend.watches.test api.watches.test`

If so, update the `.env` file with the proper hostname:

```ini {filename="watches/.env"} theme={null}
APP_URL=http://api.watches.test
```

We can now launch our development services. In two terminals, run:

```bash {filename="Terminal"} theme={null}
php artisan serve
```

```bash {filename="Terminal"} theme={null}
npm run dev -- --host=frontend.watches.test
```

Note the `--` for the argument to be able to run. Your local applications are now available at `http://frontend.watches.test:5137` and `http://api.watches.test`.

## Getting some data about watches

As we will recommend a specific watch to our user, we must first have a database containing the potential results. Fortunately, Kaggle has a Luxury Watch Dataset (no longer available. Check [https://www.kaggle.com/kashnitsky/datasets/](https://www.kaggle.com/kashnitsky/datasets/) for other public data sets) available for download. Create an account if needed and download the CSV file.

<img alt="Kaggle dataset" />

We will now move and rename the CSV file into our project:

```bash {filename="Terminal"} theme={null}
mkdir watches/seeds/
mv ~/Downloads/Luxury\ watch.csv ./seeds/watches-full.csv
```

## Configuring our external services

For us to use [OpenAI](https://platform.openai.com/api-keys) and [Groq](https://console.groq.com/keys) APIs, we need to inject our credentials. Create new API keys from their respective websites.

In Laravel, we will add the respective arrays in the services configuration:

```php {filename="config/services.php"} theme={null}
<?php

return [

  'openai' => [
    'key' => env('OPENAI_API_KEY'),
  ],

  'groq' => [
    'key'=> env('GROQ_API_KEY'),
  ],
```

Once done, add the variables to your local `.env` file:

```ini {filename="watches/.env"} theme={null}
APP_URL=http://api.watches.test
[...]
OPENAI_API_KEY=sk-proj-**************
GROQ_API_KEY=gsk_**************
```

For them to work on Upsun, create two variables using the cli :

```bash {filename="Terminal"} theme={null}
upsun variable:create --name GROQ_API_KEY -l project --sensitive=true --prefix=env: --value=gsk_xxxxxxxxxxxxxx
upsun variable:create --name OPENAI_API_KEY -l project --sensitive=true --prefix=env: --value=sk-proj-xxxxxxxxxxxxxx
```

## Let's import our watches into the database

We will need a few things first. Create a Watch model. You can create it using `php artisan make:model Watch --m` or by adding the files manually:

```php {filename="watches/app/Models/Watch.php"} theme={null}
<?php 

namespace App\Models;

use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;
use Pgvector\Laravel\HasNeighbors;
use Pgvector\Laravel\Vector;

class Watch extends Model
{
    use HasFactory, HasNeighbors;

    protected $casts = ['embedding' => Vector::class];

    protected $fillable = [
        'brand',
        'model',
        'case_material',
        'strap_material',
        'movement_type',
        'water_resistance',
        'case_diameter_mm',
        'case_thickness_mm',
        'band_width_mm',
        'dial_color',
        'crystal_material',
        'complications',
        'power_reserve',
        'price_usd',
    ];
}
```

Note in the model that we use our `Vector` custom type to store and cast the embedding column. Create the migration file for the model:

```bash {filename="Terminal"} theme={null}
php artisan make migration create_watches_table
```

```php {filename="database/migrations/xxxx_xx_xx_xxxxxx_create_watches_table.php"} theme={null}
<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    /**
     * Run the migrations.
     */
    public function up(): void
    {
        Schema::create('watches', function (Blueprint $table) {
            $table->id();
            $table->string('brand');
            $table->string('model');
            $table->string('case_material')->nullable();
            $table->string('strap_material')->nullable();
            $table->string('movement_type')->nullable();
            $table->string('water_resistance')->nullable();
            $table->decimal('case_diameter_mm', 5, 2)->nullable();
            $table->decimal('case_thickness_mm', 5, 2)->nullable();
            $table->decimal('band_width_mm', 5, 2)->nullable();
            $table->string('dial_color')->nullable();
            $table->string('crystal_material')->nullable();
            $table->string('complications')->nullable();
            $table->string('power_reserve')->nullable();
            $table->integer('price_usd')->nullable();
            $table->vector('embedding', 1536)->nullable();
            $table->timestamps();
        });
    }

    /**
     * Reverse the migrations.
     */
    public function down(): void
    {
        Schema::dropIfExists('watches');
    }
};
```

Our `embedding` columns will use the vector type from the `pg_vector` package.

Migrate the database:

```bash {filename="Terminal"} theme={null}
php artisan migrate
```

We now need to code a job that will import the watches and generate the embedding. Create the command and the job:

```bash {filename="Terminal"} theme={null}
php artisan make:command Vectorize
php artisan make:job Vectorize
```

Our command is simple and only triggers the job:

```php {filename="watches/app/Console/Commands/Vectorize.php"} theme={null}
<?php 

namespace App\Console\Commands;

use Illuminate\Console\Command;

class Vectorize extends Command
{
    /**
     * The name and signature of the console command.
     *
     * @var string
     */
    protected $signature = 'app:vectorize';

    /**
     * The console command description.
     *
     * @var string
     */
    protected $description = 'Vectorize the CSV file and stores it into the database.';

    /**
     * Execute the console command.
     */
    public function handle()
    {
        \App\Jobs\Vectorize::dispatchSync();
    }
}
```

Our `Vectorize` job is more complex. It will:

* Parse the CSV and create the watches in the database
* Combine all attributes of each watch into a text string that we will send to OpenAI to get an embedding
* Store that embedding in our database as a vector

```php {filename="watches/app/Jobs/Vectorize.php"} theme={null}
<?php

namespace App\Jobs;

use App\Models\Watch;
use DB;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;
use OpenAI;
use Pgvector\Laravel\Vector;

class Vectorize implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    /**
     * Create a new job instance.
     */
    public function __construct()
    {
        //
    }

    /**
     * Execute the job.
     */
    public function handle(): void
    {
        // Empty DB
        DB::table('watches')->truncate();

        $client = OpenAI::client(config('services.openai.key'));

        // Parse the CSV and get the headers
        $file = base_path("seeds/watches-full.csv");
        $csv = array_map("str_getcsv", file($file));
        $header = array_shift($csv);

        // Transform the rows into an array with the header and the row
        $watches = array_map(fn($row) => array_combine($header, $row), $csv);

        // Loop the CSV and create the watches in database
        foreach($csv as $row) {
            try{
                Watch::create([
                    'brand' => $row[0],
                    'model' => $row[1],
                    'case_material' => $row[2],
                    'strap_material' => $row[3],
                    'movement_type' => $row[4],
                    'water_resistance' => $row[5],
                    'case_diameter_mm' => $row[6],
                    'case_thickness_mm' => $row[7],
                    'band_width_mm' => $row[8],
                    'dial_color' => $row[9],
                    'crystal_material' => $row[10],
                    'complications' => $row[11],
                    'power_reserve' => $row[12],
                    'price_usd' => preg_replace("/[^0-9.]/", "", $row[13]),
                ]);
            } catch(\Exception $e){
                ray($row);
            }
        }

        // Create a text version of the watch row that will list the 
        // attributes and their values as a large string
        $watchesInput = collect($watches)->map(function ($watch) {
            $str = '';
            foreach($watch as $key=>$item) {
                $str .= $key.':'.$item.',';
            }
            return rtrim($str, '|');
        });

        // Send the text version of all watches to the OpenAI embedding 
        // endpoint. We do a batch query to avoid sending 500 different API calls
        $response = $client->embeddings()->create([
            'model' => 'text-embedding-3-small',
            'input' => $watchesInput->toArray()
        ]);

        // Loop through the embeddings sent and update our watches
        // in the database with the matching embedding
        foreach ($response->embeddings as $embedding) {
            $watch = Watch::find($embedding->index + 1);
            $watch->embedding = new Vector($embedding->embedding);
            $watch->save();
        }
    }
}
```

You can now run the job by triggering:

```bash {filename="Terminal"} theme={null}
php artisan app:vectorize
```

It should take a few seconds. Once done you can connect to your Postgres instance and check the results:

```bash {filename="Terminal"} theme={null}
upsun sql
Enter a number to choose an app:
  [0] app
  [1] frontend
 > 0
```

```sql {filename="psql"} theme={null}
psql (16.2 (Debian 16.2-1.pgdg120+2), server 15.6 (Debian 15.6-1.pgdg110+2))
Type "help" for help.

main=> SELECT brand, model FROM watches;

    brand        |          model
---------------------+--------------------------
 Omega               | Seamaster
 Tag Heuer           | Carrera
 Breitling           | Navitimer

[...]
```

Perfect, we have our database of 508 watches and the embeddings created from their content.

## Create the API controller to get the search request

Let's create the API controller for our frontend to query the database. The controller will take care of:

* Parsing and validating the query value sent through the POST request
* Creating an embedding of the query
* Query the database using `nearestNeighbors` to find the most relevant watch
* Send a streamed request to the Grok Chat API to create a proper answer with the details of the watch and the reason why it is the best.

As the response is streamed from Grok, we automatically stream it to our client using an Event Stream. This will allow us to display the answer being generated in real-time instead of waiting for the full answer being processes.

```php {filename="watches/app/Http/Controllers/WatchController.php"} theme={null}
<?php 

namespace App\Http\Controllers;

use App\Helpers\MarkdownHelper;
use App\Http\Requests\SearchWatchRequest;
use App\Models\Watch;
use OpenAI;
use Pgvector\Laravel\Distance;
use Pgvector\Laravel\Vector;

class WatchController extends Controller
{
    public function search(SearchWatchRequest $request)
    {
        $embeddingClient = OpenAI::client(config('services.openai.key'));
        $chatClient = OpenAI::factory()
            ->withApiKey(config('services.groq.key'))
            ->withBaseUri('api.groq.com/openai/v1') // default: api.openai.com/v1
            ->make();

        // Create the embedding of the query
        $response = $embeddingClient->embeddings()->create([
            'model' => 'text-embedding-3-small',
            'input' => $request->input('query')
        ]);

        $embedding = new Vector($response->embeddings[0]->embedding);

        // Find the closest watch
        $neighbor = Watch::query()->nearestNeighbors('embedding', $embedding, Distance::L2)->first();

        // Ask OpenAI for the closest watches
        $stream = $chatClient->chat()->createStreamed([
            'model' => 'llama3-8b-8192',
            'messages' => [
                [
                    'role' => 'system',
                    'content' => "You are an helpful AI that will recommend watches to the user. The watch selected is below with its attributes as a list. Your response is a markdown document.First, output the brand and model of the watch as a title.  Second, send the user a bullet list view of the watch attributes without doing any modification. Then, add a paragrah of why this watch matches their request using the watch attributes."
                ],
                [
                    'role' => 'user',
                    'content' => "The recommended watch is: " . MarkdownHelper::toMarkdown($neighbor)
                ],
                ['role' => 'user', 'content' => $request->input('query')],
            ],
        ]);

        return response()->stream(function () use ($stream) {
            $i = 0;
            $text = "";

            foreach($stream as $response){
                $text .= $response->choices[0]->delta->content;

                $i++;

                echo "event: chunk\n";
                echo "data: {\"index\": " . $i . ", \"chunk\": " . json_encode($response->choices[0]->delta->content) . "}\n\n";

                ob_flush();
                flush();

                // Break the loop if the client aborted the connection (closed the page)
                if (connection_aborted()) {
                    break;
                }
            }
        }, 200, [
            'Cache-Control' => 'no-cache',
            'X-Accel-Buffering' => 'no',
            'Content-Type' => 'text/event-stream',
        ]);
    }
}
```

As you can see, we are validating the POST request via the `SearchWatchRequest` validator. Remember to return `true` in the `authorize()` method, or you will get a 403 when POSTing to it.

```php {filename="watches/app/Http/Requests/SearchWatchRequest.php"} theme={null}
<?php 

namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;

class SearchWatchRequest extends FormRequest
{
    /**
     * Determine if the user is authorized to make this request.
     */
    public function authorize(): bool
    {
        return true;
    }

    /**
     * Get the validation rules that apply to the request.
     *
     * @return array<string, \Illuminate\Contracts\Validation\ValidationRule|array<mixed>|string>
     */
    public function rules(): array
    {
        return [
            'query' => 'required|string',
        ];
    }
}
```

In a production application, you must also validate that the user exists and is not abusing the system. You can leverage [Laravel Sanctum](https://laravel.com/docs/11.x/sanctum) for this.

## Wrap up the Laravel configuration

Two tasks need to be done before our Laravel is fully operational. First, create a new route to handle the request:

```php {filename="watches/routes/api.php"} theme={null}
<?php 

use Illuminate\Support\Facades\Route;

Route::post('/watch', [App\Http\Controllers\WatchController::class, 'search']);
```

Then, as we will query our API through a React frontend, we need to make CORS will be correctly set. Publish the CORS configuration file with:

```bash {filename="Terminal"} theme={null}
php artisan config:publish cors
```

Open `cors.php` and review the settings:

```php {filename="watches/config/cors.php"} theme={null}
<?php 

return [
    'paths' => ['api/', 'api/watch'],
    'allowed_methods' => ['*'],
    'allowed_origins' => ['*'],
    'allowed_origins_patterns' => ['*'],
    'allowed_headers' => ['*'],
    'exposed_headers' => [],
    'max_age' => 0,
    'supports_credentials' => true,
];
```

## Let's test our API!

You can now use `curl` or a tool like Postman to query the API and get your result. As you can see, the result is streamed in chunks by our Laravel API. Congratulations!

<img alt="API Test with Postman" />

## Let's deploy it!

Add the vectorize job in `.upsun/config.yaml` so it is done every time in the background after you deploy the app without impacting the app availability. You might want to trigger this manually if you have more data to avoid increasing your OpenAI bill too much.

```yaml {filename=".upsun/config.yaml"} theme={null}
app:
    source:
      root: "watches"
    [...]
    hooks:
      build: |
        [...]
      deploy: |
        [...]
      post_deploy: |
        set -eux
        php artisan app:vectorize
```

```bash {filename="Terminal"} theme={null}
git add .
git commit -m "Working API"
upsun push
```

The deploy log will output the URLs for both endpoint. You can now retest the API with Postman on the Upsun API hostname.

## Time to build our frontend

Let's switch to our frontend React app now.

```bash {filename="Terminal"} theme={null}
cd ../frontend
```

As our UI will be really straightforward, we only need two basic `shacdn/ui` components:

```bash {filename="Terminal"} theme={null}
npx shadcn-ui@latest add button
npx shadcn-ui@latest add textarea
```

The components are now installed in `src/components/ui`.

We will use two different libraries to query our APIs:

* `axios` would be used to query other potential endpoints of our Laravel API
* `@microsoft/fetch-event-source` to stream the result from our API

Let's install both:

```bash {filename="Terminal"} theme={null}
npm i axios
npm i @microsoft/fetch-event-source

# We also use markdown to format the output so let's install it
npm i react-markdown
```

We are now creating a shared axios instance for our project with the configuration and a method to define our API URL:

```typescript {filename="src/lib/axios.ts"} theme={null}
/* src/lib/axios.ts */
import Axios from 'axios'

export const getApiURL = () => {
    if(window.location.hostname === 'watches.test') {
        return('http://api.watches.test')
    } else {
        return window.location.origin.replace('frontend', 'api')
    }
}

const entrypoint = getApiURL()

const axios = Axios.create({
    baseURL: entrypoint,
    headers: {
        'X-Requested-With': 'XMLHttpRequest',
        'Content-Type': 'application/json',
    },
})
export default axios
```

`getApiURL` will use our local development values if the hostname is `watches.test`. If not, it will replace the `frontend` string with `api` on any other hostname. This will allow us to make it functional in any preview environment on Upsun as well as production. You can always change the logic there to map your own deployment needs.

### The main App.tsx

It's time to build that frontend application layout and logic:

```typescript {filename="src/App.tsx"} theme={null}
/* src/App.tsx */

import { useState } from 'react'
import './App.css'
import { Button } from './components/ui/button'
import { Textarea } from './components/ui/textarea'
import './index.css'
import Markdown from 'react-markdown'
import { fetchEventSource } from '@microsoft/fetch-event-source'
import { getApiURL } from './lib/axios'
function App() {

  const [prompt, setPrompt] = useState('')
  const [answer, setAnswer] = useState('Try queries like: "affordave dive watch", "dress watch with a black dial", "more affordable alternative to a Rolex submariner", ...')
  const [isStreaming, setIsStreaming] = useState(false)

  const submitForm = () => {
    newStreamResponse(prompt)
  }

  const newStreamResponse = async (prompt :string) => {
        const ctrl = new AbortController()
        setAnswer('')

        let messageContent = ''
        setIsStreaming(true)

        await fetchEventSource(`${getApiURL()}/api/watch`, {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                'Accept': '*/*',
            },
            openWhenHidden: true,
            body: JSON.stringify({
              'query': prompt,
            }),

            onmessage(ev) {
                const tmp = JSON.parse(ev.data)

                if (tmp.chunk !== null) {
                    messageContent += tmp.chunk
                    setAnswer(messageContent)
                }
            },
            onclose() {
                // do not retry
                ctrl.abort()
            },
            onerror(err) {
                console.log(err)
                // toast.error('Something unexpected happened.', {
                //     position: toast.POSITION.BOTTOM_RIGHT,
                //     toastId: 'prompt-error',
                // })
                ctrl.abort()
                throw err;
            },
            signal: ctrl.signal,
        }).then(() => {
            setIsStreaming(false)
        })
    }

  return (
    <>
      <div className="grid w-full gap-2">
        <h1 className="text-4xl mb-8 text-center">⌚ Watch Finder</h1>
        <Textarea 
          onChange={(e) => setPrompt(e.target.value)} 
          placeholder="Describe the watch you are looking for..." 
          value={prompt} />
        <Button 
          onClick={() => submitForm()}
          disabled={isStreaming || prompt === ''}
          >Find a watch!</Button>

        <div className="p-4 rounded-sm my-8 bg-gray-100 prose lg:prose-md w-full max-w-max text-left">
          <Markdown>{answer}</Markdown>
        </div>
      </div>
    </>
  )
}

export default App
```

How it works:

* The JSX is rendered on load. We use a `<Markdown/>` field to render the answer.
* The user writes a prompt in the main `<TextArea/>` that is store in a variable `prompt` using `useState`.
* When clicking the `<Button/>` , the script triggers `submitForm()` which creates a newStreamResponse
* `newStreamResponse` starts by setting the state variable `streaming` as true so we can use it to freeze our UI while the request loads and reset the answer as well as creating a local variable named `messageContent` to store the stream content coming back from the API.
* It then uses `fetchEventSource` to query our Laravel API. The `openWhenHidden` option specifies if the stream should be listened to when the tab or window is not in focus. We pass our prompt as the body of this POST request.
* The `onmessage` method defines how we treat incoming data from the Event stream. Here we concatenate the new chunk to our `messageContent` and then update the state variable `answer` to show the result. In case your content is too long or the chunks are coming in too fast, you might want to delay the update to avoid too many renderings.
* When the stream ends, we reset the `streaming` variable to `false`.

## Final deploy

Once these files added, let's deploy:

```bash {filename="Terminal"} theme={null}
git add .
git commit -m "Add frontend"
upsun push
```

## The result

You can now use the frontend URL that Upsun gave you in the deploy log to access your app. Let's query it!

<img alt="Final Application Demo" />

Everything works as expected! You can see in my recording above, that I am using a custom hostname. In your Upsun console, click the Go Live button and follow the instructions to configure your DNS and setup the domain!

<img alt="Setup domain" />

## Conclusion

While this example is stripped down to the core, it is interesting to see how you can leverage embeddings for search, classification or any other Machine Learning process. With all the tooling now available, it becomes super accessible to everyone to query models and run these applications on a Cloud Applications Platform like Upsun.com.


# How to Use Harlequin SQL IDE with Upsun
Source: https://developer.upsun.com/posts/hands-on/how-to-use-harlequin-sql-ide-with-upsun

Learn two ways to connect Harlequin SQL IDE to your Upsun PostgreSQL database: using local SSH tunnels or deploying Harlequin directly on the platform.


<PostMeta />

The Upsun CLI includes `upsun sql`, a quick way to run queries against your database from the command line. But sometimes you want more than a basic prompt. You want autocomplete, syntax highlighting, a visual schema browser, and the ability to scroll through large result sets. That's where [Harlequin](https://harlequin.sh/) comes in.

Harlequin is a terminal-based (TUI) SQL IDE that brings a rich, interactive experience to your shell. It includes a data catalog for browsing tables and columns, a query editor with autocompletion, and a results viewer that handles millions of rows. All without leaving your terminal.

This tutorial covers two ways to use Harlequin with your Upsun PostgreSQL database:

1. **Run Harlequin locally** and connect through an SSH tunnel
2. **Install Harlequin on your Upsun environment** and access it via SSH

Both approaches give you the same powerful interface. Choose the one that fits your workflow.

<img alt="Harlequin's interface showing the data catalog, query editor, and results pane" />

## Prerequisites

Before you start, make sure you have:

* An [Upsun account](https://upsun.com/) with a project deployed
* A PostgreSQL service configured in your `.upsun/config.yaml`
* The [Upsun CLI](https://docs.upsun.com/administration/cli.html) installed and authenticated
* For [Option 1](#option-1-run-harlequin-locally-with-an-ssh-tunnel): Python 3.10+ and [uv](https://docs.astral.sh/uv/) (or pip) installed locally

Your project should have a [PostgreSQL](https://docs.upsun.com/anchors/services/postgresql/) service defined. If you don't have one yet, add this to your `.upsun/config.yaml`:

```yaml {filename=".upsun/config.yaml",hl_lines=["1-3","8-9"],linenostart=1} theme={null}
services:
  postgresql:
    type: postgresql:16

applications:
  myapp:
    # ... your app config
    relationships:
      database: "postgresql:postgresql"
```

## Option 1: Run Harlequin locally with an SSH tunnel

This approach keeps Harlequin on your local machine and connects to Upsun through a secure SSH tunnel. It's ideal for day-to-day development when you want quick access to your database without modifying your deployment.

### Install Harlequin with the PostgreSQL adapter

Harlequin uses adapters to connect to different database types. Install both Harlequin and its PostgreSQL adapter:

```bash {filename="Terminal"} theme={null}
uv tool install 'harlequin[postgres]'
```

Alternatively, you can use pip:

```bash {filename="Terminal"} theme={null}
pip install harlequin harlequin-postgres
```

Or Homebrew on macOS:

```bash {filename="Terminal"} theme={null}
brew install harlequin
```

Verify the installation:

```bash {filename="Terminal"} theme={null}
harlequin --version
harlequin, version 2.5.0

Installed Adapters:
  - duckdb, version 2.5.0
  - sqlite, version 2.5.0
  - postgres, version 1.3.0
```

### Open an SSH tunnel to your Upsun services

The Upsun CLI can create [SSH tunnels](https://docs.upsun.com/anchors/ssh/tunnel/direct/) to all services in your environment. Run:

```bash {filename="Terminal"} theme={null}
upsun tunnel:open
```

You'll see output similar to:

```bash {filename="Terminal"} theme={null}
upsun tunnel:open
Enter a number to choose an app:
  [0] api
  [1] chainlit
  [2] next
 > 0

SSH tunnel opened to postgresql at: postgresql://main:main@127.0.0.1:30000/main
SSH tunnel opened to cache at: valkey://127.0.0.1:30001

Logs are written to: /Users/nls/.upsun-cli/tunnels.log

List tunnels with: upsun tunnels
View tunnel details with: upsun tunnel:info
Close tunnels with: upsun tunnel:close

Save encoded tunnel details to the PLATFORM_RELATIONSHIPS variable using:
  export PLATFORM_RELATIONSHIPS="$(upsun tunnel:info --encode)"
```

Note the connection details. In this example:

* **Host**: `127.0.0.1`
* **Port**: `30000`
* **Username**: `main`
* **Password**: `main`
* **Database**: `main`

Your values may differ depending on your configuration.

### Connect Harlequin to the tunnel

With the tunnel open, launch Harlequin using the connection details:

```bash {filename="Terminal"} theme={null}
harlequin -a postgres "postgres://main:main@127.0.0.1:30000/main"
```

You can also pass the connection parameters individually:

```bash {filename="Terminal"} theme={null}
harlequin -a postgres -h 127.0.0.1 -p 30000 -U main --password main -d main
```

Harlequin opens in your terminal, ready to explore your database.

### Explore your database

<img alt="harlequin-tunnel" />

Once connected, you can:

* **Browse the data catalog**: The left sidebar shows all schemas, tables, and columns in your database
* **Write queries**: The center pane is a full-featured editor with syntax highlighting and autocomplete (press `Ctrl+Space` to trigger suggestions)
* **View results**: Execute queries with `Ctrl+Enter` and scroll through results in the bottom pane
* **Export data**: Select results and export to CSV, JSON, or Parquet formats

Press `F1` to see all keyboard shortcuts.

When you're done, close the tunnel:

```bash {filename="Terminal"} theme={null}
upsun tunnel:close
```

## Option 2: Install Harlequin on Upsun

If you prefer to keep your tools on the platform, or want consistent access for your team, you can install Harlequin directly in your Upsun environment. Since Harlequin is a terminal UI, you'll access it by [SSH-ing into your container](https://docs.upsun.com/anchors/ssh/tunnel/app/).

### Add Harlequin to your build hook

Modify your `.upsun/config.yaml` to install Harlequin during the build phase. Add the pip install command to your existing build hook:

```yaml {filename=".upsun/config.yaml",hl_lines=["4-6","10"],linenostart=1} theme={null}
applications:
  myapp:
    type: python:3.13
    dependencies:
      python3:
        uv: "*"
    hooks:
      build: |
        set -eux
        uv tool install --python 3.13 'harlequin[postgres]'
        # Add your other build commands here

    relationships:
      database: "postgresql:postgresql"

    # ... rest of your config
```

If your application isn't Python-based, you can still install Harlequin. Python is available in most Upsun containers. Add a build hook that installs it:

```yaml {filename=".upsun/config.yaml",hl_lines=["4-6","10"],linenostart=1} theme={null}
applications:
  myapp:
    type: nodejs:22  # or php:8.3, etc.
    dependencies:
      python3:
        uv: "*"
    hooks:
      build: |
        set -eux
        uv tool install --python 3.13 'harlequin[postgres]'
        # Your other build commands

    relationships:
      database: "postgresql:postgresql"

    # ... rest of your config
```

### Deploy your changes

Commit and push your configuration changes:

```bash {filename="Terminal"} theme={null}
git add .upsun/config.yaml
git commit -m "Add Harlequin SQL IDE"
upsun push
```

Wait for the deployment to complete.

### SSH into your environment

Connect to your running container:

```bash {filename="Terminal"} theme={null}
upsun ssh
```

### Launch Harlequin

Upsun generate one environment variable for the database DSN automatically (see [Service Environment variables](https://docs.upsun.com/anchors/variables/environment/service/)):

```bash {filename="Terminal"} theme={null}
web@api.0:~$ env | grep DATABASE
DATABASE_URL=postgresql://main:main@postgresql.internal:5432/main
```

The name can vary as it is using the `relationships` name in the `myapp` section of the `.upsun/config.yaml` file (e.g. `database:` in the example above)

You can now launch Harlequin:

```bash {filename="Terminal"} theme={null}
/app/.local/bin/harlequin -a postgres $DATABASE_URL
```

If you want to avoid specifying the whole path, update your `PATH` variable in the deploy hook of your application:

```yaml {filename=".upsun/config.yaml",hl_lines=["4"],linenostart=1} theme={null}
hooks:
  deploy: |
    set -x -e
    export PATH="$PATH:/app/.local/bin/"
```

## Tips and best practices

### Create a shell alias for quick access

If you use Option 1 frequently, add an alias to your shell configuration:

```bash {filename="~/.bashrc or ~/.zshrc"} theme={null}
alias upsun-harlequin='upsun tunnel:open && harlequin -a postgres "$(upsun tunnel:info --property=database.0.url)"'
```

### Use read-only credentials for safety

When exploring production data, consider creating a read-only PostgreSQL user to prevent accidental modifications. You can configure additional database endpoints in your services configuration.

### Keyboard shortcuts

Here are the most useful Harlequin shortcuts:

| Action | Shortcut |
| - | - |
| Execute query | `Ctrl+Enter` |
| Autocomplete | `Ctrl+Space` |
| New query tab | `Ctrl+N` |
| Close tab | `Ctrl+W` |
| Focus data catalog | `Ctrl+B` |
| Help / all shortcuts | `F1` |
| Quit | `Ctrl+Q` |

### Query history

Harlequin automatically saves your query history. Press `F8` to browse previous queries and re-run them.

## Conclusion

You now have two ways to use Harlequin with your Upsun PostgreSQL database:

1. **Local installation with SSH tunnel**: Best for individual developers who want quick, on-demand access
2. **Installed on Upsun**: Best for team environments or when you want tools available directly on the platform

Both approaches give you a powerful, visual way to explore and query your data without leaving the terminal.

For more Harlequin features and configuration options, check out the [official documentation](https://harlequin.sh/docs/getting-started).

Ready to try it out? [Create a free Upsun account](https://upsun.com/) and deploy your first PostgreSQL-powered application.


# Up(sun) and ready with GitHub release assets installation
Source: https://developer.upsun.com/posts/hands-on/install-gh-asset-on-upsun

Discover how to install any GitHub release asset you want in your Upsun project.


<PostMeta />

One of my colleagues recently asked me how to install `yq` on his Upsun project,
and after some searching, I discovered that the library can be easily installed from a [GitHub repository](https://github.com/mikefarah/yq).

This whole process made me realize that I didn't really explain how this [`github-install-asset.sh`](https://github.com/upsun/snippets/blob/main/src/install-github-asset.sh) shell script works
in my previous blogpost about [how to install Pandoc on Upsun](https://devcenter.upsun.com/posts/how-tos/install-pandoc-on-upsun).
So, this is it.

In this guide, you will learn how to install any binary from a GitHub release into your Upsun project using this script.
I've chosen `yq` as an example here, but feel free to test the process using your own favorite GitHub repository.

<Note>
  **Assumptions:**

  * You already have an Upsun account. If you don’t, [please register for a trial account](https://auth.upsun.com/register). You can sign up with an email address or an existing GitHub, Bitbucket, or Google account. If you choose one of these accounts, you can set a password for your Upsun account later.
  * You already have an Upsun project live and ready on local. If you don't, please follow [this blogpost first](https://upsun.com/blog/upsun-and-running-with-symfony-demo/) to install a Symfony Demo on Upsun.
  * You have the [Upsun CLI](https://docs.upsun.com/administration/cli.html) installed locally.
</Note>

## Create a new environment

As we never test things directly on production, we first need to create a new [preview environment](https://docs.upsun.com/glossary.html#preview-environment) in order to test before going live.

To create a new environment, execute the following from the root of your source code.

```bash {filename="Terminal"} theme={null}
upsun branch install-yq
```

## Call `github-install-asset.sh` in your `hooks.build`

As your application container is writable only during the `hooks.build` phase, you can install any additional packages you need.
Using this [`github-install-asset.sh`](https://github.com/upsun/snippets/blob/main/src/install-github-asset.sh) script allows you to install any chosen [GitHub release asset](https://docs.github.com/en/rest/releases/assets?apiVersion=2022-11-28) you want.

In this guide we're using `yq` as an example, so you can update your `.upsun/config.yaml` file with the following:

```yaml {filename=".upsun/config.yaml",linenos=table,hl_lines=["8", "12"],linenostart=1} theme={null}
applications:
  app:
    #.. 
    hooks:
      build: |
        set -x -e
        #...
        curl -fsS https://raw.githubusercontent.com/upsun/snippets/main/src/install-github-asset.sh | bash /dev/stdin "mikefarah/yq"
      deploy: |
        set -x -e
        #..
        yq -v
```

This generic `install-github-asset.sh` script can take 3 parameters:

```shell theme={null}
curl -fsS https://raw.githubusercontent.com/upsun/snippets/main/src/install-github-asset.sh | bash /dev/stdin "<org/repo>" ["<release_version>"] ["<asset_name>"]
```

* `<org/repo>`: required, the GitHub organisation/repository where to find the asset
* `<release_version>`: optional, get the latest release version if empty
* `<asset_name>`: optional, if empty, we look for the first asset that contains `linux` + `[amd64|arm64|x86]` in its name.

<Note>
  🚨 **Please note**: In this blogpost, we're using `yq` as an example, but this script also works with other GitHub release assets, like [Pandoc](https://github.com/jgm/pandoc) or [FrankenPHP](https://github.com/dunglas/frankenphp/):

  ```yaml {filename=".upsun/config.yaml",linenos=table,hl_lines=["8-9","13-14"],linenostart=1} theme={null}
  applications:
    app:
      #.. 
      hooks:
        build: |
          set -x -e
          #...
          curl -fsS https://raw.githubusercontent.com/upsun/snippets/main/src/install-github-asset.sh | bash /dev/stdin "jgm/pandoc" "3.6.4"
          curl -fsS https://raw.githubusercontent.com/upsun/snippets/main/src/install-github-asset.sh | bash /dev/stdin "dunglas/frankenphp" "v1.5.0" "frankenphp-linux-x86_64-gnu"
        deploy: | 
          set -x -e
          #..
          pandoc -v
          frankenphp -v
  ```
</Note>

Now commit your change:

```shell {filename="Terminal"} theme={null}
git add . && git commit -m "adding yq installation and/or pandoc + frankenphp"
upsun push 
```

Any tool installed via this `install-github-asset.sh` script will be available globally (installed in the `/app/.global/bin` folder) and you will be able to call it using the `repo` name:

```shell theme={null}
upsun ssh 
yq -v
pandoc -v
frankenphp -v
```

## Install from private GitHub repository

If you're trying to install a GitHub release asset from a private repository, you’ll likely encounter an error like the one below in your deployment logs:

```shell {filename="Terminal"} theme={null}
>> Install <org/repo> GitHub asset.
On an Upsun/Platform.sh environment.
❌ Repository not accessible (404).
💡 It might be a private repository. Please set a valid GITHUB_API_TOKEN environment variable.
```

This is the excepted result, as the [GitHub API](https://docs.github.com/en/rest/repos/repos?apiVersion=2022-11-28#get-a-repository) returns a 404 HTTP response when access is denied.
At this point, you're still an anonymous GitHub user making the API request.

To fix this, you need to use [a GitHub API Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens), with at least the `repo` read access.

To access private GitHub repositories, you will need to define a `GITHUB_API_TOKEN` [environment variable](https://docs.upsun.com/development/variables/set-variables.html) in your Upsun project.
Our `install-github-asset.sh` will automatically use this `GITHUB_API_TOKEN` envVar and install any corresponding private release assets.

To define an environment variable in your project, use the [Console](https://docs.upsun.com/development/variables/set-variables.html#create-project-variables) or the following ['variable:create'](https://docs.upsun.com/administration/cli/reference.html#variablecreate) command line:

```shell {filename="Terminal"} theme={null}
upsun variable:create env:GITHUB_API_TOKEN --value=ghp_[...] --sensitive=true --visible-build=true
```

and then redeploy your environment:

```shell {filename="Terminal"} theme={null}
upsun redeploy
```

## Conclusion

Et voilà, you're now in control and can easily install any GitHub release asset you want in your Upsun project.

Stay tuned.


# Migration day: executing your Upsun cutover
Source: https://developer.upsun.com/posts/hands-on/migration-day-executing-your-upsun-cutover

A step-by-step guide to migration day: maintenance windows, cutover sequences, verification, and post-migration monitoring strategies.

<PostMeta />

You've planned for weeks. Now it's time to flip the switch. Here's how to make migration day boring (in the good way).

The goal of migration day isn't excitement. It isn't drama. The goal is to make it so boring that you can tell the story later and people's eyes glaze over. "We went into maintenance, copied the files, switched the DNS, and went home. The end."

That kind of boring doesn't happen by accident. It happens because you've prepared, tested, and planned for every step. If you've followed the planning process from [Part 1](/posts/how-tos/planning-your-upsun-migration-the-6-9-week-roadmap), you're ready. Let's walk through execution.

Throughout this guide, you'll see insights from Lucas Stil, Upsun's Senior Manager of Onboarding & Migration from Part 1. His field experience shows up in all the practical details that follow.

## T-minus 48 hours: final preparations

Before you even think about putting up a maintenance page, there are a few things to lock down.

### Reduce your DNS TTL (if applicable)

If you're not using a CDN (or switching CDN backends), you'll need to change DNS records. That means dealing with cache. Here's the move:

**Lucas on DNS preparation:**

> "If you need to change DNS, lower your TTL in advance. We usually suggest dropping it to 30 seconds. That way, when you make the switch, you're not waiting hours for the cache to expire. Most of your traffic will flip over quickly."

Do this 48-72 hours before migration, not the day of. DNS changes take time for caches to expire, including the TTL value itself.

### Communicate with your users

This might sound obvious, but it's worth emphasizing: tell people the site will be down.

**Lucas on user communication:**

> "If you can, put a banner on the site in advance: 'Between X time and Y time, the site will be unavailable.' And here's the key: always overpromise on downtime. Say you'll be down for an hour when you're planning for 30 minutes. If you finish early, users are pleasantly surprised. If you say 30 minutes and take an hour and three minutes, they're disappointed."

Under-promise, over-deliver. It works in migrations too.

### Pre-generate TLS certificates (CDN users)

If you're using Fastly or another CDN with Upsun, you can pre-generate TLS certificates using DNS validation. This means no waiting for certificate generation during your cutover window.

**Lucas explains the approach:**

> "For clients using our CDN, we provide a CNAME for verification, and we pre-generate the TLS certificates. Then there's no delay when you switch over. You can even test with a subdomain first, like prod.yourdomain.com pointing to the new infrastructure while [www.yourdomain.com](http://www.yourdomain.com) still points to the old one."

This isn't always possible (Upsun Cloud doesn't support DNS validation for certificates yet), but where it is, use it.

### Run one final sync

If you've set up [database replication](/posts/hands-on/connect-multiple-projects-applications-or-services-together) or have done a practice run of file copying, do one last sync of your data 24-48 hours before migration. This gives you:

* Confidence that the process works
* A baseline for how long the final sync will take
* A chance to catch any issues before you're under time pressure

After this sync, don't hesitate to run another reindex of your other services if relevant (e.g. OpenSearch); this is either time saved if your application supports is, or knowledge of the time it'll take if not.

## The maintenance window

Alright. It's time. You've told your users, you've prepared your team, and you're about to put the site into maintenance mode.

### Where to put the maintenance page

You have options here:

1. **CDN level**: If you're using Fastly or another CDN, set the maintenance page there. This is ideal because it doesn't hit your origin at all.

2. **Application level**: Many CMS platforms and applications support a maintenance mode flag (often just a database flag or a file in the filesystem).

**The ideal approach** is using both levels together. Here's why:

**Lucas on the two-layer approach:**

> "I recommend putting maintenance mode on both sides. Why? Because the maintenance flag in your application (a database flag or file) will get copied during the migration. So when you bring the new system online, it's already in maintenance mode. Then you can verify everything works before you lift the flag."

This prevents the scenario where you flip DNS, users hit the new site, and it's live before you've verified it works.

### Wait for workers to drain

If you use background workers (RabbitMQ, queues, etc.), don't jump straight to copying data. Wait for the queues to empty.

**Lucas on worker queues:**

> "RabbitMQ is nice because it's easy to see when queues are empty. Put the site in maintenance, then let workers finish consuming whatever's in the queues. Once they're empty, then you proceed with the migration. Otherwise you might lose jobs that were in flight."

For search services like Elasticsearch or Solr, you'll typically need to reindex on the new platform. If you've been using database replication, your data should be current, so reindexing can be fast (or even partial/incremental).

## The cutover sequence

Here's the order of operations. These can often run in parallel (if network isn't your bottleneck), but this is the logical sequence:

### 1. Final file sync with rsync

You've been using rsync for practice runs. Now you do it for real. Because rsync does differential copying, and because you've (hopefully) organized your files into a reasonable directory structure, this should be quick.

**Lucas on rsync timing:**

> "The differential copy with rsync is great. It only copies what's changed. But if you have 15,000 files in one folder, even counting them all takes time. That's why file organization matters."

### 2. Database cutover

**If you're using replication:** Promote the replica to primary. This is nearly instantaneous.

**If you're using a dump:** You're importing the database, and this is your longest step. The good news is you've timed this during your practice runs, so you know how long it takes. The bad news is it's mostly incompressible time.

**Lucas on database imports:**

> "If you're using a dump, this is the long part. The dump itself is small (it doesn't include index structures), but rebuilding indexes on the other side takes time. You can't do much to speed it up beyond giving the database service more resources temporarily."

([Learn more about why database dump sizes differ from actual database size](/posts/insights/the-mystery-of-the-shrinking-database-dump))

Pro tip: If metrics show a bottleneck during your practice import, you can temporarily upsize the database service just for the import, then size it back down. The cost is minimal (you're only upsized for an hour at most), and it can save meaningful time.

### 3. Service migrations (Redis, search, etc.)

Some services you can't easily migrate:

* **Redis**: No dump import support in Upsun (requires RDB or AOF files). For cache uses, you can just start fresh. For persistent data, you'll need a different strategy.
* **Elasticsearch/Solr**: Reindex from your database (which should be current if you used replication).

The key is that you've tested all of this during Phase 3 of planning, so nothing here is a surprise.

### 4. DNS switch (or CDN origin switch)

Once data is in place:

**If you're using a CDN:** Just change the origin backend. This is instant and doesn't involve DNS cache.

**If you're not:** Change your DNS records to point to Upsun. Even with a 30-second TTL, give it a few minutes for most traffic to flip over.

## Verification before going live

Here's the clever bit: you're going to verify everything works before you lift the maintenance page.

### The IP whitelist trick

Most CDNs and many applications let you exclude certain IPs from the maintenance page.

**Lucas on IP whitelisting:**

> "With Magento, for example, you can say 'everyone sees the maintenance page except these three IPs.' Those three IPs are your team. So you can browse the site, make a test purchase, edit content, whatever you need to verify, all while the rest of the world sees the maintenance page."

This is your safety net. If something's broken, users never see it.

### What to verify

Your verification depends on your application, but generally you'll want to confirm:

* Homepage loads correctly
* Login works (test with a real account)
* Key workflows function (checkout, form submission, content editing, etc.)
* HTTP headers confirm requests are hitting Upsun (not the old platform)
* Static assets load (images, CSS, JS)
* Critical integrations work (payment processing, email, etc.)

### The /etc/hosts trap

Here's a gotcha that's caught more than one team:

**Lucas shares a cautionary tale:**

> "We had a client testing during maintenance. They said 'looks good, but something's weird.' Turned out they'd been testing with a manual entry in their /etc/hosts file for weeks, and they forgot about it. So their browser was hitting the old platform while they were checking the database via SSH on the new platform. They couldn't figure out why test purchases didn't show up in the database."

**The lesson:** Check your headers. Make sure the response headers show you're hitting Upsun, not your old host. If you've been using /etc/hosts for testing, remove those entries before final verification.

## Post-migration: the first 24 hours

You've verified everything. You've lifted the maintenance page. Users are back on the site. You're not done.

### Monitoring: What to watch

**Lucas on post-migration vigilance:**

> "After the migration, I tend to be a bit obsessive for the first half hour or hour. I'm watching metrics, trying to do a purchase, editing an article, checking if everything still works. Once I'm confident everything's good, then I can relax."

What to monitor:

* **Upsun metrics dashboard**: Watch container resource usage, response times, error rates
* **Blackfire**: Keep an eye on performance profiles
* **Your own monitoring**: If you have external monitoring (uptime checks, etc.), make sure those are green
* **Error logs**: SSH into your environment and tail logs to catch any issues immediately

If you see problems, you have options:

* Fix forward (if it's a configuration issue you can address quickly)
* Roll back (if it's catastrophic, though this is rare if you've tested properly)

### Enable uptime SLA monitoring

Once you're confident the site is stable, this is a good time to enable Upsun's Uptime SLA monitoring if you haven't already.

**Lucas on support handoff:**

> "We recommend asking support to enable Uptime SLA monitoring. That way, if something goes wrong after hours, Upsun's support team gets notified and can react. It's the handoff from migration specialist to ongoing support."

### Resist the urge to deploy changes immediately

You've just migrated. The site is working. Resist the temptation to start deploying new features or making changes in the first day or two. Let it stabilize. Make sure normal traffic patterns look healthy before you introduce new variables.

## The two-week follow-up period

The migration isn't over when the site is live. There's a follow-up period where you're settling into the platform, and where Upsun's onboarding team is still watching.

**Lucas on the follow-up:**

> "We follow clients for 7 to 14 days after migration. We keep an eye on the site, and at the end, we do what's called a post-go-live call. We review what went well, gather feedback, and for larger clients, we introduce key members of the support team."

(Note: This follow-up support is part of Upsun's Onboarding & Migration Services. Many clients work with the OMS team for additional coordination and support throughout the migration process.)

### The support handoff

One thing Lucas mentioned that caught my attention: many clients are nervous about moving from their dedicated onboarding specialist to general support.

**Lucas on putting a face to support:**

> "We found that clients were often afraid of support—afraid they'd get a chatbot, afraid they'd get someone who doesn't know what they're doing. So we started bringing a support manager and a senior support engineer to the post-go-live call. Just putting a face to support, showing them 'this is a real person, they know what they're doing,' that alone reassures people tremendously."

It's a small thing, but it matters. You're not getting shuffled off to some faceless ticket system. You're meeting the people who'll help you going forward.

### Settling into platform workflows

During this two-week period, you'll continue using the Upsun workflows you practiced during Phase 3 testing, now applying them to your live production environment:

* Creating development environments for new features
* Running deployments through Git
* Using the CLI for debugging and management
* Following the platform's patterns and best practices

Any questions that come up during this period are normal and expected. That's what the follow-up is for.

## Rollback: the reality

Let's talk about something uncomfortable: what if you need to roll back?

**Lucas on rollback planning:**

> "We don't really encourage setting up bidirectional replication so you can roll back easily. Most of our clients are coming from hosting that's ending or nearly ending. They're in a time crunch. Rolling back isn't high on their priority list."

That said, if something goes catastrophically wrong and you need to roll back:

1. Your old platform probably still exists (at least for a few days)
2. You can export data from Upsun if needed ([no vendor lock-in](https://upsun.com/blog/vendor-lock-in/))
3. Any transactions that happened on the new platform during the brief live period can typically be exported and handled manually

**The practical reality:**

> "If it's broken enough that you need to rollback, users usually aren't successfully completing transactions anyway. If the whole site is broken, there aren't purchases to worry about. And if you catch issues during the verification phase (before lifting maintenance), you never went live at all."

This is why testing and verification matter. You want to find showstopper issues while you're still behind the maintenance page.

## Making migration day boring

If you've done everything right, here's what your migration day looks like:

* Put up maintenance page
* Wait for workers to drain
* Run rsync for files (fast, because it's differential)
* Promote database replica (instant) or import dump (timed, but expected)
* Reindex search if needed
* Switch DNS or CDN backend
* Verify everything while still in maintenance
* Lift maintenance page
* Monitor for the first hour
* Go home

No surprises. No discoveries. No "oh, we forgot about this service." Just execution of a plan you've tested multiple times.

That's the goal. Boring migrations are successful migrations.

***

*Read [Part 1: Planning Your Upsun Migration](/posts/how-tos/planning-your-upsun-migration-the-6-9-week-roadmap) for the complete planning roadmap that leads up to migration day.*


# NoCode with Upsun: Supercharge Your Automation with Zero Code
Source: https://developer.upsun.com/posts/hands-on/nocode-n8n

Learn how to leverage Upsun to deploy powerful NoCode tools like n8n for workflow automation. Fast setup, secure hosting, and real-world use cases — all without writing code.
  


<PostMeta />

The [NoCode movement](https://www.nocode.tech/article/what-is-no-code) is transforming how we build digital tools.
Whether you're a founder, a marketer, or part of an operations team,
NoCode platforms empower you to create apps, automations, and integrations — all without writing a single line of code.

In this article, you'll learn how [**Upsun**](https://www.upsun.com), a developer-friendly Cloud Application Platform,
can host your NoCode workflows with ease.
We’ll walk through the advantages of using Upsun and show you how to deploy [**n8n**](https://n8n.io/),
a powerful open-source automation tool, in just a few minutes.

## Why NoCode?

* ⚡ **Faster time to market** – Build tools in hours, not weeks.
* 💸 **Lower development cost** – No need for full-time developers.
* 🙌 **Accessibility** – Anyone on your team can contribute.
* 🔌 **Integration ready** – Easily connect hundreds of services like Slack, Google Sheets, Notion, and more.

## Deploying n8n on Upsun (Step-by-Step)

Let’s set up **n8n** on Upsun — a self-hosted, open-source alternative to Zapier or Make.com.

<Note>
  Prerequisites

  * An [Upsun account](https://auth.upsun.com/register)
  * Git installed locally
</Note>

### Create your project root

```bash {filename="Terminal"} theme={null}
mkdir -p my-n8n-project && cd my-n8n-project && git init
```

### Configure your n8n app

Create a `.upsun/config.yaml` file in your project root:

```yaml {filename=".upsun/config.yaml",linenos=table,linenostart=1,base_url="https://github.com/upsun/demo-n8n/tree/main/"} theme={null}
applications:
  app-n8n:
    type: 'nodejs:22'
    container_profile: HIGHER_MEMORY
    variables:
      env:
        N8N_EMAIL_MODE: 'smtp'
        N8N_SMTP_PORT: '25'
        N8N_SMTP_HOST: 'localhost'
        N8N_SMTP_SSL: false
        N8N_LISTEN_ADDRESS: '0.0.0.0'
        NODE_OPTIONS: --max-old-space-size=1472
    dependencies:
      nodejs:
        n8n: "*"
        n8n-nodes-mcp: "*"
    mounts:
      '.n8n': { source: storage, source_path: n8n }
      '.cache': { source: storage, source_path: cache }
    web:
      commands:
        start: "n8n start"
      upstream:
        socket_family: tcp
        protocol: http
      locations:
        '/':
          root: ""
          passthru: true
          request_buffering:
            enabled: false
    hooks:
      build: |
        set -xeu
        echo 'export N8N_PORT=$PORT' >> .environment
        echo 'export N8N_LISTEN_ADDRESS=0.0.0.0' >> .environment
routes:
  "https://{all}/": { type: upstream, upstream: "app-n8n:http", primary: true, cache: {enabled: false}}
  "http://{all}/": { type: redirect, to: "https://{all}/" }

```

<Note>
  **Please note**:

  As it is not possible to define "dynamic" environment variable (e.g. using another existing environment variable value) in the `variables.env` section,
  we are using the [`hooks.build`](https://docs.upsun.com/create-apps/app-reference/single-runtime-image.html#hooks) (line 31) to set `N8N_PORT` environment variable using internal [`$PORT`](https://docs.upsun.com/development/variables/use-variables.html#use-provided-variables) environment variable.
</Note>

### Create an Upsun project

To create an Upsun project, execute the following command line:

```bash {filename="Terminal"} theme={null}
upsun project:create
```

Follow the CLI prompts to set up your project.

### Deploy to Upsun

```bash {filename="Terminal"} theme={null}
git add .upsun/config.yaml
git commit -m "Add n8n config"
upsun push
```

After deployment, you’ll receive a live URL where your n8n instance is hosted.

### Start Automating

You can then open the frontend by using the following command line:

```bash {filename="Terminal"} theme={null}
upsun environment:url --primary
```

You should end up on this frontend page:

<img alt="n8n frontend setup page" />

Log in with the credentials to your n8n account.

You can now start creating powerful automations using n8n's drag-and-drop workflow builder.

## 🔍 Example Use Cases

Here are just a few real-world automations you can build with n8n on Upsun:

* 📧 **Email Marketing**: Sync new Airtable contacts to Mailchimp.
* 💬 **Slack Alerts**: Notify your team when a customer submits a form.
* 📈 **Social Monitoring**: Track Twitter mentions and store them in Notion.
* 🗂️ **File Watchers**: Upload new Dropbox files to Google Drive automatically.

## Conclusion

With **Upsun**, deploying and scaling powerful NoCode tools like **n8n** is fast, secure, and seamless.
Whether you're a technical founder or a business user, you now have the power to automate anything — without DevOps or complex infrastructure.

👉 **Start building smarter workflows with n8n + Upsun today.** 🚀

*Have questions or need help setting up your first workflow? Feel free to reach out on the [Upsun Community Forum](https://community.upsun.com/).*

***

Demo Project on our [Github Upsun](https://github.com/upsun/demo-n8n/tree/main)


# Using PostgreSQL MCP with Upsun Remote Database
Source: https://developer.upsun.com/posts/hands-on/postgres-mcp-on-upsun

Learn how to set up an MCP server to connect your Upsun PostgreSQL database to language models like Claude or IDE like VSCode GitHub Copilot and Cursor, enabling natural language data queries without writing SQL.


<PostMeta />

## Introduction to Model Context Protocol (MCP)

Model Context Protocol (MCP) is an open standard that creates a bridge between large language models (LLMs) and external tools, data sources, or services. It standardizes how AI assistants can access and interact with information outside their training data, allowing them to perform actions in the real world through a consistent interface.

MCP servers act as specialized connectors that expose specific capabilities to AI assistants. These servers follow the MCP specification to provide tools and resources that LLMs can use to:

1. Access data sources (like databases, APIs, or file systems)
2. Execute functions (like running queries or performing calculations)
3. Interact with external systems (like applications or services)

<Info>
  Learn more about the MCP protocol on [the official documentation](https://modelcontextprotocol.io/introduction).
</Info>

## Why Connect Databases to LLMs via MCP?

Connecting a PostgreSQL database to an LLM through MCP offers several compelling advantages:

1. **Natural language access to data**: Non-technical team members can query complex databases using plain English instead of SQL.

2. **Controlled, secure access**: MCP servers can enforce read-only access, preventing accidental data corruption or unauthorized changes.

3. **Deeper context for AI conversations**: The AI can reference your actual data when answering questions, making responses more accurate and relevant to your specific situation.

4. **Simplified data exploration**: Quickly explore database structures and content without writing SQL queries for every investigation.

5. **Enhanced productivity**: Developers can focus on higher-level problems while the AI handles routine data retrieval and analysis tasks.

6. **Cross-platform compatibility**: The same MCP server works with multiple AI assistants (Claude, GitHub Copilot, etc.) that support the protocol.

This guide demonstrates how to connect a PostgreSQL Model Context Protocol (MCP) server to an Upsun remote database, enabling AI assistants like Claude or GitHub Copilot to interact with your database data through natural language.

<Warning>
  As always when dealing with LLM's, be wary of possible hallucinations!
</Warning>

## 1. Adding a PostgreSQL Database to Upsun

If you don't have one already, add a PostgreSQL database service on your Upsun project:

1. Edit your `.upsun/config.yaml` file to add a PostgreSQL service:

```yaml {filename=".upsun/config.yaml"} theme={null}
services:
  # The name of the service container - can be any name you choose
  postgresql:
    type: postgresql:17  # Use your preferred PostgreSQL version
```

2. Create a relationship to this service in your application configuration:

```yaml {filename=".upsun/config.yaml"} theme={null}
applications:
  myapp:
    # Other configuration...
    relationships:
      database: "postgresql:postgresql"
```

3. Push your changes to deploy the PostgreSQL service:

```bash {filename="Terminal"} theme={null}
git add .upsun/config.yaml
git commit -m "Add PostgreSQL service"
upsun push
```

In order for the MCP to retrieve information, it is up to you to populate that database with some tables and records!

## 2. Opening a Tunnel to Your Remote Database

Use the Upsun CLI to open a secure tunnel to your Upsun PostgreSQL database:

```bash {filename="Terminal"} theme={null}
upsun tunnel:open
```

This command will create SSH tunnels to all your project's services, including PostgreSQL. The output will show connection details similar to:

```bash {filename="Terminal"} theme={null}
SSH tunnel opened to postgresql at: pgsql://main:main@127.0.0.1:30000/main
```

Note the connection string details - you'll need these for the MCP configuration.

Alternatively, you can obtain PostgreSQL connection details from your environment variables:

```bash {filename="Terminal"} theme={null}
upsun ssh env | grep DATABASE
```

Look for variables like `DATABASE_HOST`, `DATABASE_PORT`, `DATABASE_USERNAME`, and `DATABASE_PASSWORD`.

<Info>
  The variable prefix (`DATABASE_`) depends on how you named the relationship to the application in `config.yaml`
</Info>

## 3. Installing the PostgreSQL MCP Server

The PostgreSQL MCP server provides a standardized way for AI tools to interact with your database.

1. Make sure you have Node.js installed on your system.
2. You don't need to install anything manually - we'll use `npx` to run the server directly.

## 4. Configuring the MCP Server in Your Editor

### For VSCode

1. Install the GitHub Copilot extension if you haven't already.
2. Create a `.vscode/mcp.json` file in your project with the following configuration:

```json {filename=".vscode/mcp.json"} theme={null}
{
  "inputs": [],
  "servers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://main:main@127.0.0.1:30000/main"
      ]
    }
  }
}
```

Replace the connection string with your actual tunnel connection details from step 2.

### For Cursor

1. Open Cursor and go to Settings > Features > MCP.
2. Click on "+ Add New MCP Server"
3. Fill out the form:
   * Name: "postgres"
   * Type: "stdio"
   * Command: "npx"
   * Arguments: `-y @modelcontextprotocol/server-postgres postgresql://main:main@127.0.0.1:30000/main`

You can also edit the `mcp.json` settings file as below:

```json {filename="mcp.json"} theme={null}
{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://main:main@127.0.0.1:30002/main"
      ]
    }
  }
}
```

Replace the connection string with your actual tunnel connection details from step 2.

## 5. Testing the Setup

1. Make sure your Upsun tunnel is open and running. You can check the tunnel status and credentials with the following command:

```bash {filename="Terminal"} theme={null}
upsun tunnel:info -A api
postgresql:
    -
        [...]
        service: postgresql
        rel: postgresql
        scheme: pgsql
        username: main
        password: main
        port: 30000
        path: main
        [...]
        type: 'postgresql:17'
        url: 'pgsql://main:main@127.0.0.1:30000/main'
```

2. Activate the AI assistant in your editor:
   * In VSCode: Open the Copilot Chat panel and switch to "Agent mode"
   * In Cursor: Open Composer and ensure the MCP server is active
3. Try asking questions about your database:
   * "What tables are in my database?"
   * "Can you show me the schema of the users table?"
   * "How many records are in the orders table?"

<img alt="Testing the MCP" />

## Troubleshooting

* **Connection issues**: Ensure your Upsun tunnel is open and the connection string is correct
* **Permission errors**: Check that your database credentials are matching
* **MCP server not responding**: Verify the MCP server configuration and ensure the required packages are installed

## Security Considerations

* The PostgreSQL MCP server provides read-only access to your database
* Always use tunnels for secure connections to remote databases
* For sensitive data, work with non-production environments by creating development branches in Upsun

## Using Non-Production Databases

One of Upsun's key advantages is the ability to create isolated environments with cloned databases:

1. Create a development branch from your production environment:
   ```bash theme={null}
   git checkout -b test-db
   git push -u origin test-db
   ```

2. Upsun automatically creates a new environment with a complete copy of your production database

3. You can then safely connect your MCP server to this development environment:
   ```bash theme={null}
   upsun tunnel:open -e test-db
   ```

This approach allows you to work with real data structures while minimizing any risk to your production environment. Each environment in Upsun has its own isolated database, making it ideal for development and testing with AI tools.

## Additional Resources

* [Upsun PostgreSQL Documentation](https://docs.upsun.com/add-services/postgresql.html)
* [Model Context Protocol Documentation](https://modelcontextprotocol.io)


# Power-up Your Local Development with DDEV
Source: https://developer.upsun.com/posts/hands-on/powerup-your-local-development-with-ddev

Get the best local development experience with the DDEV-Platform.sh add-on. Follow our guide, share your feedback, and optimize your workflow

<PostMeta />

Have you ever had to set up and/or maintain a local development environment using Docker that mirrors your production
environment as much as possible? Setting-up and supporting such a docker-based local environment is no easy feat! Common
problems include performance issues, broken dependencies, broken relationships between your services and uncontrolled
updates of your docker images, among many other issues.

So, the question is, *what can we do about that?*

### **DDEV: The simplest way to integrate containers on top of Docker**

[DDEV](https://ddev.com/) is an open-source tool that simplifies integrating the power and consistency of
[containerization](https://platform.sh/blog/what-the-heck-is-a-container/) into your workflows. With DDEV you can launch
local development environments in minutes!

DDEV is built on top of Docker, but fear not - it doesn’t demand any specific experience or knowledge of Docker to get
going. In addition, it does not require the use of the closed-source Docker Desktop either
([Colima](https://github.com/abiosoft/colima) can be used instead). Plus,
[DDEV circumvents the common performance issues](https://ddev.readthedocs.io/en/stable/users/install/performance/) that
developers encounter when working on macOS and Windows with Docker while ensuring you still get all of the benefits. Yay
[Mutagen](https://mutagen.io/)!

In fact, Platform.sh has been
[proudly sponsoring the DDEV open-source project](https://ddev.com/ddev-local/platform-sh-becomes-a-lead-sponsor-of-ddev/)
for more than 6 months now and this is just the beginning. At Platform.sh, we ❤️ open-source!

### **DDEV + Platform.sh = The best local development experience**

Sponsorship just wasn’t enough for us when it comes to DDEV. In the pursuit of providing the best Platform.sh local
development experience possible, allow me to introduce you to the
[DDEV-platform.sh add-on](https://github.com/platformsh/ddev-platformsh). The goal of this add-on is to provide a rich
integration between your checked-out Platform.sh project and DDEV.

It includes:

* Automated DDEV configuration based on your Platform.sh YAML configuration files: `.platform.app.yaml` and `services.yaml`
* Hassle-free integration of your remote database and files: just use `ddev pull platform`
* Easily access the relevant `$PLATFORM_*` environment variables, including `$PLATFORM_RELATIONSHIPS` and `$PLATFORM_ROUTES`
* Support of build and deploy hooks as configured in your `.platform.app.yaml` file

This add-on is already extremely valuable but the work is not quite complete. Here are some of the known limitations:

* It only supports PHP applications. There is an ongoing discussion to be able to support other languages such as Python
  and NodeJS
* Platform.sh multi-apps setup is not supported yet
* Routes defined in `.platform.routes.yaml` are not parsed yet
* Only supports the following platform.sh services:
  * Single database only: MariaDB, Oracle MySQL, PostgreSQL
  * Redis
  * Memcached
  * ElasticSearch

### **How to install the DDEV add-on**

To improve your local development experience with Platform.sh & DDEV, you need to ensure that you have the
[most recent version of DDEV](https://ddev.readthedocs.io/en/latest/users/install/ddev-installation/) (v1.21+). Then,
assuming that your project is already configured for Platform.sh:

* Run `ddev config`, and answer the interactive questions
* Get the add-on: `ddev get drud/ddev-platformsh`, and answer the interactive questions
* Run `ddev start`

And that’s it! You are all set - go and enjoy your fantastic, new local development experience.

### **Help improve DDEV & Platform.sh with your feedback!**

We really love and value Open-Source Software and gaining an understanding of how our solution is working for you and
your team. The best way to do that is to share your feedback with us via the
[add-on Github repository](https://github.com/platformsh/ddev-platformsh/issues) and don’t forget, if you encounter any
issues, you can always report them in there too. All feedback and/or contribution is welcome!


# How to run PyTorch in an Upsun application?
Source: https://developer.upsun.com/posts/hands-on/pytorch-running-on-upsun

Learn how to deploy a sentiment analysis application powered by PyTorch and FastAPI on the Upsun cloud platform


<PostMeta />

PyTorch is one of the most popular deep learning frameworks, particularly for natural language processing tasks. This tutorial will guide you through creating a sentiment analysis API using **PyTorch** and **FastAPI**, then deploying it on the **Upsun** Cloud Application Platform.

## Prerequisites

* An Upsun account
* Basic knowledge of Python
* Familiarity with REST APIs
* Git installed on your local machine

## Setting Up a new Python application on Upsun

Let's start by creating a new Python application on Upsun. We'll use **Python 3.12**, which is well-supported by both PyTorch and Upsun.

### 1. Create a new project directory

First, let's create a new directory for our project and initialize it as a Git repository:

```bash {filename="Terminal"} theme={null}
mkdir pytorch-sentiment-api
cd pytorch-sentiment-api
git init
```

### 2. Configure the Upsun project

Create the necessary Upsun configuration files to define our application's environment. First, create a `.upsun` directory and then a `config.yaml` file inside it:

```bash {filename="Terminal"} theme={null}
mkdir -p .upsun
touch .upsun/config.yaml
```

Now, open the `config.yaml` file and add the following configuration:

```yaml {filename=".upsun/config.yaml"} theme={null}
# Define the applications within the project
applications:
  # Name of the application (can be anything, 'api' used here)
  api:
    # Request a container with more memory, suitable for ML models
    container_profile: HIGH_MEMORY

    # Specify the language and version for the runtime environment
    type: "python:3.12"

    # Define persistent storage mounts for the application container
    mounts:
      # Mount a persistent storage volume named 'pycache' at /app/__pycache__
      # This persists compiled Python bytecode across deployments
      "__pycache__":
        source: "storage" # Use Upsun persistent storage
        source_path: "pycache" # Subdirectory within the storage volume
      # Mount a persistent storage volume named 'cache' at /app/.cache
      # Used by tools like pip or transformers to cache downloads
      ".cache":
        source: "storage"
        source_path: "cache"

    # Configuration for how the application serves web requests
    web:
      # The command Upsun runs to start the web server
      # Uses the PORT environment variable provided by Upsun
      commands:
        start: "uvicorn main:app --host 0.0.0.0 --port $PORT"
      # Defines how Upsun communicates with the application internally
      upstream:
        socket_family: tcp # Use TCP sockets
      # Defines how specific paths are handled
      locations:
        # For the root path "/"
        "/":
          root: ""
          passthru: true # Pass requests directly to the application (defined by commands.start)
          
    # Commands to run during different phases of the deployment process
    hooks:
      # Commands executed during the build phase
      build: |
        set -eux # Exit on error, print commands
        pip install --upgrade pip # Ensure pip is up-to-date
        pip install -r requirements.txt # Install dependencies
        # Compile Python files to bytecode for potentially faster startup
        python -m compileall .

# Define how incoming HTTP/HTTPS requests are routed to applications
routes:
  # Route requests for the default domain(s) configured for the environment
  "https://{default}/":
    type: upstream # Route to an application defined above
    upstream: "api:http" # Route to the 'api' application using HTTP
```

## Creating a FastAPI application for sentiment analysis

Now, let's create our FastAPI application that will serve as the API for our sentiment analysis model.

### 1. Set up the project structure

Let's organize our project with the following structure:

```
pytorch-sentiment-api/
├── .upsun/
│   └── config.yaml
├── main.py
├── model.py
├── requirements.txt
└── README.md
```

### 2. Define the requirements

Create a `requirements.txt` file with the necessary dependencies:

```txt {filename="requirements.txt"} theme={null}
fastapi>=0.68.0
uvicorn>=0.15.0
--extra-index-url https://download.pytorch.org/whl/cpu
torch==2.1.0+cpu
transformers>=4.11.0
pydantic>=1.8.0
```

Notice how we're using the `--extra-index-url` directive to specify that we want the CPU-only version of PyTorch, which is much smaller and suitable for deployment on CPU based containers.

### 3. Create the Model module

Let's create a `model.py` file that will handle the sentiment analysis logic:

```python {filename="model.py"} theme={null}
from transformers import pipeline
import torch

class SentimentModel:
    def __init__(self):
        # Verify we're using the CPU version
        print(f"CUDA available: {torch.cuda.is_available()}")
        print(f"PyTorch version: {torch.__version__}")
        
        # Load a small pretrained model for sentiment analysis
        self.classifier = pipeline(
            "sentiment-analysis",
            model="distilbert-base-uncased-finetuned-sst-2-english",
            return_all_scores=True
        )
    
    def predict(self, text):
        """
        Predict the sentiment of the given text.
        Returns the sentiment (POSITIVE/NEGATIVE) and confidence score.
        """
        result = self.classifier(text)
        
        # Process the results
        scores = result[0]
        
        # Find the label with the highest score
        highest_score = max(scores, key=lambda x: x['score'])
        sentiment = highest_score['label']
        confidence = highest_score['score']
        
        return {
            "text": text,
            "sentiment": sentiment,
            "confidence": confidence,
            "all_scores": scores
        }
```

### 4. Create the FastAPI application

Now, let's create the `main.py` file for our FastAPI application:

```python {filename="main.py"} theme={null}
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
import os
import time
from model import SentimentModel

# Create the FastAPI app
app = FastAPI(
    title="Sentiment Analysis API",
    description="An API for sentiment analysis using PyTorch and transformers",
    version="1.0.0"
)

# Load the model (this might take a moment)
print("Loading sentiment analysis model...")
model = None

# Define request and response models
class SentimentRequest(BaseModel):
    text: str

class SentimentResponse(BaseModel):
    text: str
    sentiment: str
    confidence: float

@app.on_event("startup")
async def startup_event():
    global model
    model = SentimentModel()
    print("Model loaded successfully!")

@app.get("/")
def read_root():
    return {"message": "Welcome to the Sentiment Analysis API"}

@app.post("/classification", response_model=SentimentResponse)
async def classify_sentiment(request: SentimentRequest):
    if not model:
        raise HTTPException(status_code=503, detail="Model not loaded yet")
    
    if not request.text or len(request.text.strip()) == 0:
        raise HTTPException(status_code=400, detail="Empty text provided")
    
    try:
        # Perform the prediction
        result = model.predict(request.text)
        
        # Return the response
        return {
            "text": request.text,
            "sentiment": result["sentiment"],
            "confidence": result["confidence"]
        }
    except Exception as e:
        raise HTTPException(status_code=500, detail=f"Error during prediction: {str(e)}")

@app.get("/health")
def health_check():
    return {"status": "healthy", "model_loaded": model is not None}
```

## Deploying the application to Upsun

Now that we have our application ready, let's deploy it to Upsun.

### 1. Initialize Git repository

Make sure all files are added to Git:

```bash {filename="Terminal"} theme={null}
git add .
git commit -m "Initial commit of PyTorch sentiment analysis API"
```

### 2. Create a new Upsun project

You can create a new Upsun project through the Upsun Console or using the Upsun CLI:

```bash {filename="Terminal"} theme={null}
upsun project:create # and follow the prompts!
```

The Upsun remote should be set automatically on the repository. If it's not, use

```bash {filename="Terminal"} theme={null}
upsun project:set {project_id}
```

### 3. Push to Upsun

Deploy your application by pushing your code to Upsun:

```bash {filename="Terminal"} theme={null}
upsun push -y
```

Upsun will automatically build your application according to the configuration files we created. This process includes installing dependencies, compiling Python files, and starting the FastAPI server.

### 4. Access your application

Once the deployment is complete, you can access your application at the URL provided by the Upsun console or with `upsun url --primary`. You should see the welcome message when you visit the root endpoint.

## Testing the Sentiment Analysis API

Now that our application is deployed, let's test it by sending a request to the sentiment analysis endpoint.

### Using cURL

```bash {filename="Terminal"} theme={null}
curl -X POST $(upsun url --primary --pipe)classification \
     -H "Content-Type: application/json" \
     -d '{"text": "I really enjoyed this movie, it was fantastic!"}'
```

You should receive a response like:

```json theme={null}
{
  "text": "I really enjoyed this movie, it was fantastic!",
  "sentiment": "POSITIVE",
  "confidence": 0.9978765249252319
}
```

### Using the Swagger UI

FastAPI automatically generates interactive API documentation. You can access it by navigating to `/docs` on your application URL:

```bash {filename="Terminal"} theme={null}
open $(upsun url --primary --pipe)docs
```

This will open the Swagger UI where you can test the API through a user-friendly interface.

<img alt="Swagger" />

## Advanced considerations

### Model size and disk space

The DistilBERT model we're using is relatively small, but if you're working with larger models, you might need to increase the disk space and the memory allocated in the Upsun configuration.

### Performance optimization

For better performance, you might want to:

1. Pre-load the model during the build phase
2. Use model quantization to reduce size
3. Consider implementing caching for frequently requested inputs

## Conclusion

In this tutorial, you've learned how to:

1. Set up a Python application on Upsun
2. Create a FastAPI app with a sentiment analysis endpoint
3. Configure PyTorch (CPU version) for efficient deployment
4. Deploy and test your application

Upsun provides an excellent platform for hosting CPU-based PyTorch applications, with its flexible configuration options and robust scaling capabilities. This approach allows you to deliver machine learning functionality through APIs or in your application without managing complex infrastructure.

Happy coding and machine learning with Upsun!


# How to automatically inject multi-app endpoints as environment variables
Source: https://developer.upsun.com/posts/hands-on/route-ids-env

Learn how to use Upsun route identifiers and the PLATFORM_ROUTES variable to easily get and use the hostnames of dynamically deployed applications in your project.
  


<PostMeta />

Many projects deployed on Upsun contain multiple applications. For example, you might have a frontend application and a separate backend API, or several microservices working together.

Upsun lets you [create relationships between your applications](https://docs.upsun.com/create-apps/multi-app/relationships.html), similar to how you connect services like databases. However, these relationships are mainly for server-side communication over the internal network. Sometimes, one application needs the *public* hostname, or Uniform Resource Identifier (URI), of another application in the same project.

For instance, imagine a **Next.js frontend** application. It might need to call your **API application** from both server components (running on the server) and client components (running in the user's browser). To do this, the frontend needs the API's public URI.

Every application container deployed on Upsun automatically gets an environment variable called `PLATFORM_ROUTES`. This variable contains information about all the project's routes. This guide uses the following example project structure:

<img alt="Multi-Apps project" />

## Define route identifiers

First, define your application routes in your project's routing configuration, within `.upsun/config.yaml`. Here's a basic example:

```yaml {filename=".upsun/config.yaml"} theme={null}
routes:
  "https://api.{all}/":
    type: upstream
    upstream: "api:http"
  "https://{all}/": 
    type: upstream
    upstream: "next:http"
```

To easily reference these routes later, add an `id` attribute to each one. Choose a meaningful string for the ID. Using the application name often works well:

```yaml {filename=".upsun/config.yaml",linenos=table,hl_lines=["5","9"],linenostart=1} theme={null}
routes:
  "https://api.{all}/":
    type: upstream
    upstream: "api:http"
    id: api # Identifier for the API route
  "https://{all}/": 
    type: upstream
    upstream: "next:http"
    id: next # Identifier for the Next.js frontend route
```

Read the full Upsun documentation on [Route identifiers](https://docs.upsun.com/define-routes.html#route-identifiers).

## Fetch specific URIs from `$PLATFORM_ROUTES`

After deploying these changes, connect to one of your application containers using the Upsun CLI. For example, use `upsun ssh -A api` where `api` is your application's name. Inside the container, you can view the `PLATFORM_ROUTES` variable:

```bash {filename="Terminal"} theme={null}
web@api.0:~$ echo $PLATFORM_ROUTES 
eyJodHRwOi8vYXBpLm1haW4tYnZ4ZWE2aS1yY...........
```

The output is a base64 encoded JSON string. To see the actual JSON content, you need to decode it:

```bash {filename="Terminal"} theme={null}
web@api.0:~$ echo $PLATFORM_ROUTES | base64 --decode
{"http://api.main-bvxea6i-abcdefgh.ca-1.platformsh.site/": {"id": null, "original_url": "http://api.{all}/", "primary": false, "production_url": "http://api.main-bvxea6i-abcdefgh.ca-1.platformsh.site/", "to": "https://api.main-bvxea6i-abcdefgh.ca-1.platformsh.site/", "type": "redirect"}, "http://main-bvxea6i-abcdefgh.ca-1.platformsh.site/": {"attributes": {}, "id": null, "original_url": "http://{all}/", "primary": false, "production_url": "http://main-bvxea6i-abcdefgh.ca-1.platformsh.site/", "to": "https://main-bvxea6i-abcdefgh.ca-1.platformsh.site/", "type": "redirect"}, "https://api.main-bvxea6i-abcdefgh.ca-1.platformsh.site/": {"attributes": {}, "id": "api", "original_url": "https://api.{all}/", "primary": true, "production_url": "https://api.main-bvxea6i-abcdefgh.ca-1.platformsh.site/", "type": "upstream", "upstream": "api"}, "https://main-bvxea6i-abcdefgh.ca-1.platformsh.site/": {"attributes": {}, "id": "next", "original_url": "https://{all}/", "primary": false, "production_url": "https://main-bvxea6i-abcdefgh.ca-1.platformsh.site/", "type": "upstream", "upstream": "next"}}
```

You can make this JSON easier to read by piping it through `jq`. `jq` is a command-line tool for processing JSON data. It helps you parse, filter, and transform JSON, which is useful when working with APIs and configuration files. You can find more information on the [jq website](https://jqlang.org/).

***

```bash {filename="Terminal"} theme={null}
web@api.0:~$ echo $PLATFORM_ROUTES | base64 --decode | jq
{
  "http://api.main-bvxea6i-abcdefgh.ca-1.platformsh.site/": {
    "id": null,
    "original_url": "http://api.{all}/",
    "primary": false,
    "production_url": "http://api.main-bvxea6i-abcdefgh.ca-1.platformsh.site/",
    "to": "https://api.main-bvxea6i-abcdefgh.ca-1.platformsh.site/",
    "type": "redirect"
  },
  "http://main-bvxea6i-abcdefgh.ca-1.platformsh.site/": {
    "attributes": {},
    ...
  },
  "https://api.main-bvxea6i-abcdefgh.ca-1.platformsh.site/": {
     "attributes": {},
     "id": "api",
     ...
  },
  "https://main-bvxea6i-abcdefgh.ca-1.platformsh.site/": {
     "attributes": {},
     "id": "next",
     ...
  }
}
```

That's much better!

Now, you need a `jq` query to extract the specific URI you want, using the route `id` defined earlier. Here's how you can select the URI associated with the `id` "api":

```bash {filename="Terminal"} theme={null}
web@api.0:~$ echo $PLATFORM_ROUTES | base64 --decode | jq -r 'to_entries[] | select(.value.id=="api") | .key'
https://api.main-bvxea6i-abcdefgh.ca-1.platformsh.site/
```

Here's how that `jq` query works:
*(You can experiment with this query and the example JSON using the [online jq playground](https://play.jqlang.org/s/MWvtpbqG5ExfBgB).)*

1. `to_entries[]`: Converts the JSON object into an array where each item has a `key` (the URI) and a `value` (the route details object). The `[]` processes each item in the array.
2. `select(.value.id=="api")`: Filters these items, keeping only those where the `id` field inside the `value` object equals `"api"`. Change `"api"` to the route ID you need.
3. `.key`: Extracts the `key` field (the URI) from the filtered item.
4. The `-r` flag tells `jq` to output the raw value instead of its JSON representation.

Now you know how to get a specific URI. The next step is making this URI available to your applications as an environment variable.

## Set up environment variables using `.environment`

Upsun lets you define environment variables dynamically during the build process. You do this using a special script file named `.environment` placed in your application's source code directory. Find more details in the [documentation on setting variables via script](https://docs.upsun.com/development/variables/set-variables.html#set-variables-via-script).

Suppose your Next.js application needs an `API_HOST` variable with the API's URI. And your API application needs a `NEXT_PUBLIC_BASE_URL` variable with the frontend's URI. You can create a `.environment` file using the `jq` queries from the previous step.

<Warning>
  ⚠️ Important: If multiple applications need these variables, place a copy of the `.environment` file in each application's source directory.
</Warning>

```bash {filename=".environment"} theme={null}
# This file runs during deployment to set environment variables.
# Place it in the root directory of applications that need these variables.

# Export the API host URI (identified by id: api)
export API_HOST=$(echo $PLATFORM_ROUTES | base64 --decode | jq -r 'to_entries[] | select(.value.id=="api") | .key')

# Export the Next.js frontend URI (identified by id: next)
# NEXT_PUBLIC_BASE_URL is a common convention for Next.js public variables.
export NEXT_PUBLIC_BASE_URL=$(echo $PLATFORM_ROUTES | base64 --decode | jq -r 'to_entries[] | select(.value.id=="next") | .key')

```

Commit the `.environment` file(s) to your repository and push the changes to Upsun. After the deployment finishes, connect to an application container again and check the variables:

```bash {filename="Terminal"} theme={null}
web@api.0:~$ echo $API_HOST
https://api.main-bvxea6i-abcdefgh.ca-1.platformsh.site/
web@api.0:~$ echo $NEXT_PUBLIC_BASE_URL
https://main-bvxea6i-abcdefgh.ca-1.platformsh.site/
```

Your applications can now access these URIs directly through the environment variables:

```php theme={null}
# In PHP
echo getenv('API_HOST');

# In Node.js
console.log(process.env.API_HOST);

# In Python
import os
print(os.environ.get("API_HOST"))
```

## Bonus tip: Use these variables in statically exported JavaScript applications

JavaScript applications that are statically exported (like some Next.js static exports or Create React App builds) generate their assets and configuration during a build phase.

The way most static generators work is that they will replace the `process.env.*` variables at build time with their actual values. Let's take an example with a variable called `API_ENDPOINT`.

This `API_ENDPOINT` variable has a value of `https://api.example.com` in either your `.env` file or the server environment variable. Your Javascript code refers to that variable with `process.env.API_ENDPOINT`.

When you are triggering the generation of the static export with `npm run build`, the `process.env.API_ENDPOINT` get replaced in the generated code with the actual value `https://api.example.com`.

While it does seem to be a satisfactory way of doing it, it creates a problem when that code needs to run on multiple environments where that variable could have different values.

On `production`, you might want to query `https://api.example.com` but `staging` should target \`\`[https://staging.api.example.com\`](https://staging.api.example.com`).

"Hard-coding" the value during prevent us from running the exact same build on different environments with different configurations make the build process undertiministic. Upsun's goal is to run the exact same applications builds on all environment to guarantee the exact same behaviors during testing.

### Injecting different variable values on different environments

In our example, the client application running in the user's browser needs to be able to query a different `API_ENDPOINT` based on the environment it is running in. Let's explore two approaches.

#### Approach 1: Dynamically constructing the URI (If applicable)

The simplest approach, **if your routes structure allows it**, is to dynamically construct the necessary URI in the browser. For example, consider these routes again:

```yaml {filename=".upsun/config.yaml"} theme={null}
routes:
  "https://api.{all}/":
    type: upstream
    upstream: "api:http"
  "https://{all}/":
    type: upstream
    upstream: "next:http"
```

Here, the API endpoint (`api.{all}`) is always on the same base domain as the frontend (`{all}`), just prefixed with `api.`. You could potentially use the browser's current `location.hostname` to figure out the API endpoint:

```ts theme={null}
// Example function to get the API endpoint
export const getAPIEndpoint = (): string => {
  // Check if running server-side (Node.js) where build-time env var might exist
  // Ensure NEXT_PUBLIC_API_ENDPOINT is set during build if needed server-side
  if (typeof window === 'undefined' && process.env.NEXT_PUBLIC_API_ENDPOINT) {
    return process.env.NEXT_PUBLIC_API_ENDPOINT;
  }

  // Check if running in a browser
  if (typeof window !== 'undefined') {
    // Construct the API endpoint from the browser's hostname
    return `https://api.${window.location.hostname}`;
  }

  // Fallback or error if environment is unknown
  throw new Error("Cannot determine API endpoint: Unknown environment.");
};
```

However, this dynamic construction might not always work, especially if you don't control the API endpoint naming structure or if the relationship between frontend and API hostnames is more complex.

#### Approach 2: Using a Deploy Hook and Runtime Configuration File

When dynamic construction isn't suitable, the recommended alternative is to write the necessary environment-specific variables to a JSON configuration file during the `deploy` hook. This hook runs after your application build is complete and deployed to the server, at which point it has access to runtime environment variables, services, and mounts.

Let's assume your project uses an `API_ENDPOINT` environment variable whose value changes per environment (e.g., defined using Upsun's [environment variables features](https://docs.upsun.com/development/variables.html)).

During the `deploy` hook, you can read this variable's value and store it in a publicly accessible JSON file, for example, `variables.json`.

First, ensure you have a writable mount defined in your application configuration where you can store this file:

```yaml {filename=".upsun/config.yaml"} theme={null}
# .upsun/app.yaml or .upsun/config.yaml depending on your setup

# Define a writable mount named 'storage'
mounts:
  'storage':
    source: storage # Use 'local:files/storage' for local storage
    source_path: '' # Optional: subdirectory within the source
```

Next, make this storage location accessible via HTTP so the frontend JavaScript can fetch the file. Configure this in your `web` settings:

```yaml {filename=".upsun/config.yaml"} theme={null}
# .upsun/app.yaml or .upsun/config.yaml

web:
  locations:
    # Make the 'storage' mount publicly readable at /storage
    /storage:
      root: "storage" # Corresponds to the mount name
      passthru: true  # Allow direct access to files
      scripts: false
      allow: true
      expires: -1     # Disable caching or set appropriate headers
```

*Note: Adjust `passthru`, `scripts`, `allow`, and `expires` based on your security and caching needs.*

Finally, add the `deploy` hook to write the environment variable into the JSON file within the mounted directory. The path `/app/storage` typically corresponds to the `storage` mount point inside the container:

```yaml {filename=".upsun/config.yaml"} theme={null}
# .upsun/app.yaml or .upsun/config.yaml

hooks:
  deploy: |
    # Write the environment variable to a JSON file
    printf '{"API_ENDPOINT": "%s"}\\n' "$API_ENDPOINT" > /app/storage/variables.json
```

Your application can then fetch this `/storage/variables.json` file at runtime using a library like `axios` or the native `fetch` API to get the correct `API_ENDPOINT` for the current environment:

```ts theme={null}
// Using native fetch API
fetch('/storage/variables.json')
  .then(response => {
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    return response.json(); // Parses the JSON response body
  })
  .then(data => {
    const apiEndpoint = data.API_ENDPOINT;
    console.log('API Endpoint from fetch:', apiEndpoint);
    // Use the apiEndpoint in your application
  })
  .catch(error => {
    console.error('Error fetching config:', error);
  });

// Using axios (assuming axios is installed and imported)
// import axios from 'axios';

axios.get('/storage/variables.json')
  .then(response => {
    const apiEndpoint = response.data.API_ENDPOINT; // axios automatically parses JSON
    console.log('API Endpoint from axios:', apiEndpoint);
    // Use the apiEndpoint in your application
  })
  .catch(error => {
    console.error('Error fetching config with axios:', error);
  });
```

Choose the method that best suits your project structure and needs. Both methods allows a single build artifact to be deployed across different environments, each retrieving its specific configuration at runtime.

This approach ensures your application build remains deterministic while allowing runtime flexibility for environment-specific settings like API endpoints.


# Run Tailscale on Upsun: Create secure VPN connections for your applications
Source: https://developer.upsun.com/posts/hands-on/run-tailscale-on-upsun-secure-vpn-connections

Learn how to integrate Tailscale VPN with your Upsun applications to create secure, private network connections between your containers and infrastructure.


<PostMeta />

[Tailscale](https://tailscale.com/) is a VPN service that creates secure, private networks between your devices and applications. By integrating Tailscale with your Upsun applications, you can make your containers part of a "tailnet" - Tailscale's term for their private networks.

This guide demonstrates how you can leverage Tailscale to connect to external endpoints over a secure network. An example Go application will be added as a placeholder and example for your own application. This setup enables secure communication between your application and other resources in your tailnet.

## Prerequisites

Before starting, you'll need:

* A [Tailscale](https://tailscale.com/) account with an auth key
* Basic familiarity with Upsun configuration
* Understanding of Go applications

## Tailscale implementation limitations

Tailscale usually relies on a specific tunnel networking device (`tun0`) to route traffic from their machine to their network. Because Upsun run containers directly, a userspace application can't add a new network interface. To work around this limitation, Tailscale can be started as a HTTP proxy to the tailnet. Our example application will connect to the external endpoints via this exposed HTTP proxy.

## Create a basic Go application

Start by creating a simple Go application. Create a `go.mod` file:

```go {filename="go.mod"} theme={null}
module example-app
go 1.25
```

Create a `main.go` file:

```go {filename="main.go"} theme={null}
package main

import (
	"fmt"
	"net/http"
	"os"
)

func main() {
	http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
		w.Write([]byte("Hello, Upsun!"))
	})
	err := http.ListenAndServe(fmt.Sprintf(":%s", os.Getenv("PORT")), nil)
	panic(err)
}
```

Create your initial Upsun configuration in `.upsun/config.yaml`:

```yaml {filename=".upsun/config.yaml"} theme={null}
routes:
  https://{default}:
    type: upstream
    upstream: app:http

applications:
  app:
    type: golang:1.25
    web:
      commands:
        start: ./hello
      locations:
        '/':
          passthru: true
    hooks:
      build: go build -o hello
```

This basic configuration creates a working example Go application on Upsun. You now need to add the Tailscale integration to the project.

## Configure multiple processes with Supervisor

Since Upsun's `web.commands.start` is designed to run only one process, you will use [Supervisor](https://supervisord.org/) to start and manage both your application and the Tailscale daemon processes. Update your `.upsun/config.yaml`:

```yaml {filename=".upsun/config.yaml"} theme={null}
routes:
  https://{default}:
    type: upstream
    upstream: app:http

applications:
  app:
    type: golang:1.25
    dependencies:
      python3:
        supervisor: '*'
    web:
      commands:
        start: supervisord -n -c supervisor.conf
      locations:
        '/':
          passthru: true
    hooks:
      build: go build -o hello
```

Create a `supervisor.conf` file to manage your processes:

```ini {filename="supervisor.conf"} theme={null}
[supervisord]
logfile=/tmp/supervisord.log
nodaemon=true
minfds=1024
pidfile=/tmp/supervisord.pid

[program:hello]
command=/app/hello
process_name=%(program_name)s
autostart=true
autorestart=true
```

## Download and configure Tailscale

The easiest way to run Tailscale is to download and run the `amd64` binary directly. Create a script to download Tailscale and cache it between builds. Create `scripts/download-tailscale.sh`:

```bash {filename="scripts/download-tailscale.sh"} theme={null}
#!/bin/bash

set -e

version=1.86.2

# This uses $PLATFORM_CACHE_DIR to avoid re-downloading the binary on every build
cache="$PLATFORM_CACHE_DIR"/tailscale_"$version"_amd64.tgz

if [ ! -f "$cache" ]; then
    curl https://pkgs.tailscale.com/stable/tailscale_"$version"_amd64.tgz -o "$cache"
fi

tar xf "$cache"
mv tailscale_"$version"_amd64 tailscale
```

Make the script executable:

```bash {filename="Terminal"} theme={null}
chmod +x scripts/download-tailscale.sh
```

Update your build hook in `.upsun/config.yaml` to use this script:

```yaml {filename=".upsun/config.yaml"} theme={null}
applications:
  app:
    # ... rest of configuration ...
    hooks:
      build: |
        set -e
        ./scripts/download-tailscale.sh
        go build -o hello
```

## Add Tailscale daemon to Supervisor

Update your `supervisor.conf` file to include the Tailscale daemon:

```ini {filename="supervisor.conf"} theme={null}
[supervisord]
logfile=/tmp/supervisord.log
nodaemon=true
minfds=1024
pidfile=/tmp/supervisord.pid

[program:hello]
command=/app/hello
process_name=%(program_name)s
autostart=true
autorestart=true

[program:tailscale]
command=/app/tailscale/tailscaled --state=mem: --socket=/tmp/tailscaled.sock --tun=userspace-networking --outbound-http-proxy-listen=0.0.0.0:8080 --socks5-server=0.0.0.0:1080
process_name=%(program_name)s
autostart=true
autorestart=true
```

Key configuration options:

* `--state=mem:` creates a new Tailscale client on each restart. For persistent clients, use a file on a mount instead
* `--outbound-http-proxy-listen=0.0.0.0:8080` exposes the VPN through an HTTP proxy on port 8080
* `--socks5-server=0.0.0.0:1080` provides SOCKS5 proxy access on port 1080

## Connect to your tailnet

After the Tailscale daemon starts, you need to run `tailscale up` to join your tailnet. You could add this to your `post_start` command:

```yaml {filename=".upsun/config.yaml"} theme={null}
applications:
  app:
    # ... rest of configuration ...
    web:
      commands:
        start: supervisord -n -c supervisor.conf
        post_start: /app/tailscale/tailscale --socket="$sock" up --auth-key="$TAILSCALE_AUTHKEY"
```

However, the `tailscaled` daemon needs time to start, causing `tailscale up` to fail. Instead, create a `scripts/tailscale-up.sh` script that waits for the daemon:

```bash {filename="scripts/tailscale-up.sh"} theme={null}
#!/bin/bash

set -xe

sock=/tmp/tailscaled.sock

while ! curl --unix-socket "$sock" localhost -w1; do
    sleep 0.5
done

/app/tailscale/tailscale --socket="$sock" up --auth-key="$TAILSCALE_AUTHKEY"
```

Make this script executable:

```bash theme={null}
chmod +x scripts/tailscale-up.sh
```

And update your Upsun configuration to use this script:

```yaml {filename=".upsun/config.yaml"} theme={null}
applications:
  app:
    # ... rest of configuration ...
    web:
      commands:
        start: supervisord -n -c supervisor.conf
        post_start: ./scripts/tailscale-up.sh
```

## Set up authentication

Create an environment variable with your Tailscale authentication key:

```bash theme={null}
upsun variable:create env:TAILSCALE_AUTHKEY your-auth-key-here
```

Your application container is now part of your tailnet!

## Using your tailnet connection

### Outbound connections

To connect to resources in your tailnet from your application, use the HTTP proxy on port 8080:

```bash theme={null}
# Example with curl
http_proxy=localhost:8080 curl 100.87.175.78
```

As mentioned earlier, our applications needs to configure their HTTP proxy settings to be able to connect to other machines on the tailnet. Refer to the proxy documentation of your specific runtime or framework.

### Inbound connections

Your application becomes immediately accessible from other devices in your tailnet. To expose additional services like databases, use tools like `socat` to forward traffic:

```bash theme={null}
# Forward database traffic (example)
socat tcp-listen:3306,bind=0.0.0.0,fork,reuseaddr tcp:database.internal:3306
```

## Next steps

With Tailscale running on Upsun, you can:

* Connect securely to your application from any device in your tailnet
* Access private databases and services through your application
* Create secure communication channels between multiple Upsun applications
* Implement zero-trust networking for your infrastructure

[Get started with Upsun](https://upsun.com) and create your secure, scalable application infrastructure today.


# Scriberr on Upsun
Source: https://developer.upsun.com/posts/hands-on/scriberr-on-upsun

Learn how to deploy Scriberr, an AI-powered transcription tool, on Upsun for self-hosted audio and video transcription.

<PostMeta />

Scriberr is an AI-powered media transcription and subtitle generation tool. It automatically transcribes video and audio content using advanced speech recognition models, making your content more accessible and searchable.

In this tutorial, you'll deploy a fully working Scriberr instance on Upsun. By the end, you'll have your own private transcription service that you control.

## Prerequisites

Before you begin, make sure you have:

* An [Upsun account](https://auth.upsun.com/register)
* The [Upsun CLI](https://docs.upsun.com/administration/cli.html) installed and authenticated
* [Git](https://git-scm.com/) installed on your local machine

**Resource note**: Scriberr requires substantial resources. You'll need a container with at least 10GB RAM and 40GB disk space. Keep this in mind when reviewing your Upsun plan.

## Why self-host your transcription service?

Commercial transcription services charge per minute of audio. If you're transcribing large amounts of content, those costs add up fast. Self-hosting gives you predictable monthly costs regardless of how much you transcribe.

Privacy is another consideration. When you use external services, your audio files leave your infrastructure. With a self-hosted solution, your recordings never leave your control. This matters for sensitive content like internal meetings, legal recordings, or medical dictation.

You also gain full control over your data. Keep transcriptions as long as you want, organize them however you prefer, and integrate with your own systems without API limitations.

## Understanding the resource requirements

Scriberr runs AI models locally for transcription. These models need significant memory to load and run. The minimum requirement is 10GB RAM, and you'll want 40GB of disk space for the models, temporary files during processing, and your transcription library.

This configuration uses CPU inference rather than GPU. GPU would be faster, but CPU costs less and works well for Scriberr's workflow. You upload files, then check back later for results. The processing time is longer, but you're not waiting in real-time.

The `HIGH_MEMORY` container profile in Upsun allocates the necessary resources for AI workloads. Expect higher hosting costs compared to a typical web application due to these requirements.

## Current limitations

Scriberr is a single-user application with basic access control. You set up an admin username and password on first use. All subsequent access requires those credentials. There's no support for multiple user accounts.

If multi-user support matters to you, consider contributing to the [Scriberr project](https://github.com/rishikanthc/Scriberr).

## Project setup

Start by cloning the example repository:

```bash theme={null}
git clone https://github.com/ralt/scriberr-upsun.git
cd scriberr-upsun
```

The repository structure is minimal. The only configuration you need is in `.upsun/config.yaml`. Scriberr itself gets downloaded during the build process.

## Understanding the Upsun configuration

Here's the complete configuration file:

```yaml {filename=".upsun/config.yaml"} theme={null}
applications:
  scriberr:
    container_profile: HIGH_MEMORY
    type: python:3.11
    hooks:
      build: |
        set -ex
        curl -L https://github.com/rishikanthc/Scriberr/releases/download/v1.2.0/Scriberr_Linux_x86_64.tar.gz | tar xz
    variables:
      env:
        APP_ENV: production
        SECURE_COOKIES: false
        XDG_DATA_HOME: /app/data
        XDG_CONFIG_HOME: /app/data
    dependencies:
      python3:
        uv: "*"
    mounts:
      data:
        source: storage
        source_path: data
      nltk_data:
        source: storage
        source_path: nltk_data
    web:
      upstream:
        socket_family: tcp
        protocol: http
      commands:
        pre_start: ln -s /app/data/uv /tmp/uv
        start: ./scriberr
      locations:
        /:
          passthru: true

routes:
  https://{default}/:
    type: upstream
    upstream: scriberr:http
```

Let's break down the key sections.

### Container profile

```yaml theme={null}
container_profile: HIGH_MEMORY
```

The `HIGH_MEMORY` profile provides the memory allocation needed for AI inference. Standard profiles don't provide enough RAM for the speech recognition models.

### Build hook

```yaml theme={null}
hooks:
  build: |
    set -ex
    curl -L https://github.com/rishikanthc/Scriberr/releases/download/v1.2.0/Scriberr_Linux_x86_64.tar.gz | tar xz
```

During build, this downloads the Scriberr v1.2.0 binary from GitHub releases and extracts it. The binary includes everything needed to run the application.

### Environment variables

```yaml theme={null}
variables:
  env:
    APP_ENV: production
    SECURE_COOKIES: false
    XDG_DATA_HOME: /app/data
    XDG_CONFIG_HOME: /app/data
```

These configure Scriberr's runtime behavior. The `XDG_*` variables direct application data to a persistent mount so your configuration and transcriptions survive deployments.

### Mounts

```yaml theme={null}
mounts:
  data:
    source: storage
    source_path: data
  nltk_data:
    source: storage
    source_path: nltk_data
```

Two persistent mounts store your data between deployments:

* `data`: Stores your transcriptions, configuration, and downloaded AI models
* `nltk_data`: Stores Natural Language Toolkit data used for text processing

### Web configuration

```yaml theme={null}
web:
  upstream:
    socket_family: tcp
    protocol: http
  commands:
    pre_start: ln -s /app/data/uv /tmp/uv
    start: ./scriberr
```

Scriberr runs as an HTTP server. The `pre_start` command creates a symlink that works around a temporary directory issue with uv, the Python package manager. The `start` command runs the Scriberr binary.

## Deploying to Upsun

With the configuration in place, create your Upsun project:

```bash theme={null}
upsun project:create
```

Follow the prompts to name your project and select a region. Then push your code to deploy:

```bash theme={null}
git push upsun main
```

The first deployment takes several minutes. Upsun downloads the Scriberr binary and builds your container. Subsequent deployments are faster since the build cache persists.

Watch the deployment logs to track progress. When you see the deployment succeed message, your application is ready.

## Accessing Scriberr

Get your application URL:

```bash theme={null}
upsun url --primary
```

The first time you access Scriberr, expect a slow response. Scriberr downloads the speech recognition models on first use. This happens once and the models persist in your data mount. Depending on the model size, this initial download takes a few minutes.

After the download completes, you'll see the Scriberr interface. You can then upload audio or video files for transcription.

## Conclusion

You now have a private transcription service running on your own infrastructure. Upload audio or video files, and Scriberr generates accurate transcriptions using AI speech recognition.

Your transcriptions stay on your infrastructure. You control the data retention and access. And your costs are predictable regardless of transcription volume.

For more details on Scriberr's features and configuration options, see the [Scriberr documentation](https://scriberr.app/).

<Note>
  Ready to deploy your own AI-powered services? [Start your free Upsun trial](https://upsun.com/) and get your applications running in minutes.
</Note>


# Stop testing JCR apps in production
Source: https://developer.upsun.com/posts/hands-on/stop-testing-jcr-apps-in-production

Learn why JCR-based applications benefit from fast, production-grade environment cloning. Discover how Upsun removes one of JCR's biggest operational challenges through instant repository duplication.


<PostMeta />

If you've worked with JCR implementations like Apache Jackrabbit, Adobe Experience Manager, or Magnolia, you know the pain. Your production repository is a complex, stateful beast with hierarchical nodes, years of version history, and cascading ACLs. When you need to debug or test a migration, you're either exporting CSV files at 3 AM or testing in production.

Here's why JCR is different: repositories are stateful, hierarchical, and behavior-rich in ways that can't be partially reproduced. [Upsun's fast environment cloning](https://upsun.com/product/) removes this operational pain by making full repository duplication part of your normal workflow.

## JCR repositories aren't "content tables"

With a relational database, you can export the schema, add sample rows, and call it done. JCR doesn't work like that.

A JCR repository contains hierarchical nodes with types and mixins, version histories, ACLs with inheritance, strong and weak references, workflow state, and asynchronous indexes. It's a graph database with content management semantics baked in.

You can't export a subset without breaking path-based access. You can't fake production with seed data because relationships matter as much as content. Schema-only copies are useless when half the behavior lives in the structure itself.

Fast cloning gives you real behavior parity.

## Partial environments break everything

Missing ancestor nodes break path-based access. Missing users break ACL resolution. Incomplete version history breaks rollback. Missing references break rendering.

Teams face two bad options: test in production (risky) or accept that staging "kind of" works (expensive bugs).

Instant cloning fixes this. You get a complete copy with all nodes, references, ACLs, and history. Your staging environment isn't an approximation. It's production with a different URL.

## Workflows need real content

AEM, Magnolia, and Bloomreach rely on long-lived workflow nodes, content lifecycle metadata, authoring vs publish states, and version comparisons. These aren't things you can fake with seed data.

With fast cloning, editors test on real content, developers debug actual edge cases, and QA validates rollback operations with confidence. You can't anticipate every weird node structure production throws at you. With a clone, you don't have to.

## Migrations are risky without full repos

Migrating from Jackrabbit to Oak, changing index definitions, or evolving node types requires the full repository structure, real content volume, and actual version history.

With Upsun you can clone, migrate, validate, and discard without touching production. Run parallel dry runs to compare approaches. Rehearse until you're confident.

For enterprise teams, this is the difference between planned maintenance and emergency recovery.

## Performance debugging needs real scale

JCR performance issues depend on path depth, node fan-out, version history size, and index selectivity. A query that runs in milliseconds locally might take seconds in production.

Small staging repos lie. Fast cloning lets you tune indexes against real structures, optimize queries with realistic costs, and load test without production risk.

## Why this matters more for JCR

Let's compare staging strategies across different CMS architectures:

* **Relational databases**: You can get away with schema plus sample data. Cloning is nice but (usually) not critical.
* **Headless CMSs**: API mocks work fine for most testing. Cloning adds minimal value.
* **Git-based CMSs**: Content is already in version control. Branches are your cloning mechanism.
* **JCR**: It's full repository or bust. Partial data breaks everything.

Upsun shines where state is complex, history matters, and structure is implicit rather than declared. That's JCR in a nutshell.

## What this means for you

Engineers can stop writing brittle export scripts and debugging in production. Platform teams can treat JCR environments as disposable and reproducible instead of fragile. Editors and QA work with real content, reducing regression risk.

JCR doesn't have to be operationally painful. With the right platform, it's another architecture you deploy, clone, and manage like anything else.


# Store embeddings in chroma with persistent storage (nodejs and python examples)
Source: https://developer.upsun.com/posts/hands-on/store-embeddings-in-chroma-with-persistent-storage-nodejs-and-python-examples

Learn how to implement Chroma with persistent storage on Upsun using both Node.js and Python, including document ingestion and embedding storage.

<PostMeta />

[Chroma](https://www.trychroma.com/) is an open-source vector database designed for AI applications that need to store, query, and manage embeddings efficiently. This tutorial demonstrates how to deploy Chroma with persistent storage on Upsun, along with both Python and Node.js client applications that can ingest documents and store their embeddings.

<Info>
  The complete source code for this tutorial is available on GitHub: [upsun/tutorial-chromadb](https://github.com/upsun/tutorial-chromadb). You can clone this repository and deploy it directly to Upsun.
</Info>

## Why Chroma?

Chroma excels in several use cases:

* **Semantic Search**: Find documents based on meaning rather than exact keyword matches
* **Retrieval Augmented Generation (RAG)**: Enhance LLMs with relevant context from your knowledge base
* **Recommendation Systems**: Build similarity-based recommendation engines
* **Content Classification**: Automatically categorize documents based on their semantic content
* **Duplicate Detection**: Identify similar or duplicate content across large document collections

## Architecture Overview

```mermaid theme={null}
graph LR
    subgraph "Upsun Platform"
        subgraph "Applications"
            PY[Python App<br/>Flask + uv]
            NODE[Node.js App<br/>Express + TypeScript]
            CHROMA[Chroma Server<br/>Vector Database]
        end
        
        subgraph "Storage"
            STORAGE[(Persistent Storage<br/>.db & .chroma)]
        end
        
        subgraph "External Services"
            OPENAI[OpenAI API<br/>Embeddings]
        end
    end
    
    subgraph "Routes"
        PYROUTE[python.domain.com]
        NODEROUTE[nodejs.domain.com]
    end
    
    %% Connections
    PY -.->|HTTP| CHROMA
    NODE -.->|HTTP| CHROMA
    CHROMA --> STORAGE
    PY -->|API calls| OPENAI
    NODE -->|API calls| OPENAI
    
    PYROUTE --> PY
    NODEROUTE --> NODE
    
    %% Styling with Upsun colors
    classDef primary fill:#D0F302,stroke:#000,stroke-width:2px,color:#000
    classDef secondary fill:#6046FF,stroke:#000,stroke-width:2px,color:#fff
    classDef storage fill:#fff,stroke:#000,stroke-width:2px,color:#000
    classDef external fill:#f9f9f9,stroke:#000,stroke-width:1px,color:#000
    
    class PY,NODE,CHROMA primary
    class PYROUTE,NODEROUTE secondary
    class STORAGE,OPENAI storage
```

Our setup includes three applications:

1. **Chroma Server**: The vector database with persistent storage
2. **Python Application**: Uses [uv](https://docs.upsun.com/languages/python.html#python-should-switch-to-uv) for dependency management and Flask for the web interface
3. **Node.js Application**: TypeScript-based Express server

Both client applications can ingest markdown documents, generate embeddings using OpenAI's API, and store them in Chroma.

## Chroma configuration on Upsun

The `.upsun/config.yaml` file defines our multi-applications setup. Let's start with the Chroma server configuration:

```yaml {filename=".upsun/config.yaml"} theme={null}
applications:
  chroma:
    type: "python:3.12"
    source:
      root: "chroma"
    dependencies:
      python3:
        uv: "*"
    
    hooks:
      build: |
        uv init
        uv add chromadb
        
    web:
      commands:
        start: "uv run --no-sync chroma run --host 0.0.0.0 --port $PORT --path /app/.db"

    mounts:
      ".db":
        source: "storage"
        source_path: "db"
      ".chroma":
        source: "storage"
        source_path: "chroma"

    variables:
      env:
        uv_CACHE_DIR: "/tmp/uv-cache"
        PYTHONPATH: "."
```

Key configuration points for Chroma:

* **Persistent Storage**: Chroma uses mounted volumes to persist data between deployments
* **uv Integration**: Uses uv for fast, reliable dependency management
* **Internal Access**: Other applications connect via internal networking

Note that Chroma doesn't have a public HTTP endpoint, it's only accessible internally within the Upsun platform. The Python and Node.js applications will establish relationships to Chroma through their respective configurations, allowing them to connect to the vector database using the internal `chroma.internal` hostname.

## Python implementation

The Python application uses uv for dependency management and includes both ingestion and web interface capabilities.

### Upsun configuration

```yaml {filename=".upsun/config.yaml"} theme={null}
  python-app:
    source:
      root: "python-app"
    type: "python:3.12"
    dependencies:
      python3:
        uv: "*"
    
    hooks:
      build: |
        uv sync --frozen
      deploy: |
        uv run --no-sync python ingest.py
        
    web:
      commands:
        start: "uv run --no-sync uvicorn main:main --reload --host 0.0.0.0 --port $PORT"
    
    relationships:
      chroma: chroma:http
    
    variables:
      env:
        uv_CACHE_DIR: "/tmp/uv-cache"
        PYTHONPATH: "."
```

The Python app route configuration:

```yaml {filename=".upsun/config.yaml"} theme={null}
routes:
  "https://python.{default}/":
    type: upstream
    upstream: "python-app:http"
```

### Document ingestion

The ingestion script processes markdown files and stores their embeddings:

```python {filename="python-app/ingest.py"} theme={null}
import os
import glob
import chromadb
from openai import OpenAI
from typing import List, Dict
import hashlib

def read_markdown_files(data_dir: str = "data") -> List[Dict[str, str]]:
    """Read all markdown files from the data directory."""
    md_files = glob.glob(os.path.join(data_dir, "*.md"))
    documents = []
    
    for file_path in md_files:
        with open(file_path, 'r', encoding='utf-8') as file:
            content = file.read()
            documents.append({
                "content": content,
                "filename": os.path.basename(file_path),
                "filepath": file_path
            })
    
    return documents

def chunk_text(text: str, chunk_size: int = 1000, overlap: int = 200) -> List[str]:
    """Split text into overlapping chunks."""
    words = text.split()
    chunks = []
    
    for i in range(0, len(words), chunk_size - overlap):
        chunk = " ".join(words[i:i + chunk_size])
        if chunk.strip():
            chunks.append(chunk)
    
    return chunks

def get_chroma_client():
    """Create Chroma client based on environment variables."""
    chroma_host = os.getenv("CHROMA_HOST")
    chroma_port = os.getenv("CHROMA_PORT", "8000")
    chroma_ssl = os.getenv("CHROMA_SSL", "false").lower() == "true"
    chroma_headers = {}
    
    if os.getenv("CHROMA_AUTH_TOKEN"):
        chroma_headers["Authorization"] = f"Bearer {os.getenv('CHROMA_AUTH_TOKEN')}"
    
    if chroma_host:
        return chromadb.HttpClient(
            host=chroma_host,
            port=int(chroma_port),
            ssl=chroma_ssl,
            headers=chroma_headers
        )
    else:
        return chromadb.Client()

def ingest_documents(data_dir: str = "data", collection_name: str = "python-app"):
    """Main ingestion function."""
    openai_client = OpenAI()
    chroma_client = get_chroma_client()
    
    # Get or create collection
    try:
        collection = chroma_client.get_collection(name=collection_name)
        collection.delete()
    except Exception:
        collection = chroma_client.create_collection(name=collection_name)
    
    # Process documents
    documents = read_markdown_files(data_dir)
    all_chunks = []
    all_metadatas = []
    all_ids = []
    
    for doc in documents:
        chunks = chunk_text(doc['content'])
        
        for i, chunk in enumerate(chunks):
            all_chunks.append(chunk)
            all_metadatas.append({
                "filename": doc['filename'],
                "filepath": doc['filepath'],
                "chunk_index": i,
                "total_chunks": len(chunks)
            })
            content_hash = hashlib.md5(chunk.encode()).hexdigest()[:8]
            all_ids.append(f"{doc['filename']}_{i}_{content_hash}")
    
    # Generate embeddings and store
    batch_size = 100
    all_embeddings = []
    
    for i in range(0, len(all_chunks), batch_size):
        batch_chunks = all_chunks[i:i + batch_size]
        response = openai_client.embeddings.create(
            model="text-embedding-3-small",
            input=batch_chunks
        )
        batch_embeddings = [embedding.embedding for embedding in response.data]
        all_embeddings.extend(batch_embeddings)
    
    collection.add(
        documents=all_chunks,
        metadatas=all_metadatas,
        ids=all_ids,
        embeddings=all_embeddings
    )
    
    print(f"Successfully ingested {len(all_chunks)} chunks")
```

### Flask web interface

The main application provides a web interface to view stored documents:

```python {filename="python-app/main.py"} theme={null}
import os
import chromadb
from flask import Flask, render_template_string
from collections import defaultdict

app = Flask(__name__)

def get_chroma_client():
    """Create Chroma client based on environment variables."""
    chroma_host = os.getenv("CHROMA_HOST")
    chroma_port = os.getenv("CHROMA_PORT", "8000")
    chroma_ssl = os.getenv("CHROMA_SSL", "false").lower() == "true"
    chroma_headers = {}
    
    if os.getenv("CHROMA_AUTH_TOKEN"):
        chroma_headers["Authorization"] = f"Bearer {os.getenv('CHROMA_AUTH_TOKEN')}"
    
    if chroma_host:
        return chromadb.HttpClient(
            host=chroma_host,
            port=int(chroma_port),
            ssl=chroma_ssl,
            headers=chroma_headers
        )
    else:
        return chromadb.Client()

@app.route('/')
def list_files():
    try:
        chroma_client = get_chroma_client()
        collection = chroma_client.get_collection(name="python-app")
        
        result = collection.get()
        metadatas = result['metadatas']
        
        if not metadatas:
            return render_template_string(HTML_TEMPLATE, 
                                        error="No documents found. Run ingest.py first.")
        
        # Group chunks by filename
        file_chunks = defaultdict(int)
        for metadata in metadatas:
            filename = metadata.get('filename', 'Unknown')
            file_chunks[filename] += 1
        
        files = []
        for filename, chunk_count in sorted(file_chunks.items()):
            files.append({
                'filename': filename,
                'chunk_count': chunk_count
            })
        
        return render_template_string(HTML_TEMPLATE,
                                    files=files,
                                    total_files=len(files),
                                    total_chunks=sum(file_chunks.values()))
    except Exception as e:
        return render_template_string(HTML_TEMPLATE, 
                                    error=f"Error: {str(e)}")
```

## Node.js implementation

The Node.js application uses TypeScript and Express, with similar document ingestion capabilities.

### Upsun configuration

```yaml {filename=".upsun/config.yaml"} theme={null}
  nodejs-app:
    source:
      root: "nodejs-app"
    type: nodejs:22
    
    web:
      commands:
        start: "npm run start"
    
    hooks:
      build: |
        npm ci
        npm run build
      deploy: |
        npm run ingest
    
    relationships:
      chroma: chroma:http
```

The Node.js app route configuration:

```yaml {filename=".upsun/config.yaml"} theme={null}
routes:
  "https://nodejs.{default}/":
    type: upstream
    upstream: "nodejs-app:http"
```

### TypeScript ingestion script

```typescript {filename="nodejs-app/src/ingest.ts"} theme={null}
import { ChromaClient, OpenAIEmbeddingFunction } from 'chromadb';
import OpenAI from 'openai';
import { readFileSync } from 'fs';
import { glob } from 'glob';
import path from 'path';
import { createHash } from 'crypto';

function getChromaClient(): ChromaClient {
  const chromaHost = process.env.CHROMA_HOST;
  const chromaPort = parseInt(process.env.CHROMA_PORT || '8000');
  const chromaSsl = process.env.CHROMA_SSL?.toLowerCase() === 'true';
  
  if (chromaHost) {
    const auth = process.env.CHROMA_AUTH_TOKEN 
      ? { provider: 'token', credentials: process.env.CHROMA_AUTH_TOKEN }
      : undefined;
    
    return new ChromaClient({
      path: `http${chromaSsl ? 's' : ''}://${chromaHost}:${chromaPort}`,
      auth
    });
  } else {
    return new ChromaClient();
  }
}

export async function ingestDocuments(dataDir: string = 'data', collectionName: string = 'nodejs-app'): Promise<void> {
  const openaiClient = new OpenAI({
    apiKey: process.env.OPENAI_API_KEY
  });
  const chromaClient = getChromaClient();
  
  const embedder = new OpenAIEmbeddingFunction({
    openai_api_key: process.env.OPENAI_API_KEY!,
    openai_model: 'text-embedding-3-small'
  });
  
  // Get or create collection
  let collection;
  try {
    collection = await chromaClient.getCollection({ 
      name: collectionName,
      embeddingFunction: embedder
    });
    await collection.delete();
  } catch (error) {
    collection = await chromaClient.createCollection({ 
      name: collectionName,
      embeddingFunction: embedder
    });
  }
  
  // Read and process documents
  const mdFiles = glob.sync(path.join(dataDir, '*.md'));
  const allChunks: string[] = [];
  const allMetadatas: any[] = [];
  const allIds: string[] = [];
  
  for (const filePath of mdFiles) {
    const content = readFileSync(filePath, 'utf-8');
    const chunks = chunkText(content);
    
    for (let i = 0; i < chunks.length; i++) {
      const chunk = chunks[i];
      allChunks.push(chunk);
      allMetadatas.push({
        filename: path.basename(filePath),
        filepath: filePath,
        chunk_index: i,
        total_chunks: chunks.length
      });
      
      const contentHash = createHash('md5').update(chunk).digest('hex').substring(0, 8);
      allIds.push(`${path.basename(filePath)}_${i}_${contentHash}`);
    }
  }
  
  // Store in Chroma
  await collection.add({
    documents: allChunks,
    metadatas: allMetadatas,
    ids: allIds
  });
  
  console.log(`Successfully ingested ${allChunks.length} chunks`);
}
```

### Express web server

```typescript {filename="nodejs-app/src/index.ts"} theme={null}
import express from 'express';
import { ChromaClient, OpenAIEmbeddingFunction } from 'chromadb';

const app = express();

function getChromaClient(): ChromaClient {
  const chromaHost = process.env.CHROMA_HOST;
  const chromaPort = parseInt(process.env.CHROMA_PORT || '8000');
  const chromaSsl = process.env.CHROMA_SSL?.toLowerCase() === 'true';
  
  if (chromaHost) {
    const auth = process.env.CHROMA_AUTH_TOKEN 
      ? { provider: 'token', credentials: process.env.CHROMA_AUTH_TOKEN }
      : undefined;
    
    return new ChromaClient({
      path: `http${chromaSsl ? 's' : ''}://${chromaHost}:${chromaPort}`,
      auth
    });
  } else {
    return new ChromaClient();
  }
}

app.get('/', async (req, res) => {
  try {
    const chromaClient = getChromaClient();
    const embedder = new OpenAIEmbeddingFunction({
      openai_api_key: process.env.OPENAI_API_KEY!,
      openai_model: 'text-embedding-3-small'
    });
    
    const collection = await chromaClient.getCollection({ 
      name: 'nodejs-app',
      embeddingFunction: embedder
    });
    
    const result = await collection.get();
    const metadatas = result.metadatas;
    
    if (!metadatas || metadatas.length === 0) {
      const errorContent = `<div class="error">No documents found. Run npm run ingest first.</div>`;
      return res.send(HTML_TEMPLATE.replace('{{CONTENT}}', errorContent));
    }
    
    // Group and display file statistics
    const fileChunks = new Map();
    for (const metadata of metadatas) {
      const filename = metadata?.filename || 'Unknown';
      fileChunks.set(filename, (fileChunks.get(filename) || 0) + 1);
    }
    
    // Generate HTML content
    let content = `<div class="total"><strong>Total Files:</strong> ${fileChunks.size}<br><strong>Total Chunks:</strong> ${metadatas.length}</div>`;
    
    for (const [filename, chunkCount] of Array.from(fileChunks.entries()).sort()) {
      content += `<div class="file-item"><div class="file-name">📄 ${filename}</div><div class="chunk-count">${chunkCount} chunks</div></div>`;
    }
    
    res.send(HTML_TEMPLATE.replace('{{CONTENT}}', content));
    
  } catch (error) {
    const errorContent = `<div class="error">Error: ${error.message}</div>`;
    res.send(HTML_TEMPLATE.replace('{{CONTENT}}', errorContent));
  }
});
```

## Deployment

To deploy this setup:

1. **Clone the repository**:
   ```bash {filename="Terminal"} theme={null}
   git clone https://github.com/upsun/tutorial-chromadb.git
   cd tutorial-chromadb
   ```

2. **Create a new Upsun project**:
   ```bash {filename="Terminal"} theme={null}
   upsun create
   ```

3. **Set up the OpenAI environment variable**:
   ```bash {filename="Terminal"} theme={null}
   upsun variable:create -e main --level project --name OPENAI_API_KEY --value "your-openai-key"
   ```

4. **Deploy to Upsun**:
   ```bash {filename="Terminal"} theme={null}
   upsun deploy
   ```

The deployment process will:

* Set up the Chroma server with persistent storage
* Build and deploy both Python and Node.js applications
* Automatically run document ingestion during deployment
* Configure internal networking between applications

The `deploy` hook injests the data for both apps:

```bash {filename="Terminal"} theme={null}
Executing deploy hook for application nodejs-app
    
    > nodejs-app@0.1.0 ingest
    > node dist/ingest.js
    
    Created new collection: nodejs-app
    Found 13 markdown files
    Processing: why-python-developers-should-switch-to-uv.md
      Created 2 chunks
    [...]
    Total chunks to process: 36
    Storing in ChromaDB...
    Successfully ingested 36 chunks into collection 'nodejs-app'
```

You can now access your deployed applications with the endpoint displayed in the CLI or the console.

### Python app:

<img alt="Python app" />

### Node.js app:

<img alt="Node.js app" />

Both applications will display the ingested documents and their chunk counts, demonstrating successful embedding storage in Chroma with persistent storage across deployments.


# That cron should be a worker
Source: https://developer.upsun.com/posts/hands-on/that-cron-should-be-a-worker

Long-running crons block your deployments, steal resources from your app container, and create support tickets. Here's when to use workers instead.


<PostMeta />

You've pushed a new feature hours ago, but the push activity still says it's in "pending" state. The activity log shows `Waiting for other activities to complete`. What exactly is the push waiting on? Nine out of ten times, it's a cron.

## Diagnosing the problem

When you have activities that aren't proceeding, you first need to identify what exactly is keeping everything stuck. In the Console you can see a list of all activities that are Running and Pending.

The CLI can also give you an overview:

```bash theme={null}
upsun activity:list --incomplete
```

```text theme={null}
+---------------+---------------------------+---------------------------------------------------+----------+-------------+--------+----------------+
| ID            | Created                   | Description                                       | Progress | State       | Result | Environment(s) |
+---------------+---------------------------+---------------------------------------------------+----------+-------------+--------+----------------+
| o42d2e53kaovq | 2024-03-05T03:08:53+00:00 | Platform.sh Bot created a backup of Master        | 0%       | pending     |        | master         |
| luowvmcyr3dt4 | 2024-03-04T13:05:12+00:00 | Platform.sh Bot ran cron send-publisher-email     | 0%       | pending     |        | master         |
| huak2o4ytoxjo | 2024-03-04T12:50:12+00:00 | Platform.sh Bot ran cron send-publisher-sugar-crm | 0%       | pending     |        | master         |
| xsr4ncsbvnfpu | 2024-03-04T12:50:12+00:00 | Platform.sh Bot ran cron send-publisher-email     | 0%       | in progress |        | master         |
+---------------+---------------------------+---------------------------------------------------+----------+-------------+--------+----------------+
```

Notice there's only one activity in progress. The rest are all waiting on their turn.

To figure out what that cron is doing, you have to dig a little deeper.

**Check the cron output first.** Open the activity log in the Upsun Console and find the cron execution entry. It captures all the stdout and stderr output from your cron scripts. You might see something like "Processing record 40 of 100" and realize it's still working through a batch. Or you might see the same error repeating in a loop, which tells you the cron is stuck and safe to kill.

**List processes.** SSH into the environment and run `ps faux` to see what's running. Crons tend to show up near the top. Check the CPU and memory usage columns: if both are at zero, the process is likely stuck waiting on something rather than actively processing data.

**Use strace for the brave.** If you want to know exactly what a process is doing at the system call level, `strace -p <pid>` will show you. If it's spamming write calls, it's actively doing work. If it's sitting on a single `read` call going nowhere, it's probably stuck. This is power-user territory, but it's often enough to tell you whether it's safe to pull the plug.

**Kill the cron.** Once you've decided the cron can be interrupted, you have two options. From the Console, use the "cancel activity" button on the cron entry. From the command line, SSH into the environment and kill the process directly with `kill <pid>`. Either way, the queued activities will start proceeding once the cron is gone.

## Why crons block deployments

On Upsun, a cron and a deployment can't run at the same time on the same environment. The platform waits for your cron to finish before it starts deploying.

The reason is pretty pragmatic. A cron runs your code, and that code is often modifying data: updating database records, writing to the file system, processing files. If the platform killed it at 50% completion, you could end up with corrupt database entries or half-written files. Since the platform can't know whether your cron is safe to interrupt (it's your code, after all), it errs on the side of not destroying your data.

That's a reasonable trade-off until your cron takes 45 minutes and you're trying to ship a hotfix.

## Preventing is better than curing

If there's one thing you take away from this article, let it be this: set a `shutdown_timeout` on your crons.

In your `.upsun/config.yaml`, you can specify how long a cron is expected to run. If it exceeds that duration, the platform sends a `SIGTERM` to the process, giving it 10 seconds to clean up before sending `SIGKILL`. Without a shutdown timeout, crons can run indefinitely, and your deployments will wait indefinitely too.

Think about how long your cron should reasonably take, then set the timeout a bit higher. If you expect it to finish in 5 minutes, set the timeout to 15 minutes. That gives you a safety net without being so tight that normal variance triggers a kill.

You might have seen older recommendations to use the Linux `timeout` command in your cron script. Don't do that. The YAML-based `shutdown_timeout` is the better approach because it integrates with the platform's lifecycle management and lets you define the stop command that should be run to gracefully terminate your process. See the [cron commands documentation](https://fixed.docs.upsun.com/create-apps/image-properties/crons.html#cron-commands) for configuration details.

## Should this be a cron at all?

Crons have been around for decades, and most of us reach for them out of habit. But it's 2026, and if your cron runs every 5 or 10 minutes, what you actually have is a worker pretending to be a cron.

Think about what happens every time a cron fires. The platform spins up the process, bootstraps your entire application framework, does some work, tears everything down, and then 5 minutes later does it all over again. That's a lot of overhead for something that could be a single long-running process checking a queue.

It gets worse when your cron takes longer than its interval. If you have a cron set to run every 5 minutes but it takes 10 minutes to complete, the next run can't start until the first one finishes. So instead of running every 5 minutes, it runs back to back with no gap. At that point you've accidentally created the world's least efficient worker.

And crons aren't free, even though they might look that way. They run inside your app container, sharing CPU and memory with the processes serving your web users. A heavy cron can degrade your site's performance or, in extreme cases, cause outages. Moving that workload to a dedicated worker container keeps your app container focused on what it's supposed to do: serve web requests. See the [workers vs cron jobs documentation](https://docs.upsun.com/create-apps/workers.html#workers-vs-cron-jobs) for a detailed comparison.

## Workers handle deployments better too

When Upsun needs to deploy new code, it sends a `SIGTERM` to your worker process, giving it 30 seconds to finish what it's doing and shut down gracefully. Your worker can catch that signal, wrap up its current task, and exit cleanly. Then the platform deploys the new code and starts the worker again.

Compare that with crons, where the platform has no choice but to sit and wait for the cron to finish on its own. Workers give you a controlled shutdown mechanism; crons give you a "please finish whenever you're ready."

## When crons are fine

Crons aren't evil. They're a poor fit for frequent, long-running tasks, but they're perfectly reasonable for things that happen infrequently and finish quickly.

A monthly cleanup script that takes 30 seconds? Great cron. A weekly report generation that runs for a minute? Perfectly fine. Something that needs to happen at a specific calendar time and doesn't do heavy processing? That's what crons are for.

The line gets blurry somewhere around the hourly mark. If something runs every hour, it might not be worth spinning up a worker for it. But if you find yourself reaching for crons that run every few minutes, that's a worker. No ambiguity there.

One hybrid approach: keep your crons, but make them short. Instead of having a cron that processes 10,000 records, have the cron push a message to a queue and return immediately. A worker picks up the message and does the heavy lifting. Your cron takes milliseconds instead of minutes, and your deployments stay unblocked. For a deeper look at the queue-based approach, see [Unstable website? Use queues](/posts/hands-on/unstable-website-use-queues).

## Framework schedulers: the modern alternative

Many frameworks ship with built-in schedulers that blur the line between crons and workers in a good way. Laravel's task scheduler and Symfony's Scheduler component both let you define scheduled tasks in your application code rather than in YAML configuration.

You run a single worker process that acts as a scheduler. It sits there in a loop, checking the clock, and fires off tasks at the times you've defined. From the platform's perspective, it's a worker. From your perspective, it feels like crons, but all the scheduling logic lives in your codebase where it belongs, not in infrastructure configuration.

## The short version

If you're seeing a lot of activities waiting, they're most likely waiting on crons.

* Diagnose the problem with `upsun activity:list --incomplete`.
* At a bare minimum, add `shutdown_timeout` values to your cron configuration.
* For anything that runs frequently or takes more than a few minutes, move it to a worker.


# From DrupalCon keynote to live Upsun demo: the real story of setting up Drupal Canvas with AI
Source: https://developer.upsun.com/posts/hands-on/the-real-story-of-setting-up-drupal-canvas-with-ai

Discover how the Lemberg Solutions team set up Drupal Canvas with an AI
assistant: how long it took, the challenges we faced and lessons we learned. 


<PostMeta />

At [DrupalCon Vienna 2025](https://dri.es/state-of-drupal-presentation-october-2025), Dries Buytaert presented a big new feature: Drupal Canvas.
It is a visual page builder in Drupal that allows users to drag and drop to design layouts without touching templates or code.

At [Lemberg Solutions](https://lembergsolutions.com/), we wanted to try it out and show its capabilities to clients as quickly as possible. Instead of setting it up locally, we decided to deploy it live on Upsun (formerly Platform.sh), so anyone could open it in a browser and explore it firsthand.

In this article, we will take you through a step-by-step process, highlight the issues we faced, share the lessons we learned, and reveal how long this task actually took.

# **How our journey looked like: Step-by-step process**

## **Step 1: Write a detailed prompt for AI code generation**

We started in the Cursor IDE with a simple prompt for AI, asking it to act as a senior Drupal and DevOps engineer. We provided all the details that the AI assistant needed to prepare a demo environment. Below, you can see our prompt:

```shell theme={null}
You are a senior Drupal + DevOps engineer helping me prepare a client-facing demo environment for Drupal Canvas on Upsun (formerly Platform.sh).

Drupal Canvas was presented as a major new visual page-building feature in Dries Buytaert’s “State of Drupal” keynote at DrupalCon Vienna 2025.

There is an official demo project here:

        Blog post: https://dri.es/state-of-drupal-presentation-october-2025
        Demo repo: https://github.com/phenaproxima/canvas-demo

I want to adapt this demo to Upsun so that I can spin up short-lived demo environments for clients (preview links), not build a real production site.
```

<img alt="AI prompt in Cursor IDE" />

### **Problem #1: The wrong package**

The first issue we faced is that our AI assistant picked up outdated information and used the wrong Composer package name. Specifically, it installed `drupal/experience_builder` instead of `drupal/canvas`.

This happened because during DrupalCon, the module was still referred to as "Experience Builder" in some places, which confused the tool. Using the wrong package can lead to serious compatibility issues later.

**Lesson learned:** Always double-check Composer package names on drupal.org before hitting “Deploy.” AI knowledge isn’t always up to date, so it can rely on irrelevant and old data. A quick manual check can save hours of debugging.

## **Step 2: Check project structure**

After AI created the Drupal structure, ready for Upsun deployment, we spent some time ensuring that the structure of the project had all the needed files. Our final files and folder structure looked like this:

<img alt="Final project structure" />

### **Problem #2: Excessive output from AI**

Our AI assistant wanted to be helpful, but went overboard — during the process, it generated 18 extra files. For a quick demo, all we needed was a single README. But it created eight documentation files, multiple setup scripts, and even a “Quickstart Guide” for tools we never planned to use.

**Lesson learned:** When prompting AI, be crystal clear about your intent and what the AI tool should deliver. Don’t say “set up Drupal Canvas on Upsun”, instead, say “set up Drupal Canvas on Platform.sh with DDEV, one README, minimal structure.”

<img alt="Redundant files generated by AI that were deleted in the end" />

## **Step 3: Check platform configurations**

Our project configuration originally lived in .upsun/config.yaml. It defined a single PHP application with a MariaDB service and pointed web/ as the document root. That’s where the next issue appeared.

### **Problem #3: Platform.sh vs Upsun: name confusion**

Since Platform.sh recently rebranded to Upsun, the AI tool was confused and treated them as two separate platforms. As a result, it created two setups: **Upsun files in .upsun/config.yaml and Platform.sh files in .platform.app.yaml**, along with the entire **.platform/ directory**. To avoid confusion and duplication, we manually deleted one set of files.

**Lesson learned:** Check your git remote and ensure that your project configuration matches the platform you are actually deploying to. Rebrands might confuse AI.

## **Step 4: Build and deploy hooks**

We added simple hooks that allow the site to install itself automatically during deployment. Now, every new environment on Upsun builds a fresh Drupal Canvas instance, with no manual configuration setup required.

```
deploy: |

    set -eux

    # Check if site is already installed

    if ! vendor/bin/drush status bootstrap 2>/dev/null | grep -q 

"Successful"; then

      echo "Installing Drupal site..."

      vendor/bin/drush site:install standard \

        --site-name="Drupal Canvas Demo" \
        --yes

      echo "Enabling Drupal Canvas module..."

      vendor/bin/drush pm:enable canvas --yes

      echo "Site installed successfully!"

    else

    echo "Site already installed, running updates..."

      vendor/bin/drush updatedb --yes
      vendor/bin/drush config:import --yes || true
      vendor/bin/drush cache:rebuild
    fi

    echo "Deployment complete!"
```

### **Problem #4: Wrong Drupal profile**

On the first deployment, we noticed that the AI generated the wrong installation profile name. It tried to install canvas\_demo profile, which doesn’t exist.

**Lesson learned:** After this failure, we switched the installation command to use the standard profile and then explicitly enabled the canvas module inside the deploy hook. That small fix finally made the deployment fully automated and reliable.

<img alt="Platform.sh build log showing “The profile canvas_demo does not exist” error" />

### **The final result**

After all the iterations and fixes, we ended up with a clean, lightweight Drupal Canvas demo, deployed on Upsun and running locally with DDEV. While we didn’t get instant success, now, after several iterations, the demo finally works reliably, and it’s easy to reuse for client demos.

<img alt="Final Drupal Canvas page on Upsun" />

What was the actual timeline for development?
Here is a clear breakdown of the time we spent setting up the Drupal Canvas demo:

| Phase | Time | Key actions |
| :- | :- | :- |
| Initial setup | 3 min | AI-generated base configs |
| First deploy errors | 10 min | Config + permission fixes |
| Docker troubleshooting | 15 min | Build failures, switched tools |
| DDEV migration | 7 min | Migration completed successfully |
| Wrong package fix | 20 min | Replaced experience\_builder with canvas |
| Cleanup & simplification | 30 min | Deleted docs, folders, cleaned git, final review |
| **Total time** | **1 h 25 min** | **From start to stable demo** |

All in all, AI wrote the initial configurations in about 20 minutes. However, 70% of the work still fell on the human developers, who spent nearly an hour reviewing, fixing, and simplifying the code.

# **Key takeaways**

Working with the AI assistant revealed to us several critical lessons that we want to share.
First, start small and keep it simple. The best way to cooperate with the AI tool is to give well-defined and simple tasks at the beginning. Slowly add complexity within the time. This helps AI to be more accurate and keeps developers from getting stuck on task details.

Second, provide not only context but also concrete examples. If you think you shared enough context at the start, for better results, you may need to write more follow-up prompts with clear examples. This will allow the AI assistant to understand your expectations and deliver results that align with your idea.

Third, human review matters. AI may write code fast, but as you can see above, most of the time it needs human oversight. People still must be in charge of the whole decision-making process.

For more insight into using AI for development, [read our article on vibe coding](https://lembergsolutions.com/blog/vibe-coding-explained-what-buzz-and-can-it-really-cut-development-costs). There we explore which companies can benefit the most from this approach, how to choose the right tools and maintain security.


# Unstable website? Use queues.
Source: https://developer.upsun.com/posts/hands-on/unstable-website-use-queues

Your site throws 502 errors when external APIs are slow. The fix isn't more resources. It's offloading that work to background jobs so your responses stay fast.


<PostMeta />

Your e-commerce site calls an ERP (Enterprise Resource Planning system) to record orders. The ERP is slow today. Users are waiting 8 seconds for checkout to complete. Some of them give up. Others see 502 errors because your PHP-FPM workers are all stuck waiting on that ERP.

You scale up resources. It helps a little. The 502s come back when traffic increases.

The problem isn't your infrastructure. It's that your users are waiting for something they don't need to wait for.

## Keep your responses fast

Here's the pattern we see in support tickets constantly: an application makes an external API call during a user request, and that call is slow. The user waits. The connection stays open. Resources get tied up.

With PHP-FPM, this becomes visible fast. Worker pools are small by design. If each worker is stuck waiting on an external API for 8 seconds, you run out of workers quickly. New requests have nowhere to go. 502 errors start appearing.

Other stacks handle concurrent connections better. Node.js can juggle thousands of open connections without breaking a sweat. But limits exist everywhere. Your router has a maximum connection count. Linux has file descriptor limits. Push hard enough and you'll hit something.

The real issue isn't which limit you hit. It's that your users are waiting 8 seconds for a checkout page to load. That's a terrible experience regardless of whether your infrastructure can technically handle it.

And it costs you money. E-commerce sites loading in 1 second convert at 2.5x the rate of sites taking 5 seconds, [according to Portent's research](https://portent.com/blog/analytics/research-site-speed-hurting-everyones-revenue.htm). Amazon found that 100ms of latency cost them 1% in sales. Walmart saw a 2% conversion increase for every second shaved off load time.

## Do users actually need to wait?

When your application calls an external API during a request, ask: does the user need that response before they can continue?

For order processing, the answer is usually no.

Think about Amazon. You click "Place order" and immediately see confirmation. But your order hasn't actually been processed yet. It's in a queue. A worker will pick it up, validate payment, check inventory, and eventually send a confirmation email. That email might arrive minutes later.

The user doesn't need to watch your application talk to the ERP in real time. They need to know their order was received. Those are different things.

## Offload to a queue

The fix is straightforward. Instead of calling the external API during the request, push the work to a queue and return immediately:

```mermaid theme={null}
graph LR
    USER[User Request] --> APP[Application]
    APP --> QUEUE[Message Queue]
    APP --> RESPONSE[Immediate Response]
    QUEUE --> WORKER[Worker]
    WORKER --> ERP[External API]
    WORKER --> EMAIL[Email Confirmation]

    classDef app fill:#D0F302,stroke:#000,stroke-width:2px,color:#000
    classDef queue fill:#6046FF,stroke:#000,stroke-width:2px,color:#fff
    classDef external fill:#B5A8FF,stroke:#000,stroke-width:2px,color:#000

    class APP app
    class QUEUE queue
    class WORKER app
    class ERP external
    class EMAIL external
```

Before:

1. User places order
2. Application calls ERP (8 seconds)
3. Application returns confirmation

After:

1. User places order
2. Application pushes message to queue (milliseconds)
3. Application returns "Order received"
4. Worker picks up message
5. Worker calls ERP (8 seconds, but nobody is waiting)
6. Worker sends confirmation email

Your checkout now takes milliseconds. The ERP integration still works, it's just not blocking the user anymore.

RabbitMQ is a popular choice and available as a managed service on Upsun. Redis works too, with its Streams or pub/sub features.

## Workers vs. crons

Once you have a queue, something needs to process it. Two options:

**Workers** run continuously, watching the queue. When a message arrives, they process it immediately. On Upsun, workers get their own containers with dedicated resources. More responsive, but they cost more since they're always running.

**Crons** run on a schedule and share resources with your main application. A cron might check the queue every 5 minutes and process what's there. Cheaper, but you get latency (up to 5 minutes before work starts) and potential resource contention if the processing is heavy.

The choice depends on what you're processing. Order confirmations? Customers expect quick emails, so use workers. Nightly data sync? A cron is fine.

On Upsun, you can also scale worker resources dynamically with the CLI. Some customers use crons to boost worker resources during peak hours and scale them back at night.

## When to use this pattern

This applies when:

* Your application calls external APIs during user requests
* Those calls are slow or unreliable
* Users don't actually need the result before continuing

Common cases:

* **E-commerce → ERP**: Order data syncs, but not during checkout
* **Notifications**: Emails, SMS, push notifications should never block requests
* **Third-party integrations**: Analytics, CRM updates, shipping rate calculations
* **Report generation**: Users can download reports later

If users genuinely need the external API's response before they can proceed, you're stuck waiting on it. But that's less common than you might think.

## The takeaway

Slow external API calls during user requests cause two problems: bad user experience and infrastructure strain. Adding resources helps marginally, but you're treating symptoms.

The fix is to stop making users wait for things they don't need to wait for. Push that work to a queue. Return fast. Process in the background. Send a confirmation when it's done.

Upsun provides [RabbitMQ](https://docs.upsun.com/add-services/rabbitmq.html), [Redis](https://docs.upsun.com/add-services/redis.html), and [workers](https://docs.upsun.com/create-apps/app-reference/single-runtime-image.html#workers) for exactly this pattern.


# Varnish 101: Protecting Paths with HTTP Basic Authentication on Upsun
Source: https://developer.upsun.com/posts/hands-on/varnish-101-protecting-paths-with-http-basic-authentication-on-upsun

Learn how to implement HTTP Basic Authentication directly in Varnish VCL on Upsun to protect specific paths like admin areas, staging environments, and work-in-progress content without touching your backend.

<PostMeta />

**Welcome to the first article in our Varnish series**, where we'll explore practical techniques for leveraging Varnish Cache (soon to be [rebranded as Vinyl](https://varnish-cache.org/#years-old-and-it-is-time-to-get-serious-er)) beyond simple caching. While many developers view Varnish as just an HTTP accelerator, its VCL (Varnish Configuration Language) provides powerful capabilities for traffic control, security, and request processing—all before requests reach your backend application.

Throughout this series, we'll cover practical implementations including path protection, rate limiting, URL normalization, and advanced traffic filtering. This first article focuses on implementing HTTP Basic Authentication directly in VCL to protect specific paths like admin areas and staging environments.

## Why Protect Paths in Varnish?

[Varnish Cache](https://docs.upsun.com/add-services/varnish.html) sits between your application and your users as a powerful HTTP accelerator. Beyond caching, it's the perfect place to implement simple access controls for specific paths—blocking unauthorized requests before they consume backend resources.

While Upsun offers [environment-level HTTP access control](https://docs.upsun.com/environments/http-access-control.html#use-a-username-and-password), implementing authentication directly in VCL gives you more flexibility:

* **Path-specific protection**: Secure only certain URLs (e.g., `/admin`, `/staging`)
* **Multiple credential sets**: Use different passwords for different areas
* **Custom logic**: Combine authentication with other VCL conditions
* **Edge enforcement**: Block unauthorized traffic at the Varnish layer

## Understanding HTTP Basic Authentication

HTTP Basic Authentication is a simple challenge-response mechanism where:

1. Client requests a protected resource
2. Server responds with `401 Unauthorized` and a `WWW-Authenticate` header
3. Browser displays a login prompt
4. Client resends the request with an `Authorization` header containing Base64-encoded credentials
5. Server validates credentials and either allows or denies access

In VCL, we implement this by checking the `Authorization` header against known credentials and generating synthetic responses for authentication challenges.

## Implementation

HTTP Basic Auth in VCL requires two parts: checking credentials in `vcl_recv` and generating the authentication challenge in `vcl_synth`.

### Part 1: Credential Verification in vcl\_recv

```vcl {filename=".upsun/config.vcl"} theme={null}
sub vcl_recv {
...
    # --- Basic Auth ---
    # Check if the path is restricted.
    if (req.url ~ "^/admin") {
        # Check for the Authorization header
        if (!req.http.Authorization) {
            # If no Authorization header, request credentials
            return (synth(401, "Authentication Required"));
        }

        # Decode the Base64 encoded credentials (e.g., "Basic dXNlcm5hbWU6cGFzc3dvcmQ=")
        # In this example, we'll hardcode the expected credentials
        # "username:password" and "admin:admin" Base64 encoded
        # Use https://www.debugbear.com/basic-auth-header-generator to generate credentials
        if (req.http.Authorization !~ "^Basic (YWRtaW46YWRtaW4=|dXNlcm5hbWU6cGFzc3dvcmQ=)$") {
            return (synth(401, "Authentication Required"));
        }
    }
...
}
```

### Part 2: Authentication Challenge in vcl\_synth

```vcl {filename=".upsun/config.vcl"} theme={null}
sub vcl_synth {
...
    if (resp.status == 401) {
        set resp.http.WWW-Authenticate = {"Basic realm="Restricted area""};
        set resp.http.Content-Type = "text/plain";
        set resp.body = "Access Denied";
        return (deliver);
    }
...
}
```

## How It Works

1. **Path Matching**: The condition `if (req.url ~ "^/admin")` identifies protected paths. The `^` anchor ensures only paths starting with `/admin` are restricted (e.g., `/admin`, `/admin/dashboard`, but not `/public/admin`).

2. **Authorization Header Check**: `if (!req.http.Authorization)` verifies whether the client sent credentials. If not, we immediately return a `401` status, triggering the authentication challenge.

3. **Credential Validation**: The second check validates the Base64-encoded credentials:
   * HTTP Basic Auth sends credentials as `Authorization: Basic <base64-string>`
   * The base64 string encodes `username:password`
   * Example: `admin:admin` becomes `YWRtaW46YWRtaW4=`
   * Example: `username:password` becomes `dXNlcm5hbWU6cGFzc3dvcmQ=`

4. **Multiple Allowed Credentials**: The regex pattern `(YWRtaW46YWRtaW4=|dXNlcm5hbWU6cGFzc3dvcmQ=)` allows multiple username/password combinations using alternation (OR logic).

5. **Synthetic Response**: When authentication fails, `return (synth(401, "Authentication Required"))` triggers `vcl_synth` with a 401 status.

6. **WWW-Authenticate Header**: In `vcl_synth`, the `WWW-Authenticate` header tells the browser to display the login prompt. The `realm` parameter appears in the browser's authentication dialog.

## Generating Base64 Credentials

To create your own credential strings, use the [DebugBear Basic Auth Header Generator](https://www.debugbear.com/basic-auth-header-generator) or encode manually:

```bash {filename="Terminal"} theme={null}
# Using command line
echo -n "myuser:mypassword" | base64
# Output: bXl1c2VyOm15cGFzc3dvcmQ=

# Using Python
python3 -c "import base64; print(base64.b64encode(b'myuser:mypassword').decode())"
# Output: bXl1c2VyOm15cGFzc3dvcmQ=
```

Then add the encoded string to your VCL pattern:

```vcl {filename=".upsun/config.vcl"} theme={null}
sub vcl_recv {
...
    if (req.http.Authorization !~ "^Basic (YWRtaW46YWRtaW4=|dXNlcm5hbWU6cGFzc3dvcmQ=|bXl1c2VyOm15cGFzc3dvcmQ=)$") {
        return (synth(401, "Authentication Required"));
    }
...
}
```

## Protecting Multiple Paths

You can protect different areas with different credentials:

```vcl {filename=".upsun/config.vcl"} theme={null}
sub vcl_recv {
...
    # Admin area with one set of credentials
    if (req.url ~ "^/admin") {
        if (!req.http.Authorization ||
            req.http.Authorization !~ "^Basic YWRtaW46YWRtaW4=$") {
            return (synth(401, "Admin Authentication Required"));
        }
    }

    # Staging area with different credentials
    if (req.url ~ "^/staging") {
        if (!req.http.Authorization ||
            req.http.Authorization !~ "^Basic c3RhZ2luZzpzdGFnZTEyMw==$") {
            return (synth(401, "Staging Authentication Required"));
        }
    }

    # API with third set of credentials
    if (req.url ~ "^/api/internal") {
        if (!req.http.Authorization ||
            req.http.Authorization !~ "^Basic YXBpOnNlY3JldGtleQ==$") {
            return (synth(401, "API Authentication Required"));
        }
    }
...
}
```

## Security Considerations

**Important**: HTTP Basic Auth has several security limitations:

1. **Credentials in VCL**: The credentials are stored in plain text (Base64 is just encoding, not encryption) in your VCL configuration. Anyone with access to your VCL can decode them instantly.

2. **HTTPS Required**: Always use HTTPS when deploying Basic Auth. Over HTTP, credentials are transmitted in the clear and can be intercepted.

3. **Not for Primary Production User Auth**: This approach is suitable for:

   * Restricting admin areas with a shared password
   * Adding a simple barrier to work-in-progress content
   * Protecting staging environments from public access
   * Securing internal APIs with simple tokens

   **Do NOT use** for:

   * Production user authentication (use proper session-based auth in your application)
   * Primary protection for sensitive customer data
   * Any scenario requiring user-specific permissions or audit trails

## Use Cases

HTTP Basic Auth in Varnish is ideal for:

### Admin Areas

Protect administrative interfaces that should only be accessible to team members:

```vcl {filename=".upsun/config.vcl"} theme={null}
if (req.url ~ "^/admin") {
    # Check credentials
}
```

### Staging Content

Hide work-in-progress content from public view while allowing authorized reviewers access:

```vcl {filename=".upsun/config.vcl"} theme={null}
if (req.url ~ "^/preview/") {
    # Check credentials
}
```

### Internal APIs

Add a simple authentication layer for internal API endpoints:

```vcl {filename=".upsun/config.vcl"} theme={null}
if (req.url ~ "^/api/internal/") {
    # Check API credentials
}
```

## Conclusion

HTTP Basic Authentication in Varnish VCL provides a lightweight way to protect specific paths without adding complexity to your application code. While it's not suitable for production user authentication, it's perfect for admin areas, staging content, and internal tools.

Ready to take your Varnish security further? In our next article, Varnish 102: Rate Limiting, we'll explore protecting your backend from abuse using the vsthrottle VMOD to implement intelligent request throttling.


# Varnish 102: Protecting Your Application with Rate Limiting on Upsun
Source: https://developer.upsun.com/posts/hands-on/varnish-102-protecting-your-application-with-rate-limiting-on-upsun

Learn how to implement effective rate limiting in Varnish using the vsthrottle VMOD to protect your application from abuse, prevent DDoS attacks, and ensure fair resource allocation.

<PostMeta />

**Rate limiting is essential for protecting your application from abuse and ensuring fair resource allocation.** While Varnish is best known for caching, its [`vsthrottle` VMOD](https://docs.varnish-software.com/varnish-enterprise/vmods/vsthrottle/) provides powerful rate limiting capabilities that can protect your backend infrastructure from being overwhelmed by excessive requests, whether from malicious actors or legitimate traffic spikes.

## Why Rate Limiting in Varnish?

Rate limiting at the Varnish layer offers several key advantages:

* **Early Termination**: Excessive requests are blocked at the edge, never reaching your application servers
* **Resource Protection**: Prevents any single client from monopolizing backend resources
* **DDoS Mitigation**: Provides a first line of defense against distributed denial-of-service attacks
* **Fair Resource Allocation**: Ensures all users get reasonable access to your application
* **Reduced Infrastructure Costs**: Less load on backend servers means more efficient resource usage

On [Upsun](https://www.upsun.com), [Varnish Cache](https://docs.upsun.com/add-services/varnish.html) combined with rate limiting VCL creates a robust protective layer that keeps your application running smoothly even under attack.

## Understanding vsthrottle

The `vsthrottle` VMOD (Varnish Module) provides the core functionality for rate limiting. It works by tracking request counts per identifier (typically IP address) within sliding time windows.

The primary function is `vsthrottle.is_denied()`, which takes four parameters:

```vcl {filename=".upsun/config.vcl"} theme={null}
vsthrottle.is_denied(key, limit, period, block_duration)
```

* **key**: Identifier for tracking (usually IP address)
* **limit**: Maximum number of requests allowed
* **period**: Time window for counting requests
* **block\_duration**: How long to block after exceeding the limit

## General Request Rate Limiting

The most common rate limiting pattern restricts how many requests a client can make within a time window:

```vcl {filename=".upsun/config.vcl"} theme={null}
sub vcl_recv {
...
    # --- Rate limiting ---
    if (req.url !~ "^/(media|static|banner|admin)/")  {
                if (vsthrottle.is_denied(req.http.X-Client-IP, 30, 15s, 15s)) {
                    # Client has exceeded 30 reqs per 15s.
                    # When this happens, block altogether for the next 15s.
                    return (synth(429, "Too Many Requests - Please wait 15 seconds"));
                }
    }
...
}
```

### How It Works

1. **Path Exclusion**: The first condition `if (req.url !~ "^/(media|static|banner|admin)/")` excludes certain paths from rate limiting:
   * `!~`: Negative regex match (does NOT match)
   * Static assets (`/media`, `/static`) are excluded because they're cacheable and typically high-volume
   * Admin paths are excluded (these might have their own authentication/rate limiting)

2. **vsthrottle.is\_denied() Function**: This is the core rate limiting logic with four parameters:
   * **Parameter 1** (`req.http.X-Client-IP`): The identifier key for rate limiting. Uses the [client's IP address](https://docs.upsun.com/development/headers.html#:~:text=Client) to track individual users.
   * **Parameter 2** (`30`): Request threshold - maximum number of requests allowed
   * **Parameter 3** (`15s`): Time window for counting requests (15 seconds)
   * **Parameter 4** (`15s`): Penalty period - how long to block after exceeding the limit

3. **Rate Limiting Logic**: "30 requests per 15 seconds" means:
   * Client can make up to 30 requests in any 15-second rolling window
   * Once exceeded, the client is blocked completely for 15 seconds
   * After the penalty period, the counter resets

4. **HTTP 429 Response**: Returns a standard ["Too Many Requests"](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#429) status code with a clear message indicating the wait time.

### Why Exclude Static Assets?

Static assets like images, CSS, and JavaScript files are:

* Usually cached by Varnish (subsequent requests don't hit backend)
* High-volume but low-cost to serve
* Essential for page rendering

Including them in rate limits would punish users for simply loading a page with many assets.

### Understanding the Rolling Window

The time window is "rolling," not fixed. This means:

```
Time: 0s  → Request count: 1
Time: 1s  → Request count: 5
Time: 5s  → Request count: 15
Time: 10s → Request count: 25
Time: 12s → Request count: 30 (limit reached)
Time: 13s → BLOCKED (penalty period begins)
Time: 28s → Penalty expires, counter resets
```

The client isn't tracked per "15-second bucket" but rather "requests in the last 15 seconds at any given moment."

## POST/PUT Rate Limiting

Write operations (POST, PUT) are more expensive than reads and require stricter limits:

```vcl {filename=".upsun/config.vcl"} theme={null}
sub vcl_recv {
...
    # Only allow a few POST/PUTs per client.
    if ((req.method == "POST" || req.method == "PUT") && (req.url !~ "^/admin")) {
            if (vsthrottle.is_denied("rw" + req.http.X-Client-IP, 5, 10s, 15s)) {
                return (synth(429, "Too Many Requests - Please wait 15 seconds"));
            }
    }
...
}
```

### How Write Rate Limiting Works

1. **Method Check**: `(req.method == "POST" || req.method == "PUT")` targets only write operations, allowing unlimited GET requests.

2. **Admin Exclusion**: `(req.url !~ "^/admin")` excludes admin paths, which may need different rate limiting rules or have their own authentication.

3. **Separate Counter**: The key `"rw" + req.http.X-Client-IP` creates a separate rate limit counter:
   * The `"rw"` prefix ensures write operations have their own bucket
   * A client could make 30 GET requests AND 5 POST requests in the same period
   * Prevents read traffic from consuming write quota

4. **Stricter Limits**: `5, 10s, 15s` means:
   * Only 5 write requests per 10-second window
   * Block for 15 seconds after exceeding
   * Much more restrictive than read limits (5 vs 30 requests)

5. **Different Penalty Window**: The 10-second measurement window is shorter than the 15-second penalty, meaning clients stay blocked even after their offense window expires.

### Why Separate Write Limits?

Write operations typically:

* Consume more server resources (database writes, processing)
* Have security implications (CSRF, injection attacks)
* Are used in brute force attacks (login forms, API abuse)
* Should be rate-limited more aggressively than reads

### Real-World Example

Consider a user browsing an e-commerce site:

```
GET  /products       → General rate limit counter (1/30)
GET  /products/item1 → General rate limit counter (2/30)
POST /cart/add       → Write rate limit counter (1/5)
GET  /cart           → General rate limit counter (3/30)
POST /cart/update    → Write rate limit counter (2/5)
GET  /checkout       → General rate limit counter (4/30)
POST /order/submit   → Write rate limit counter (3/5)
```

The user can browse freely (30 page views) while write operations remain tightly controlled (5 actions).

## Advanced Rate Limiting Patterns

### Per-Path Rate Limiting

Different endpoints may need different limits:

```vcl {filename=".upsun/config.vcl"} theme={null}
sub vcl_recv {
...
    # Aggressive rate limiting for APIs
    if (req.url ~ "^/api/") {
        if (vsthrottle.is_denied("api:" + req.http.X-Client-IP, 100, 60s, 60s)) {
            return (synth(429, "API rate limit exceeded"));
        }
    }

    # Strict limits for login endpoints
    if (req.url ~ "^/(login|auth|signin)") {
        if (vsthrottle.is_denied("login:" + req.http.X-Client-IP, 5, 60s, 300s)) {
            return (synth(429, "Too many login attempts. Please wait 5 minutes."));
        }
    }

    # Lenient limits for authenticated users
    if (!req.http.Authorization) {
        # Stricter limits for unauthenticated traffic
        if (vsthrottle.is_denied("unauth:" + req.http.X-Client-IP, 10, 10s, 30s)) {
            return (synth(429, "Please log in for higher rate limits"));
        }
    }
...
}
```

### Key Insights

1. **API Endpoints**: Higher limits (100 req/60s) but longer penalty periods for legitimate API usage
2. **Login Protection**: Very strict limits (5 req/60s) with long penalties (5 minutes) to prevent brute force
3. **Authentication-Based**: Different limits for authenticated vs anonymous users

### Combining Rate Limiting with Security Headers

Layer rate limiting with abuse scores and geographic filtering for enhanced protection, the last article in the series covers these headers in more detail:

```vcl {filename=".upsun/config.vcl"} theme={null}
sub vcl_recv {
...
    # More aggressive rate limiting for suspicious IPs
    if (std.integer(req.http.client-abuse-score, 0) > 15) {
        if (vsthrottle.is_denied("suspicious:" + req.http.X-Client-IP, 10, 30s, 120s)) {
            return (synth(429, "Rate limit exceeded for suspicious traffic"));
        }
    }

    # Stricter limits for certain geographic regions
    if (req.http.client-country ~ "(?i)^(CN|RU)$") {
        if (vsthrottle.is_denied("geo:" + req.http.X-Client-IP, 15, 30s, 60s)) {
            return (synth(429, "Geographic rate limit exceeded"));
        }
    }
...
}
```

### Dynamic Rate Limiting by Risk Level

You can create tiered rate limiting based on risk scores:

**Important**: The `vsthrottle.is_denied()` function requires literal values for time parameters. To implement tiered limits, use separate conditional blocks:

```vcl {filename=".upsun/config.vcl"} theme={null}
sub vcl_recv {
...
    # Tiered rate limiting by abuse score
    if (std.integer(req.http.client-abuse-score, 0) > 50) {
        # Very high abuse: 5 req per 60 seconds
        if (vsthrottle.is_denied("high:" + req.http.X-Client-IP, 5, 60s, 120s)) {
            return (synth(429, "Severe rate limit for high-risk IP"));
        }
    } elsif (std.integer(req.http.client-abuse-score, 0) > 25) {
        # Medium abuse: 15 req per 30 seconds
        if (vsthrottle.is_denied("med:" + req.http.X-Client-IP, 15, 30s, 60s)) {
            return (synth(429, "Rate limit exceeded for suspicious IP"));
        }
    } else {
        # Normal traffic: 30 req per 15 seconds
        if (vsthrottle.is_denied("normal:" + req.http.X-Client-IP, 30, 15s, 15s)) {
            return (synth(429, "Too Many Requests"));
        }
    }
...
}
```

## Tuning Rate Limits

Adjust parameters based on your application's needs and traffic patterns:

### Finding the Right Limits

1. **Baseline Analysis**: Monitor your application logs to understand typical request patterns:
   * Average requests per second per user
   * Peak traffic during normal usage
   * Page load request counts (including assets)

2. **Conservative Start**: Begin with generous limits and tighten based on observed abuse:
   ```vcl {filename=".upsun/config.vcl"} theme={null}
   # Start here
   vsthrottle.is_denied(req.http.X-Client-IP, 100, 60s, 30s)

   # Adjust down if seeing abuse
   vsthrottle.is_denied(req.http.X-Client-IP, 50, 60s, 60s)

   # Final tuned value
   vsthrottle.is_denied(req.http.X-Client-IP, 30, 30s, 30s)
   ```

3. **Test Legitimate Use Cases**: Ensure normal user workflows don't trigger limits:
   * Single page application (SPA) initial load
   * Form submissions with multiple validations
   * Mobile app burst traffic on app open

### Monitoring and Alerting

Track 429 responses in your logs to identify:

* False positives (legitimate users being blocked)
* Attack patterns (sudden spikes in rate-limited requests)
* Effectiveness (reduction in backend load during attacks)

## Rate Limiting Best Practices

1. **Use X-Client-IP**: The `X-Client-IP` header typically contains the true client IP, even behind proxies or load balancers on Upsun.

2. **Namespace Your Keys**: Use prefixes like `"rw"`, `"api:"`, or `"login:"` to create separate rate limit buckets for different types of traffic.

3. **Monitor and Adjust**: Start with conservative limits and relax them based on legitimate traffic patterns.

4. **Clear Error Messages**: Tell users how long to wait and consider including support contact information:
   ```vcl {filename=".upsun/config.vcl"} theme={null}
   return (synth(429, "Too many requests. Please wait 60 seconds or contact support@example.com"));
   ```

5. **Document Your Limits**: Provide API documentation that clearly states rate limits so developers can code accordingly.

6. **Consider Business Logic**: Don't rate-limit so aggressively that it impacts revenue:
   * E-commerce checkout flows should be permissive
   * Payment endpoints need special consideration
   * Customer support areas may need higher limits

7. **Graceful Degradation**: Consider returning cached content instead of blocking entirely:
   ```vcl {filename=".upsun/config.vcl"} theme={null}
   if (vsthrottle.is_denied(req.http.X-Client-IP, 30, 15s, 15s)) {
       # Return stale cache if available, otherwise block
       if (obj.ttl + obj.grace > 0s) {
           return (deliver);
       }
       return (synth(429, "Too Many Requests"));
   }
   ```

## Common Pitfalls to Avoid

### 1. Rate Limiting Static Assets

**Problem**: Including cached static assets in rate limits punishes normal page loads.

**Solution**: Exclude paths that serve cached content:

```vcl {filename=".upsun/config.vcl"} theme={null}
if (req.url !~ "^/(static|media|assets|cdn)/") {
    # Apply rate limiting
}
```

### 2. Shared IP Addresses

**Problem**: Corporate offices, schools, and mobile carriers often share IP addresses across many users.

**Solution**: Consider using session cookies or API keys for more accurate per-user tracking, or use more permissive limits:

```vcl {filename=".upsun/config.vcl"} theme={null}
# More permissive for common shared IP scenarios
if (req.http.X-Client-IP ~ "^(10\.|172\.(1[6-9]|2[0-9]|3[01])\.|192\.168\.)") {
    # Use higher limits
    vsthrottle.is_denied("corp:" + req.http.X-Client-IP, 100, 30s, 15s)
}
```

### 3. Inconsistent Penalty Periods

**Problem**: Short penalty periods may not deter attackers.

**Solution**: Use exponentially increasing penalties or ensure penalty periods exceed measurement windows:

```vcl {filename=".upsun/config.vcl"} theme={null}
# Good: Penalty (60s) > Measurement (30s)
vsthrottle.is_denied(req.http.X-Client-IP, 30, 30s, 60s)

# Less effective: Penalty (15s) = Measurement (15s)
vsthrottle.is_denied(req.http.X-Client-IP, 30, 15s, 15s)
```

### 4. Not Excluding Health Checks

**Problem**: Load balancer health checks can consume rate limit quotas.

**Solution**: Exclude monitoring endpoints:

```vcl {filename=".upsun/config.vcl"} theme={null}
if (req.url ~ "^/(health|status|ping)$") {
    return (pass);  # Skip rate limiting entirely
}
```

## Conclusion

Effective rate limiting with vsthrottle provides robust protection for your Upsun applications. By implementing tiered limits for different request types and carefully tuning your thresholds, you can ensure fair resource allocation while protecting against abuse and attacks.

Start with conservative limits, monitor your traffic patterns, and adjust based on real-world behavior. In our next article, Varnish 103: Cache Optimization, we'll explore URL normalization and query string handling techniques to dramatically improve your cache hit ratios and reduce backend load.


# Varnish 103: Cache Optimization with URL Normalization on Upsun
Source: https://developer.upsun.com/posts/hands-on/varnish-103-cache-optimization-with-url-normalization-on-upsun

Learn how to maximize Varnish cache efficiency through URL normalization, query string sorting, and tracking parameter removal to dramatically improve cache hit ratios and reduce backend load.

<PostMeta />

**Cache efficiency can make or break your application's performance.** While Varnish is incredibly powerful at caching, small URL variations can fragment your cache and dramatically reduce hit ratios. A single page with tracking parameters, query string variations, or trailing punctuation can create dozens of duplicate cache entries, each consuming memory and forcing unnecessary backend requests. The technniques covered in this article are essential for anyone looking serve traffic at scale.

## The Cache Fragmentation Problem

Consider these URLs that all represent the exact same content:

```
https://example.com/products
https://example.com/products?
https://example.com/products?utm_source=twitter&utm_campaign=spring
https://example.com/products?utm_campaign=spring&utm_source=twitter
https://example.com/products/?
```

Without URL normalization, Varnish creates **five separate cache entries** for identical content. For a high-traffic site, this pattern repeated across thousands of pages results in:

* **Wasted memory**: Storing duplicate content
* **Lower cache hit ratio**: More requests miss cache and hit backend
* **Higher backend load**: Unnecessary duplicate requests to application servers
* **Slower response times**: More requests waiting for backend processing

## URL Normalization Strategies

On Upsun, [Varnish Cache](https://docs.upsun.com/add-services/varnish.html) combined with intelligent URL normalization VCL can dramatically improve cache efficiency. Let's explore proven techniques that consolidate cache entries and maximize hit ratios.

## Removing Empty Query Strings

One of the simplest yet most effective optimizations is removing trailing question marks from URLs.

```vcl {filename=".upsun/config.vcl"} theme={null}
sub vcl_recv {
...
    # Remove empty query string parameters
    # e.g.: www.example.com/index.html?
    if (req.url ~ "\?$") {
        set req.url = regsub(req.url, "\?$", "");
    }
...
}
```

### Why This Matters

Empty query strings often appear when:

* Users manually type URLs with trailing `?`
* Applications generate links with optional parameters that aren't always present
* URL builders concatenate parameters conditionally, leaving trailing `?` when none apply

Consider these two URLs:

* `https://example.com/products/widget`
* `https://example.com/products/widget?`

Without normalization, Varnish treats these as completely different URLs, creating separate cache entries for identical content.

### How It Works

1. **Pattern Detection**: The condition `if (req.url ~ "\?$")` uses regex matching to detect URLs ending with a question mark:
   * `~`: Regex match operator
   * `\?`: Escaped question mark (literal `?` character)
   * `$`: End-of-string anchor

2. **URL Rewriting**: The `regsub()` function performs string substitution:
   * **First parameter** (`req.url`): The string to modify
   * **Second parameter** (`"\?$"`): The regex pattern to find (trailing `?`)
   * **Third parameter** (`""`): The replacement string (empty, effectively removing the `?`)

3. **In-Place Modification**: `set req.url = ...` updates the request URL before cache lookup or backend request.

### The Impact on Caching

**Without normalization:**

```
Request 1: /page?     → Cache MISS → Backend request → Cache entry A
Request 2: /page      → Cache MISS → Backend request → Cache entry B
Request 3: /page?     → Cache HIT  → Served from entry A
Request 4: /page      → Cache HIT  → Served from entry B
```

Cache hit ratio: 50% (2 hits, 2 misses)

**With normalization:**

```
Request 1: /page? → normalized to /page → Cache MISS → Backend request → Cache entry
Request 2: /page  → Cache HIT  → Served from cache
Request 3: /page? → normalized to /page → Cache HIT  → Served from cache
Request 4: /page  → Cache HIT  → Served from cache
```

Cache hit ratio: 75% (3 hits, 1 miss)

## Query String Sorting for Cache Consistency

URLs with identical parameters in different orders should result in the same cached response, but by default they don't.

```vcl {filename=".upsun/config.vcl"} theme={null}
sub vcl_recv {
...
    # Sorts query string parameters alphabetically for cache normalization purposes, only when there are multiple parameters
    if (req.url ~ "\?.+&.+") {
        set req.url = std.querysort(req.url);
    }
...
}
```

### The Query String Problem

Consider these URLs that represent the same content:

* `https://example.com/search?category=books&sort=price&color=blue`
* `https://example.com/search?color=blue&category=books&sort=price`
* `https://example.com/search?sort=price&color=blue&category=books`

Without query string sorting, Varnish creates three separate cache entries for identical content, drastically reducing cache efficiency.

### How It Works

1. **Multi-Parameter Detection**: The regex `\?.+&.+` checks if the URL has multiple query parameters:
   * `\?`: Escaped question mark (start of query string)
   * `.+`: One or more characters (first parameter)
   * `&`: Ampersand separator (indicates multiple parameters)
   * `.+`: One or more characters (second/additional parameters)

2. **Conditional Sorting**: The `if` condition ensures we only call `std.querysort()` when needed:
   * Single-parameter URLs like `/page?id=123` skip sorting (no `&` present)
   * Multi-parameter URLs get sorted
   * This minor optimization avoids unnecessary function calls

3. **Alphabetical Sorting**: The `std.querysort()` function (from the Varnish standard library) sorts parameters alphabetically by key:
   * `/page?z=1&a=2&m=3` becomes `/page?a=2&m=3&z=1`
   * Maintains parameter values unchanged
   * Creates consistent cache keys regardless of parameter order

### Why Skip Single Parameters?

The condition `\?.+&.+` specifically checks for the `&` character, which only appears when multiple parameters exist. This is a small VCL optimization:

```vcl {filename=".upsun/config.vcl"} theme={null}
    # Without the multi-parameter check
    set req.url = std.querysort(req.url);  # Called on every request with query string

    # With the multi-parameter check (recommended)
    if (req.url ~ "\?.+&.+") {
        set req.url = std.querysort(req.url);  # Only called when sorting is needed
    }
```

For URLs like `/page?id=123` (single parameter), there's nothing to sort, so we skip the function call entirely.

### Real-World Impact

Query parameter ordering is especially problematic with:

**E-commerce filters:**

```
/products?category=electronics&brand=sony&price_max=1000
/products?price_max=1000&brand=sony&category=electronics
/products?brand=sony&price_max=1000&category=electronics
```

All represent the same filtered product list, but create 3 cache entries without sorting.

**Search results:**

```
/search?q=varnish&sort=relevance&page=1
/search?page=1&q=varnish&sort=relevance
```

Identical search results, different cache entries.

**API endpoints:**

```
/api/users?limit=10&offset=20&sort=name
/api/users?sort=name&limit=10&offset=20
```

Same API response, fragmented cache.

### Cache Efficiency Example

Consider an e-commerce site with 3 common filters (category, price, brand):

* **Without sorting**: 3! = 6 possible orderings = 6 cache entries per unique filter combination
* **With sorting**: 1 canonical ordering = 1 cache entry per unique filter combination
* **Result**: 6x reduction in cache fragmentation

For 1,000 unique filter combinations:

* Without sorting: 6,000 cache entries
* With sorting: 1,000 cache entries
* Memory saved: 83%

### Important Considerations

1. **Parameter Values Unchanged**: `std.querysort()` only sorts keys, not values:
   ```
   Before: /page?ids=3,1,2&sort=desc
   After:  /page?ids=3,1,2&sort=desc  # ids value order preserved
   ```

2. **Case Sensitivity**: Parameter names are case-sensitive:
   ```
   /page?Category=books&category=books  # Different parameters!
   ```
   Consider adding case normalization if needed.

3. **Array Parameters**: Some applications use repeated parameter names:
   ```
   /page?tag=red&tag=blue&tag=green
   ```
   `std.querysort()` handles these, but behavior depends on your application's expectations.

4. **Fragment Identifiers**: URL fragments (`#section`) are client-side only and never sent to servers, so they don't affect caching.

## Removing Tracking and Marketing Parameters

Marketing and analytics platforms add tracking parameters to URLs that don't affect content but severely fragment your cache. When users click links from social media, email campaigns, or ads, third-party platforms automatically append tracking parameters that create multiple cache entries for identical content.

**Key insight**: These tracking parameters are typically processed by JavaScript running in the user's browser, not by your server application. Since JavaScript can read parameters from `window.location.search`, your server doesn't need to see them—the client-side analytics code extracts and sends them directly to the analytics platform.

Here's a comprehensive VCL snippet that handles virtually all known tracking parameters from major platforms:

```vcl {filename=".upsun/config.vcl"} theme={null}
sub vcl_recv {
...
    # Remove all marketing get parameters to minimize the cache objects
    if (req.url ~ "(\?|&)(_branch_match_id|srsltid|_bta_c|_bta_tid|_ga|_gl|_ke|_kx|campid|cof|customid|cx|dclid|dm_i|ef_id|epik|fbclid|gad_source|gbraid|gclid|gclsrc|gdffi|gdfms|gdftrk|hsa_acc|hsa_ad|hsa_cam|hsa_grp|hsa_kw|hsa_mt|hsa_net|hsa_src|hsa_tgt|hsa_ver|ie|igshid|irclickid|matomo_campaign|matomo_cid|matomo_content|matomo_group|matomo_keyword|matomo_medium|matomo_placement|matomo_source|mc_cid|mc_eid|mkcid|mkevt|mkrid|mkwid|msclkid|mtm_campaign|mtm_cid|mtm_content|mtm_group|mtm_keyword|mtm_medium|mtm_placement|mtm_source|nb_klid|ndclid|origin|pcrid|piwik_campaign|piwik_keyword|piwik_kwd|pk_campaign|pk_keyword|pk_kwd|redirect_log_mongo_id|redirect_mongo_id|rtid|sb_referer_host|ScCid|si|siteurl|s_kwcid|sms_click|sms_source|sms_uph|toolid|trk_contact|trk_module|trk_msg|trk_sid|ttclid|twclid|utm_campaign|utm_content|utm_creative_format|utm_id|utm_marketing_tactic|utm_medium|utm_source|utm_source_platform|utm_term|wbraid|yclid|zanpid|mc_[a-z]+|utm_[a-z]+|_bta_[a-z]+)=") {
        set req.url = regsuball(req.url, "(_branch_match_id|srsltid|_bta_c|_bta_tid|_ga|_gl|_ke|_kx|campid|cof|customid|cx|dclid|dm_i|ef_id|epik|fbclid|gad_source|gbraid|gclid|gclsrc|gdffi|gdfms|gdftrk|hsa_acc|hsa_ad|hsa_cam|hsa_grp|hsa_kw|hsa_mt|hsa_net|hsa_src|hsa_tgt|hsa_ver|ie|igshid|irclickid|matomo_campaign|matomo_cid|matomo_content|matomo_group|matomo_keyword|matomo_medium|matomo_placement|matomo_source|mc_cid|mc_eid|mkcid|mkevt|mkrid|mkwid|msclkid|mtm_campaign|mtm_cid|mtm_content|mtm_group|mtm_keyword|mtm_medium|mtm_placement|mtm_source|nb_klid|ndclid|origin|pcrid|piwik_campaign|piwik_keyword|piwik_kwd|pk_campaign|pk_keyword|pk_kwd|redirect_log_mongo_id|redirect_mongo_id|rtid|sb_referer_host|ScCid|si|siteurl|s_kwcid|sms_click|sms_source|sms_uph|toolid|trk_contact|trk_module|trk_msg|trk_sid|ttclid|twclid|utm_campaign|utm_content|utm_creative_format|utm_id|utm_marketing_tactic|utm_medium|utm_source|utm_source_platform|utm_term|wbraid|yclid|zanpid|mc_[a-z]+|utm_[a-z]+|_bta_[a-z]+)=[-_A-z0-9+(){}%.]+&?", "");
        set req.url = regsub(req.url, "[?|&]+$", "");
    }
...
}
```

### Platform Coverage

This extended list covers tracking parameters from dozens of platforms and services that automatically append parameters outside your control:

**Major advertising platforms:**

* Google Ads: `gclid`, `gclsrc`, `gbraid`, `wbraid`, `gad_source`
* Facebook/Meta: `fbclid`
* Twitter: `twclid`
* TikTok: `ttclid`
* Bing/Microsoft: `msclkid`
* Yahoo: `yclid`

**Analytics platforms:**

* Google Analytics: `_ga`, `_gl`, `utm_*` (multiple variants)
* Matomo/Piwik: `matomo_*`, `mtm_*`, `piwik_*`, `pk_*`

**Email marketing:**

* Mailchimp: `mc_cid`, `mc_eid`, `mc_*` (pattern match)
* SMS campaigns: `sms_click`, `sms_source`, `sms_uph`

**Affiliate and commerce:**

* eBay: `mkcid`, `mkevt`, `mkrid`, `mkwid`, `toolid`
* Rakuten: `rtid`, `zanpid`
* Impact: `irclickid`

**Social media:**

* Instagram: `igshid`
* Branch.io (deep linking): `_branch_match_id`

**Specialized tracking:**

* Pinterest: `epik`
* Bing Shopping: `_bta_c`, `_bta_tid`, `_bta_*` (pattern match)
* Custom tracking: `trk_*`, `redirect_*`

### Pattern Matching for Flexibility

Notice the regex patterns at the end of the parameter list:

* `mc_[a-z]+`: Matches any Mailchimp parameter starting with `mc_`
* `utm_[a-z]+`: Matches any UTM parameter, including future additions
* `_bta_[a-z]+`: Matches any Bing Tracking parameters

This approach future-proofs your VCL against new tracking parameters from existing platforms.

### How It Works

1. **Two-Stage Approach**: The pattern is checked twice for efficiency:
   * **First check** (`if` condition): Quick regex to see if ANY tracking parameter exists
   * **Second operation** (`regsuball`): More expensive operation to remove all matches
   * The initial check short-circuits when no tracking parameters are present, avoiding expensive `regsuball()` calls on 40-50% of traffic

2. **Enhanced Value Matching**: The removal pattern `[-_A-z0-9+(){}%.]+` matches a wide range of characters found in tracking parameter values, accommodating encoded characters and complex tracking IDs

3. **Cleanup**: The final `regsub` uses `[?|&]+$` to remove any trailing combination of `?` or `&` characters

### Real-World Example

Consider a product page with tracking from multiple campaigns:

```
Without parameter removal:
/products/widget?utm_source=facebook&utm_campaign=spring&fbclid=xyz123
/products/widget?utm_source=twitter&utm_campaign=spring&twclid=abc456
/products/widget?gclid=def789
/products/widget
→ 4 cache entries for identical content

With parameter removal:
All normalize to: /products/widget
→ 1 cache entry
```

### Real-World Impact

For a content site running marketing campaigns across multiple platforms:

* **Daily requests**: 10 million
* **URLs with tracking parameters**: 70% (7 million)
* **Tracking parameter combinations per page**: 100+ variants
* **Cache entries without stripping**: 100 entries per unique page
* **Cache entries with stripping**: 1 entry per unique page
* **Cache hit ratio improvement**: 30% → 85%
* **Backend load reduction**: 55%

### Best Practices

1. **Start Conservative**: Begin with a small list and add parameters as you observe them in your logs

2. **Monitor for False Positives**: Ensure you're not accidentally removing functional parameters that affect content

3. **Coordinate with Teams**: Reassure marketing that analytics will still work (client-side processing is unaffected), and verify with development that no application logic depends on these parameters server-side

4. **Customize**: Remove parameters for platforms you don't use to simplify the regex

## Extended URL Normalization

You can expand normalization patterns to handle other URL variations:

```vcl {filename=".upsun/config.vcl"} theme={null}
sub vcl_recv {
...
    # Remove empty query strings
    if (req.url ~ "\?$") {
        set req.url = regsub(req.url, "\?$", "");
    }

    # Remove trailing slashes (except root) - This can break some applications and redirects
    if (req.url ~ "^/(.+)/$") {
        set req.url = regsub(req.url, "/$", "");
    }

    # Convert multiple slashes to single slash
    if (req.url ~ "//+") {
        set req.url = regsuball(req.url, "//+", "/");
    }
...
}
```

**Important**: Always test trailing slash removal thoroughly. Some applications and frameworks rely on the distinction between `/path` and `/path/` for routing or generating canonical URLs.

## Combining Normalization Techniques

For maximum cache efficiency, combine multiple normalization strategies in the correct order:

```vcl {filename=".upsun/config.vcl"} theme={null}
sub vcl_recv {
...
    # Step 1: Remove empty query strings
    if (req.url ~ "\?$") {
        set req.url = regsub(req.url, "\?$", "");
    }

    # Step 2: Remove tracking parameters
    if (req.url ~ "(\?|&)(_branch_match_id|srsltid|_bta_c|_bta_tid|_ga|_gl|_ke|_kx|campid|cof|customid|cx|dclid|dm_i|ef_id|epik|fbclid|gad_source|gbraid|gclid|gclsrc|gdffi|gdfms|gdftrk|hsa_acc|hsa_ad|hsa_cam|hsa_grp|hsa_kw|hsa_mt|hsa_net|hsa_src|hsa_tgt|hsa_ver|ie|igshid|irclickid|matomo_campaign|matomo_cid|matomo_content|matomo_group|matomo_keyword|matomo_medium|matomo_placement|matomo_source|mc_cid|mc_eid|mkcid|mkevt|mkrid|mkwid|msclkid|mtm_campaign|mtm_cid|mtm_content|mtm_group|mtm_keyword|mtm_medium|mtm_placement|mtm_source|nb_klid|ndclid|origin|pcrid|piwik_campaign|piwik_keyword|piwik_kwd|pk_campaign|pk_keyword|pk_kwd|redirect_log_mongo_id|redirect_mongo_id|rtid|sb_referer_host|ScCid|si|siteurl|s_kwcid|sms_click|sms_source|sms_uph|toolid|trk_contact|trk_module|trk_msg|trk_sid|ttclid|twclid|utm_campaign|utm_content|utm_creative_format|utm_id|utm_marketing_tactic|utm_medium|utm_source|utm_source_platform|utm_term|wbraid|yclid|zanpid|mc_[a-z]+|utm_[a-z]+|_bta_[a-z]+)=") {
        set req.url = regsuball(req.url, "(_branch_match_id|srsltid|_bta_c|_bta_tid|_ga|_gl|_ke|_kx|campid|cof|customid|cx|dclid|dm_i|ef_id|epik|fbclid|gad_source|gbraid|gclid|gclsrc|gdffi|gdfms|gdftrk|hsa_acc|hsa_ad|hsa_cam|hsa_grp|hsa_kw|hsa_mt|hsa_net|hsa_src|hsa_tgt|hsa_ver|ie|igshid|irclickid|matomo_campaign|matomo_cid|matomo_content|matomo_group|matomo_keyword|matomo_medium|matomo_placement|matomo_source|mc_cid|mc_eid|mkcid|mkevt|mkrid|mkwid|msclkid|mtm_campaign|mtm_cid|mtm_content|mtm_group|mtm_keyword|mtm_medium|mtm_placement|mtm_source|nb_klid|ndclid|origin|pcrid|piwik_campaign|piwik_keyword|piwik_kwd|pk_campaign|pk_keyword|pk_kwd|redirect_log_mongo_id|redirect_mongo_id|rtid|sb_referer_host|ScCid|si|siteurl|s_kwcid|sms_click|sms_source|sms_uph|toolid|trk_contact|trk_module|trk_msg|trk_sid|ttclid|twclid|utm_campaign|utm_content|utm_creative_format|utm_id|utm_marketing_tactic|utm_medium|utm_source|utm_source_platform|utm_term|wbraid|yclid|zanpid|mc_[a-z]+|utm_[a-z]+|_bta_[a-z]+)=[-_A-z0-9+(){}%.]+&?", "");
        set req.url = regsub(req.url, "[?|&]+$", "");
    }

    # Step 3: Sort remaining parameters (only if multiple exist)
    if (req.url ~ "\?.+&.+") {
        set req.url = std.querysort(req.url);
    }

    # Step 4: Remove trailing slashes
    if (req.url ~ "^/(.+)/$") {
        set req.url = regsub(req.url, "/$", "");
    }
...
}
```

**Order matters!** Remove unwanted parameters *before* sorting to avoid sorting parameters you'll delete anyway.

## URL Normalization Best Practices

1. **Apply Early**: Place normalization logic at the beginning of `vcl_recv` before any cache lookups or routing decisions.

2. **Be Consistent**: Normalize URLs the same way on both request and cache key generation.

3. **Test Thoroughly**: Ensure normalization doesn't break functionality. Some applications may rely on empty query strings or specific URL formats.

4. **Document Your Rules**: URL normalization rules should be clearly documented, especially when removing query parameters that might be meaningful to some users.

5. **Consider Application Behavior**: Some single-page applications (SPAs) or tracking systems may generate URLs with query parameters. Understand your application's URL patterns before normalizing.

6. **Monitor Impact**: Track cache hit ratio improvements and watch for any broken functionality after implementing normalization.

## Performance Benefits

URL normalization provides several advantages:

* **Higher Cache Hit Ratio**: Fewer unique URLs mean more cache hits
* **Reduced Memory Usage**: Fewer cached objects consume less memory
* **Lower Backend Load**: More cache hits mean fewer backend requests
* **Faster Response Times**: Cached responses are orders of magnitude faster than backend requests
* **Improved Origin Performance**: Less load on your application servers

### Real-World Example

For a high-traffic site serving 1 million requests per day:

* **Without normalization**: 5% of URLs have trailing `?` = 50,000 duplicate cache entries
* **With normalization**: These 50,000 requests now hit existing cache entries
* **Impact**: 50,000 fewer backend requests, reduced memory usage, faster response times

This simple 4-line VCL snippet can have a measurable impact on your application's performance and infrastructure costs.

## Performance Impact by the Numbers

For a site receiving 10 million requests per day with 30% containing multiple query parameters:

* **Requests affected**: 3 million
* **Average parameter orderings**: 4 variations per unique parameter set
* **Cache entries without sorting**: 12 million
* **Cache entries with sorting**: 3 million
* **Backend requests saved**: \~2.25 million per day (assuming 75% cache hit rate on normalized URLs)

This optimization alone can reduce backend load by 20-30% for parameter-heavy applications.

## Conclusion

URL normalization is one of the highest-impact, lowest-effort optimizations you can implement in Varnish. By removing empty query strings, sorting parameters, and stripping tracking parameters, you can dramatically improve cache hit ratios and reduce backend load.

These simple VCL patterns consolidate duplicate cache entries, freeing memory and ensuring that more requests are served from cache. Start with these foundational normalization patterns, monitor your cache hit ratios, and adjust based on your application's specific URL patterns and traffic characteristics.

In our final article, Varnish 104: Advanced Traffic Filtering, we'll explore how to use classification headers to block malicious traffic based on abuse scores, geographic location, and network operators—adding an advanced security layer to your Varnish configuration.


# Varnish 104: Advanced Traffic Filtering with Classification Headers on Upsun
Source: https://developer.upsun.com/posts/hands-on/varnish-104-advanced-traffic-filtering-with-classification-headers-on-upsun

Learn how to implement advanced security controls in Varnish on Upsun using classification headers to block malicious traffic, restrict geographic access, filter by ASN, and protect sensitive paths with HTTP Basic Auth.

<PostMeta />

[Varnish Cache](https://docs.upsun.com/add-services/varnish.html) is a powerful HTTP accelerator that sits between your application and your users, dramatically improving performance through intelligent caching. On Upsun, Varnish becomes even more powerful and can protect your application when combined with our [data classification headers](https://docs.upsun.com/development/headers.html#classification-data-headers).

## How Varnish on Upsun Protects Your Applications

In this guide, we'll explore practical VCL techniques for building a more secure application by blocking malicious traffic based on abuse scores, geographic location and network operators.

## Blocking Requests by Abuse Score

One of the most effective ways to protect your application is to block traffic from known malicious IP addresses before it reaches your application layer. Using classification headers like `client-abuse-score`, you can make intelligent decisions about which requests to block directly in Varnish.

### Understanding the Abuse Score Header

The `client-abuse-score` header contains a numeric value indicating the likelihood that a request originates from a malicious source. Higher scores indicate higher risk. Services like AbuseIPDB aggregate reports of malicious activity from across the internet, and this data can be surfaced through classification headers.

### Implementation

Here's a VCL snippet that blocks requests with high abuse scores:

```vcl {filename=".upsun/config.vcl"} theme={null}
sub vcl_recv {
...
    # --- Block by Abuse Score ---
    # Check if the "client-abuse-score" header exists in the request.
    if (req.http.client-abuse-score) {
        # If the header exists, convert its value to an integer.
        # Then, check if the score is greater than 25.
        if (std.integer(req.http.client-abuse-score, 0) > 25) {
            # If the score is high, send a synthetic 403 Forbidden response.
            return (synth(403, "High client abuse score detected. Please check your IP on https://www.abuseipdb.com"));
        }
    }
...
}
```

### How It Works

1. **Header Check**: First, we verify that the `client-abuse-score` header exists in the incoming request using `if (req.http.client-abuse-score)`. This prevents errors if the header isn't present.

2. **Score Conversion**: The `std.integer()` function converts the header value to an integer. The second parameter (`0`) serves as a fallback value if the conversion fails, ensuring safe handling of unexpected data.

3. **Threshold Evaluation**: We compare the abuse score against a threshold (25 in this example). This value is configurable based on your security requirements:
   * **Lower thresholds (10-20)**: More aggressive blocking, may include false positives
   * **Medium thresholds (25-50)**: Balanced approach, blocks clearly malicious traffic
   * **Higher thresholds (50+)**: Conservative, only blocks highly suspicious IPs

4. **Synthetic Response**: When the threshold is exceeded, `return (synth(403, ...))` generates an HTTP 403 Forbidden response without touching your backend servers. The custom message directs users to check their IP reputation, which is helpful for legitimate users who may be on shared networks.

### Benefits

* **Early Termination**: Malicious requests are blocked at the edge, never reaching your application servers
* **Resource Savings**: Reduces load on backend infrastructure by filtering bad traffic early
* **Customizable**: Easy to adjust thresholds based on your traffic patterns and security needs

### Tuning Your Threshold

Start with a conservative threshold (like 50) and monitor your traffic. Review blocked requests and adjust downward if you're not catching enough malicious traffic, or upward if you're seeing false positives.

To understand your typical traffic patterns, review your Upsun environment logs and look for the `client-abuse-score` header values in legitimate requests. This baseline will help you set appropriate thresholds that protect against attacks without blocking real users.

## Geographic Access Control

Another powerful classification header available on Upsun is `client-country`, which identifies the geographic origin of a request using ISO 3166-1 alpha-2 country codes. This enables you to implement geographic access controls directly in Varnish, blocking or allowing traffic based on country of origin.

### When to Use Country-Based Blocking

Geographic filtering is useful in several scenarios:

* **Compliance Requirements**: Certain regulations (GDPR, export controls, sanctions) may require restricting access from specific regions
* **Threat Mitigation**: If you're experiencing attacks predominantly from certain geographic regions
* **Service Availability**: When your application or content is only licensed or intended for specific markets
* **Resource Protection**: Reducing load from regions where you don't operate or have customers

### Implementation

Here's how to block requests from specific countries:

```vcl {filename=".upsun/config.vcl"} theme={null}
sub vcl_recv {
...
    # --- Block by Country ---
    # Check if the "client-country" header exists.
    if (req.http.client-country) {
        # Match against a list of blocked country codes.
        # The (?i) flag makes the regex case-insensitive.
        # Example: Russia (RU), and North Korea (KP).
        if (req.http.client-country ~ "(?i)(RU|KP)") {
            # If the country is in the blocklist, return a 403 Forbidden error.
            return (synth(403, "Access from your country is restricted."));
        }
    }
...
}
```

### How It Works

1. **Header Validation**: The outer `if (req.http.client-country)` statement checks whether the country header exists. This defensive check prevents errors if geolocation data is unavailable.

2. **Regex Pattern Matching**: The `~` operator performs regular expression matching against the header value. Let's break down the regex pattern:
   * `(?i)`: Case-insensitive flag, ensuring matches work regardless of uppercase/lowercase
   * `(RU|KP)`: Matches any of the specified country codes using alternation (OR logic)

3. **Country Code Format**: The pattern uses [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements):
   * `RU`: Russian Federation
   * `KP`: Democratic People's Republic of Korea (North Korea)

4. **Rejection Response**: When a match occurs, `return (synth(403, ...))` immediately terminates the request with a 403 Forbidden status, providing a clear message to the user.

### Customizing Your Country List

Modify the regex pattern to match your requirements:

```vcl {filename=".upsun/config.vcl"} theme={null}
sub vcl_recv {
...
    # Block a larger set of countries
    if (req.http.client-country ~ "(?i)^(RU|CN|KP|IR|SY)$") {
        return (synth(403, "Access from your country is restricted."));
    }

    # Allow only specific countries (inverse logic)
    if (req.http.client-country && req.http.client-country !~ "(?i)^(US|CA|GB|AU)$") {
        return (synth(403, "Service is only available in select regions."));
    }
...
}
```

### Best Practices

* **Legal Review**: Consult with legal counsel before implementing geographic restrictions to ensure compliance with applicable laws
* **VPN Awareness**: Users can bypass country-based blocking using VPNs; this is a deterrent, not absolute security
* **Monitoring**: Log blocked countries to understand impact and adjust your list accordingly
* **Graceful Messaging**: Provide clear, professional error messages that explain the restriction
* **Exception Handling**: Consider implementing allowlists for specific IPs (partners, business relationships) within blocked countries

### Combining with Other Filters

Country-based filtering works well alongside other security measures:

```vcl {filename=".upsun/config.vcl"} theme={null}
sub vcl_recv {
...
    # Block high-risk combinations
    if (req.http.client-country ~ "(?i)^(RU|KP)$" &&
        std.integer(req.http.client-abuse-score, 0) > 10) {
        # Lower abuse threshold for certain countries
        return (synth(403, "Access denied due to security policies."));
    }
...
}
```

## Blocking by Autonomous System Number (ASN)

Beyond country codes and abuse scores, you can also filter traffic based on the Autonomous System Number (ASN) using the `client-asn` classification header. An ASN identifies the network operator responsible for routing internet traffic for a particular IP address block.

### Understanding ASN-Based Filtering

ASN filtering provides more granular control than country-based filtering. You might want to block specific ASNs because:

* **Cloud Provider Abuse**: Certain cloud hosting providers are frequently used for bot traffic or attacks
* **Known Bad Actors**: Specific ISPs or hosting companies with poor abuse management
* **Corporate Policy**: Blocking competitors' networks or specific corporate entities
* **Targeted Threats**: When attacks originate from specific network operators

### Implementation

Here's how to block traffic from specific ASNs:

```vcl {filename=".upsun/config.vcl"} theme={null}
sub vcl_recv {
...
    # --- Block by ASN (Autonomous System Number) ---
    # Check if the "client-asn" header exists.
    if (req.http.client-asn) {
        # Match against a list of blocked ASNs.
        # Example: Alibaba AS45102 and Huawei AS136907 ASNs "45102" and "AS136907".
        if (req.http.client-asn ~ "^(45102|136907)$") {
             # If the ASN is in the blocklist, return a 403 Forbidden error.
            return (synth(403, "Access from your network is restricted."));
        }
    }
...
}
```

### How It Works

1. **Header Check**: Verifies the `client-asn` header exists before attempting to match against it.

2. **Regex Matching**: Uses the `~` operator with a regex pattern to match specific ASNs:
   * `^`: Start anchor ensures matching from the beginning
   * `(45102|136907)`: Matches either ASN using alternation
   * `$`: End anchor ensures complete string match

3. **ASN Format**: ASNs are numeric identifiers. In this example:
   * `45102`: Alibaba
   * `136907`: Huawei Cloud

### Finding ASN Information

You can identify ASNs using various tools:

```bash {filename="Terminal"} theme={null}
# Using whois
whois -h whois.cymru.com " -v 1.2.3.4"

# Using online tools
# - https://bgp.he.net/
# - https://ipinfo.io/
```

### Important Considerations

* **Collateral Damage**: ASNs can represent large networks with many legitimate users. Block carefully.
* **Dynamic Threat Landscape**: Networks change ownership and abuse patterns shift. Review your blocklist regularly.
* **Granularity vs Coverage**: ASN blocking is more precise than country blocking but requires more maintenance.

## Combining Classification Headers with Other Security Patterns

Classification headers become even more powerful when combined with the security techniques from earlier in this series:

### Enhanced Rate Limiting

Layer rate limiting (from Varnish 102) with abuse scores for dynamic protection:

```vcl {filename=".upsun/config.vcl"} theme={null}
sub vcl_recv {
...
    # More aggressive rate limiting for suspicious IPs
    if (std.integer(req.http.client-abuse-score, 0) > 15) {
        if (vsthrottle.is_denied("suspicious:" + req.http.X-Client-IP, 10, 30s, 120s)) {
            return (synth(429, "Rate limit exceeded for suspicious traffic"));
        }
    }
...
}
```

### Path Protection with Geofencing

Combine HTTP Basic Auth (from Varnish 101) with geographic restrictions:

```vcl {filename=".upsun/config.vcl"} theme={null}
sub vcl_recv {
...
    # Require authentication for admin from outside trusted countries
    if (req.url ~ "^/admin") {
        if (req.http.client-country && req.http.client-country !~ "(?i)^(US|CA|GB)$") {
            # Non-trusted country accessing admin - require auth
            if (!req.http.Authorization ||
                req.http.Authorization !~ "^Basic YWRtaW46YWRtaW4=$") {
                return (synth(401, "Authentication Required"));
            }
        }
    }
...
}
```

## Conclusion

These advanced classification header techniques complete our Varnish security series. Combined with HTTP Basic Authentication (Varnish 101), rate limiting (Varnish 102), and cache optimization (Varnish 103), you now have a comprehensive toolkit for building secure, high-performance applications on Upsun.

By leveraging classification headers to block malicious traffic based on abuse scores, geographic location, and network operators, you can protect your applications at the edge before threats ever reach your backend infrastructure.

Start with conservative thresholds, monitor your traffic patterns, and adjust based on real-world behavior to find the right balance between security and accessibility for your specific use case.


# Zero-downtime deployments: now in open beta
Source: https://developer.upsun.com/posts/hands-on/zero-downtime-deployments-with-upsun

We've launched zero-downtime deployments in open beta. Deploy your applications without service interruption.

<PostMeta />

We're excited to announce the open beta of **zero-downtime deployments** on Upsun. This feature lets you deploy your applications without interrupting your live traffic—no more maintenance pages or brief service interruptions during deployments.

## What's available in beta

This beta feature focuses on **application deployments**, not services. You can now deploy application code changes, updates to environment variables, and configuration changes without any downtime for your users.

## How it works

The zero-downtime deployment process uses a rolling strategy with three key steps:

### 1. Clone and route traffic

Upsun creates a temporary clone of your current application and routes all live traffic to this clone while keeping the original running in the background.

<img alt="A clone is made of your current application" />

Upsun starts a temporary container running a cloned version of your app. The cloned app begins handling all live traffic during this time. Your services (for example Redis) will serve the cloned app as well as the original app.

### 2. Upgrade the original

While traffic is being served by the clone, the original application gets upgraded with your new code, configuration, or environment changes.

### 3. Switch back and cleanup

Once the original is fully upgraded and healthy, traffic switches back to the original application. The temporary clone is then removed.

<img alt="Cloned apps are removed after deployment" />

When deployment is complete, the clone of your app is shut down and removed. All traffic and services are now solely applied to the original app alone.

This ensures that your application is available throughout the entire deployment process—users never experience downtime.

## Important considerations

### Applications only

This feature applies to **applications**, not services. Services like databases, Redis, or other data storage systems stay intact and uninterrupted throughout the deployment. To upgrade services, you need to restart the application.

### Temporary resource increase

During the zero-downtime deployment, both the original and cloned applications run simultaneously for a brief period. This means:

* You'll temporarily use more resources while both versions are active
* Additional costs during this time are proportional to your application's resource usage and deployment duration
* The impact is minimal for typical deployments, especially for smaller applications

### Connection handling

Long-lived connections like WebSockets or Server-Sent Events (SSE) are dropped during any deployment. We recommend implementing reconnection logic in your applications.

To ensure your application only starts receiving traffic when it's steady and ready, we recommend using the `post_start` hook. This helps prevent 502 errors that can occur if traffic is routed to your application before it's fully initialized. For more information, see the [application startup documentation](https://docs.upsun.com/learn/overview/build-deploy.html#application-is-slow-to-start).

## How to try it

Zero-downtime deployments are available on **Upsun Flex**.

### Recommended: Enable manual deployments

The recommended way to use zero-downtime deployments is to enable **manual deployments** on your environment. This gives you full control over when and how deployments happen.

Once enabled, you can trigger deployments via the CLI:

```bash theme={null}
upsun environment:deploy --strategy rolling
```

Or via the Console: navigate to your environment settings and trigger a deployment from the deployment modal. Select **Zero Downtime** as your deployment strategy.

### Alternative: Using CLI push

If you don't want to enable manual deployments, you can use the latest CLI to deploy directly with zero-downtime strategy:

```bash theme={null}
upsun push --deploy-strategy=rolling
```

## Use cases

Zero-downtime deployments are ideal for:

* **Code pushes**: Deploy new features or bug fixes without service interruption
* **Configuration changes**: Update environment variables or application settings
* **High-traffic applications**: Keep critical services available during updates

**Not recommended for:**

* Database schema migrations (except when fully backward and forward compatible)
* Stateful service updates

## Need help?

If you encounter any issues or have questions about zero-downtime deployments, please raise a support ticket.

## Learn more

For more details on zero-downtime deployments, including troubleshooting and best practices, check out our [documentation](https://docs.upsun.com/learn/overview/build-deploy.html#zero-downtime-deployments).

Deploy with confidence!


# Airflow on a locked-down platform
Source: https://developer.upsun.com/posts/how-it-works/airflow-on-a-locked-down-platform

Running Apache Airflow on Upsun's hardened containers takes 30 lines of C and a decision about how much task isolation you actually want back.

<PostMeta />

Apache Airflow is a workflow orchestrator. You describe your pipelines as directed acyclic graphs (DAGs), which is a fancy way of saying "steps with dependencies", and Airflow schedules them, runs them, retries the ones that fail, and shows you what happened. People sometimes call it a Jenkins for data pipelines. That undersells the scheduling and dependency model, but it puts you in the right neighborhood.

It's also a Python application. And Python applications are supposed to be the boring case: install the package, point it at a database, run the process. On most hosts that's exactly how it goes.

On Upsun, if you deploy it the boring way, your tasks die before writing a single line of log. The scheduler looks healthy, the web UI loads, and every task instance you trigger fails with a `pid` of `None` and a 0-byte log file. That is a genuinely confusing place to start debugging.

The reason is a good one. And the fix is 30 lines of C, followed by a decision that's more interesting than the C.

## Your own process disappears

Upsun mounts `/proc` inside every container with `hidepid`. That option changes who's allowed to see a process. Instead of every process on the box being world-readable through `/proc/<pid>`, a process is visible only to callers that would be allowed to `ptrace` it. This is part of [how Upsun hardens its containers](/posts/how-it-works/how-weve-been-hardening-containers-since-before-docker-made-it-cool), and most of the time you never notice it.

The kernel decides "allowed to ptrace" with a check called `ptrace_may_access`. One of its conditions is that the target process has to be *dumpable*. A dumpable process is one the kernel will write a core dump for, and by extension one that same-user tooling is allowed to inspect. Normal processes are dumpable by default.

Here's where Airflow and the platform disagree. Airflow's Task SDK runs each task under a small supervisor process, and that supervisor calls `prctl(PR_SET_DUMPABLE, 0)` on the task. In plain terms, the task tells the kernel "nobody sharing my user id gets to read my memory". Airflow does this on purpose, to stop one task from reading another task's memory, environment, and secrets through `ptrace` or `process_vm_readv`.

On a machine with an ordinary `/proc`, that's a reasonable hardening step and nothing breaks. On a `hidepid` `/proc`, it backfires. The moment the task marks itself non-dumpable, it fails the `ptrace_may_access` check, so it vanishes from `/proc`, including from the supervisor that spawned it. The supervisor watches its task with `psutil`, `psutil` goes looking for `/proc/<pid>`, finds nothing, and raises `NoSuchProcess`. The task is killed off before it does any real work.

So you get two hardening mechanisms that are each correct on their own, and together they make Airflow unable to see its own children.

## Thirty lines of C

Airflow reaches `prctl` the way a lot of Python does: through `ctypes.CDLL(None).prctl(...)`, which resolves the libc symbol at runtime with `dlsym`. Anything resolved that way can be intercepted with `LD_PRELOAD`. That's the whole opening.

The interposer swallows exactly one call, the "make me non-dumpable" one, and passes every other `prctl` straight through to the real implementation:

```c theme={null}
#define _GNU_SOURCE
#include <dlfcn.h>
#include <linux/prctl.h>

typedef int (*prctl_fn)(int, unsigned long, unsigned long,
                        unsigned long, unsigned long);

int prctl(int option, unsigned long arg2, unsigned long arg3,
          unsigned long arg4, unsigned long arg5) {
    /* Swallow only "set dumpable to 0"; report success so Airflow's
       error handling stays happy. Pass everything else through. */
    if (option == PR_SET_DUMPABLE && arg2 == 0) {
        return 0;
    }
    static prctl_fn real_prctl = 0;
    if (!real_prctl) {
        real_prctl = (prctl_fn)dlsym(RTLD_NEXT, "prctl");
    }
    return real_prctl(option, arg2, arg3, arg4, arg5);
}
```

Build it during the container build hook, and set `LD_PRELOAD` on the process that runs tasks:

```bash theme={null}
cc -shared -fPIC -O2 -o no_nondumpable.so no_nondumpable.c -ldl
```

```bash theme={null}
LD_PRELOAD=/app/lib/no_nondumpable.so airflow celery worker
```

Because it hooks the syscall wrapper and not an Airflow function, it keeps working across Airflow upgrades, even if the internal helper gets renamed or moved. It also refuses to overreach: a `PR_SET_DUMPABLE` with a non-zero value, or any other `prctl` option, goes through untouched.

Now your tasks run.

## The variables you set regardless

Whichever isolation level you land on, Airflow needs a handful of values set as environment variables on the environment before the first deploy. The sensitive ones should be set as sensitive variables so they stay out of logs and the config file.

| Variable | Purpose |
| - | - |
| `AIRFLOW_ADMIN_USERNAME` | Admin login, created on first deploy |
| `AIRFLOW_ADMIN_EMAIL` | Admin account email |
| `AIRFLOW_ADMIN_PASSWORD` | Admin password (sensitive) |
| `AIRFLOW__CORE__FERNET_KEY` | Encrypts stored connections and variables at rest (sensitive) |
| `AIRFLOW__API__SECRET_KEY` | Signs session cookies (sensitive) |

The rest, the database connection, the executor choice, the DAGs folder, and the log folder, live in the config. Airflow reads any `AIRFLOW__SECTION__KEY` environment variable as a config override, which is what makes it comfortable to run this way. The database connection comes from the Upsun relationship, decoded into a SQLAlchemy URL at startup and exported as `AIRFLOW__DATABASE__SQL_ALCHEMY_CONN`.

## The interesting part: how much isolation do you want back?

Airflow turned that protection on for a reason. By neutralizing it, you've reopened the door it was closing: two tasks that share a container can read each other's memory, environment variables, and secrets. Whether that matters depends entirely on who writes your DAGs.

If every DAG in your deployment comes from the same team, targets the same data, and holds the same secrets, then a task reading another task's environment is not a threat. You've decided the blast radius is one team's own code. That's a legitimate choice, and it buys you the simplest setup.

If your DAGs come from different teams, or handle secrets that shouldn't mix, that shared container is a problem you'll want to fix. Upsun gives you a few ways up that ladder, and they cost progressively more to run.

### You don't need the isolation

The plainest deployment runs the whole of Airflow in one container: the API server, the scheduler, the triggerer, the DAG processor, and the workers, all supervised together. Tasks run as subprocesses next to everything else.

One thing worth flagging from experience: give that container real headroom. Airflow's scheduler and workers are memory-hungry, and forking task subprocesses out of a cramped container is where you meet flaky, hard-to-reproduce failures. A generous [container profile](/docs/configure-apps/image-properties/container_profile) with guaranteed resources pays for itself in debugging time you don't spend.

The next step out is a dedicated [worker](/docs/configure-apps/image-properties/workers#workers). The web container keeps the scheduler and the UI, and the task execution moves to its own container that you can size and scale on its own:

```yaml theme={null}
applications:
  airflow:
    type: python:3.12
    web:
      commands:
        start: bash scripts/start_airflow.sh
    workers:
      worker:
        commands:
          start: bash scripts/start_worker.sh
```

Same image, same code, separate resources. Since the two containers don't share `localhost`, the worker reaches Airflow's execution API over the environment's public route instead. This still runs multiple tasks side by side in the worker container, so the isolation trade-off is unchanged. What you gain is the ability to scale scheduling and execution independently, which is often the real reason to split them.

### You want the isolation, cheaply

The cheapest way to get isolation back is to stop running tasks side by side. Set your executor parallelism to 1, and a task never shares its container with another task, because there is no other task. Nothing to peek at.

This is a real option for low-volume pipelines, and it costs nothing extra. It also serializes everything, so it falls apart the moment you need two things to run at once. For a nightly batch that walks a handful of steps, that can be perfectly fine. For anything with fan-out, it isn't.

### You want the isolation, properly

The version I'm happiest with uses [task containers](/docs/configure-apps/tasks). A task container is an on-demand, run-to-completion container: something triggers it through the API, it runs a single command with full access to your environment's services, and it's destroyed when the command exits.

Run each Airflow task in its own task container and the isolation question disappears. Nothing else shares that container, so the non-dumpable protection you removed was protecting against a neighbor that no longer exists. The `LD_PRELOAD` shim is still needed for `psutil` to see the process, but its only downside is gone.

Airflow doesn't ship with an executor that knows how to do this, so you write one. Airflow 3's executor interface is small: the scheduler hands you `ExecuteTask` workloads, each carrying the task's identity and a short-lived API token, and you decide where they run. Instead of enqueueing to Celery, the executor triggers a task container and passes the serialized workload in as an environment variable:

```python theme={null}
"""UpsunTaskExecutor — an Airflow 3.x executor that runs every task instance in
its own ephemeral, fully-isolated Upsun *task* container.

The scheduler hands the executor `ExecuteTask` workloads (each carrying the TI
identity + a short-lived Execution API JWT). Instead of enqueueing to Celery,
this executor triggers an Upsun task (`task-runner`), passing the serialized
workload as an env var. The task container deserializes it and runs the task
via the same Task SDK `supervise()` path the celery worker uses
(runtime/task_runner.py), talking to the Execution API with the token.

Because each container runs exactly one task and is then destroyed, the
hidepid/PR_SET_DUMPABLE shim that the runner still needs has no security
downside there — nothing else shares the container.

Auth: mints a scoped token from the in-container OAuth2 service
(localhost:8200); the app must declare `authorizations: [{type: task,
resource: task-runner, action: operate}]`. Falls back to $UPSUN_API_TOKEN.

CAVEATS (by design of the tasks feature): per-task container cold-start is a few
seconds, and the tasks API caps concurrency (default 3 parallel runs). This
executor is therefore best for isolation-sensitive / long-running tasks, not
high-throughput short ones.
"""
from __future__ import annotations

import base64
import json
import logging
import os
import time
import urllib.error
import urllib.parse
import urllib.request
from typing import TYPE_CHECKING, Sequence

from airflow.executors.base_executor import BaseExecutor
from airflow.utils.state import TaskInstanceState

if TYPE_CHECKING:
    from airflow.executors import workloads
    from airflow.models.taskinstance import TaskInstance
    from airflow.models.taskinstancekey import TaskInstanceKey

log = logging.getLogger(__name__)

_API_BASE = os.environ.get("UPSUN_API_BASE", "https://api.upsun.com")
_TOKEN_URL = "http://localhost:8200/oauth2/token"
_TERMINAL = {"complete", "cancelled"}


class UpsunTaskExecutor(BaseExecutor):
    """Run each task instance in a one-shot Upsun task container."""

    #: name of the Upsun task (the `tasks:` key in .upsun/config.yaml)
    task_name = os.environ.get("UPSUN_RUNNER_TASK", "task-runner")

    def __init__(self, parallelism: int = 32, team_name: str | None = None) -> None:
        super().__init__(parallelism=parallelism, team_name=team_name)
        self._activities: dict[TaskInstanceKey, str] = {}
        self._token: str | None = None
        self._token_expiry: float = 0.0
        project = os.environ.get("PLATFORM_PROJECT", "")
        env = os.environ.get("PLATFORM_BRANCH") or os.environ.get("PLATFORM_ENVIRONMENT", "")
        self._base = f"{_API_BASE}/projects/{project}/environments/{env}"
        # Map Airflow queue -> Upsun task definition, so specific DAGs/tasks can
        # run in a differently-resourced task container. Convention: the
        # "default" queue uses self.task_name; any other queue "q" uses
        # "<task_name>-<q>" (declare that task + its app authorization in
        # config). Override/extend via UPSUN_QUEUE_TASK_MAP (JSON
        # {"<queue>": "<upsun task name>"}).
        self._queue_map: dict = json.loads(os.environ.get("UPSUN_QUEUE_TASK_MAP", "{}"))
        # The task container can't reach the api-server on localhost and has no
        # PLATFORM_ROUTES, so we resolve the public Execution API URL here (the
        # web app knows it) and pass it to the task.
        self._exec_api = self._execution_api_url()

    @staticmethod
    def _execution_api_url() -> str:
        base = os.environ.get("AIRFLOW__API__BASE_URL")
        if base:
            return base.rstrip("/") + "/execution/"
        routes = json.loads(base64.b64decode(os.environ["PLATFORM_ROUTES"]).decode())
        for url, cfg in routes.items():
            if cfg.get("primary"):
                return url.rstrip("/") + "/execution/"
        raise RuntimeError("cannot determine Execution API URL (no AIRFLOW__API__BASE_URL / primary route)")

    def _task_for_queue(self, queue: str | None) -> str:
        q = queue or "default"
        if q in self._queue_map:
            return self._queue_map[q]
        if q == "default":
            return self.task_name
        return f"{self.task_name}-{q}"

    # -- auth ----------------------------------------------------------------
    def _token_value(self, force: bool = False) -> str:
        explicit = os.environ.get("UPSUN_API_TOKEN")
        if explicit:
            return explicit
        if not force and self._token and time.monotonic() < self._token_expiry - 30:
            return self._token
        data = urllib.parse.urlencode({"grant_type": "client_credentials"}).encode()
        req = urllib.request.Request(_TOKEN_URL, data=data, method="POST")
        req.add_header("Content-Type", "application/x-www-form-urlencoded")
        req.add_header("x-token-ttl", "900")  # match our polling cadence
        with urllib.request.urlopen(req, timeout=15) as resp:
            payload = json.loads(resp.read().decode())
        self._token = payload["access_token"]
        self._token_expiry = time.monotonic() + int(payload.get("expires_in", 900))
        return self._token

    def _api(self, method: str, url: str, body: dict | None = None, _retry: bool = True) -> dict:
        data = json.dumps(body).encode() if body is not None else None
        req = urllib.request.Request(url, data=data, method=method)
        req.add_header("Authorization", f"Bearer {self._token_value()}")
        if data is not None:
            req.add_header("Content-Type", "application/json")
        try:
            with urllib.request.urlopen(req, timeout=30) as resp:
                raw = resp.read().decode()
        except urllib.error.HTTPError as e:
            if e.code == 401 and _retry:
                self._token_value(force=True)
                return self._api(method, url, body, _retry=False)
            raise RuntimeError(f"{method} {url} -> HTTP {e.code}: {e.read().decode(errors='replace')}") from e
        return json.loads(raw) if raw else {}

    # -- scheduler interface -------------------------------------------------
    def _process_workloads(self, workloads_seq: Sequence["workloads.All"]) -> None:
        from airflow.executors.workloads import ExecuteTask

        for workload in workloads_seq:
            if not isinstance(workload, ExecuteTask):
                raise ValueError(f"{type(self).__name__} cannot handle {type(workload).__name__}")
            key = workload.ti.key
            task_name = self._task_for_queue(getattr(workload.ti, "queue", None))
            try:
                activity_id = self._trigger(workload, task_name)
            except Exception as e:  # noqa: BLE001 - report as a failed launch
                self.log.error("Failed to trigger Upsun task %r for %s: %s", task_name, key, e)
                self.queued_tasks.pop(key, None)
                self.event_buffer[key] = (TaskInstanceState.FAILED, None)
                continue
            self.queued_tasks.pop(key, None)
            self.running.add(key)
            self._activities[key] = activity_id
            self.event_buffer[key] = (TaskInstanceState.QUEUED, activity_id)
            self.log.info("Task %s (queue=%s) -> %s / Upsun activity %s",
                          key, getattr(workload.ti, "queue", None), task_name, activity_id)

    def _trigger(self, workload: "workloads.ExecuteTask", task_name: str) -> str:
        body = {"variables": {"env": {
            "UPSUN_WORKLOAD": workload.model_dump_json(),
            "AIRFLOW__CORE__EXECUTION_API_SERVER_URL": self._exec_api,
        }}}
        resp = self._api("POST", f"{self._base}/tasks/{task_name}/run", body)
        emb = resp.get("_embedded", {})
        acts = emb.get("activities")
        activity = acts[0] if isinstance(acts, list) and acts else (acts if isinstance(acts, dict) else resp)
        activity_id = activity.get("id")
        if not activity_id:
            raise RuntimeError(f"no activity id in run response: {resp}")
        return activity_id

    def sync(self) -> None:
        for key, activity_id in list(self._activities.items()):
            try:
                act = self._api("GET", f"{self._base}/activities/{activity_id}")
            except Exception as e:  # noqa: BLE001 - transient API error, retry next heartbeat
                self.log.warning("Polling activity %s failed: %s", activity_id, e)
                continue
            state = (act.get("state") or act.get("status") or "").lower()
            if state not in _TERMINAL:
                continue
            result = (act.get("result") or "").lower()
            self._activities.pop(key, None)
            if state == "complete" and result != "failure":
                self.log.info("Upsun activity %s complete -> success for %s", activity_id, key)
                self.success(key)
            else:
                self.log.warning("Upsun activity %s ended state=%s result=%s -> fail for %s",
                                 activity_id, state, result, key)
                self.fail(key)

    def try_adopt_task_instances(self, tis: Sequence["TaskInstance"]) -> Sequence["TaskInstance"]:
        # We don't persist activity ids across scheduler restarts; let the
        # scheduler reschedule orphaned TIs rather than adopt them.
        return list(tis)

    def end(self) -> None:
        self.heartbeat()

    def terminate(self) -> None:  # pragma: no cover - nothing long-lived to kill here
        pass
```

The task container's side is a short script that deserializes the workload and runs it through the same Task SDK path a Celery worker would use. The token in the workload authorizes it, so the container needs no database or broker access at all. The app declares an [authorization](/docs/configure-apps/image-properties/authorizations) to operate the task, and Upsun's in-container token service mints a scoped, credential-less token at runtime.

The part I find genuinely useful is that you can define more than one class of task container. Route memory-hungry DAGs to a large one and everything else to a small one:

```yaml theme={null}
tasks:
  task-runner:
    type: python:3.12
    container_profile: HIGH_MEMORY
    source:
      root: /runtime
    run:
      command: LD_PRELOAD=/app/lib/no_nondumpable.so python task_runner.py
      timeout: 3600
```

Because a task container only exists while a task runs, you pay for compute per task instead of for a worker that sits idle between DAG runs. The queue-to-task mapping in the executor lets you tune that per workload.

Two caveats to plan around. A per-task container has a cold start of a few seconds, so this suits isolation-sensitive or long-running tasks better than a flood of sub-second ones. And task containers cap concurrency at a default of 3 parallel runs, with further triggers queuing behind them. That default is adjustable, but design for it rather than against it.

## Why go to the trouble

At the end of the ladder you have Airflow running the way it's meant to, and you have it inside an Upsun environment. That second part is what makes the effort worth it.

Branch an environment and Upsun clones its data, so a staging copy of your Airflow comes up with a real Postgres database instead of an empty one. Add [object storage](/docs/manage-resources/object-storage) and the buckets clone alongside it, so your DAGs run against realistic data in staging without touching production. You get scoped secrets, per-environment variables, and the same container hardening this whole article started with, applied to a data platform you can branch, test, and throw away.

The 30 lines of C get you in the door. The isolation model is the choice worth making deliberately, and it's nice that the platform lets you make it at all.

<Note>
  Task containers are in prerelease. Read [the task containers documentation](/docs/configure-apps/tasks) to see how they work and request access on your project.
</Note>


# Auto-scaling on Upsun Flex. A deep dive.
Source: https://developer.upsun.com/posts/how-it-works/autoscaling-deep-dive

Learn how Upsun's autoscaling dynamically adjusts application instances based on CPU usage, ensuring performance during traffic spikes while optimizing costs.

<PostMeta />

## Introduction

Traffic doesn't arrive on schedule. Your application might handle steady requests for hours, then face a sudden spike from a product launch, marketing campaign, or unexpected viral moment. Manual scaling requires you to predict these patterns and adjust resources ahead of time, often leading to over-provisioning during quiet periods or scrambling to add capacity during peak load.

Upsun's new [autoscaling feature](https://docs.upsun.com/manage-resources/autoscaling.html) removes this guesswork. Your applications automatically scale horizontally based on real-time CPU metrics, adding instances when demand increases and removing them when traffic subsides. This ensures consistent performance for your users while keeping infrastructure costs aligned with actual usage.

## How autoscaling works on Upsun

### The scaling mechanism

Autoscaling continuously monitors average CPU utilization across all running instances of your application. When you configure autoscaling, you define two critical [thresholds](https://docs.upsun.com/manage-resources/autoscaling.html#thresholds):

**Scale-up threshold**: When average CPU usage exceeds this level for your configured evaluation period, Upsun launches additional instances to distribute the load. The default threshold is 80% CPU for 5 minutes.

**Scale-down threshold**: When average CPU usage falls below this level for the evaluation period, Upsun removes unnecessary instances to reduce costs. The default threshold is 20% CPU for 5 minutes.

Between scaling actions, a cooldown window prevents rapid fluctuations. This waiting period (default: 5 minutes) ensures the system stabilizes before making another adjustment.

### Architecture considerations

Autoscaling applies specifically to application containers, including your [PHP](https://docs.upsun.com/languages/php.html), [Node.js](https://docs.upsun.com/languages/nodejs.html), [Python](https://docs.upsun.com/languages/python.html), or [other runtime](https://docs.upsun.com/languages.html) environments. Services like [MySQL](https://docs.upsun.com/add-services/mysql.html), [PostgreSQL](https://docs.upsun.com/add-services/postgresql.html), [Redis](https://docs.upsun.com/add-services/redis.html), and [Elasticsearch](https://docs.upsun.com/add-services/elasticsearch.html) continue to scale vertically through manual configuration. This separation makes sense because databases and caches typically require different scaling strategies than stateless application layers.

```mermaid theme={null}
graph LR
    subgraph Upsun_Environment["Upsun Environment"]
        Router[Router]

        subgraph Application_Layer["Application Layer"]
            PHP1["PHP App<br/>Instance 1<br/>CPU: 85%"]
            PHP2["PHP App<br/>Instance 2<br/>CPU: 82%"]
            PHP3["PHP App<br/>Instance 3<br/>CPU: 79%"]
        end
        
        Network[Internal Network]

        subgraph Service_Layer["Service Layer"]
            MySQL["MySQL Primary<br/>4 CPU / 6.7 GB"]
            ES["Elasticsearch<br/>2 CPU / 4 GB"]
            Network_Storage["Network Storage<br/>"]
        end

        Router --> PHP1
        Router --> PHP2
        Router --> PHP3

        PHP1 --> Network
        PHP2 --> Network
        PHP3 --> Network

        Network -.-> MySQL
        Network -.-> Network_Storage
        Network -.-> ES
    end

    style Application_Layer fill:#D0F302,stroke:#000,color:#000
    style Service_Layer fill:#fff,stroke:#000,color:#000
    style Router fill:#000,stroke:#000,color:#D0F302
    style PHP1 fill:#D0F302,stroke:#000,color:#000
    style PHP2 fill:#D0F302,stroke:#000,color:#000
    style PHP3 fill:#D0F302,stroke:#000,color:#000
    style Network fill:#000,stroke:#000,color:#fff
    style MySQL fill:#6046FF,stroke:#000,color:#fff
    style ES fill:#6046FF,stroke:#000,color:#fff
    style Network_Storage fill:#6046FF,stroke:#000,color:#fff
```

### Practical example: E-commerce traffic spike

Consider a [Magento](https://docs.upsun.com/get-started/stacks/magento.html) storefront running on Upsun. During normal business hours, two PHP application instances handle incoming requests comfortably, maintaining 40% average CPU usage.

A flash sale begins at noon. Traffic increases fivefold within minutes. Average CPU across your two instances climbs to 85% and stays there for 5 minutes. Autoscaling detects this sustained elevation above the 80% threshold and launches a third instance. The load distributes across three containers, bringing average CPU down to 60%.

As the sale winds down two hours later, traffic returns to baseline levels. Average CPU drops to 25%, then 18% over the evaluation period. Autoscaling waits for the cooldown window to expire, confirms CPU remains below 20% for another 5 minutes, then removes one instance. Your infrastructure returns to two instances, matching the original capacity.

Throughout this cycle, your MySQL database and Elasticsearch service continue running with their manually configured resources: 4 CPU with 6.7 GB RAM for MySQL, 2 CPU with 4 GB RAM for Elasticsearch. These services don't need horizontal scaling for this workload pattern.

## Configure autoscaling for your application

### Enable autoscaling through the Console

Access your project in the Upsun Console and select the environment where you want autoscaling:

<img alt="Autoscaling config" />

1. Click **Configure resources** in the project card
2. Locate the autoscaling column for your application
3. Select **Enable**
4. Configure your thresholds and guardrails:
   * **Scale-up threshold**: CPU percentage that triggers instance addition (default: 80%)
   * **Scale-down threshold**: CPU percentage that triggers instance removal (default: 20%)
   * **Evaluation period**: How long metrics must exceed thresholds (1-60 minutes, default: 5)
   * **Cooldown window**: Wait time between scaling actions (default: 5 minutes)
   * **Minimum instances**: Baseline capacity that's always available (default: 1)
   * **Maximum instances**: Upper limit to prevent runaway scaling (default: 8, region-dependent)

### Understand your guardrails

Minimum and maximum instance counts act as safety boundaries. Setting minimum instances to 2 ensures your application maintains redundancy even during low traffic periods. This prevents a single point of failure and gives you instant capacity if traffic arrives suddenly.

Maximum instances protect against unexpected scaling costs. If your application experiences abnormal behavior (perhaps a bug causing excessive CPU usage), the maximum cap prevents unlimited resource consumption.

### Available triggers

Currently, autoscaling responds to **average CPU utilization** as its primary trigger. This metric provides a reliable indicator of application load across most workload types. Future releases will add memory-based triggers for applications with different resource consumption patterns.

## Autoscaling for different roles

### For developers: Implementation patterns

When you enable autoscaling, your application architecture becomes critical. Store session data in Redis or another shared service rather than in memory or local filesystem—sessions won't transfer between instances, breaking user experience. Similarly, use object storage (S3-compatible services) or network storage for uploaded files, since mount points on one instance won't appear on others.

Design your application to be stateless. Each instance should handle requests identically without depending on previous requests processe

### For technical leads: Capacity planning

Autoscaling shifts capacity planning from prediction to configuration. Set your scale-up threshold based on acceptable response times. If 80% CPU correlates with sub-200ms responses, that threshold maintains performance during growth. Evaluation periods balance responsiveness against stability. Short periods (2-3 minutes) respond quickly but may scale unnecessarily for brief spikes, while longer periods (10-15 minutes) provide stability at the cost of slower response.

For applications with predictable traffic patterns, like daily peaks at specific hours, consider scheduling vertical resource adjustments to supplement autoscaling. Scale CPU and RAM on your baseline instances before known traffic increases, then let autoscaling handle horizontal expansion as needed.

### For business decision-makers: Cost and availability optimization

Traditional fixed-capacity infrastructure requires paying for peak capacity around the clock. A retail site needing 8 application instances during holiday shopping peaks runs those 8 instances all year, including slow January weeks when traffic drops 70%. Autoscaling aligns costs with revenue-generating activity. During low-traffic periods, infrastructure scales down to minimum instances, reducing spend. When traffic and sales increase, scaling adds capacity automatically.

Reliability improves through automatic response to load. Manual scaling requires someone to notice performance degradation, access infrastructure controls, and trigger scaling actions. By the time this happens, users may have already experienced slow responses or errors. Autoscaling responds within minutes of detecting elevated load, often before human intervention would begin.

## Monitor autoscaling behavior

### Metrics and dashboards

Upsun provides several visibility layers for autoscaling activity. The [Infrastructure Metrics dashboard](https://docs.upsun.com/increase-observability/metrics/http-metrics.html) displays current instance count alongside CPU, memory, and request metrics. Track how scaling responds to traffic patterns and identify opportunities to refine thresholds.

Application metrics through Blackfire integration show performance impact at the code level. Compare response times and throughput across different instance counts to verify scaling improves application behavior as expected.

### Alerts and notifications

The Console displays scaling events with specific icons:

* Bell icon: Threshold alerts (e.g., "CPU above 80% for 5 minutes")
* Resources icon: Scaling actions (e.g., "1 instance added to application")

Configure custom notifications by setting up activity scripts that respond to `environment.alert` events. Send [Slack messages](https://docs.upsun.com/integrations/activity/slack.html), emails, or [webhook notifications](https://docs.upsun.com/integrations/activity/webhooks.html) when scaling occurs. This provides operational awareness without requiring constant dashboard monitoring.

### CLI access

Use the Upsun CLI to review [scaling events](https://docs.upsun.com/integrations/activity/reference.html#type) programmatically:

```bash {filename="Terminal"} theme={null}
upsun activity:list --type environment.alert
upsun activity:list --type environment.resources.update
```

These commands show historical scaling actions, including timestamps, triggering conditions, and resulting instance counts.

## Cost implications and billing

Autoscaling projects bill for consumed resources. Each instance added through autoscaling incurs the same charges as a manually configured instance with equivalent CPU and RAM.

Calculate maximum potential costs by multiplying your single-instance resource allocation by your maximum instance count. An application configured for 2 CPU and 4 GB RAM with maximum instances of 8 could consume up to 16 CPU and 32 GB RAM during peak scaling.

Monitor actual usage patterns through the billing dashboard. Compare costs across time periods to identify opportunities for optimization. If your application consistently runs at maximum instances, either traffic has permanently increased (requiring higher baseline resources), or your thresholds need adjustment to prevent aggressive scaling.

## Best practices and optimization strategies

### Threshold tuning

Start with default thresholds (80% scale-up, 20% scale-down) and adjust based on observed behavior. Applications with consistent, predictable load benefit from tighter thresholds (75% up, 30% down) that maintain resources closer to actual needs. Applications with spiky, unpredictable traffic need wider thresholds to prevent constant scaling fluctuations.

Monitor the frequency of scaling events. Multiple scale-up and scale-down cycles within an hour suggest overly sensitive thresholds or too-short evaluation periods. Adjust one parameter at a time to isolate the effect of each change.

### Application design for horizontal scaling

External services (databases, caches, search indexes) should live outside your application containers. Upsun's service architecture supports this naturally. Your application containers connect to services through configuration, allowing instances to share data stores without architectural changes.

Avoid local state within application containers. Each instance should handle requests identically, without depending on previous requests processed by the same instance. Store session data in [Redis](https://docs.upsun.com/add-services/redis.md), [Valkey](https://docs.upsun.com/add-services/valkey.md), or your database. Never store sessions in local memory or filesystem. Redis and Valkey offer the best performance for session storage with their in-memory architecture, while database storage provides an alternative if you already have a database service configured. This ensures the load balancer can distribute traffic efficiently across all available instances without breaking user sessions.

For file storage and volumes, use [Network Storage](https://docs.upsun.com/add-services/network-storage.md) to ensure all application instances can access the same files. Standard mounts are local to each container. Files written to one instance won't appear on others. Network Storage provides a shared filesystem accessible across all instances, perfect for user uploads, generated assets, or any files that need to persist across your horizontally scaled application layer. Configure Network Storage as a service in your project, then mount it in your application configuration following the guidelines for [composable images](https://docs.upsun.com/create-apps/app-reference/composable-image.md#mounts) or [single-runtime images](https://docs.upsun.com/create-apps/app-reference/single-runtime-image.md#mounts).

### Evaluation periods and cooldown windows

Longer evaluation periods (10-15 minutes) work well for applications where traffic changes gradually. E-commerce sites often see traffic build over 30-60 minutes as promotions spread through email and social media. A 15-minute evaluation period prevents scaling for temporary spikes while responding appropriately to sustained growth.

API services handling burst traffic need shorter periods (3-5 minutes). These applications see rapid load changes that require quick response. Balance this against cooldown windows to prevent oscillation.

### Managing cron jobs

[Cron jobs](https://docs.upsun.com/create-apps/app-reference/single-runtime-image.html#crons) executing during scaling events continue on their original instance until completion. This prevents interrupted tasks but means CPU-intensive cron jobs may trigger scale-ups.

Schedule resource-intensive jobs during known low-traffic periods. Database maintenance, report generation, and data processing work better late at night or early morning when autoscaling runs at minimum capacity.

Alternatively, move long-running tasks to dedicated [worker](https://docs.upsun.com/create-apps/app-reference/single-runtime-image.html#workers) containers that scale independently. Separate [cron job](https://docs.upsun.com/create-apps/app-reference/single-runtime-image.html#crons) execution from request handling, giving you fine-grained control over resources for each workload type.

## Advanced scenario: Multi-app autoscaling

Upsun's [multi-app architecture](https://docs.upsun.com/create-apps.html#use-multiple-apps) allows different applications within a single project to scale independently. Consider a headless commerce implementation:

* **API application** (Node.js): Handles product data, cart operations, checkout
* **Frontend application** (Next.js): Delivers server-rendered pages to users
* **Admin application** (PHP): Provides merchant dashboard for order management

Enable autoscaling on each application with different thresholds:

* API: 70% scale-up (CPU-intensive data processing), minimum 2 instances
* Frontend: 80% scale-up (lighter workload), minimum 2 instances
* Admin: Manual scaling only (predictable load from internal users)

During a marketing campaign, the frontend and API scale independently based on their respective loads. The admin application maintains fixed capacity since merchant activity doesn't correlate with customer traffic.

## Limitations and current support

Autoscaling currently supports:

* Application containers (PHP, Node.js, Python, Go, Java, Ruby, .NET)
* CPU-based triggers
* Upsun Flex product tier
* All environment types (development, staging, production)

Autoscaling does not support:

* Services (databases, caches, search indexes)
* Worker containers and background job queues
* Memory-based triggers (planned for future release)
* Scaling to zero instances

## Related resources

**Configuration and management**:

* [Resource configuration](https://docs.upsun.com/manage-resources/adjust-resources.html)
* [Resource initialization strategies](https://docs.upsun.com/manage-resources/resource-init.html)
* [Manual horizontal scaling](https://docs.upsun.com/manage-resources/adjust-resources.html#horizontal-scaling)

**Monitoring and observability**:

* [Infrastructure metrics](https://docs.upsun.com/increase-observability/metrics.html)
* [Application performance monitoring](https://docs.upsun.com/increase-observability/application-metrics.html)
* [Blackfire integration](https://docs.upsun.com/increase-observability/application-metrics/blackfire.html)

**Cost management**:

* [Monitor billing](https://docs.upsun.com/administration/billing/bp-monitor-billing.html)
* [Upsun pricing](https://www.upsun.com/pricing/)

***

**Get started with autoscaling**:

Create a free Upsun account at [upsun.com](https://upsun.com) and enable autoscaling on your first project. Configure thresholds based on your application's performance characteristics, then monitor scaling behavior through the Console metrics dashboard. Adjust settings as you learn your application's patterns, finding the balance between performance, stability, and cost that works for your specific workload.


# Backup consistency: why it matters and how Upsun handles it
Source: https://developer.upsun.com/posts/how-it-works/backup-consistency-why-it-matters-and-how-upsun-handles-it

Learn what backup consistency means at the filesystem and service levels, and how Upsun balances consistent backups with zero-disruption live backups.

<PostMeta />

A backup is only useful if you can restore it. Copying the bytes is the straightforward part. The hard part is making sure those bytes still make sense together once you restore them. That property is called consistency, and it lives at 2 levels: within a single filesystem, and across the services that make up your application.

## Consistency at the filesystem level

Picture what happens when you snapshot a disk while the application is writing to it. A file's data blocks may already be on disk while the filesystem metadata (the structures that describe what lives where, like the superblock) still says something else. Restore that snapshot and you get a filesystem that disagrees with itself. Repair tools can sometimes fix it, and sometimes they can't.

Linux has a utility for this called [fsfreeze](https://man7.org/linux/man-pages/man8/fsfreeze.8.html). It flushes all in-flight IO to disk and blocks any new writes until the filesystem is thawed. While it's frozen, you can copy the filesystem and know the copy is valid: it will mount, and it will restore, every time.

On Upsun, consistent backups freeze every filesystem this way before the snapshot is taken. You never have to think about it.

## Consistency between services

Freezing 1 filesystem stops being enough the moment your application is more than a static website. Add a database next to your app and a second consistency problem appears, at a higher level this time.

Take the most common example: file uploads. A user uploads an image, your application writes the file to disk, then stores its path in the database. That's 2 writes, on 2 services, a few milliseconds apart.

Now a backup runs in between. The database snapshot has the row with the path. The filesystem snapshot doesn't have the file yet. Each snapshot is valid on its own, and together they describe an application state that never existed. Restore them and your database points at files that aren't there.

## How a consistent backup works on Upsun

When you click the backup button in the Console (or run `upsun backup:create`), here is what happens by default:

1. Incoming requests are held at the edge. They're not dropped, they wait.
2. Every service pauses its own work. The database, for example, locks its tables so no transaction is left mid-flight.
3. Once all services report they're paused, every filesystem is frozen.
4. Snapshots are taken across all containers, capturing the same moment in time.
5. Everything thaws, unlocks, and the held requests are released.

The result is a backup where all services agree with each other. The cost is a short window, usually 15 to 30 seconds, where your site is paused. No requests are lost, but visitors during that window are waiting on a site that feels frozen. The details are in the [backups and downtime documentation](/docs/environments/backup#backups-and-downtime).

## Live backups: zero disruption, weaker guarantees

That pause is why live backups exist. A live backup skips the coordination entirely: no held requests, no locked tables, no frozen filesystems. Snapshots are taken on the fly while the application keeps serving traffic. The impact on your live site is zero.

The trade-off is weaker guarantees. At the filesystem level you're still fine in practice: the snapshot is atomic at the block level, restoring it is like booting a machine after a power loss, and the filesystem journal replays whatever was in flight. Between services though, the guarantee goes away. There's a chance (not a certainty, a chance) that a live backup captures a state like the upload example above, and restores with some data out of sync.

[Automated backups](/docs/environments/backup#backup-policy) on Upsun are always live. The default policy takes 1 backup per day on production, and you can raise that to several per day. Take 4 live backups a day and one of them might occasionally catch your application mid-write. We think that's the right default: a scheduled backup shouldn't pause your production site 4 times a day.

Engineering is trade-offs, and this one is explicit. The default optimizes for zero disruption. When you want the stronger guarantee, [manual backups](/docs/environments/backup#create-a-manual-backup) are consistent by default. You can also take a manual live backup with the `--live` flag, though it's hard to find a reason to prefer it over the scheduled ones.

```bash theme={null}
upsun backup:create --live
```

## Which one should you use?

Let the scheduled live backups run as your safety net. They restore fine most of the time, and they cost you nothing in availability.

Before anything risky, like a schema migration, a big import, or a deploy you're unsure about, take a manual backup and accept the short pause. That's the backup you'll actually want to restore from, and you want it to be the consistent kind. If your site is busy, run it during off-peak hours.

If you're curious how the snapshots themselves work under the hood (incremental, deduplicated, built on Ceph), we wrote about that in [High-performance backups: How Ceph snapshots enable incremental full backups](/posts/how-it-works/how-do-we-do-incremental-but-really-full-backups-on-top-of-ceph).


# Building observability from scratch, three times over
Source: https://developer.upsun.com/posts/how-it-works/building-observability-from-scratch-three-times-over

A look back at how Platform.sh / Upsun's observability evolved from Nagios on a single box to a unified stack across thousands of VMs, and the migration patterns that made each transition smooth.

<PostMeta />

I've been at ~~Platform.sh~~ Upsun since the beginning. First customer, first region, first outage. When you're one of the first engineers at a company that's building a cloud platform, you end up owning whatever needs to exist next. For me, that was observability, more than once.

Our observability stack wasn't designed in a single pass. It evolved as the platform grew, each layer replaced when we outgrew it. And looking back, that's the right way to do it. You don't build the final system on day one. You build what works at the scale you're at, and you upgrade when the requirements change.

In 2013, we had a handful of customers and a single "admin box" that ran everything. Builds, the Puppet master, and eventually our first monitoring. At that scale, we didn't need observability. We needed to know if things were up.

That lasted a few weeks. Here are 3 separate concerns (health checks, metrics, and logs) that each went through their own evolution. Sometimes in parallel, sometimes years apart.

## Health checks

### Nagios and the giant text file

The first real monitoring tool was [Nagios](https://www.nagios.org/). It ran on the admin box alongside everything else. We used it for health checks and for rudimentary metrics; each health check update sent a small piece of usage data along with it.

Nagios is written in Perl, and at the time it kept its entire database in a single text file called `index`. Every metric, every health check result, everything went into that one file. Updates happened via regex. It worked for a while.

Around 300 VMs, it stopped working. Parsing a multi-gigabyte text file on every update got painfully slow. EBS performance at the time didn't help either. We disabled the metrics part to buy time, but it wasn't enough.

### Angel and Pub/Sub

We evaluated a few alternatives, but they all had the same fundamental problem: centralization that would eventually fall over at our scale.

This was around the time Go was blowing up, and we were rewriting a lot of internal tools in it. So we built Angel: a custom health check service written in Go, using BoltDB for storage. Everything in a single binary, everything in memory. And with Google Pub/Sub as the transport layer between hosts and Angel.

With Nagios, hosts sent health checks directly over HTTP. If the server went down for a restart, clients had to retry. Those clients are customer workloads running on resources they're paying for. Unnecessary backpressure from our own monitoring infrastructure isn't acceptable.

With Pub/Sub in the middle, hosts publish to a topic and Angel subscribes. If Angel restarts, messages buffer in Pub/Sub and get consumed when it comes back. No retries, no backpressure on customer resources. We've been running it for years without a single hiccup. It's remarkably cheap for the amount of data it handles. We considered self-hosted Kafka, but Pub/Sub won on cost and reliability.

The migration was smooth because we reused the Nagios protocol. Angel initially exposed an HTTP endpoint that spoke the same format: text-based, same exit codes, same field structure. It also consumed from Pub/Sub simultaneously. We switched hosts over to Pub/Sub, then decommissioned the HTTP endpoint. All the Puppet configuration and existing health check scripts stayed the same.

We still use the Nagios protocol today. It's text-based, easy to understand, and every health check script we've ever written speaks it.

### Angel today

Angel is still a single Go binary. It runs on 8 vCPUs and 32 GB of RAM, with everything in memory. It handles health checks for thousands of VMs across all our regions.

We kept it focused on health checks only. Early on, we tried having it handle metrics too, but we'd have ended up with the same scaling problems we had with Nagios. Separating concerns was the right call. Pub/Sub also means we can restart Angel without backpressure on customer workloads. That's been critical for keeping the monitoring layer invisible to customers.

## Metrics

### Munin

While Nagios handled health checks, we added [Munin](https://munin-monitoring.org/) for metrics and graphs. Also on the admin box. The graphs were generated and stored locally, and we'd share them with customers as screenshots when needed.

Munin wasn't super stable. I remember frequently having to investigate missing data, holes in graphs where collection had gotten stuck. It was fine for what it was, but not something we could rely on for real-time decisions. Mostly we'd look at it after the fact, when something had already gone wrong.

### Grafana (2018)

In 2018, we set up [Grafana](https://grafana.com/) to replace Munin as the metrics frontend. We applied the same migration pattern we'd used for health checks: keep the collection, change the backend.

We're still running munin-node on every host for local metric collection. A custom script called `platform-munin-report` transforms the Munin output into a format Grafana can consume. The collection infrastructure from the early days is the same. We swapped the visualization layer.

For Dedicated customers, the Grafana dashboards were useful. On the grid side, the metrics situation was honestly weaker. We were mostly reactive, looking at the data after a support ticket came in, not before.

### Per-container metrics with Agilis (\~2018)

Around the same time, we built Agilis for per-container metrics. Data was collected on each host, sent through Pub/Sub to BigQuery. We built capacity dashboards on top of it, which was a step toward being proactive.

But lack of proactiveness was still our main weakness. We had the data, but we weren't consistently acting on it before things broke. There was no single place to see the health of all our regions at a glance. We'd reach for the data after a support ticket came in, not to prevent it.

### Customer observability projects

The biggest shift for metrics came when we built per-region observability projects that give each customer visibility into their own container metrics. This was a product improvement, but it made our internal lives better too.

Having structured, per-container data available consistently across all regions was something we should have had from the beginning. In retrospect, it would have saved us countless hours of cross-referencing Grafana dashboards and digging through BigQuery. But you can't build the end state when you have one customer and no budget.

## Logs

### Graylog and Elasticsearch

For logs, we briefly tried [Graylog](https://graylog.org/). It didn't work out. Then we set up Elasticsearch with Kibana, which worked better but came with a cost problem. The Elasticsearch cluster became by far the biggest disk consumer we had. Terabytes of log data on a single project in the EU region.

### S3 (\~2019)

Cost drove us to move logs to S3 around 2019. Compressed text files in a structured format, with toolbox commands to dig them out. We built an internal tool called Hera to search through them. Not elegant, but the cost difference was dramatic.

The customer observability projects are also rolling out per-container log access, which is coming soon. Under the hood, logs are stored in the blob storage of whatever cloud provider the region runs on. The architecture behind that pipeline deserves its own article.

## Bringing it all together

For years, health checks lived in Angel, metrics in Grafana, and logs in S3. They evolved independently, and each one worked well enough on its own. The problem was the gaps between them.

When you get an alert from Angel, the relevant logs are in S3. The metrics are in Grafana. The container data is in BigQuery. That's 3 tools and 3 context switches before you understand what's happening.

We're now moving to Elastic Cloud to unify everything: logs, metrics, health checks, and alerting. With everything in one place, an alert can come with the relevant logs already attached. No context-switching, no digging.

Yes, Elastic Cloud is centralized and expensive. After years of building decentralized, cost-optimized tools, that's a deliberate trade-off. At our current scale, the engineering cost of maintaining separate systems outweighs the hosting cost of a managed platform. The cheapest tool is the one your team can actually operate without burning out.

There's also a compliance angle. Our security team needs a centralized place to manage and analyze logs for SIEM and incident response. S3 compressed text files don't cut it for that.

Elastic is open source, which matters. We're not locked into the managed service. If we need to self-host part of the stack later, that flexibility exists. And the data stays accessible to AI/LLM analysis down the road, which is where incident response is heading.

## What I'd tell someone building this from scratch

You don't need to get it right the first time. You need to get it right for the scale you're at. Nagios was fine for 50 VMs. Munin was fine when 3 people looked at the graphs. S3 was fine when logs were an occasional debugging tool.

Every migration we did followed the same pattern: wrap the new tool in the old protocol, run both side by side, migrate, decommission. It's not glamorous, but it works every time. If your new system can't speak the old protocol, you're going to have a bad migration.

The best decision we made was adopting Pub/Sub early. Decoupling producers from consumers made every subsequent change easier. Angel can be restarted, replaced, or scaled without touching a single host. If I were starting over, I'd put a message bus in the middle on day one.

And build the customer-facing observability first. We built internal tools for years before giving customers the same data. When we finally did, it turned out the customer-facing version was better than what we had internally. The product team solved the problem we'd been patching with scripts.


# Can you trust the X-Client-IP header?
Source: https://developer.upsun.com/posts/how-it-works/can-you-trust-the-x-client-ip-header

Why the X-Client-IP header on Upsun holds the real visitor IP behind Fastly, Cloudflare, and CloudFront, and how to log real client IPs behind any other CDN.

<PostMeta />

Where do your visitors come from? Your access logs have an answer on every line: an IP address. Whether that address is your visitor's, or a machine somewhere in the middle, depends on your setup.

On [Upsun](https://upsun.com), that address comes from the `X-Client-IP` request header. Most of the time it holds the real client IP without you configuring anything. This post is about the "most of the time" part.

## Why the remote IP isn't the client

The obvious candidate for the client IP is the remote address of the TCP connection. That stopped being reliable once everything sat behind load balancers and proxies. Between your visitor and your application sits a chain: edge routers, load balancers, and often a CDN. Each hop terminates the connection and opens a new one, and each new connection carries the IP of the hop, not the visitor. By the time a request reaches your container, the remote address is the last machine that touched it.

That's why proxies pass the original address along in a header instead. On Upsun, that header is [`X-Client-IP`](/docs/development/headers), set by our router. Its value is what your application sees as the remote address, and what ends up in `/var/log/access.log`. What goes into it depends on where the request comes from.

## A chain of trust

When a request reaches an Upsun region directly from the client, there's nothing to figure out. The remote address is the client, and that's what goes into `X-Client-IP`.

It gets interesting behind a CDN. We support 3 of them: [Fastly](/docs/domains/cdn/fastly), [Cloudflare](/docs/domains/cdn/cloudflare), and CloudFront. What these 3 have in common is an API that publishes the IP ranges of their points of presence. When a connection reaches our region, we check the remote address against those ranges. A match means the connection really comes from that CDN.

And once we know that, we can trust what the CDN tells us. Each of them forwards the real client IP in its own request header, such as `Fastly-Client-IP` or `CF-Connecting-IP`. We take that value and put it in `X-Client-IP`. Your application sees the visitor's real address, and the access log records it, even though the TCP connection comes from a CDN datacenter.

The verification step is what carries the trust: anyone can send a request with a `Fastly-Client-IP` header, but only Fastly can send one from a Fastly IP address.

## When your CDN isn't on the list

Akamai doesn't publish its IP ranges through an API. Without the ranges, there's no way to verify that a connection comes from Akamai, and without that verification, its `True-Client-IP` header is a claim anyone can make. The chain of trust can't be built, and `X-Client-IP` falls back to the remote address: an Akamai edge server. Your access log fills up with Akamai datacenter IPs. The same goes for any CDN that doesn't expose its ranges.

We can't fix the platform access log in that situation. But you can still get the real client IP into your own logs, with 2 rules to follow.

## Rule 1: set the header unconditionally

At the CDN level, configure a header that carries the client IP. It can be the CDN's own header or a custom one. The important part: the CDN must set it on every request, overwriting anything already there. Never "set if missing".

The reason is the same trust argument as before. If the header is only set sometimes, then sometimes its value comes from the client, and a client can put anything in there. Overwriting on every request removes that possibility.

## Rule 2: check who's talking to you

In your application, before reading the header, check that the remote address belongs to your CDN. Most CDNs give their customers the list of ranges, even when there's no public API for it:

```python {filename="client_ip.py"} theme={null}
  from ipaddress import ip_address, ip_network

  CDN_RANGES = [ip_network(r) for r in RANGES_FROM_YOUR_CDN]

  def client_ip(request):
      remote = ip_address(request.remote_addr)
      if any(remote in network for network in CDN_RANGES):
          return request.headers.get("True-Client-IP", str(remote))
      return str(remote)
```

Skip this check, and anyone who finds your origin's address can send requests directly, header included, and your logs record whatever IP they chose. And origin addresses aren't secret: they leak through DNS history, certificate transparency logs, and plain guessing.

There's one setup where the check is redundant: origin restriction. If nothing but your CDN can reach your project, because you set up [HTTP access control](/docs/environments/http-access-control) with your CDN's ranges, or [mTLS](/docs/domains/cdn#enable-mtls) with an Origin CA certificate from your CDN, then every request that reaches your app already comes from the CDN. In that case, read the header directly.

Either way, the last step is yours: log the resolved client IP from your application, in your own access log. That gives you real visitor addresses even behind a CDN we can't verify.

## The takeaway

On Upsun, `X-Client-IP` holds the real client IP when requests arrive directly, or through Fastly, Cloudflare, or CloudFront. Behind anything else, it holds the last hop, and getting the real address into your logs is on you: one header set unconditionally at the CDN, one check on the remote address in your app, or origin restriction instead of the check.

None of it is hard. But get one step wrong and nothing breaks: the logs keep filling up, with the wrong IPs in them.


# Cloning a terabyte in a minute, and the limit hiding behind it
Source: https://developer.upsun.com/posts/how-it-works/cloning-a-terabyte-in-a-minute-and-the-limit-hiding-behind-it

Upsun clones a terabyte production environment in under a minute using Ceph copy-on-write. Here is the 16-level clone-depth limit behind it, why flattening is the price you pay, and what it says about engineering trade-offs.

<PostMeta />

Cloning your whole production environment, database included, takes about a minute on Upsun. It doesn't matter whether that database is 10 GB or a terabyte. You get a preview environment with all of your production data, ready to break in whatever way you need.

That speed isn't magic. It's a storage trick called copy-on-write, and like every good trick, it comes with a bill attached. The funny part is where the bill shows up.

## How a one-minute clone works

Every container on Upsun gets its own volume on a [Ceph](https://ceph.io/) cluster. Ceph is distributed storage: think of it as network-attached disks you can map to any machine and unmap a second later. We covered the move to it in [why we moved from LVM to Ceph](/posts/how-it-works/why-upsun-moved-from-lvm-to-ceph/).

When you clone an environment, Ceph doesn't copy your data. It takes a copy-on-write snapshot. At that moment, nothing is written to disk except a bit of metadata. The clone and the original share the same underlying blocks.

The copying happens later, lazily. The first time you write to a given spot on the disk, Ceph writes the new block and updates the metadata so the clone stops pointing at the parent's version. Every untouched block keeps falling through to the parent. That first write to each spot is a touch slower, because there is metadata to update, but you never notice it in practice.

That's the whole reason a terabyte clones as fast as a gigabyte. You pay only for what you change, and you pay for it at the moment you change it.

## The bill: walking the chain

Now clone the clone. Then clone that one. Each new environment points at its parent, which points at its parent, all the way back to the original.

Reads are where this adds up. When you read a block that nobody in the chain has modified, Ceph asks the clone, then its parent, then its parent's parent, until it finds the block or reaches the original. The deeper the chain, the more hops per read.

Ceph draws a line here. The Linux kernel's RBD driver caps the parent chain at 16 levels (`RBD_MAX_PARENT_CHAIN_LEN`). A clone can sit at most 15 levels below the original. Try to go deeper and Ceph refuses. It's a hard limit, and a reasonable one: they're trading a little flexibility for predictable read performance, which is the right call.

Some pick an even lower line. OpenStack's Cinder defaults `rbd_max_clone_depth` to 5, and breaks the chain on its own once a clone would cross it, rather than riding the kernel's 16 all the way up. It decided 5 layers of read amplification is already enough to hurt. Same mechanism, same trade-off, two teams drawing the line in different places.

## Depth, not breadth

One thing worth being clear about: this is about depth, not about how many clones you make.

Give production 20 staging environments and you're fine. Each one has exactly one parent. Give each of those 20 its own child and you're still fine, because every child is only 2 levels deep.

The limit bites only when you clone a clone of a clone of a clone, 16 times over. What matters is the length of a single ancestry line, not the size of the family.

## The escape hatch, and its price

There is a way out, and Ceph calls it flattening. Flattening tells a volume to copy every block it was sharing with its parents and become standalone. No more chain, no more parent lookups, and you can start a fresh line of clones from it.

You probably see the catch. Flattening copies all the data. It's the exact slow, full copy that copy-on-write let you skip. Break the chain and that one clone is no longer instant.

## Nothing is free

I can't picture a real customer stacking 16 clones in a line. You'd have to make a development environment from a development environment from a development environment, and keep going past the point of sense. We test for it anyway, because "no customer would ever" is how you end up debugging it at 2 a.m.

What I like about this limit is what it says about engineering. Copy-on-write is a genuinely good choice. It's why the one-minute clone exists at all, and it has held up for years. But the same mechanism that makes clones instant is the one that makes deep chains slow, and that's not a bug you can patch away. It's the shape of the trade-off.

Every technology you pick hands you its own limits along with its strengths. The job isn't finding the option with no downsides. It's picking the best one for the problem, and knowing exactly where it stops working.


# How we cut AWS bandwidth costs 95% with dm-cache: fast local SSD caching for network storage
Source: https://developer.upsun.com/posts/how-it-works/cut-aws-bandwidth-costs-95-with-dm-cache

Learn how Upsun solved costly inter-AZ bandwidth billing by implementing dm-cache with local SSDs, achieving 95% read traffic reduction and 30x performance improvement.

<PostMeta />

## The bandwidth billing challenge

When deploying infrastructure across multiple AWS availability zones (AZs), bandwidth costs can become a significant operational expense. Some of our Upsun infrastructure spans three AZs for high availability, but this architecture created an unexpected challenge with our [Ceph-based storage system](/posts/how-it-works/how-do-we-do-incremental-but-really-full-backups-on-top-of-ceph).

Since Ceph distributes data across the cluster and AWS bills for inter-AZ traffic, approximately two-thirds of our disk I/O traffic crossed AZ boundaries—generating substantial bandwidth charges. With all disk operations flowing over the network rather than accessing local storage, we needed a solution that could reduce this costly network traffic without compromising our distributed storage benefits.

## The local SSD caching experiment

Our AWS instance types included small amounts of local SSD storage that weren't being utilized for primary storage. This presented an opportunity: what if we could use these fast, local disks as a read cache in front of our network-based Ceph storage?

We implemented a three-step caching strategy using Linux device mapper (dm-cache):

1. **Volume partitioning**: Used LVM to split the local SSD into small 512MB cache volumes
2. **Read-only caching**: Configured dm-cache to place these volumes in front of our Ceph RBD (RADOS Block Device) volumes, caching reads while passing writes directly through to the network storage
3. **Container integration**: Exposed the dm-cache devices to our containers as their primary storage interface

## Understanding dm-cache architecture

<img alt="dm-cache architecture" />

The dm-cache kernel module was originally designed to address a classic storage trade-off: placing small, expensive SSDs in front of large, affordable HDDs to create hybrid storage with both capacity and performance. Our use case follows the same pattern—except instead of slow HDDs, we're caching in front of network-attached storage.

This approach works because of how application I/O patterns typically behave. Most applications exhibit temporal locality in their data access, repeatedly reading the same files or database pages. By caching frequently accessed blocks locally, we can serve repeated reads from fast SSD without network round-trips.

For detailed setup instructions, check out the [Red Hat documentation on caching logical volumes](https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/configuring_and_managing_logical_volumes/advanced-logical-volume-management_configuring-and-managing-logical-volumes#caching-logical-volumes_advanced-logical-volume-management).

## Implementation considerations

When implementing dm-cache in production environments, consider these key factors:

**Cache sizing**: While our 512MB cache proved effective, the optimal size depends on your application's working set. Monitor cache hit rates and adjust accordingly.

**Write policy**: We chose write-through mode exclusively, where all writes bypass the cache and go directly to network storage. This decision was crucial for Upsun because we host thousands of e-commerce applications where data integrity is non-negotiable.

In e-commerce environments, every transaction—whether it's inventory updates, order processing, or payment confirmations—must be immediately persisted to durable storage. A lost write due to cache failure could mean:

* Customer orders disappearing after payment processing
* Inventory miscounts leading to overselling
* Financial transaction data corruption
* Regulatory compliance violations

While write-back mode offers better write performance by buffering writes in the local cache, it introduces risk scenarios we couldn't accept:

* **Cache device failure**: Unwritten data in the cache would be permanently lost
* **Power failures**: Cached writes might not survive unexpected shutdowns
* **Split-brain scenarios**: Cache and storage could become inconsistent during network partitions

For e-commerce workloads, the performance benefit of write-back mode isn't worth the data integrity risk. Our customers depend on transactional consistency, and write-through mode ensures every write operation is safely committed to our replicated Ceph storage before the application considers it complete.

**Performance monitoring**: Track metrics like cache hit ratios, network bandwidth utilization, and application response times to validate the effectiveness of your caching strategy.

## Results: dramatic performance and cost improvements

The impact exceeded our expectations. With cache volumes of only 512MB serving RBD volumes ranging from 5-50GB, we achieved:

* **95% reduction in read traffic** over the network
* **30x improvement in IOPS** for cached operations
* **50% reduction in read latency**
* **30x increase in read bandwidth** for frequently accessed data

These improvements translate directly to cost savings through reduced inter-AZ bandwidth charges, while the performance gains provide a significantly better experience for applications running on our platform.

## Why this approach works at scale

The success of this caching strategy relies on several key factors that align well with typical container workloads:

**Read-heavy patterns**: Many applications read configuration files, static assets, and database indexes repeatedly, making them ideal for caching.

**Working set locality**: Applications tend to access a subset of their total data frequently, allowing small caches to be highly effective.

**Write-through simplicity**: By passing writes directly to network storage, we maintain data consistency while avoiding complex cache invalidation scenarios.

The 512MB cache size might seem small, but it's sufficient to cache the most frequently accessed blocks for typical containerized applications, delivering outsized performance benefits.


# How we host a Debian repository on AWS S3
Source: https://developer.upsun.com/posts/how-it-works/debian-repo-s3



<PostMeta />

Pretty cool fact about our internal Debian repositories: they’re hosted entirely on AWS S3. Why is that cool? For 2
reasons:

1. There’s no active components to maintain.
2. It’s super cheap. Like, really.

Now, you will wonder: how is that possible?! Isn’t a Debian repository something super complicated to host?

That is a great question. The answer lies in the technical intricacies of how Debian repositories work, and this is what
this post will go through, leading us to the technical prowess of hosting those repositories that are serving hundreds
of thousands of VMs and CI jobs on a monthly basis for cheaper than a pack of Kinder Bueno.

In order to explain how it is organized, I believe it is easier to start with what you would typically put
in your `/etc/apt/sources.list`:

`deb http://deb.debian.org/debian/ bookworm main non-free-firmware`

Let’s anatomize this line and see what each part means:

* `deb`: nothing special here, this just indicates that this line specifies a remote repository.
* `http`: the protocol to use to communicate with the repository. By the way, HTTPS is not necessary (although supported
  nowadays), as packages are later verified with GPG signatures. See more below.
* `://deb.debian.org/debian/`: URL where the repository lives.
* `bookworm`: this is the *distribution*. In the Debian world, each version’s name is called the “distribution”.
* `main`, `non-free-firmware`: those are *components*. In the Debian world, this is how packages are grouped. While we
  don’t particularly care for it, it allows Debian to separate the non-free packages, as well as probably other legacy
  reasons. (Feel free to enlighten us if you know more!)

By giving those 3 parameters (URL, distribution, component), a Debian system can download the list of packages, and
install whatever is available.

Now, how do we go back to our S3 repos? Oh, yes. Here is how a Debian system downloads the list of packages, with a few
assumptions:

* It’s an `http` repository and this dumb Debian system only knows `curl`.
* We’re taking the easy path. Debian systems provide many features, we only care about the most straightforward ones.
* `$URL`, `$distribution`, `$component` are the 3 parameters mentioned above.
* `$architecture` is the CPU architecture, such as amd64.

1. It does a `curl $URL/dists/$distribution/InRelease` and `curl $URL/dists/$distribution/Release.gpg`, where:
   * The `InRelease` file has the list of `Packages` files (among others) and their hash sums.
   * The `Release.gpg` file has a signature of the `InRelease` file.
2. It then does a `curl $URL/dists/$distribution/$component/binary-$architecture/Packages.gz`, which has the list of packages.

The `Packages` file looks like this:

```yaml theme={null}
Package: 0ad  
Version: 0.0.26-3  
Installed-Size: 28591  
Maintainer: Debian Games Team <pkg-games-devel@lists.alioth.debian.org>
Architecture: amd64 
Depends: [ ... skipped for brevity ... ] 
Description: Real-time strategy game of ancient warfare  
Filename: pool/main/0/0ad/0ad_0.0.26-3_amd64.deb 
Size: 7891488  
MD5sum: 4d471183a39a3a11d00cd35bf9f6803d  
SHA256: 3a2118df47bf3f04285649f0455c2fc6fe2dc7f0b237073038aa00af41f0d5f2
```

(That’s the first package in
[https://deb.debian.org/debian/dists/bookworm/main/binary-amd64/Packages.gz](https://deb.debian.org/debian/dists/bookworm/main/binary-amd64/Packages.gz))

You will notice several things in there:

* With the hash sums, you can actually verify that the package you end up downloading is valid thanks to the top-level
  signature that was previously downloaded. Transitive trust matters!
* There is a `Filename` property: it points to the actual `.deb` file that you can download and run `dpkg -i` on.

***

I think you can see where I’m going with that. And yes, this is all static. It is all easy to just replicate that hierarchy to AWS S3, and poof, it works. That’s what our CI jobs do: they replicate this folder hierarchy on local disk:

```
dists/
  bookworm/
    Release.gpg
    InRelease
    main/
      binary-amd64/
        Packages.gz
pool/
  foo.deb
  bar.deb
```

And then they run `aws s3 sync . s3://...` (essentially an “rsync”) and magic! We’re done! 🪄

… almost.

Well, yeah, these are internal Debian repositories. We don’t really want them to be open to the world. How do we do
authentication, then? We cannot just have public S3 buckets, can we?

On a related note, you might have found it a bit weird how `http` was separated when it was explained what the
`sources.list` line was made up of. This was intentional: Debian systems support more than one protocol for the remote.
Of course, `http` and `https` are installed by default.

But you know what’s even better? *You can add support for new protocols*.

By default, all our Debian systems install `apt-transport-s3`. This package allows us to have this `sources.list`:

`deb s3://internal-debian-repository.platform.sh bookworm main`

Custom protocol, with our S3 bucket URL, and the package allows for authentication details to be provided as part of the
URL. (As in, `s3://<access key ID>:<secret key>@<bucket name>`.)

***

And that’s it! With these simple tricks, or really, knowledge of how Debian repositories work, it was straightforward to
host our own repositories on S3, allowing us to be very flexible with how we organize our repositories. As an example,
we define a new Debian component per tag of a given repository, allowing us to upgrade our systems very
deterministically.

I hope that was helpful and that you learned something!


# Event Loop Monitoring in Next.js: Performance Guide
Source: https://developer.upsun.com/posts/how-it-works/event-loop-monitoring-in-nextjs-performance-guide

Learn to implement event loop monitoring in Next.js applications to identify blocking operations, optimize performance, and scale confidently with production-ready code.

<PostMeta />

If your Next.js application struggles under load, crashes with 200+ concurrent users, or shows uneven CPU usage across PM2 instances, you're likely experiencing event loop blocking. This guide explains what event loops are, why they matter, and how to implement monitoring to diagnose and fix performance bottlenecks.

## Table of Contents

1. [Understanding Event Loops](#understanding-event-loops)
2. [Why Event Loops Matter for Next.js](#why-event-loops-matter-for-nextjs)
3. [Implementing Event Loop Monitoring](#implementing-event-loop-monitoring)
4. [Interpreting Monitoring Data](#interpreting-monitoring-data)
5. [Common Blocking Patterns and Fixes](#common-blocking-patterns-and-fixes)
6. [Advanced Monitoring Setup](#advanced-monitoring-setup)

## Understanding Event Loops

### What is an Event Loop?

Node.js (and by extension, Next.js) runs on a single thread. Yet it can handle thousands of concurrent connections efficiently. The event loop makes this possible.

Think of a restaurant kitchen with one chef. Instead of preparing one complete order before starting the next, the chef:

1. Puts burger #1 on the grill
2. While it cooks, starts burger #2
3. While both cook, prepares fries
4. Checks which items are done
5. Serves completed orders
6. Repeats

This is how Node.js works. The event loop continuously cycles through tasks, checking what's ready to execute next.

### The Event Loop Cycle

```mermaid theme={null}
%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#E8F9A3','primaryTextColor':'#000','primaryBorderColor':'#495867','lineColor':'#495867','secondaryColor':'#B5A8FF','tertiaryColor':'#495867','background':'#fff','mainBkg':'#E8F9A3','secondBkg':'#B5A8FF'}}}%%
flowchart TD
    A[Event Loop<br/>Runs Continuously] -->|Check callbacks| B[Callback Queue<br/>CB1, CB2, CB3]
    B -->|Execute next| C[Execute JavaScript<br/>Your code runs here]
    C -->|Complete?| D{Done?}
    D -->|Yes| A
    D -->|Takes too long| E[⚠️ Event Loop Blocked<br/>Other callbacks wait]
    E --> A

    style A fill:#E8F9A3,stroke:#495867,stroke-width:3px,color:#000
    style B fill:#B5A8FF,stroke:#495867,stroke-width:2px,color:#000
    style C fill:#fff,stroke:#495867,stroke-width:2px,color:#000
    style D fill:#E8F9A3,stroke:#495867,stroke-width:2px,color:#000
    style E fill:#ff686b,stroke:#495867,stroke-width:3px,color:#fff
```

**Key Point:** The loop waits if a callback takes too long.

### Non-Blocking vs Blocking Code

**Non-Blocking (Good):**

```javascript {filename="non-blocking.js"} theme={null}
// Request 1
app.get('/api/users', async (req, res) => {
  const users = await db.query('SELECT * FROM users');
  res.json(users);
});

// Timeline:
// 0ms:  Request 1 starts → db.query (async) → Event loop free
// 1ms:  Request 2 arrives → handled immediately ✓
// 2ms:  Request 3 arrives → handled immediately ✓
// 10ms: Request 1 db done → response sent ✓
```

**Blocking (Bad):**

```javascript {filename="blocking.js"} theme={null}
// Request 1
app.get('/api/users', (req, res) => {
  let result = [];
  for (let i = 0; i < 10000000; i++) {
    result.push(heavyCalculation(i));
  }
  res.json(result);
});

// Timeline:
// 0ms:   Request 1 starts → heavy loop → Event loop BLOCKED
// 100ms: Request 2 arrives → WAITING ⏳
// 200ms: Request 3 arrives → WAITING ⏳
// 500ms: Request 1 finally done → Request 2 can now start
```

The blocking code prevents the event loop from processing other requests, creating a bottleneck even with available CPU capacity. The symptom will be a degraded experience for users while your resources are still not used 100%.

## Why Event Loops Matter for Next.js

### The PM2 Cluster Scenario

When running Next.js with PM2 in cluster mode, you typically have multiple worker processes:

```mermaid theme={null}
%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#E8F9A3','primaryTextColor':'#000','primaryBorderColor':'#495867','lineColor':'#495867','secondaryColor':'#B5A8FF','tertiaryColor':'#495867'}}}%%
flowchart TD
    PM2[PM2 Master Process<br/>Distributes Requests] --> W0[Worker 0<br/>Event Loop<br/>CPU: 100%<br/>🔴 BLOCKED]
    PM2 --> W1[Worker 1<br/>Event Loop<br/>CPU: 25%<br/>🟢 Healthy]
    PM2 --> W2[Worker 2<br/>Event Loop<br/>CPU: 25%<br/>🟢 Healthy]
    PM2 -.-> W3[Workers 3-5<br/>Similar to 1-2]

    style PM2 fill:#E8F9A3,stroke:#495867,stroke-width:3px,color:#000
    style W0 fill:#ff686b,stroke:#495867,stroke-width:2px,color:#fff
    style W1 fill:#ffa69e,stroke:#495867,stroke-width:2px,color:#000
    style W2 fill:#ffa69e,stroke:#495867,stroke-width:2px,color:#000
    style W3 fill:#B5A8FF,stroke:#495867,stroke-width:2px,color:#000
```

If one worker's event loop is blocked by expensive synchronous operations, that worker can't handle new requests. PM2 continues sending it requests via round-robin distribution, but they queue up, causing timeouts and poor performance.

### Symptoms of Event Loop Blocking

* One PM2 instance at 100% CPU, others underutilized
* Requests timing out despite available server resources
* Uneven request distribution across workers
* Application crashes under moderate load (200+ concurrent users)
* Response times increase dramatically under load

## Implementing Event Loop Monitoring

### Step 1: Create the Monitor

Create the monitoring module using Node.js's built-in `perf_hooks` API to track event loop delay with high precision.

Create `lib/monitoring/advancedEventLoopMonitor.js`:

```javascript {filename="lib/monitoring/advancedEventLoopMonitor.js"} theme={null}
const { performance, PerformanceObserver } = require('perf_hooks');
const { monitorEventLoopDelay } = require('perf_hooks');

class AdvancedEventLoopMonitor {
  constructor(options = {}) {
    this.resolution = options.resolution || 10;
    this.warningThreshold = options.warningThreshold || 50;
    this.criticalThreshold = options.criticalThreshold || 100;
    this.logInterval = options.logInterval || 30000;
    
    this.histogram = monitorEventLoopDelay({ resolution: this.resolution });
    this.histogram.enable();
    
    this.startTime = Date.now();
    this.requestCount = 0;
    this.slowRequests = [];
    
    this.startLogging();
    this.setupProcessMetrics();
    
    console.log('🔬 Advanced Event Loop Monitor initialized');
  }

  startLogging() {
    this.logIntervalId = setInterval(() => {
      this.logDetailedStats();
    }, this.logInterval);
  }

  setupProcessMetrics() {
    try {
      if (global.gc) {
        const gcStats = { count: 0, totalDuration: 0 };
        
        const obs = new PerformanceObserver((list) => {
          const entries = list.getEntries();
          entries.forEach((entry) => {
            if (entry.entryType === 'gc') {
              gcStats.count++;
              gcStats.totalDuration += entry.duration;
              
              if (entry.duration > 100) {
                console.warn(`⚠️  Long GC pause: ${entry.duration.toFixed(2)}ms`);
              }
            }
          });
        });
        
        obs.observe({ entryTypes: ['gc'] });
        this.gcStats = gcStats;
      }
    } catch (e) {
      console.log('GC monitoring not available (run with --expose-gc flag)');
    }
  }

  logDetailedStats() {
    const stats = this.getDetailedStats();
    
    const status = stats.p99 > this.criticalThreshold ? '🔴 CRITICAL' :
                   stats.p95 > this.warningThreshold ? '🟡 WARNING' :
                   '🟢 HEALTHY';
    
    console.log('\n' + '='.repeat(60));
    console.log(`${status} Event Loop Health Report`);
    console.log('='.repeat(60));
    console.log(`Instance: ${process.env.INSTANCE_ID || process.pid}`);
    console.log(`Uptime: ${this.formatUptime(Date.now() - this.startTime)}`);
    console.log(`\nEvent Loop Delay (ms):`);
    console.log(`  Min:    ${stats.min.toFixed(2)}ms`);
    console.log(`  Mean:   ${stats.mean.toFixed(2)}ms`);
    console.log(`  Max:    ${stats.max.toFixed(2)}ms`);
    console.log(`  P50:    ${stats.p50.toFixed(2)}ms`);
    console.log(`  P95:    ${stats.p95.toFixed(2)}ms`);
    console.log(`  P99:    ${stats.p99.toFixed(2)}ms`);
    console.log(`  StdDev: ${stats.stddev.toFixed(2)}ms`);
    
    console.log(`\nMemory:`);
    const mem = process.memoryUsage();
    console.log(`  RSS:        ${(mem.rss / 1024 / 1024).toFixed(2)} MB`);
    console.log(`  Heap Used:  ${(mem.heapUsed / 1024 / 1024).toFixed(2)} MB`);
    console.log(`  Heap Total: ${(mem.heapTotal / 1024 / 1024).toFixed(2)} MB`);
    console.log(`  External:   ${(mem.external / 1024 / 1024).toFixed(2)} MB`);
    
    if (this.gcStats) {
      console.log(`\nGarbage Collection:`);
      console.log(`  Count:        ${this.gcStats.count}`);
      console.log(`  Total Time:   ${this.gcStats.totalDuration.toFixed(2)}ms`);
      console.log(`  Avg Per GC:   ${(this.gcStats.totalDuration / this.gcStats.count || 0).toFixed(2)}ms`);
    }
    
    console.log(`\nRequests Processed: ${this.requestCount}`);
    
    if (this.slowRequests.length > 0) {
      console.log(`\n⚠️  Slow Requests (last ${this.slowRequests.length}):`);
      this.slowRequests.slice(-5).forEach(req => {
        console.log(`  ${req.method} ${req.url} - ${req.duration.toFixed(2)}ms - ${req.timestamp}`);
      });
    }
    
    console.log('='.repeat(60) + '\n');
    
    this.histogram.reset();
    
    if (this.slowRequests.length > 100) {
      this.slowRequests = this.slowRequests.slice(-50);
    }
  }

  getDetailedStats() {
    return {
      min: this.histogram.min / 1e6,
      max: this.histogram.max / 1e6,
      mean: this.histogram.mean / 1e6,
      stddev: this.histogram.stddev / 1e6,
      p50: this.histogram.percentile(50) / 1e6,
      p95: this.histogram.percentile(95) / 1e6,
      p99: this.histogram.percentile(99) / 1e6,
      p999: this.histogram.percentile(99.9) / 1e6
    };
  }

  formatUptime(ms) {
    const seconds = Math.floor(ms / 1000);
    const minutes = Math.floor(seconds / 60);
    const hours = Math.floor(minutes / 60);
    const days = Math.floor(hours / 24);
    
    if (days > 0) return `${days}d ${hours % 24}h`;
    if (hours > 0) return `${hours}h ${minutes % 60}m`;
    if (minutes > 0) return `${minutes}m ${seconds % 60}s`;
    return `${seconds}s`;
  }

  trackRequest(method, url, duration) {
    this.requestCount++;
    
    if (duration > 1000) {
      this.slowRequests.push({
        method,
        url,
        duration,
        timestamp: new Date().toISOString()
      });
    }
  }

  getStats() {
    return this.getDetailedStats();
  }

  stop() {
    if (this.logIntervalId) {
      clearInterval(this.logIntervalId);
    }
    this.histogram.disable();
    console.log('🔬 Event Loop Monitor stopped');
  }
}

module.exports = AdvancedEventLoopMonitor;
```

### Step 2: Initialize on Server Start

Next.js 13+ uses the [instrumentation hook](https://nextjs.org/docs/app/guides/instrumentation) for server initialization. Create `instrumentation.js` in your project root:

```javascript {filename="instrumentation.js"} theme={null}
export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    const AdvancedEventLoopMonitor = require('./lib/monitoring/advancedEventLoopMonitor');
    
    global.eventLoopMonitor = new AdvancedEventLoopMonitor({
      resolution: 10,
      warningThreshold: 50,
      criticalThreshold: 100,
      logInterval: 30000
    });
    
    console.log('✅ Event loop monitoring initialized');
  }
}
```

Enable instrumentation in `next.config.js`:

```javascript {filename="next.config.js"} theme={null}
/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    instrumentationHook: true,
  },
};

module.exports = nextConfig;
```

### Step 3: Create Health Check Endpoint

Create `app/api/monitoring/health/route.js`:

```javascript {filename="app/api/monitoring/health/route.js"} theme={null}
export async function GET(request) {
  try {
    const monitor = global.eventLoopMonitor;
    
    if (!monitor) {
      return Response.json(
        { error: 'Monitor not initialized' },
        { status: 503 }
      );
    }

    const stats = monitor.getStats();
    const memory = process.memoryUsage();
    
    const health = {
      status: stats.p99 > 100 ? 'critical' : 
              stats.p95 > 50 ? 'warning' : 'healthy',
      instance: process.env.INSTANCE_ID || process.pid,
      uptime: process.uptime(),
      eventLoop: {
        min: parseFloat(stats.min.toFixed(2)),
        mean: parseFloat(stats.mean.toFixed(2)),
        max: parseFloat(stats.max.toFixed(2)),
        p50: parseFloat(stats.p50.toFixed(2)),
        p95: parseFloat(stats.p95.toFixed(2)),
        p99: parseFloat(stats.p99.toFixed(2)),
      },
      memory: {
        rss: Math.round(memory.rss / 1024 / 1024),
        heapUsed: Math.round(memory.heapUsed / 1024 / 1024),
        heapTotal: Math.round(memory.heapTotal / 1024 / 1024),
        external: Math.round(memory.external / 1024 / 1024),
      },
      timestamp: new Date().toISOString()
    };

    return Response.json(health);
  } catch (error) {
    return Response.json(
      { error: error.message },
      { status: 500 }
    );
  }
}
```

### Step 4: Create Request Tracking Middleware

Create `middleware.js` in your project root:

```javascript {filename="middleware.js"} theme={null}
import { NextResponse } from 'next/server';

export function middleware(request) {
  const start = Date.now();
  
  const response = NextResponse.next();
  
  response.headers.set('X-Request-Start', start.toString());
  
  return response;
}

export const config = {
  matcher: '/api/:path*',
};
```

Create `app/api/[...route]/route.js` wrapper to track completion:

```javascript {filename="app/api/[...route]/route.js"} theme={null}
export async function GET(request) {
  const start = Date.now();
  
  try {
    // Your API logic here
    const response = await yourApiHandler(request);
    
    const duration = Date.now() - start;
    
    if (global.eventLoopMonitor) {
      global.eventLoopMonitor.trackRequest(
        'GET',
        request.url,
        duration
      );
    }
    
    return response;
  } catch (error) {
    const duration = Date.now() - start;
    
    if (global.eventLoopMonitor) {
      global.eventLoopMonitor.trackRequest(
        'GET',
        request.url,
        duration
      );
    }
    
    throw error;
  }
}
```

## Interpreting Monitoring Data

### Understanding the Metrics

The monitor tracks several key metrics:

**Event Loop Delay Percentiles:**

* **P50 (Median)**: Half of all event loop iterations complete faster than this value
* **P95**: 95% of iterations complete faster than this value
* **P99**: 99% of iterations complete faster than this value

**Target Values:**

* P50: \< 10ms (excellent), 10-25ms (good), > 25ms (investigate)
* P95: \< 50ms (excellent), 50-100ms (acceptable), > 100ms (warning)
* P99: \< 100ms (excellent), 100-250ms (warning), > 250ms (critical)

### Reading the Health Report

```text {filename="Terminal"} theme={null}
🟢 HEALTHY Event Loop Health Report
============================================================
Instance: worker-1 (PID: 12345)
Uptime: 2h 34m

Event Loop Delay (ms):
  Min:    0.05ms     ← Best case scenario
  Mean:   8.23ms     ← Average delay (good)
  Max:    156.42ms   ← Worst case (occasional spikes OK)
  P50:    4.12ms     ← 50% of loops finish this fast
  P95:    32.45ms    ← 95% of loops finish this fast
  P99:    78.91ms    ← 99% of loops finish this fast ✓
  StdDev: 12.34ms    ← Consistency (lower is better)
```

**Health Status Interpretation:**

🟢 **HEALTHY**: P99 \< 100ms

* Application responding well
* Event loop processing efficiently
* No immediate action needed

🟡 **WARNING**: P95 > 50ms or P99 100-250ms

* Event loop experiencing delays
* Investigate recent code changes
* Review slow requests log
* Consider optimization

🔴 **CRITICAL**: P99 > 250ms

* Event loop heavily blocked
* User experience degraded
* Immediate action required
* Check for CPU-intensive operations

### Real-World Example Analysis

**Good Performance:**

```text {filename="Terminal"} theme={null}
Event Loop Delay (ms):
  P50:    3.21ms
  P95:    18.45ms
  P99:    42.33ms
```

This shows consistent, fast event loop processing. The application handles load well.

**Warning Signs:**

```text {filename="Terminal"} theme={null}
Event Loop Delay (ms):
  P50:    12.45ms
  P95:    156.78ms
  P99:    342.11ms
```

High variance between P50 and P99 indicates sporadic blocking operations. Investigate slow requests.

**Critical Issues:**

```text {filename="Terminal"} theme={null}
Event Loop Delay (ms):
  P50:    45.23ms
  P95:    523.45ms
  P99:    1234.56ms
```

Consistently high delays across all percentiles indicate systemic blocking issues. Check for synchronous database operations or heavy computation.

***

## Common Blocking Patterns and Fixes

### 1. Large JSON Parsing

**❌ Blocking:**

```javascript theme={null}
export default function handler(req, res) {
  const data = JSON.parse(largeJsonString); // Blocks event loop
  res.json(data);
}
```

**✅ Non-Blocking:**

```javascript theme={null}
import { Worker } from 'worker_threads';

export default async function handler(req, res) {
  const worker = new Worker('./workers/json-parser.js');
  
  worker.postMessage(largeJsonString);
  
  const data = await new Promise((resolve, reject) => {
    worker.on('message', resolve);
    worker.on('error', reject);
  });
  
  res.json(data);
}
```

### 2. Synchronous File Operations

**❌ Blocking:**

```javascript theme={null}
import fs from 'fs';

export default function handler(req, res) {
  const data = fs.readFileSync('./large-file.json', 'utf8');
  res.send(data);
}
```

**✅ Non-Blocking:**

```javascript theme={null}
import { readFile } from 'fs/promises';

export default async function handler(req, res) {
  const data = await readFile('./large-file.json', 'utf8');
  res.send(data);
}
```

### 3. Complex Array Operations

**❌ Blocking:**

```javascript theme={null}
export default function handler(req, res) {
  const results = largeArray.map(item => {
    return expensiveOperation(item);
  });
  res.json(results);
}
```

**✅ Non-Blocking:**

```javascript theme={null}
export default async function handler(req, res) {
  const results = await Promise.all(
    largeArray.map(async item => {
      return await expensiveOperationAsync(item);
    })
  );
  res.json(results);
}
```

Or batch process:

```javascript theme={null}
export default async function handler(req, res) {
  const BATCH_SIZE = 100;
  const results = [];
  
  for (let i = 0; i < largeArray.length; i += BATCH_SIZE) {
    const batch = largeArray.slice(i, i + BATCH_SIZE);
    const batchResults = await Promise.all(
      batch.map(item => expensiveOperationAsync(item))
    );
    results.push(...batchResults);
    
    // Allow event loop to process other requests
    await new Promise(resolve => setImmediate(resolve));
  }
  
  res.json(results);
}
```

### 4. Database Queries Without Connection Pooling

**❌ Blocking:**

```javascript theme={null}
// Creating new connection each time
export default async function handler(req, res) {
  const client = await createConnection();
  const result = await client.query('SELECT * FROM users');
  await client.close();
  res.json(result);
}
```

**✅ Non-Blocking:**

```javascript theme={null}
// Use connection pool
import { pool } from '@/lib/db';

export default async function handler(req, res) {
  const result = await pool.query('SELECT * FROM users');
  res.json(result);
}
```

***

## Advanced Monitoring Setup

### Real-Time Dashboard Script

Create `scripts/monitor-dashboard.sh`. Don't forget to adapt the pm2 application name. You will also need the `jq` utility on your system.

```bash {filename="scripts/monitor-dashboard.sh"} theme={null}
#!/bin/bash

while true; do
  clear
  echo "=== Next.js Event Loop Monitoring ==="
  echo "Updated: $(date)"
  echo ""
  
  # PM2 Status
  echo "PM2 Instances:"
  pm2 list | grep next-app
  echo ""
  
  # Health Check All Instances
  echo "Health Status:"
  for i in {1..10}; do
    curl -s http://localhost:3000/api/monitoring/health 2>/dev/null | \
      jq -r '"\(.instance): P99=\(.eventLoop.p99)ms \(.status)"' || \
      echo "Instance not responding"
  done
  
  echo ""
  echo "Press Ctrl+C to exit"
  sleep 5
done
```

Make it executable:

```bash {filename="Terminal"} theme={null}
chmod +x scripts/monitor-dashboard.sh
./scripts/monitor-dashboard.sh
```

### Load Test Monitoring

Create `scripts/load-test-monitor.sh`:

```bash {filename="scripts/load-test-monitor.sh"} theme={null}
#!/bin/bash

OUTPUT_DIR="./load-test-results/$(date +%Y%m%d_%H%M%S)"
mkdir -p "$OUTPUT_DIR"

echo "timestamp,instance,p95,p99,heap_mb" > "$OUTPUT_DIR/metrics.csv"

echo "Starting load test monitoring..."
echo "Press Ctrl+C when test is complete"

while true; do
  timestamp=$(date +%s)
  
  # Collect metrics from health endpoint
  curl -s http://localhost:3000/api/monitoring/health 2>/dev/null | \
    jq -r --arg ts "$timestamp" \
    '[$ts, .instance, .eventLoop.p95, .eventLoop.p99, .memory.heapUsed] | @csv' \
    >> "$OUTPUT_DIR/metrics.csv"
  
  sleep 2
done
```

Run alongside your load test:

```bash {filename="Terminal"} theme={null}
# Terminal 1: Start monitoring
./scripts/load-test-monitor.sh

# Terminal 2: Run your load test (locust example but use whatever you prefer)
locust -f loadtest.py --host=http://localhost:3000
```

### Analyzing Results

After your load test, analyze the collected data:

```bash {filename="Terminal"} theme={null}
# View summary statistics
cat load-test-results/*/metrics.csv | \
  awk -F',' 'NR>1 {sum+=\$4; count++; if(\$4>max) max=\$4} 
             END {print "Avg P99:", sum/count, "ms\nMax P99:", max, "ms"}'

# Find instances with high P99
cat load-test-results/*/metrics.csv | \
  awk -F',' 'NR>1 && \$4>100 {print \$2, \$4}' | \
  sort -k2 -rn | \
  head -10
```

***

## Best Practices

### 1. Set Appropriate Thresholds

Adjust thresholds based on your application:

```javascript theme={null}
const monitor = new AdvancedEventLoopMonitor({
  warningThreshold: 30,   // Stricter for high-performance apps
  criticalThreshold: 75,
  logInterval: 60000      // Less frequent for production
});
```

### 2. Monitor in Staging First

Test your monitoring setup in a staging environment before production deployment to:

* Verify thresholds are appropriate
* Ensure logging doesn't impact performance
* Validate alerting mechanisms

### 3. Combine with APM Tools

Event loop monitoring complements Application Performance Monitoring tools like [Blackfire.io](https://blackfire.io):

* Use event loop monitoring to identify blocking operations
* Use APM for distributed tracing and end-to-end monitoring
* Correlate event loop delays with external service latencies

### 4. Regular Performance Audits

Schedule monthly performance reviews:

* Analyze P99 trends over time
* Identify endpoints with degrading performance
* Review and optimize slow requests
* Update monitoring thresholds as needed

## Conclusion

Event loop monitoring is essential for building performant Next.js applications at scale. By implementing the monitoring system described in this guide, you can:

* **Identify bottlenecks** before they impact users
* **Optimize critical paths** with data-driven insights
* **Scale confidently** knowing your application's limits
* **Diagnose issues quickly** with detailed metrics

Remember: The event loop is the heartbeat of your Node.js application. Keep it healthy, and your application will scale smoothly.

***

## Additional Resources

* [Node.js Event Loop Documentation](https://nodejs.org/en/docs/guides/event-loop-timers-and-nexttick/)
* [Performance Hooks API](https://nodejs.org/api/perf_hooks.html)
* [Next.js Instrumentation](https://nextjs.org/docs/app/building-your-application/optimizing/instrumentation)
* [PM2 Cluster Mode](https://pm2.keymetrics.io/docs/usage/cluster-mode/)

*Ready to deploy your optimized Next.js application? [Create a free Upsun account](https://upsun.com) to get instant preview environments, Git-driven infrastructure, and built-in observability tools for production-ready deployments.*


# Mastering the Explore, Plan, Execute methodology for AI-assisted development
Source: https://developer.upsun.com/posts/how-it-works/explore-plan-execute-methodology

Learn how to transform AI coding assistants from eager juniors into rockstar developers using proven context strategies, quality assurance, and the three-phase workflow

<PostMeta />

Working with AI coding assistants in 2025 feels like managing an exceptionally eager, overly confident junior developer who types at superhuman speed (thank you [Paul](/) for the metaphor). They'll confidently write thousands of lines of code before you realize they've misunderstood the assignment. The difference between frustration and productivity lies not in the AI's capabilities, but in how you guide it.

After months of refining workflows with Claude Code and other AI assistants, one methodology has consistently transformed these tools from unpredictable helpers into reliable development partners for my needs: **Explore, Plan, Execute**. This article breaks down each phase with practical examples, showing you how to build the right context, leverage advanced features, and maintain code quality throughout the process.

## The fundamental challenge: Context vs. prompts

Most developers confuse prompts with context. A prompt tells the AI **what to do right now**. Context teaches it who you are, what your project does, and how you work. Without proper context, even the best prompts produce mediocre results.

Think of it this way: Would you hire a developer, point them at your codebase, and immediately ask them to implement a payment system? Of course not. You'd onboard them, explain the architecture, share coding standards, and review similar implementations. AI assistants need the same foundation.

### Building your knowledge foundation

Before any coding session, your AI assistant needs two types of knowledge: project-specific information and team conventions. This isn't about dumping your entire codebase into a context window, that's like giving a new hire 10,000 pages of documentation on their first day. Instead, you need structured, purposeful context.

#### The README.md: Your project's story

Your README should answer the questions a new developer would ask on day one. Here's a template optimized for AI comprehension:

````markdown theme={null}
# Project Name

## What This Project Does
[2-3 sentences explaining the core purpose and value proposition]

## Architecture Overview
- **Frontend**: Next.js 14 with TypeScript, deployed on Vercel
- **Backend**: Node.js + Express, containerized with Docker
- **Database**: PostgreSQL with Prisma ORM
- **Infrastructure**: Upsun PaaS with preview environments

## Quick Start
```bash
npm install
npm run dev
# API runs on http://localhost:3000
# Frontend runs on http://localhost:3001

## Core Concepts
- **User**: Authenticated entity with roles (admin, user, guest)
- **Workspace**: Isolated environment for team collaboration
- **Pipeline**: Automated workflow triggered by events

## Project Structure
src/
├── api/          # Express routes and middleware
├── services/     # Business logic layer
├── models/       # Database models (Prisma)
├── utils/        # Shared utilities
└── types/        # TypeScript definitions

## External Dependencies
- Stripe API for payments (test mode in development)
- SendGrid for transactional emails
- Redis for session management
- S3-compatible storage for file uploads
````

This structure gives AI assistants immediate understanding of your technology choices, project layout, and key abstractions. When you later ask "add user authentication," the assistant knows you're using Express, Prisma, and Redis for sessions.

## The AGENTS.md: Your team's DNA

While README describes what your project is, [AGENTS.md](https://agents.md) defines how you build it. This file contains your team's coding philosophy, standards, and preferences—essentially your team's DNA that the AI assistant needs to internalize.

### Comprehensive AGENTS.md template

Here's a battle-tested AGENTS.md structure that covers all aspects of team conventions. This example uses specific technologies and stacks so it needs to be tailored to your needs!

```markdown theme={null}
# Development Guidelines for AI Assistants

## Team Philosophy
We prioritize code readability over cleverness. Our codebase should be maintainable by any team member, including juniors. We favor explicit over implicit, and simple over complex. When in doubt, choose the solution that's easier to debug at 3 AM during an incident.

## Code Style Preferences

### General Principles
- Functions should do one thing well (Single Responsibility)
- Prefer composition over inheritance
- Use early returns to reduce nesting
- Maximum line length: 100 characters
- Maximum file length: 300 lines (split larger files)
- Indent with 2 spaces (never tabs)

### Naming Conventions
- Variables: camelCase (userId, orderTotal)
- Constants: UPPER_SNAKE_CASE (MAX_RETRIES, API_TIMEOUT)
- Classes: PascalCase (UserService, OrderController)
- Interfaces: PascalCase with 'I' prefix (IUserService, IOrderData)
- Type aliases: PascalCase (UserRole, OrderStatus)
- Files: kebab-case (user-service.ts, order-controller.ts)
- Test files: *.spec.ts or *.test.ts adjacent to source
- React components: PascalCase files (UserProfile.tsx)
- Hooks: use prefix (useAuth, useLocalStorage)
- Boolean variables: is/has/should prefix (isLoading, hasError, shouldRefresh)
- Event handlers: on prefix (onSubmit, onClick)
- Private methods: underscore prefix (_validateInput, _processData)

### Comment Standards
- Use JSDoc for public APIs
- Comments explain "why" not "what"
- TODO comments must include author and date: // TODO(john, 2024-03): Refactor after v2 launch
- No commented-out code in main branch
- Document complex regex patterns
- Document magic numbers

Example:

/**
 * Calculates compound interest with monthly contributions
 * @param principal - Initial investment amount
 * @param rate - Annual interest rate as decimal (0.05 for 5%)
 * @param years - Investment period in years
 * @param monthlyContribution - Optional monthly addition
 * @returns Total value after compound interest
 */
function calculateCompoundInterest(
  principal: number,
  rate: number, 
  years: number,
  monthlyContribution = 0
): number {
  // Using monthly compounding for more accurate results
  const monthlyRate = rate / 12;
  const months = years * 12;
  
  // Formula: P(1 + r)^n + PMT × (((1 + r)^n - 1) / r)
  // where P = principal, r = rate, n = periods, PMT = payment
  const compoundPrincipal = principal * Math.pow(1 + monthlyRate, months);
  const contributionValue = monthlyContribution * 
    ((Math.pow(1 + monthlyRate, months) - 1) / monthlyRate);
  
  return compoundPrincipal + contributionValue;
}

## TypeScript Conventions

### Type Safety Rules
- Always define explicit return types for functions
- Use interfaces for object shapes, types for unions/primitives
- Prefer `unknown` over `any` when type is truly unknown
- Use strict mode with all checks enabled
- Define DTOs for all API boundaries
- Use branded types for domain primitives

### Type Examples

// Branded type for type safety
type UserId = string & { readonly brand: unique symbol };
type OrderId = string & { readonly brand: unique symbol };

// Domain types with clear constraints
type OrderStatus = 'pending' | 'processing' | 'shipped' | 'delivered' | 'cancelled';

// Interface for data objects
interface IOrderData {
  id: OrderId;
  userId: UserId;
  items: IOrderItem[];
  status: OrderStatus;
  createdAt: Date;
  updatedAt: Date;
}

// Type for function options
type CreateOrderOptions = {
  skipInventoryCheck?: boolean;
  notifyUser?: boolean;
  priority?: 'normal' | 'high';
};

// Utility types we use frequently
type Nullable<T> = T | null;
type Optional<T> = T | undefined;
type AsyncResult<T, E = Error> = Promise<Result<T, E>>;

## Architecture Patterns

### Service Layer Pattern
All business logic lives in services, not controllers or models:

// ✅ Good: Business logic in service
class OrderService {
  async createOrder(data: CreateOrderDTO): Promise<Order> {
    // Validation
    await this.validateInventory(data.items);
    
    // Business logic
    const pricing = this.calculatePricing(data.items);
    
    // Persistence
    return this.orderRepository.create({
      ...data,
      ...pricing
    });
  }
}

// ❌ Bad: Business logic in controller
class OrderController {
  async create(req: Request, res: Response) {
    // Don't put business logic here!
    const pricing = calculatePricing(req.body.items); // Wrong!
  }
}

### Dependency Injection
Use constructor injection with interfaces:

class OrderService {
  constructor(
    private readonly orderRepo: IOrderRepository,
    private readonly inventoryService: IInventoryService,
    private readonly emailService: IEmailService
  ) {}
}

### Repository Pattern
Abstract data access behind repositories:

interface IUserRepository {
  findById(id: UserId): Promise<User | null>;
  findByEmail(email: string): Promise<User | null>;
  create(data: CreateUserDTO): Promise<User>;
  update(id: UserId, data: UpdateUserDTO): Promise<User>;
  softDelete(id: UserId): Promise<void>;
}

## Error Handling

### Error Classes
Define specific error classes for different scenarios:

// Base error class
abstract class ApplicationError extends Error {
  constructor(
    message: string,
    public statusCode: number,
    public code: string
  ) {
    super(message);
    this.name = this.constructor.name;
    Error.captureStackTrace(this, this.constructor);
  }
}

// Specific error types
class ValidationError extends ApplicationError {
  constructor(message: string, public fields: Record<string, string>) {
    super(message, 400, 'VALIDATION_ERROR');
  }
}

class NotFoundError extends ApplicationError {
  constructor(resource: string, id: string) {
    super(`${resource} with id ${id} not found`, 404, 'NOT_FOUND');
  }
}

class UnauthorizedError extends ApplicationError {
  constructor(message = 'Unauthorized') {
    super(message, 401, 'UNAUTHORIZED');
  }
}

### Error Handling Rules
- Never use `console.log` in production code
- Use structured logging with context
- Always handle promise rejections
- Throw custom error classes, not strings
- Don't expose internal errors to users
- Log full error details, return safe messages

Example:

async function processPayment(orderId: OrderId): Promise<void> {
  try {
    const order = await orderRepo.findById(orderId);
    if (!order) {
      throw new NotFoundError('Order', orderId);
    }
    
    await paymentGateway.charge(order.total);
    
  } catch (error) {
    logger.error('Payment processing failed', {
      orderId,
      error: error instanceof Error ? error.message : 'Unknown error',
      stack: error instanceof Error ? error.stack : undefined,
      timestamp: new Date().toISOString()
    });
    
    if (error instanceof ApplicationError) {
      throw error; // Re-throw known errors
    }
    
    // Don't expose internal errors
    throw new ApplicationError('Payment processing failed', 500, 'PAYMENT_ERROR');
  }
}

## Testing Philosophy

### Testing Principles
- Write tests first (TDD approach)
- Aim for 80% code coverage minimum
- Focus on behavior, not implementation
- Test public interfaces, not private methods
- Each test should test one thing
- Tests should be independent and idempotent

### Test Structure
Follow AAA pattern (Arrange, Act, Assert):

describe('OrderService', () => {
  describe('createOrder', () => {
    it('should calculate correct total with tax and shipping', async () => {
      // Arrange
      const mockItems = [
        { productId: '1', quantity: 2, price: 10.00 },
        { productId: '2', quantity: 1, price: 20.00 }
      ];
      const orderData = { items: mockItems, userId: 'user123' };
      
      // Act
      const result = await orderService.createOrder(orderData);
      
      // Assert
      expect(result.subtotal).toBe(40.00);
      expect(result.tax).toBe(4.00); // 10% tax
      expect(result.shipping).toBe(5.00);
      expect(result.total).toBe(49.00);
    });
    
    it('should throw ValidationError when items array is empty', async () => {
      // Arrange
      const orderData = { items: [], userId: 'user123' };
      
      // Act & Assert
      await expect(orderService.createOrder(orderData))
        .rejects
        .toThrow(ValidationError);
    });
  });
});

### Mocking Strategy
- Mock external services (APIs, databases)
- Don't mock internal modules
- Use factories for test data
- Reset mocks between tests

## Database Patterns

### Query Patterns
- Use transactions for multi-table operations
- Always use parameterized queries
- Implement soft delete with `deletedAt` timestamps
- Include audit fields on all tables
- Use optimistic locking for concurrent updates

### Standard Fields
Every table must include:

interface IAuditFields {
  id: string; // UUID
  createdAt: Date;
  createdBy: UserId;
  updatedAt: Date;
  updatedBy: UserId;
  deletedAt: Date | null;
  deletedBy: UserId | null;
  version: number; // For optimistic locking
}

### Migration Rules
- Never modify existing migrations
- Always provide rollback logic
- Test migrations on copy of production data
- Name migrations descriptively: `001_add_user_email_verification.ts`

## API Design

### RESTful Conventions

GET    /api/v1/orders          # List with pagination
GET    /api/v1/orders/:id      # Get single resource
POST   /api/v1/orders          # Create new resource
PUT    /api/v1/orders/:id      # Full update
PATCH  /api/v1/orders/:id      # Partial update
DELETE /api/v1/orders/:id      # Soft delete

### Response Formats
Success response:

{
  "success": true,
  "data": {
    "id": "123",
    "name": "Example"
  },
  "meta": {
    "timestamp": "2024-01-01T00:00:00Z",
    "version": "1.0.0"
  }
}

Error response:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      }
    ]
  },
  "meta": {
    "timestamp": "2024-01-01T00:00:00Z",
    "requestId": "req_123456"
  }
}

### Pagination Standard

{
  "data": [...],
  "pagination": {
    "page": 1,
    "perPage": 20,
    "total": 100,
    "totalPages": 5,
    "hasNext": true,
    "hasPrev": false
  }
}

## Security Requirements

### Authentication & Authorization
- Use JWT with refresh tokens
- Implement RBAC (Role-Based Access Control)
- Session timeout after 30 minutes of inactivity
- Require MFA for admin accounts
- Log all authentication events

### Input Validation
- Validate all input with Zod schemas
- Sanitize HTML content with DOMPurify
- Reject requests with unexpected fields
- Implement request size limits

### Security Headers

app.use(helmet({
  contentSecurityPolicy: {
    directives: {
      defaultSrc: ["'self'"],
      styleSrc: ["'self'", "'unsafe-inline'"],
      scriptSrc: ["'self'"],
      imgSrc: ["'self'", "data:", "https:"],
    },
  },
  hsts: {
    maxAge: 31536000,
    includeSubDomains: true,
    preload: true
  }
}));

### Rate Limiting
- Public endpoints: 100 requests/minute
- Authenticated endpoints: 1000 requests/minute  
- Login endpoints: 5 attempts/15 minutes
- Use sliding window algorithm

## Performance Standards

### Response Time Targets
- API endpoints: < 200ms (p95)
- Database queries: < 50ms
- External API calls: implement circuit breakers
- Page load time: < 3 seconds

### Optimization Rules
- Implement pagination for lists (max 100 items)
- Use database indexes on foreign keys and frequently queried fields
- Cache expensive computations with Redis
- Implement database connection pooling
- Use CDN for static assets

## Git Workflow

### Branch Naming
- Features: `feature/JIRA-123-user-authentication`
- Bugfixes: `bugfix/JIRA-456-payment-calculation`
- Hotfixes: `hotfix/JIRA-789-critical-security-fix`
- Releases: `release/v1.2.0`

### Commit Message Format
Follow conventional commits:

type(scope): subject

body (optional)

footer (optional)

Types:
- feat: New feature
- fix: Bug fix
- docs: Documentation changes
- style: Code style changes
- refactor: Code refactoring
- perf: Performance improvements
- test: Test additions or corrections
- chore: Build process or auxiliary tool changes

Example:

feat(auth): implement OAuth2 login with Google

- Added Google OAuth2 strategy
- Created callback endpoint for token exchange
- Updated user model to store OAuth profiles

Closes JIRA-123

### PR Rules
- PRs must pass all CI checks
- Require at least 2 approvals
- Must include tests for new features
- Update documentation for API changes
- Link to JIRA ticket in description

## Documentation Standards

### Code Documentation
- Document all public APIs with JSDoc
- Include examples in documentation
- Keep documentation next to code
- Update documentation with code changes

### API Documentation
- Use OpenAPI 3.0 specification
- Include request/response examples
- Document all error codes
- Provide curl examples

### README Files
Each module should have a README explaining:
- Purpose and responsibilities
- Public interface
- Usage examples
- Dependencies
- Configuration options

## Monitoring and Logging

### Logging Levels
- ERROR: System errors requiring immediate attention
- WARN: Issues that should be investigated
- INFO: Important business events
- DEBUG: Detailed diagnostic information

### What to Log
- All API requests (method, path, duration, status)
- Authentication events (login, logout, failed attempts)
- Database query times > 100ms
- External API calls and responses
- Business events (order created, payment processed)
- Errors with full context

### Metrics to Track
- Request rate and latency (by endpoint)
- Error rate (4xx vs 5xx)
- Database connection pool usage
- Queue lengths and processing times
- Business metrics (orders/hour, conversion rate)

## Development Environment

### Required Tools
- Node.js 20.x LTS
- TypeScript 5.x
- Docker and Docker Compose
- Git 2.x
- VS Code with team settings

### VS Code Extensions
- ESLint
- Prettier
- GitLens
- Docker
- Thunder Client (API testing)
- Error Lens
- TODO Highlight

### Environment Variables
Never commit .env files. Use .env.example:

# Database
DATABASE_URL=postgresql://user:pass@localhost:5432/dbname

# Redis
REDIS_URL=redis://localhost:6379

# Auth
JWT_SECRET=your-secret-here
JWT_REFRESH_SECRET=your-refresh-secret

# External APIs
STRIPE_API_KEY=sk_test_...
SENDGRID_API_KEY=SG...

# Feature Flags
ENABLE_NEW_PAYMENT_FLOW=false

## Definition of Done

A task is only "done" when:
- [ ] Code is written and follows team conventions
- [ ] Unit tests written and passing (>80% coverage)
- [ ] Integration tests for API endpoints
- [ ] Code reviewed and approved by 2 team members
- [ ] Documentation updated (code, API, README)
- [ ] No linting or TypeScript errors
- [ ] Security scan passed
- [ ] Performance requirements met
- [ ] Deployed to staging and tested
- [ ] Monitoring and alerts configured
- [ ] Feature flag configured (if applicable)
- [ ] JIRA ticket updated and moved to Done

## AI-Specific Instructions

When generating code:
1. Always follow these conventions without exception
2. If unsure about a convention, ask for clarification
3. Generate complete code, not snippets
4. Include error handling in all examples
5. Write tests alongside implementation
6. Add detailed comments for complex logic
7. Use our established patterns, don't introduce new ones
8. Validate all inputs according to our standards
9. Follow our Git commit message format
10. Alert us to any security concerns

Remember: Consistency is more important than perfection. Follow team patterns even if you know a "better" way.
```

## Team-specific customization

Different teams have different needs. Here are specialized sections you might add:

### For Frontend Teams

```markdown theme={null}
## React/Frontend Conventions

### Component Structure
- One component per file
- Co-locate styles, tests, and stories
- Use function components with hooks
- Props interface named `I{ComponentName}Props`

### State Management
- Use Zustand for global state
- React Query for server state
- Local state with useState/useReducer
- No Redux (legacy pattern for us)

### Styling
- CSS Modules for component styles
- Tailwind for utility classes
- No inline styles except dynamic values
- Mobile-first responsive design
```

### For Microservices Teams

```markdown theme={null}
## Microservices Patterns

### Service Communication
- REST for synchronous communication
- RabbitMQ for async messaging
- gRPC for internal service-to-service
- GraphQL federation for client-facing API

### Service Boundaries
- Each service owns its database
- No shared database access
- Data duplication is acceptable
- Event sourcing for data sync
```

### For DevOps-Heavy Teams

```markdown theme={null}
## Infrastructure as Code

### Container Standards
- Multi-stage Docker builds
- Non-root user in containers
- Health checks required
- Resource limits defined

### CI/CD Pipeline
- Build -> Test -> Security Scan -> Deploy
- Automatic rollback on metric degradation
- Blue-green deployments for production
- Canary releases for high-risk changes
```

<Note>
  For Claude Code users, create a symlink from CLAUDE.md to AGENTS.md:

  ```bash theme={null}
  ln -s AGENTS.md CLAUDE.md
  ```
</Note>

### Organizing knowledge for larger projects

As projects grow, flat files become unwieldy. You can organize your context hierarchically:

```
.ai/
├── knowledge/
│   ├── architecture/
│   │   ├── database-schema.md
│   │   ├── api-design.md
│   │   └── deployment.md
│   ├── decisions/
│   │   ├── ADR-001-chose-postgresql.md
│   │   ├── ADR-002-event-driven-architecture.md
│   │   └── ADR-003-monorepo-structure.md
│   └── examples/
│       ├── service-pattern.ts
│       ├── test-structure.spec.ts
│       └── error-handling.ts
└── rules/
    ├── code-style.md
    ├── security.md
    └── performance.md
```

But beware of context rot—too much information degrades performance. [Research](https://research.trychroma.com/context-rot) shows that beyond 10K tokens, AI assistants struggle to find relevant information. Keep your context focused and relevant to current work.

## Phase 1: Explore - Teaching your AI to understand

The **Explore** phase transforms your AI from an outsider to an informed team member. This isn't about writing code, it's about building understanding. Most developers skip this phase, jumping straight to implementation, then wonder why the AI misses obvious patterns or violates architectural principles.

### The exploration mindset

When you explore, you're explicitly preventing the AI from coding. This counterintuitive approach forces deeper analysis and prevents premature implementation based on incomplete understanding.

#### Example: Exploring a payment service

```prompt {filename="claude"} theme={null}
We're going to work on the payment processing module. I need you to understand how it currently works before we make changes.

Read through:
- src/services/payment/
- src/api/routes/payment.ts
- tests/payment.test.ts
- docs/payment-flow.md

DO NOT write any code yet. After reading, explain:
1. How does the current payment flow work?
2. What external services are involved?
3. What are the main data models?
4. What error cases are handled?
5. What patterns do you notice in the implementation?

Focus on understanding the business logic and architectural decisions.
```

The AI will analyze your codebase and provide insights like:

```prompt {filename="claude"} theme={null}
After analyzing the payment module, here's my understanding:

1. **Payment Flow**:
   - User initiates payment through POST /api/payment/create
   - System creates a pending PaymentIntent with Stripe
   - Frontend confirms payment using Stripe Elements
   - Webhook receives confirmation from Stripe
   - System updates order status and sends confirmation email

2. **External Services**:
   - Stripe for payment processing (using SDK v12.5)
   - SendGrid for email notifications
   - Redis for idempotency keys (preventing duplicate charges)

3. **Data Models**:
   - Payment: Core record with amount, status, metadata
   - PaymentMethod: Stored customer payment methods
   - Transaction: Audit log of all payment events

4. **Error Handling**:
   - Retry logic for network failures (3 attempts with exponential backoff)
   - Webhook signature validation to prevent fraud
   - Graceful degradation if email service is down

5. **Patterns Observed**:
   - Service layer pattern isolates business logic from routes
   - All monetary amounts stored as integers (cents)
   - Event sourcing pattern for payment state changes
   - Dependency injection for testability
```

### Advanced exploration with Claude Code

Claude Code's exploration capabilities extend beyond simple file reading. Use these commands to build comprehensive understanding:

```prompt {filename="claude"} theme={null}
# Initialize Claude with exploration mode
claude --explore "src/services/" --depth=3 --prepare-discuss

# For complex features, use think modes during exploration
claude --think-hard
```

<Note>
  You can use `Shift + Tab` in `claude` to switch from plan mode to classic.
</Note>

Then provide exploration prompts that leverage Claude's thinking capabilities:

```prompt {filename="claude"} theme={null}
Think hard about the authentication system. 

Read through:
- All files in src/auth/
- Middleware implementations in src/middleware/
- Session management in src/services/session/
- Related tests

Create a mental model of:
- How tokens are generated and validated
- Session lifecycle from creation to expiration  
- Permission checking flow
- Refresh token rotation strategy

After exploring, prepare to discuss potential security improvements.
```

### Multi-file exploration patterns

For features spanning multiple modules, structure your exploration systematically:

```prompt {filename="claude"} theme={null}
We need to understand the document processing pipeline. This touches multiple systems.

Phase 1 - Input Layer:
- Read src/api/upload/ to understand file ingestion
- Review src/validators/document.ts for validation rules

Phase 2 - Processing Core:
- Examine src/workers/document-processor.ts
- Understand src/services/ocr/ for text extraction
- Review src/services/nlp/ for entity recognition

Phase 3 - Storage and Retrieval:
- Check src/models/document.ts for data structure
- Review src/services/search/ for indexing logic

DO NOT suggest improvements yet. First, map out:
1. The complete data flow from upload to search
2. All transformation steps
3. Error handling at each stage
4. Performance bottlenecks you observe

We'll discuss optimizations after you fully understand the current implementation.
```

### Context preservation between sessions

One challenge with AI assistants is maintaining context across sessions. Document your exploration findings:

```prompt {filename="claude"} theme={null}
After exploring the codebase, write your understanding to knowledge/payment-system-analysis.md

Include:
- High-level architecture diagram (as ASCII art)
- Key components and their responsibilities
- Data flow for main use cases
- Integration points with external services
- Current limitations or technical debt observed

This will help future sessions start with context.
```

## Phase 2: Plan - Architecting before implementing

Planning transforms vague requirements into concrete, testable specifications. This phase leverages AI's ability to think systematically while keeping you in control of architectural decisions.

### Strategic thinking modes in Claude Code

Claude Code offers multiple thinking modes, each consuming different token budgets:

* **Think** (4,000 tokens): Quick planning for simple features
* **Think hard** (10,000 tokens): Standard planning for most tasks
* **Think hardest** (32,000 tokens): Complex architectural decisions
* **Ultrathink** (customizable): Comprehensive system design

Choose your mode based on task complexity:

```prompt {filename="claude"} theme={null}
Think hard about implementing real-time notifications.

Consider:
- WebSocket vs Server-Sent Events vs polling
- Scalability with multiple server instances
- Message delivery guarantees
- Offline message queueing
- Battery optimization for mobile clients

Create a detailed implementation plan including:
1. Technology choice with justification
2. Server architecture changes needed
3. Client integration approach
4. Database schema for message storage
5. Testing strategy for real-time features
```

### The planning template

Effective plans follow consistent structure. Here's a template that works across different feature types:

```prompt {filename="claude"} theme={null}
Create a detailed plan for [FEATURE]. Think hardest about this.

Requirements:
- [Specific requirement 1]
- [Specific requirement 2]
- [Performance requirement]
- [Security requirement]

Constraints:
- Must work with existing [system/API]
- Cannot modify [protected component]
- Must maintain backwards compatibility
- Deploy to Upsun with preview environments

Deliverables needed:
1. List all files that need changes
2. New files to create with purpose
3. Database migrations required
4. API endpoint changes
5. Test scenarios to cover
6. Rollback strategy if deployment fails

For each component, specify:
- Function/class names to create
- 2-3 sentences about implementation approach
- Dependencies on other components
- Estimated complexity (simple/medium/complex)

Focus on implementing only what we need now. Don't include "nice to have" features or future extensibility unless specifically required.
```

### Example: Planning a multi-tenant feature

Let's walk through planning a real feature—adding multi-tenancy to an existing application:

```prompt {filename="claude"} theme={null}
Think hardest about adding multi-tenant support to our application.

Current state:
- Single-tenant PostgreSQL database
- User authentication with JWT
- Express API with Prisma ORM

Requirements:
- Separate data between organizations
- Users can belong to multiple organizations
- Organization admins can invite users
- Data isolation must be bulletproof
- Gradual rollout capability

Create a plan that:
1. Identifies the isolation strategy (schema-per-tenant vs row-level security)
2. Lists all models needing tenant_id
3. Describes middleware for tenant context injection
4. Outlines migration strategy for existing data
5. Specifies test scenarios for isolation verification

Be specific about implementation details.
```

The AI might respond with:

```markdown {filename="claude"} theme={null}
## Multi-Tenant Implementation Plan

### Isolation Strategy: Row-Level Security (RLS)
**Justification**: Simpler operations, better resource utilization, easier backup/restore per tenant

### Database Changes

#### New Tables
1. **organizations**
   - id, name, slug (unique), created_at, settings (JSONB)
   - Purpose: Root tenant entity

2. **organization_users**
   - organization_id, user_id, role, joined_at
   - Purpose: Many-to-many relationship with roles

#### Modified Tables (add tenant_id)
- projects → add organization_id (FK, NOT NULL after migration)
- documents → add organization_id (via projects relation)
- api_keys → add organization_id

#### Migrations Required

// 001_add_organizations.ts
- Create organizations table
- Create organization_users table
- Add organization_id to affected tables (nullable initially)

// 002_populate_default_org.ts
- Create default organization for existing data
- Update all records with default org
- Make organization_id NOT NULL

// 003_add_rls_policies.ts
- Enable RLS on all tenant tables
- Create policies for tenant isolation

### API Changes

#### New Middleware: src/middleware/tenantContext.ts

// Extracts organization from subdomain or header
// Verifies user has access to organization
// Injects organizationId into req.context
// All queries automatically filtered by tenant

#### Modified Services
1. **src/services/auth.service.ts**
   - Add organization selection to login response
   - Include available organizations in JWT

2. **src/services/prisma.service.ts**
   - Extend Prisma client with automatic tenant filtering
   - Use middleware to inject WHERE clauses

### Test Scenarios

1. **Isolation Tests** (src/tests/multitenancy/isolation.spec.ts)
   - User A in Org1 cannot see Org2 data
   - API calls without org context fail
   - Direct database queries respect RLS

2. **Migration Tests** (src/tests/multitenancy/migration.spec.ts)
   - Existing data accessible after migration
   - Rollback preserves data integrity

3. **Performance Tests**
   - Query performance with tenant filtering
   - Index effectiveness on organization_id

### Rollout Strategy
1. Deploy with feature flag disabled
2. Run migrations in maintenance window
3. Enable for internal testing organization
4. Gradual percentage rollout
5. Full enablement after 1 week stability

### Rollback Plan
- Feature flag disables tenant filtering
- Keep organization_id columns (harmless if unused)
- Revert RLS policies if issues arise
```

### The "My Developer" review technique

After generating a plan, use this psychological trick to get better critique:

```prompt {filename="claude"} theme={null}
My developer created this plan for multi-tenancy. Review it critically—both high-level architecture and implementation details.

What are the potential issues? 
Where might this fail in production?
What security concerns do you see?
How could we simplify this approach?
Are there any race conditions or edge cases not considered?

Be harsh but constructive. I need to know the problems before we build this.
```

The AI responds more critically when reviewing "someone else's" work, often catching issues it wouldn't identify in its own output.

### Risk-based planning strategies

Not all features require the same planning depth:

#### Low risk (simple CRUD, UI changes)

```prompt theme={null}
Quick plan to add a "favorite" feature to projects. Users should be able to star/unstar projects. Keep it simple.
```

#### Medium risk (integrations, data migrations)

```prompt theme={null}
Think hard about integrating with Slack for notifications. Plan the implementation including webhook handling, retry logic, and user configuration.
```

#### High risk (security, payments, data privacy)

```prompt theme={null}
Think hardest about implementing end-to-end encryption for sensitive documents. 

Generate three different implementation approaches:
1. Client-side encryption with key management service
2. Proxy re-encryption for sharing
3. Hardware security module integration

Compare the approaches across:
- Security strength
- Implementation complexity  
- Performance impact
- User experience
- Maintenance burden

Recommend the best approach with detailed justification.
```

## Storing the specifications

When developing a new feature, you may find useful to actually keep the results from the Explore and Plan steps for future use. One way to achieve this easily is to ask your AI assistant to write the specifications for that feature:

```prompt {filename="claude"} theme={null}
Write the specifications for the feature discussed in `features/NEW_FEATURE.md`.
```

This is especially handy when your organization needs to develop multiple clients for the same project. You can for example ask the assistant to produce the iOS specification of the app based on the work you are doing on the web version. Another AI assistant can then pick up the spec and will have everything it needs to produce the new feature in native Swift.

## Phase 3: Execute - From plan to production code

Execution transforms your carefully crafted plan into working code. This phase requires different strategies depending on your confidence level and the code's impact radius.

### The execution spectrum

Execution isn't 1 or 0, it's a spectrum from full automation to careful supervision:

#### Watched execution (high-risk changes)

```prompt {filename="claude"} theme={null}
Now implement the authentication middleware based on our plan.

After each code block:
1. Run the linter: npm run lint
2. Run the specific tests: npm test -- auth.middleware.spec.ts
3. Show me any errors before proceeding
4. Wait for my confirmation before the next file

Start with src/middleware/auth.ts
```

#### Guided execution (medium-risk)

```prompt {filename="claude"} theme={null}
Implement the planned notification system.

Rules:
- Write tests FIRST for each component
- Run tests to confirm they fail
- Then implement the feature
- Run tests again to confirm they pass
- Use our established error handling patterns
- Follow the service layer architecture

Start with the WebSocket manager service.
```

#### Autonomous execution (low-risk)

```prompt {filename="claude"} theme={null}
Now think hard and write elegant code that completes the favorite projects feature.

After implementation:
- Run the full test suite
- Check TypeScript compilation
- Verify no linting errors
- Create the migration file

Don't add any features we didn't plan. Focus on clean, minimal implementation.
```

### Test-driven development with AI

TDD with AI assistants requires explicit instructions to avoid the common trap of mock implementations:

```prompt {filename="claude"} theme={null}
We're implementing the payment webhook handler using TDD.

Step 1: Write comprehensive tests for handleStripeWebhook function
- Test successful payment confirmation
- Test signature validation failure  
- Test duplicate event handling (idempotency)
- Test database transaction rollback on error
- Test notification sending

Write REAL tests, not placeholders. Use our existing test patterns from tests/services/

Step 2: Run the tests and show me they fail

Step 3: Implement the minimal code to make tests pass

Step 4: Refactor if needed while keeping tests green

Remember: No implementation until tests are written and failing.
```

### Example: Implementing a complex service

Let's implement a document processing service with proper error handling and testing:

```prompt {filename="claude"} theme={null}
Based on our plan, implement the document processing service.

Requirements reminder:
- Accept PDF, DOCX, and TXT files
- Extract text using appropriate libraries
- Run NLP for entity extraction
- Store results in PostgreSQL
- Index in Elasticsearch for search

Implementation approach:
1. First, write the TypeScript interfaces
2. Create the service class with stubbed methods
3. Implement one method at a time with tests
4. Add comprehensive error handling
5. Include logging at key points

Start with src/services/document/processor.service.ts

import { Injectable } from '@nestjs/common';
import { PrismaService } from '../prisma/prisma.service';
import { ElasticsearchService } from '../search/elasticsearch.service';
import { NlpService } from '../nlp/nlp.service';
import { Logger } from 'winston';

interface ProcessingResult {
  documentId: string;
  extractedText: string;
  entities: Entity[];
  metadata: DocumentMetadata;
}

interface Entity {
  type: 'PERSON' | 'ORGANIZATION' | 'LOCATION';
  value: string;
  confidence: number;
  positions: Array<{ start: number; end: number }>;
}

// Continue with the implementation...

Show me each method as you implement it. Include error handling and logging.
```

### Handling large file modifications

Claude Code excels at modifying large files without breaking existing functionality:

```prompt theme={null}
We need to refactor the monolithic user.service.ts file (currently 3000+ lines).

Approach:
1. Extract authentication logic to auth-user.service.ts
2. Extract profile management to profile-user.service.ts  
3. Extract notification logic to notification-user.service.ts
4. Keep core user CRUD in user.service.ts

Rules:
- Maintain all existing public interfaces
- Update dependency injection properly
- Keep all tests passing
- Use careful imports to avoid circular dependencies

Show me the extraction plan first, then proceed with implementation after I approve.
```

### Incremental execution with checkpoints

For complex features, build incrementally with validation checkpoints:

```prompt theme={null}
Implement the real-time collaboration feature in stages.

Stage 1: WebSocket connection management
- Implement connection handling
- Add authentication
- Test with multiple clients
CHECKPOINT: Show me manual test results

Stage 2: Operation transformation  
- Implement OT algorithm
- Add conflict resolution
- Test concurrent edits
CHECKPOINT: Run integration tests

Stage 3: Persistence layer
- Add operation history storage
- Implement replay functionality
- Test recovery scenarios
CHECKPOINT: Full system test

Stage 4: UI integration
- Add collaboration indicators
- Implement cursor positions
- Test user experience
CHECKPOINT: End-to-end test

Stop at each checkpoint for review before proceeding.
```

## Quality assurance: Catching AI hallucinations and anti-patterns

AI-generated code requires specialized quality assurance beyond traditional linting. The challenge isn't only syntax, it's semantic correctness, security vulnerabilities, and architectural consistency.

<Note>
  The following examples are based on a specific node.js project. While they give you a good understanding as to what should be present, you should build your own templates for this!
</Note>

### Essential TypeScript/Node.js toolchain

Configure your project with AI-specific quality gates:

#### ESLint configuration for AI code review

```javascript theme={null}
// .eslintrc.js
module.exports = {
  parser: '@typescript-eslint/parser',
  extends: [
    'eslint:recommended',
    'plugin:@typescript-eslint/recommended',
    'plugin:@typescript-eslint/recommended-requiring-type-checking',
    'plugin:security/recommended',
    'plugin:node/recommended'
  ],
  plugins: [
    '@typescript-eslint',
    'security',
    'no-secrets',
    'promise',
    'unicorn'
  ],
  rules: {
    // Catch common AI mistakes
    '@typescript-eslint/no-explicit-any': 'error',
    '@typescript-eslint/explicit-function-return-type': 'error',
    '@typescript-eslint/no-unused-vars': 'error',
    '@typescript-eslint/no-floating-promises': 'error',
    
    // Security rules for AI-generated code
    'security/detect-object-injection': 'error',
    'security/detect-non-literal-regexp': 'error',
    'security/detect-eval-with-expression': 'error',
    'no-secrets/no-secrets': 'error',
    
    // Prevent hallucinated imports
    'node/no-missing-import': 'error',
    'node/no-unpublished-import': 'error',
    
    // Code quality
    'complexity': ['error', { max: 10 }],
    'max-lines-per-function': ['error', { max: 50 }],
    'max-depth': ['error', { max: 3 }]
  },
  parserOptions: {
    project: './tsconfig.json'
  }
};
```

#### Automated testing with Vitest

```typescript theme={null}
// vitest.config.ts
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    globals: true,
    environment: 'node',
    coverage: {
      provider: 'c8',
      reporter: ['text', 'json', 'html'],
      lines: 80,
      functions: 80,
      branches: 80,
      statements: 80,
      checkCoverage: true,
      excludeNodeModules: true
    },
    testTimeout: 10000,
    hookTimeout: 10000,
    teardownTimeout: 10000,
    isolate: true,
    threads: true,
    mockReset: true
  }
});
```

### AI-specific code review checklist

Train your AI to self-review with your tailored checklist:

```prompt theme={null}
Before finalizing the implementation, review your code against this checklist:

Security:
□ All user input is validated
□ SQL queries use parameterization (or Prisma)
□ Secrets are in environment variables
□ Authentication checks on all protected routes
□ Rate limiting on public endpoints

Performance:
□ Database queries are optimized (no N+1)
□ Async operations are parallelized where possible
□ Large datasets use pagination/streaming
□ Caching implemented where appropriate
□ No synchronous file I/O in request handlers

Error Handling:
□ All promises have .catch() or try/catch
□ Custom error classes used (not string throws)
□ Errors logged with context
□ User-facing errors don't leak sensitive info
□ Database transactions rollback on error

Testing:
□ Unit tests for business logic
□ Integration tests for API endpoints
□ Edge cases covered (null, empty, overflow)
□ Error scenarios tested
□ Mocks used appropriately

Code Quality:
□ Functions do one thing well
□ No code duplication
□ Clear variable and function names
□ Comments explain "why" not "what"
□ TypeScript types are specific (no `any`)

Run through this checklist and fix any issues before marking complete.
```

### Continuous integration for AI workflows

Set up GitHub Actions to catch issues before merge:

```yaml theme={null}
# .github/workflows/ai-code-review.yml
name: AI Code Quality Check

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  quality-check:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '20'
          cache: 'npm'
      
      - name: Install dependencies
        run: npm ci
      
      - name: TypeScript compile check
        run: npm run build
        
      - name: ESLint security audit
        run: npm run lint:security
        
      - name: Run tests with coverage
        run: npm run test:coverage
        
      - name: Check for common AI anti-patterns
        run: |
          # Check for console.log in production code
          if grep -r "console\.log" --include="*.ts" --exclude-dir="test" src/; then
            echo "❌ Found console.log in production code"
            exit 1
          fi
          
          # Check for hardcoded secrets
          if grep -rE "(api[_-]?key|secret|password|token)\s*=\s*[\"'][^\"']+[\"']" --include="*.ts" src/; then
            echo "❌ Possible hardcoded secrets found"
            exit 1
          fi
          
          # Check for TODO comments (incomplete AI implementation)
          if grep -r "TODO\|FIXME\|XXX" --include="*.ts" src/; then
            echo "⚠️ Found TODO comments - ensure implementation is complete"
          fi
      
      - name: Comment PR with results
        uses: actions/github-script@v6
        if: always()
        with:
          script: |
            const fs = require('fs');
            const coverage = JSON.parse(fs.readFileSync('coverage/coverage-summary.json', 'utf8'));
            const total = coverage.total;
            
            const comment = `## AI Code Review Results
            
            ### Coverage Report
            - Lines: ${total.lines.pct}%
            - Functions: ${total.functions.pct}%
            - Branches: ${total.branches.pct}%
            - Statements: ${total.statements.pct}%
            
            ${total.lines.pct < 80 ? '⚠️ Coverage below 80% threshold' : '✅ Coverage meets requirements'}
            `;
            
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: comment
            });
```

## Claude Code tips and tricks

After months of daily use, these techniques consistently improve productivity and output quality:

### The resume pattern for long sessions

```prompt {filename="claude"} theme={null}
/resume

Continue implementing the payment service. We were working on webhook handling and got through signature validation. Next, we need to implement the event processing logic.
```

### Plan mode for research without coding

Activate Plan Mode with Shift+Tab twice, then:

```prompt {filename="claude"} theme={null}
Research how other projects handle distributed transactions. Look at:
- Saga pattern implementations
- Two-phase commit examples
- Event sourcing approaches

Find examples in our codebase and well-known open source projects. Don't implement anything yet—just gather information for discussion.
```

### Using MCP servers for enhanced capabilities

Configure Model Context Protocol servers in your `claude_mcp_config.json`:

```json theme={null}
{
  "servers": {
    "upsun": {
      "type": "http", 
      "url": "https://mcp.upsun.com",
      "headers": {
        "upsun-api-token": "---",
        "enable-write": "true"
      } 
    },
    "postgres": {
      "command": "npx",
      "args": ["mcp-server-postgres", "postgresql://localhost/mydb"]
    },
    "github": {
      "command": "npx",
      "args": ["mcp-server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "playwright": {
      "command": "npx",
      "args": ["mcp-server-playwright"]
    }
  }
}
```

Then leverage these in your workflow:

```prompt {filename="claude"} theme={null}
Using the Upsun MCP, create a new environment "test-qa" for my project "Test"

Using the postgres MCP server, analyze our database for:
- Tables without indexes on foreign keys
- Unused indexes taking space
- Slow query patterns from pg_stat_statements

Then use the playwright server to:
- Test our checkout flow end-to-end
- Capture screenshots at each step
- Identify any console errors or failed network requests
```

### Message queueing for complex tasks

Queue multiple prompts for intelligent processing:

```prompt {filename="claude"} theme={null}
[First message]
Analyze the performance bottlenecks in our API using the APM data.

[Second message]
Based on the bottlenecks found, create optimization plans for the top 3 issues.

[Third message]
Implement the highest-priority optimization with tests.

Process these in order, but pause if you need clarification on any step.
```

### The "think harder" escalation pattern

Start simple and escalate complexity as needed:

```prompt {filename="claude"} theme={null}
# First attempt - quick solution
Create a function to validate email addresses.

# If insufficient, escalate
Think harder about email validation. Consider international domains, subdomains, and new TLDs. Create a comprehensive solution.

# Maximum analysis if critical
Ultrathink: Design a complete email validation system including syntax checking, DNS verification, and disposable email detection. Consider performance, security, and user experience trade-offs.
```

## Platform-specific considerations: Upsun and modern PaaS

When developing with AI assistants for Cloud Application Platform environments like Upsun, include platform-specific context:

```markdown theme={null}
# Deployment Context (add to AGENTS.md)

## Platform: Upsun
- Git-driven deployments from main branch
- Preview environments for each pull request
- Environment variables managed via platform
- Build hooks run during deployment
- Services configured in .upsun/config.yaml

## Build Process

# .upsun/config.yaml snippet
applications:
  app:
    build:
      flavor: none
    hooks:
      build: |
        npm ci --production=false
        npm run build
        npm prune --production
    deploy: |
        npm run migrate

## Available Services
- PostgreSQL 15 (primary database)
- Redis 7 (caching and sessions)
- Elasticsearch 8 (search)
- RabbitMQ (message queue)

## Environment-Specific Behavior
- Production: main branch
- Staging: staging branch  
- Preview: PR-* branches (data cloned from staging)
- Local: Use docker-compose for service parity
```

This context helps AI assistants generate deployment-aware code:

```prompt {filename="claude"} theme={null}
Implement the transactions display feature.

Requirements:
- Create the migrations on the backend
- Add the endpoints on the API
- Create the transactions screen on the frontend
- Deploy and monitor the build and deploy processes to check for errors

Remember we're using Upsun's built-in environment variables for service connections.
```

## Common pitfalls and how to avoid them

### Pitfall 1: Context overload

**Problem**: Including entire codebase in context
**Symptom**: AI gives generic, inconsistent responses
**Solution**: Selective context loading

```prompt {filename="claude"} theme={null}
# Bad
Here's our entire repository. Implement user authentication.

# Good
For implementing JWT authentication, review:
- Current auth middleware in src/middleware/auth.ts
- User model in src/models/user.ts
- Existing login endpoint in src/api/auth.ts

Focus only on adding refresh token functionality.
```

### Pitfall 2: Ambiguous requirements

**Problem**: Vague instructions produce vague code
**Symptom**: AI implements features you didn't want
**Solution**: Specific, measurable requirements

```prompt {filename="claude"} theme={null}
# Bad
Make the search better.

# Good
Improve search with these specific changes:
1. Add fuzzy matching with max edit distance of 2
2. Implement "did you mean?" suggestions
3. Return results in <100ms for 95th percentile
4. Support filtering by date range and document type
5. Highlight matched terms in results
```

### Pitfall 3: Ignoring failed tests

**Problem**: AI continues despite test failures
**Symptom**: Broken code that "looks right"
**Solution**: Explicit test gates

```prompt {filename="claude"} theme={null}
After each implementation:
1. Run: npm test -- --watch=false
2. If ANY test fails, stop immediately
3. Show me the error
4. Fix the issue before continuing
5. Only proceed when all tests pass

This is non-negotiable. Failed tests = full stop.
```

### Pitfall 4: Missing error handling

**Problem**: AI writes happy-path code only
**Symptom**: Production crashes on edge cases
**Solution**: Explicit error scenarios

```prompt {filename="claude"} theme={null}
For each function you write, also implement:
1. What happens when inputs are null/undefined?
2. How do we handle network timeouts?
3. What if the database is unavailable?
4. How do we recover from partial failures?
5. What gets logged for debugging?

Example error handling pattern:

try {
  const result = await riskyOperation();
  return result;
} catch (error) {
  logger.error('Operation failed', {
    error: error.message,
    stack: error.stack,
    context: { userId, operationType }
  });
  
  if (error instanceof NetworkError) {
    throw new RetryableError('Network issue, please retry');
  }
  
  throw new ApplicationError('Operation failed', error);
}
```

### Pitfall 5: Security shortcuts

**Problem**: AI takes unsafe shortcuts
**Symptom**: SQL injection, XSS vulnerabilities
**Solution**: Security-first instructions

```prompt {filename="claude"} theme={null}
Security requirements for ALL code:
1. NEVER concatenate strings for SQL (use Prisma/parameters)
2. ALWAYS validate input with Zod schemas
3. Sanitize user content before rendering
4. Use crypto.randomBytes() for tokens, not Math.random()
5. Hash passwords with bcrypt, minimum 10 rounds
6. Check authorization, not just authentication

If you're unsure about security implications, flag it for review.
```

## Conclusion: From chaos to productivity

The **Explore, Plan, Execute** methodology transforms AI coding assistants from unpredictable tools into reliable development partners. Success doesn't come from better prompts alone. It comes from systematic context building, structured planning, and disciplined execution.

Remember these key principles:

1. **Context is king**: Invest time in README.md and AGENTS.md. They pay dividends in every coding session.

2. **Exploration prevents pain**: Understanding existing code before changing it catches issues that would take hours to debug later.

3. **Plans are contracts**: Detailed plans become specifications that keep AI on track during implementation.

4. **Execution needs supervision**: Match your supervision level to risk. Watch high-impact changes closely; let low-risk code flow.

5. **Quality gates catch hallucinations**: Automated testing, linting, and security scanning catch AI mistakes before they reach production.

The AI assistant remains that eager junior developer, but with proper guidance, it becomes a force multiplier for your productivity. The methodology works because it mirrors how you'd manage a human developer—clear requirements, thorough onboarding, structured planning, and quality review.

Start with small features to build confidence in the workflow. As you refine your context documents and develop prompt patterns that work for your team, you'll find yourself shipping quality code faster than ever before. The future of development isn't AI replacing developers, it's developers wielding AI tools with discipline and expertise.


# Fake IP till you make IP
Source: https://developer.upsun.com/posts/how-it-works/fake-ip-till-you-make-ip

How Upsun uses virtual IPs and NAT to keep your database connections stable even when containers move between VMs. A look at the networking tricks behind relationship stability.

<PostMeta />

Ever peek at your database connection details on [Upsun](https://upsun.com) and wonder why the IP addresses look... weird?

Check your relationship IPs and you'll spot something odd:

```bash theme={null}
$ echo $PLATFORM_RELATIONSHIPS | base64 -d | jq '.db[0].ip'
"169.254.17.139"
```

But your container's own IP tells a different story:

```bash theme={null}
$ hostname -i
247.221.80.48
```

Two completely different subnets. What's going on here?

## The great IP switcheroo

Before we explain the 169.254.0.0/16 subnet mystery, let's talk about how Upsun's infrastructure works. We run a grid of VMs, each hosting hundreds of containers. Each VM gets its own chunk of the 240.0.0.0/4 subnet. (If you're curious about that particular networking choice, [we wrote about it](/posts/how-it-works/how-upsun-built-stateless-mesh-networking-for-high-density-containers).)

All containers on a VM share that VM's subnet. This works great for routing, but creates an interesting problem: what happens when a container moves?

Containers move between VMs for all sorts of reasons - a VM might die, we might rebalance resources, or your database might need to relocate. When that happens, the container gets a new IP address in its new VM's subnet.

Do we update all your application configs every time? Update your environment variables? Force you to redeploy? That would be terrible.

## Enter the virtual IP

This is where the 169.254 subnet comes in. These are virtual IPs (VIPs), and they never change. The actual number is based on a hash of the relationship name, so it's consistent and predictable. Your application connects to the VIP, and behind the scenes we make sure it always points to the real container IP, wherever that container happens to be living.

Think of it as a forwarding address that never expires.

## The NAT trick

So how do we make one IP address magically point to another? With `iptables` and Network Address Translation (NAT). The name gives it away - we're translating one network address into another.

Here's what the `iptables` rules look like to route traffic from the virtual IP `169.254.17.139` to the real container IP `247.221.80.48`:

```
Chain PREROUTING (policy ACCEPT)
target     prot opt source               destination

Chain INPUT (policy ACCEPT)
target     prot opt source               destination

Chain POSTROUTING (policy ACCEPT)
target     prot opt source               destination

Chain OUTPUT (policy ACCEPT)
target     prot opt source               destination
ACCEPT     all  --  anywhere             anywhere             state RELATED,ESTABLISHED
DNAT       all  --  anywhere             169.254.17.139       to:247.221.80.48
```

The magic happens in that `DNAT` rule. When your application sends packets to `169.254.17.139`, the kernel rewrites the destination to `247.221.80.48` before forwarding them on. Your application doesn't know, doesn't care, and doesn't need to change its configuration.

## Bonus: load balancing for free

Here's a neat trick - `iptables` can do more than just one-to-one translation. With the `--nth` or `statistic` module, you can make a single VIP round-robin between multiple real IPs. This is perfect for load balancing across replicas.

Want to distribute traffic across three database replicas? Set up rules that send every third connection to a different backend:

```
DNAT  all  --  anywhere  169.254.17.139  statistic mode nth every 3 packet 0 to:247.221.80.48
DNAT  all  --  anywhere  169.254.17.139  statistic mode nth every 3 packet 1 to:247.221.80.52
DNAT  all  --  anywhere  169.254.17.139  statistic mode nth every 3 packet 2 to:247.221.80.61
```

Your application still connects to one address, but the kernel spreads the load across multiple backends behind the scenes. No load balancer configuration, no service mesh, no extra moving parts - the kernel handles it all.

## The takeaway

Virtual IPs give you stable relationship addresses even when the underlying infrastructure is shifting around. Your database connection string stays the same whether we're moving containers, rebalancing load, or dealing with hardware failures.

It's a neat trick that keeps your applications running smoothly while we handle the infrastructure complexity behind the scenes. You get to focus on writing code instead of managing network topology.

Sometimes faking it really is the best way to make it.


# High-performance backups: How Ceph snapshots enable incremental full backups
Source: https://developer.upsun.com/posts/how-it-works/how-do-we-do-incremental-but-really-full-backups-on-top-of-ceph

Learn how Upsun leverages Ceph's RBD export-diff feature to implement high-performance incremental backups that maintain full restore capabilities for large-scale container storage.

<PostMeta />

## The backup challenge at scale

When you're managing container storage at scale, backup performance becomes critical. Large volumes—those reaching hundreds of gigabytes—can take hours to back up using traditional full-volume streaming methods. This creates operational challenges: extended backup windows, increased resource consumption, and potential data loss exposure during long-running operations.

At Upsun, we face this challenge daily with our Ceph-based storage infrastructure. While Ceph's copy-on-write (CoW) snapshots provide instant cloning capabilities for our containers, off-site backups require a different approach. We need a solution that combines the speed of incremental backups with the reliability of full restores.

## Why Ceph RBD over traditional file-based approaches

Our storage architecture leverages Ceph's RADOS Block Device (RBD) feature rather than CephFS for container storage. This choice provides several advantages:

* **Simplified data management**: Working with block devices means handling "bags of bytes" rather than complex file systems
* **Better performance**: Block-level operations eliminate file system overhead
* **Seamless failover**: Containers can migrate across our VM grid without complex file system considerations
* **Snapshot efficiency**: RBD snapshots are instant and space-efficient

While a file-based approach like `rsync` might seem intuitive—comparing file lists and transferring only changed files—it doesn't align with our block-level storage philosophy.

## The Ceph RBD export-diff solution

Ceph provides an elegant solution through [`rbd export-diff`](https://ceph.io/en/news/blog/2013/incremental-snapshots-with-rbd/), which extracts only the changes between two snapshots at the block level. This feature becomes the foundation for our incremental backup strategy.

Here's how the basic process works:

1. Create a new RBD snapshot
2. Use `rbd export-diff` to identify changed blocks between snapshots
3. Export only the differential data

However, implementing production-ready backups requires additional considerations beyond the basic diff export.

## Building full restore capability from incremental data

To maintain the ability to perform complete volume restores from blob storage, we developed a chunked metadata system:

### Chunk-based storage architecture

* **4MB chunks**: Each volume is divided into 4MB blocks for optimal transfer and deduplication
* **Hash-based deduplication**: Chunk keys are generated from content hashes, eliminating duplicate data across the entire system
* **Project-level isolation**: Each project maintains its own chunk catalog to prevent cross-customer data leakage

### Metadata file structure

Each backup generates a metadata file containing:

* Complete list of chunks required for full volume restoration
* Chunk offsets and positions within the volume

This approach ensures that every backup point can restore a complete volume, even though we're only transferring changed data.

## The backup workflow in practice

Here's the complete backup process:

1. **Snapshot creation**: Generate a new RBD snapshot of the volume
2. **Differential analysis**: Run `rbd export-diff` between the current and previous snapshots
3. **Chunk processing**: Break the differential data into 4MB chunks and generate hashes
4. **Selective upload**: Upload only chunks that don't already exist in blob storage
5. **Metadata generation**: Create a new metadata file referencing all chunks (new and existing) required for full restoration

This workflow ensures that backup time scales with the amount of changed data rather than total volume size.

## Optimized restore performance

The hash-based chunk system also accelerates restoration:

1. **Local verification**: Before downloading chunks from blob storage, verify if they already exist locally by comparing hashes
2. **Selective download**: Only retrieve chunks that have changed or are missing locally
3. **Parallel processing**: Multiple chunks can be processed simultaneously

While restore operations still require reading the full volume to verify local chunks, the selective download significantly reduces network transfer time.

## Performance benefits and trade-offs

This architecture delivers substantial improvements:

* **Backup speed**: Scales with data change rate rather than volume size
* **Storage efficiency**: Deduplication reduces storage across all backups
* **Network optimization**: Minimal data transfer for routine backups
* **Restore flexibility**: Any backup point can restore a complete volume

The primary trade-off is complexity—managing chunk metadata and ensuring referential integrity requires more sophisticated backup orchestration than simple volume dumps.

Ceph can enable enterprise-grade backup performance without sacrificing restore capabilities. By leveraging block-level snapshots and implementing intelligent chunking strategies, you can achieve backup speeds that scale with your actual data change patterns.

Ready to experience high-performance, scalable container storage? [Start your free trial](https://upsun.com) and see how Upsun's infrastructure handles your most demanding applications.


# SSH certificates with Platform.sh
Source: https://developer.upsun.com/posts/how-it-works/how-do-you-manage-ssh-keys-in-your-organization

Learn how Platform.sh simplifies provisioning SSH certificates for secure and keyless SSH authentication, enhancing security and making compliance easier.

<PostMeta />

When it comes to secure shell (SSH) authentication, there is a widespread consensus that SSH certificates hold an edge
over SSH keys (though SSH keys are currently more widely used). SSH keys are easy to provision, but are hard to
distribute and invalidate. SSH certificates, on the other hand, are easier to use and audit, but harder to provision.
Happily, Platform.sh has made provisioning certificates easier for our users.

At Platform.sh, we use Secure Shell (SSH) certificates
[to authenticate users into their applications’ servers](https://platform.sh/blog/onboard-faster-stay-secure-with-keyless-ssh/). We rely on
a service named “Certifier” to provide the certificates. Certifier is, in essence, pretty simple:

* It exposes an endpoint with [the list of the certificate authority's public keys](https://ssh.api.platform.sh/ssh/authority).

* It exposes an endpoint that you can POST to with a public ssh key and then returns an SSH certificate that is valid
  for one hour.

The flow is mostly transparent thanks to some tricks in the `~/.ssh/config` file, such as:

```
Match host "*.platform.sh" exec "platform ssh-cert:load"
```

In this example, the `platform ssh-cert:load` command is fetching a new SSH certificate.

Effectively, this lets us provide a mostly transparent workflow. Our customers run their SSH commands, and Certifier
automatically grabs a new SSH certificate every time one is needed. Given that each certificate is only valid for one
hour, if a customer needs to offboard a user, we just need to ensure that Certifier is no longer delivering certificates
to that user.

Speaking of which, how does Certifier authenticate that user? It's obviously not just blindly returning SSH certificates
to whomever is asking for one. Certifier is relying on one of the most prominent authentication technologies on the web:
OAuth2.

When a Platform.sh customer logs in or tries to SSH, they’re effectively fetching an SSH certificate while passing along
an OAuth access token that they previously obtained from our [Authentication service](https://auth.api.platform.sh).
Certifier uses that token to get information about the customer from the OAuth token introspection
endpoint (`https://auth.api.platform.sh/oauth2/tokens`).

As an example, this is what the introspection endpoint can return:

```bash {filename="Terminal"} theme={null}
$ curl https://auth.api.platform.sh/oauth2/tokens/"$(platform auth:token)"
{
  "amr": [
	"sso",
	"mfa"
  ],
  "auth_time": 1601545043,
  "exp": 1601571772,
  "grant": "refresh_token",
  "iat": 1601570871,
  "iss": "https://auth.api.platform.sh",
  "jti": "<redacted>",
  "nbf": 1601570871,
  "ns": "platformsh",
  "sub": "<redacted>",
  "active": true,
  "scope": "offline_access",
  "client_id": "platform-cli",
  "grant_type": "refresh_token",
  "mfa_verified": 1601545043,
  "expires": 1601571772,
  "user_uuid": "<redacted>",
  "access_token": "<redacted>"
}
```

By using this endpoint, Certifier can put the following metadata in the SSH certificate before signing it:

* The Universally Unique Identifier (UUID) of the user
* Whether and when the user used Multi-Factor Authentication (MFA) when logging in

With all that said, with all this information available for any system, such as the edge layer accepting SSH connections,
Certifier can:

* Periodically fetch the certificate authority's certificates.
* Verify an SSH certificate coming in, trusting the metadata, such as the user's UUID, that is in the certificate.

In practice, we can put even more data on the certificates; that's what we're doing for the Platform.sh staff. For
example, when a Platformer connects with administrative privileges, the certificate embeds some information such as:

* The region for which the certificate was requested. If the edge layer is not on the given region, it can reject it.
* The support ticket for which the certificate was requested. The edge layer can then log it to have thorough auditing.

Essentially, using short-lived SSH certificates with Certifier gives Platform.sh customers the best of all worlds:

* There's no need to maintain any certificate revocation lists.
* There's no need to rely on users rotating their credentials.
* You can use your usual Single Sign On-based OAuth servers for authentication.
* You can embed a ton of authentication/authorization related metadata.

Thanks to Certifier, Platform.sh customers can have transparent, secure, and keyless SSH connections using our
[Platform.sh CLI](https://github.com/platformsh/platformsh-cli). You can also mandate multi-factor authentication for
all of your projects. These are all things that will make your compliance officers happy. And we are all about making people happy.

(For additional information on using keys to authenticate users and devices, please read “[What is PKI?](https://www.ssh.com/pki/)”)


# How the Platform.sh PaaS works
Source: https://developer.upsun.com/posts/how-it-works/how-platform-paas-works

Discover how Platform.sh simplifies PaaS. Focus on your code; we manage the rest. Explore our second-generation PaaS for seamless application development.

<PostMeta />

<Note>
  In this post I will present, in very broad strokes, the workings of Platform.sh from a functional perspective. This will
  not be a discussion of the intricate technical details, but rather a high-level description to help you understand what
  is happening under the hood.

  – TLDR; Now go read the whole thing.
</Note>

## Platform.sh is a PaaS

Basically what this means, is that you, the user, only have to concern yourself with writing the application code. We
take care of all the rest. We automatically manage everything that is needed to deploy the application, and all of its
runtime dependencies. You need a database? We will deploy and configure it. And we will configure your app so it
connects to it, as well as the copies of it that are made for each git branch. The same goes for search engines, caches,
and the file system. We will configure the web server, we will configure the network. We take care of making sure
everything can be consistently backed up, restored, etc. If something crashes, we take care of healing it; it’s our job
to make sure your application’s infrastructure stays alive.

You take care of the code. That’s all. Batteries included. You don’t have to do any kind of sysadmin work. In order to
put your code intro production, you just git push it.

We do give you all the tools to see what’s happening and to control precisely everything. It’s not a black box. You can
ssh to the server. You can connect directly to the database and continue to use all the tools you are accustomed to. You
can also automate everything. We have a REST API, as well as a very convenient CLI (command line interface) tool.

## Platform.sh is a new kind of PaaS

You can call it a “second generation [PaaS](https://platform.sh/blog/paas/)”. In first generation PaaS systems, like
[Heroku](https://platform.sh/alternative-to-heroku/) (but basically all the others), the service would manage the application (and do the
same kind of magic, you push code and it puts it into production), and sometimes another service (like for Heroku a
PostgreSQL database), but everything else was still the responsibility of the user. If you want a search engine, or
another type of database, well you needed to get that from a third party, as an add-on.

They tried to make it as painless as possible, with integrated billing, and some help in injecting the configuration to
your application, so it would be a bit more seamless, but this of course makes it more expensive, and more importantly
much more complex (with many more possible failure scenarios, each different provider becomes a single point of failure

* SPOF - for the whole thing). Because first generation PaaS systems manage only a small part of the application, you
* are still left with many things you need to care of by yourself.

## Platform.sh manages everything it manages

In Platform.sh all the services you use are fully managed by the platform itself. This means that when you back up your
application, everything get backed up. Consistently. Simply speaking, Platform.sh is a more general form of the same
idea. This is why we always talk about “clusters”. When we deploy your application we build the different services the
application will need and tie them together into a cluster. A group of servers that are a “whole”. Some of these
services will be things like infrastructure elements, databases and such, but you can also deploy multiple applications
in the same cluster.

## Platform.sh supports multiple apps per cluster

If you have a website that runs on multiple APIs, each such service will be run as an independent server, but the whole
thing will be tied together into a single cluster to form a coherent entity. This is really nice for people that like
the “micro-service” style of architecture. With Platform.sh, we make it easy to manage a host of apps that work together.

## Platform.sh has a persistent file system

Most  [PaaS systems](https://platform.sh/blog/five-considerations-for-choosing-a-modern-paas/), if not all, impose a
unique constraint on developers. Their file system is either fully Read-Only, or are ephemeral. So basically you can not
write to disk, or simply can not be sure it is going to be there. The main file system in Platform.sh is read-only, but
we allow you to declare as many Read/Write directories as you would like. And the storage is managed. So when you back
up your system they also get backed-up. When you clone a cluster they also get cloned. This means you do not need to
hack your application to use something like S3 in order to have file uploads. Applications like Drupal, Magento,
Prestashop or Wordspress, for example, function unmodified.

## Platform.sh can clone a running cluster

This is probably the most useful, and most innovative feature we have to propose. Because Platform.sh manages everything
as a coherent entity, with some powerful black magic we can almost instantly take a snapshot of the application cluster,
duplicate it and create a new one, and push it to production. Because everything is managed, the new cluster will get
new URLs, and all the apps inside it will get configured to work with each other. This allows you to create development
or staging environments as you need those. You can develop using “feature branches” and for each feature have a fully
isolated environment, so you can rapidly validate just that feature. This also means that you never have bugs that only
appear on production, because you can test each branch with real content.

## What happens when you deploy an app

Deploying an app means simply pushing the source code to our git server. The git server that runs on Platform.sh is at
the same time “just a normal git repository” and a very smart piece of software. When you have pushed to it, it will try
to understand what it needs to do. But you can also explicitly tell it precisely what requirements your application has.

The only modification you need to do to your application is to tell it to load its configuration from the environment
(and we supply [all the examples you need](https://github.com/platformsh-templates)).

There are a couple of “dot files” in YAML format you can put at the root of your application that will describe its
dependencies. You can say for example “my app needs mysql as a database”, or “my app needs this or that other php
extension”, or you can say “my front web app depends on these three API apps”. If for example you need to build your app
a specific Node.js, Python or Ruby library (for example Less or Jekyll) you simply specify those in the YAML file. There
are many other aspects of the application you can control through this simple declarative style. You don’t write scripts,
you just tell Platform.sh what you need.

## Platform.sh is build oriented

This very smart git server on the other side is going to operate in five steps.

### Configuration validation

First the git server is going to inspect what you have sent it and see that it understands what it is supposed to do. If
for example you have a syntax error in a configuration file, it will simply refuse the push. The same with code where
there is a huge security risk that Platform.sh knows how to detect. This is a good thing; Because it means you can’t
break your production system that easily. Once the git server has validated the configuration and sees it can satisfy
the requirements, it will build the cluster.

The git server is smart. It can diff not only the code but also the infrastructure; Say you had a single MySQL database
in your cluster. And now you want two of those, maybe a PostrgreSQL and an Elastic Search instance. It will understand
what it needs to do in the next phase to make sure the topology of your cluster is modified to your new needs.

### Build

I already said the git server was smart… and it is a git server. So it will only build stuff that has changed. This is
one of the things that make Platform.sh so fast in deployment. Using Linux Containers, Platform.sh will now, in parallel,
build each server that had something that changed. If for example you pushed a Drupal Drush Makefile, or a PHP
composer.json file, it will know it needs to go search for the dependencies, and shuffle things around to create the
correct directory structure. If in your .platform.app.yaml file you also specified a “build hook”, you can now run
whatever scripts you wish.

It is important to note that at this point the cluster has not been created yet. So you should not try to connect to a
database or imagine anything was daemonized; This is just a build phase.

### Prepare slug

The result of the build phase will be a file system, of which we now create an archive. We put this in permanent storage.
So the next time push code, if a server did not change... well we can just use this one; It also means that if you want
to revert a deploy, it is basically instantaneous. Deterministic deployments are repeatable and reversible, after all.

### Deploy slugs and cluster

Now Platform.sh provisions of all the elements it needs to run your application cluster. It will mount each service in
its own container, configure the network so they can see each other (and only each other!) Here you need to remember
that the main file system is read-only. This is what guarantees the fact that we can do deterministic deployments.

It will also mount all of the read/write directories you specified. Again unlike other PaaS systems, Platform.sh gives
you persistent, normal, storage, it just needs to know which directories contain stuff that is mutable.

### Deploy hooks

A last step allows you to run a post-deploy script (you can use this for example to run an anonymization script for
deployment on development environments, clear caches, ping external CI tools, etc.) When this script runs you already
have access to a fully running application.

### Configure routing

If everything went fine, we are now ready to configure routing, so your web traffic will arrive at your newly created
cluster. If something failed, well then nothing would have happened; the “old cluster” is still there, so from your
users’ perspective, nothing changed. Neither failed nor successful deployments result in application downtime. Because
we also route SSH you can also simply SSH to your cluster where you have the same permissions to execute commands as
the web server.

## Post-Scriptum

This was not a detailed explanation. Platform.sh has many other bells and whistles, but I hope this gives you a general
idea on what is happening behind the scenes.

As a user, you don’t really need to know all of this; Most of the time for a relatively simple app, you would just push
the code, and it would run. You would click on “branch” and it will create a new development cluster. It is our job to
try to absorb all the tedious complexities. You do features, we run the infrastructure.

But as you can understand, because Platform.sh uses standard tools (git), exposes a rich API and has a very cool CLI,
you can integrate it in more complex workflows. You could for example use the Github integration, or webhooks, to make
it work with an existing workflow or CI system like Jenkins or Travis. You could dynamically configure access rights and
per-environment routing rules; but most of the time, you’d just push code and not care about all of this.


# Semper vigilans: how Platform.sh stays ahead of emerging cybersecurity threats (so you don’t have to)
Source: https://developer.upsun.com/posts/how-it-works/how-platformsh-stays-ahead-of-emerging-cybersecurity-threats

Always vigilant is more than a motto. Find out how the Platform.sh Security team monitors vulnerabilities 24x7 to protect customers from cybersecurity threats.

<PostMeta />

October is Cybersecurity Awareness month. So, we’ve asked Diogo Sousa, Platform.sh Security team manager to share how
his team contributes to helping customers protect their websites and applications from external threats, 24x7.

***

Part of the Platform.sh Security team’s day-to-day work is to monitor for any vulnerabilities that might impact our
customers. We do this by combining information from various sources—including CVE feeds, blogs, social media
accounts—then evaluate if any of these vulnerabilities are capable of affecting our infrastructure and the services we
provide. Because Platform.sh offers a depth and breadth of [languages and frameworks](https://platform.sh/marketplace/),
we might be analyzing advisories for Golang in the morning, Drupal in the afternoon, and Linux kernel bugs in the
evening. In 2022 alone, the Security team reviewed and advised on more than 300 CVEs across a dozen technologies.

These past weeks of autumn have brought a bountiful crop of high-profile vulnerabilities in popular libraries and tools:
libwebp (CVE-2023-4863), libvpx (CVE-2023-5217), glibc (CVE-2023-4911), HTTP/2 (CVE-2023-44487) and, culminating with a
big one, libcurl (CVE-2023-38545).

**To avoid burying the lede, here’s our current situation:**

We’ve made updated versions of all the library CVEs noted above, accessible to Platform.sh customers via a
[redeploy](https://docs.platform.sh/development/troubleshoot.html#force-a-redeploy). The HTTP/2 issue has been mitigated
at our edge layer.

Our service continues to operate securely.

### **So, what exactly are these vulnerabilities?**

#### **libwebp**

Let’s start with libwebp. As the name suggests, it’s a library used to process images in the WebP format,
[developed by Google for a faster web experience](https://developers.google.com/speed/webp). Faster load times, no loss
of quality, smaller file sizes through better compression—all benefits realized by using the webp format. However, I’m
certainly not alone in saying that it’s a slight annoyance when right-clicking an image to expect a transparent PNG, but
getting a .webp file back.

WebP can compress files without any loss of quality, and it’s in that compression that this vulnerability was discovered.

To achieve the compression, WebP uses a method called [Huffman coding](https://en.wikipedia.org/wiki/Huffman_coding). A
Huffman code is generated from the image and used to efficiently store information on a special table data structure,
producing a smaller file with no loss of quality, something very important for images on the web. We’ve all seen a JPEG
full of compression artifacts, and it isn’t pretty.

It was found that by using a specially crafted image file, you could bypass a size check and trigger a heap overflow
that you could, then, chain into other attacks. This payload, a singular image, made for an interesting delivery
mechanism: if your web application didn’t accept and process webp files, delivering a malicious payload was pretty much
blocked. *But* if your application merely displayed the webp image, like a browser or a messaging app, then visiting a
website or receiving a file would be enough to trigger it.

Fortunately, creating those files required a high degree of sophistication. They had to represent a valid encoding, with
enough additional data hidden to deliver a payload. And that limited the exploitation until patches were made available.
Vendors like Apple and Google promptly made the patches available to users once the issue became known. (Hope everyone
has the good habit of always keeping your OS and browser up to date.)

#### **HTTP/2: Rapid Reset**

The HTTP/2 vulnerability, named Rapid Reset, is interesting as it’s a part of the HTTP/2 protocol itself. In essence,
it wasn’t added to the code via a faulty commit; it’s baked in.

HTTP/2 allows for multiple data streams when accessing data, increasing the capability of the connection by prioritizing
what gets retrieved. One of those optimizations is the ability for the client to cancel an ongoing stream, similar to
saying to the server that it doesn’t need to send over every image on the page because they’re now outside the viewport.
This is an inexpensive process for the client, which can move on to other requests; it’s up to the server to honor that
cancellation and keep an accurate tally of requests to process, and that’s where the issue lies.

Keeping accurate counts of what requests are in what state and are still needed to be processed is important to avoid
getting overwhelmed by requests. The protocol sets a number for the maximum number of concurrent streams, but only
streams in certain stages of their lifecycle count against this number. The Rapid Reset attack takes advantage of this
by creating a backlog of reset streams that need to be cleaned up by the server. And since they’re not in one of the
lifecycle states that counts against the limit, this backlog can grow very quickly, leading to a DoS. With HTTP/2 being
common fare—and the attack having a very low complexity—it makes for an ample choice of targets and has already broken
some [infamous records](https://blog.cloudflare.com/zero-day-rapid-reset-http2-record-breaking-ddos-attack/).

Now, to our main course, libcurl.

#### **libcurl**

The issue in libcurl should be familiar to anyone who’s written C code. When connecting to a SOCKS5 proxy, it was
possible that the buffer allocated for the hostname was too small and, under specific circumstances, it could be
overwritten into a heap overflow.

Noticing a pattern here? As with libwebp, this vulnerability’s impact is limited by its requirements: if using version
8.x, the user needs to purposely override the default configuration (which is safe) to use a lower value for the limit
rate. By itself, this vulnerability causes a crash. To leverage it for further compromise, the user must use unsafe
options, like forcing cURL to follow redirects (-L), so a payload can be delivered
([example](https://blog.aquasec.com/new-vulnerability-in-curl-and-libcurl-could-lead-to-heap-buffer-overflow)). If
you’re not in the habit of connecting to unknown (potentially malicious) servers, this should have little to no impact
on your usage.

The biggest vulnerability issue here? libcurl is used
[by a vast number of companies](https://curl.se/docs/companies.html); it’s not an easy task (particularly if you’re
doing it on your own) to ensure that all these products, which you may be using directly or indirectly, are using safe
configurations.

### **Next steps: what you can do**

If you’re a Platform.sh customer, our teams have already overseen the patching and rollout of the updated versions I’ve
just discussed. After evaluating the vulnerabilities’ impact and manner of operation, we decided against forcing a
redeployment, leaving it for each customer to schedule and minimize the disruption to their workflows. When clear
indicators of active exploitation happen, our customers can rest assured we’ll force an update to keep their projects
safe.

To ensure your project remains protected, all you need to do is redeploy. That will trigger an automated check for any
changes, and your project will update itself to the latest version with all the necessary patches. We know it’s Friday,
but you don’t need to worry: Deploy Friday is our mantra for a reason.

If you’re not currently a Platform.sh customer, vendors have made patches available, together with some recommendations
about how to mitigate the impact of these vulnerabilities.

**libwebp**\
[https://blog.isosceles.com/the-webp-0day/](https://blog.isosceles.com/the-webp-0day/)\
[https://github.com/advisories/GHSA-j7hp-h8jx-5ppr](https://github.com/advisories/GHSA-j7hp-h8jx-5ppr)

**HTTP/2**\
[https://blog.cloudflare.com/technical-breakdown-http2-rapid-reset-ddos-attack/](https://blog.cloudflare.com/technical-breakdown-http2-rapid-reset-ddos-attack/)\
[https://www.nginx.com/blog/http-2-rapid-reset-attack-impacting-f5-nginx-products/](https://www.nginx.com/blog/http-2-rapid-reset-attack-impacting-f5-nginx-products/)

**libcurl**\
[https://curl.se/docs/CVE-2023-38545.html](https://curl.se/docs/CVE-2023-38545.html)

Finally, if you’re looking for a fully managed PaaS, including security and compliance, we hope you’ll
[give Platform.sh a try](https://auth.api.platform.sh/register?trial_type=general&_utm_medium=Email&_utm_campaign=2022-09-newsletter&_utm_source=devrelcareers).


# How redundancy and failover work on Upsun
Source: https://developer.upsun.com/posts/how-it-works/how-redundancy-and-failover-work-on-upsun

Upsun handles redundancy and failover inside your region, at the compute, storage, and network layers. Here's where it happens, how fast it is, and the trade-offs behind it.

<PostMeta />

Have you ever wondered what happens to your project when a virtual machine somewhere in the fleet quietly dies at 3am? You're not alone, and the answer is more interesting than "we have backups".

Redundancy and failover are easy to wave at and hard to pin down. Where does it actually happen? How fast is it? And what doesn't it cover? Here's how we think about it on Upsun, and the trade-offs we picked on purpose.

## The region is the boundary

When you host a project on Upsun, the first thing you pick is a [region](/docs/development/regions). A region is a specific cloud provider in a specific place: Stockholm, Sweden on AWS (`eu-5`), say, or one closer to your users on a different provider. Once you've chosen, everything we do for that project, all the redundancy and all the failover, happens inside that region.

To be clear up front: we don't do automated failover across regions. There's one exception, and it's the kind you hope never to need. If a data center physically goes down, a fire being the dramatic example, we can fall back to disaster recovery and [migrate your data](/docs/projects/region-migration) elsewhere. That's a manual, exceptional process, not part of a normal day.

The reason is data gravity. We host all of your data in your region: files, databases, sessions, every cache entry. Moving all of that between regions while keeping it consistent isn't something you do quickly or casually, and we've chosen not to pretend otherwise. Every failover guarantee we make lives inside one region.

## Three redundant layers in every region

That boundary doesn't leave you with a single point of failure. Within a region, redundancy is built into the infrastructure, a layer below your database or your app. It shows up in three places: storage, compute, and the network.

Storage is backed by [Ceph](/posts/how-it-works/why-upsun-moved-from-lvm-to-ceph). Every volume is replicated several times across different virtual machines in the region. Lose one machine and your data is still sitting on the others. The redundancy is at the volume level, underneath whatever happens to write to it.

Compute is a grid of virtual machines. Each one can host containers: your apps, your databases, your caches. Every service in your project runs as a container on one of those machines, and with that many machines available, there's always somewhere healthy to land.

The network sits in front of all of it. Traffic from the internet comes in through an incoming gateway, and traffic heading out leaves through an outgoing gateway, which is how we manage and shape it. Those gateways are several machines rather than one, and they hold no state, which keeps them straightforward to scale and redundant by default.

### What happens when a machine fails

Here's why those layers matter. At our scale, thousands of virtual machines across dozens of locations, machines fail every single day. The cloud is less stable than it looks from the outside.

When one goes, the layer it belonged to absorbs it. A storage machine: Ceph handles the failover for you, and it's close to invisible apart from a brief performance dip. A compute machine: your container moves to a healthy one, usually within a minute or 2. A gateway machine: the others carry the traffic, because nothing stateful was tied to it. None of these are events you normally have to think about.

## Stateless apps scale flat

With the infrastructure covered, the interesting question is how each thing you run sits on top of it. That mostly comes down to one property: whether it holds state.

An application is a container with compute and a disk, but the difference from a database is what's on that disk. A lot of applications are stateless, and stateless is where the options open up. When nothing important lives on the local disk, you can run several copies at once. On Upsun you choose to [scale horizontally](/docs/manage-resources/scaling): 2 instances with 2 CPUs each behaves a lot like 1 instance with 4 CPUs, except now you also have redundancy. If one instance falls over, the others keep serving. That's the usual recommendation for stateless apps.

It's also why the gateways scale so cleanly. Once a thing holds no state, you stop caring which copy handles a request, and failure stops being scary.

## A database runs as a single instance

A database is a container with compute and a Ceph volume too, and it leans on the redundancy of both. What it doesn't get by default is replication. You get one MariaDB. We don't quietly run 3 copies of it behind the scenes.

That's a deliberate choice, from experience rather than laziness. We run a separate, dedicated product that does keep triple redundancy at the database level, and managing it is a different world of overhead. For most projects, the cost and risk of that setup outweigh the reward. A single database sitting on storage-level redundancy is the saner default. Real database redundancy means replication, and replication is a different kind of complicated: run 2 databases with different data on each disk and you don't have redundancy, you have 2 different databases.

That's a default, not a wall. If you want more, you can add read-only replicas. A read replica is effectively stateless: its data is a copy you can throw away and rebuild, so you can add or remove replicas without much ceremony. That makes them horizontally scalable the same way a stateless app is. Both [MariaDB](/docs/add-services/mysql/mysql-readonly-replication) and [PostgreSQL](/docs/add-services/postgresql/postgresql-readonly-replication) support them.

## Where this leaves you

One rule sits under most of this. Redundancy lives at the compute, storage, and network layers, where it covers everything you run. Stateless things, apps, read replicas, gateways, scale horizontally and gain redundancy that way. Stateful services run as a single instance on top of redundant infrastructure, because horizontally scaling them buys more complexity than most projects want.

There's a whole category of tooling that goes further. Database-as-a-service systems like Vitess do transparent sharding and automated horizontal scaling at the database layer, and that's a real capability. Most applications don't need it. You can run a database with hundreds of gigabytes of memory on Upsun and do a great deal before any of that becomes your bottleneck. So we made a deliberate choice: a single stateful instance on redundant infrastructure, rather than transparent sharding and live multi-primary replication. We picked it because it stays predictable and easy to reason about, and it scales far enough for the overwhelming majority of workloads, without the operational complexity and failure modes that sharding and live replication bring. That's the trade-off, and naming it is the point, so you can decide whether it fits what you're building.

And if you do hit that ceiling, the answer is often architectural rather than a managed sharding layer. A large international application that has to live in many places and share data across them can be designed differently: deploy it many times, scoped to where its data and its users are, and shard at the application level. That's the thinking behind [natural scaling for multi-country ecommerce](/posts/how-it-works/natural-scaling-for-multi-country-ecommerce). A big database doesn't mean you're out of options. It means the options live in your architecture rather than in an automatic feature, and whether that trade is worth it is an organizational call as much as a technical one.


# How SSH authentication works on Upsun Cloud
Source: https://developer.upsun.com/posts/how-it-works/how-ssh-authentication-works-on-upsun

Decode the SSH certificate the Upsun CLI provisions for you, then follow it through the SSH proxy: CA trust, revocation, access documents, and MFA.

<PostMeta />

You run `upsun ssh`, and a second later you have a shell inside your production container. You never uploaded a public key. The container has no `authorized_keys` file with your name in it. What let you in?

The answer is an SSH certificate. A few years ago we wrote about [how Platform.sh provisions these certificates](/posts/how-it-works/how-do-you-manage-ssh-keys-in-your-organization): the CLI generates a key pair, sends the public key to a service called Certifier, and gets back a certificate that your SSH client presents automatically. That article covered how the certificate is issued. This one covers the other side: what's inside the certificate, and what the platform does with it when you connect.

## Read your own certificate

The certificate sits in your CLI session directory, and `ssh-keygen` decodes it:

```bash theme={null}
  ssh-keygen -Lf ~/.upsun-cli/.session/sess-cli-default/ssh/id_ed25519-cert.pub
```

```text theme={null}
  Type: ssh-ed25519-cert-v01@openssh.com user certificate
  Public key: ED25519-CERT SHA256:8gtQqi3ELr/wNfavLc5I/7MUgJM54MsPGaJs8EyGaz0
  Signing CA: ECDSA SHA256:DA8PPrXsISAIChUTRieBTFbQ8ZkC3UwRlULKLKvuUsg
  Key ID: "24e0bd07-b176-466f-8ffb-1503d0e79b03"
  Serial: 0
  Valid: from 2026-07-27T12:04:18 to 2026-07-27T12:19:21
  Principals: (none)
  Critical Options: (none)
  Extensions:
          access-id@platform.sh UNKNOWN OPTION (len 47)
          access@platform.sh UNKNOWN OPTION (len 158)
          has-mfa@platform.sh
          permit-X11-forwarding
          permit-agent-forwarding
          permit-port-forwarding
          permit-pty
          permit-user-rc
          token-claims@platform.sh UNKNOWN OPTION (len 180)
          token-id@platform.sh UNKNOWN OPTION (len 30)
```

Two things stand out before you even look at the extensions. The `Key ID` is your user ID, the same UUID the API knows you by. And the validity window is about 15 minutes. This certificate expires before your coffee gets cold, and the CLI transparently requests a new one when it does. That short lifetime is the first layer of security: a stolen certificate is a paperweight within minutes.

## The extensions carry your permissions

The `permit-*` entries are standard OpenSSH extensions. The `@platform.sh` ones are ours, and they turn the certificate from an identity document into an authorization document.

One of them is a flag: `has-mfa@platform.sh` says your session was authenticated with multi-factor authentication. Its presence alone is the signal; it carries no value.

The rest are data. `access@platform.sh` embeds a permission map, a JSON document describing what your session can touch, resource by resource:

```json theme={null}
  {
    "organizations": {
      "01h9zbmrrpe6vjy5c1zk9y4dxq": ["view", "members:list"]
    },
    "projects": {
      "abcdefgh1234567": ["admin"],
      "org=01h9zbmrrpe6vjy5c1zk9y4dxq": ["view"]
    }
  }
```

We call this an access document. The keys are selectors: a bare value matches a resource ID, and `org=` matches every resource in an organization. Read this one out loud and it's a user profile: member of one organization, admin on one project, view access on every other project the organization owns. Selectors can even carry auth requirements, so `abcdefgh1234567&amr=mfa` grants its permissions only to MFA-verified sessions.

`access-id@platform.sh` is an identifier for the same document server-side, which matters later. `token-id@platform.sh` names the OAuth 2 token your session is built on. And `token-claims@platform.sh` embeds claims from that token:

```json theme={null}
  {
    "auth_time": 1785142522,
    "amr": ["sso", "mfa", "sso:google"],
    "grant": "refresh_token",
    "scp": ["offline_access"]
  }
```

If you've worked with OpenID Connect, `amr` and `auth_time` look familiar: how you authenticated, and when. The certificate is, in effect, a signed snapshot of your auth session that any SSH server can verify offline.

## What happens when you connect

You never reach your container directly. Every SSH connection lands on a proxy at the edge of the region, and that proxy is where the certificate gets taken apart.

The first check is trust. The proxy keeps a registry of certificate authority fingerprints, refreshed on a schedule from the same [authority endpoint](https://ssh.api.platform.sh/ssh/authority) your SSH client can query. If your certificate wasn't signed by one of those CAs, it's treated as a plain SSH key, and [uploaded SSH keys](/docs/development/ssh/ssh-keys) follow a separate, more restricted path.

Next come the critical options. Your certificate above has none, but certificates can carry options that pin them to specific regions or hosts. A certificate scoped to `eu-5` is rejected everywhere else, no matter how valid its signature is.

Then the proxy asks a question the certificate can't answer on its own: is the token behind it still alive? The `token-id@platform.sh` extension gets checked against a revocation list. Log out of the CLI, or have your session revoked by an organization owner, and every certificate minted from that token dies with it, even inside its 15-minute window. The check fails closed: if the revocation service can't be reached, the connection is denied rather than waved through on stale claims.

## The access check

With trust established, the proxy decides whether you can reach this specific environment. It prefers a fresh copy of your access document, fetched by the `access-id@platform.sh` identifier, and falls back to the copy embedded in the certificate. Either way, the document gets evaluated against the route you're connecting to: the project, the environment type, and the permission SSH requires there.

If the token was revoked, the embedded claims aren't trusted at all. The proxy queries the auth service in real time with your user ID, and strips the authentication methods from the result, which forces a fresh login for anything that requires one.

One more gate remains: MFA. Organizations can [require MFA](/docs/administration/security/mfa) for SSH access to their projects. The proxy compares that requirement against the `has-mfa@platform.sh` flag. When the flag is missing and the route demands it, you get a banner instead of a shell:

```text theme={null}
  Error: Access denied
  Service: abcdefgh1234567-main-bvxea6i--app
  User: 24e0bd07-b176-466f-8ffb-1503d0e79b03
  Parameters: {"amr":["mfa"]}
  Detail: Additional authentication is required:
           - Multi-factor authentication (MFA)
```

The `Parameters` line isn't decoration. The CLI parses it, walks you through the additional authentication, and retries.

## The last hop

Your connection still has one more leg: from the proxy to the container. Your certificate doesn't travel there, and neither does your key. Instead, the proxy signs a new certificate with its own upstream key, valid for 2 minutes, carrying your user ID, your client IP, and your access document trimmed down to what this route needs. That's how the container knows who you are without ever seeing your credentials.

The trimming matters. Connect to `abcdefgh1234567` with the document above, and the container learns one thing: you're an admin on this project. What else you can see in your organization is none of its business, so it never arrives.

## The takeaway

Every `upsun ssh` runs through this pipeline: a 15-minute certificate proves who you are, a CA registry proves who vouched for you, a revocation check proves your session still exists, an access document proves you belong on this route, and an MFA flag proves how strongly you authenticated. The claims are signed into the certificate, which is what lets the proxy trust them without re-deriving your identity on every connection. The round trips that remain, the revocation check and the fresh access document, exist for the one thing a signed snapshot can't tell you: what changed after it was signed.

That's the trade `authorized_keys` never offered. A key file says one thing: this key may connect, forever, until someone remembers to delete the line. A certificate says who you are, what you may touch, how you logged in, and when the claim stops being true. Revoking access is one API call, not a fleet-wide file edit.

The same trade shows up in audits. SOC 2 and PCI DSS reviews ask the questions this pipeline answers mechanically: who can reach production, how they authenticated, and how fast access dies when someone leaves. On Upsun those answers hold on every connection, because the platform enforces them rather than a policy document: SSH credentials expire in minutes, revocation is central, and MFA is checked at the door. Certificate-based SSH is one control among the [security and compliance](/docs/security) measures you inherit by deploying on the platform, and the certifications behind them are in the [Trust Center](https://upsun.com/trust-center/).

And none of it needed a proprietary protocol. This is how a modern platform does SSH in a regulated environment: a public key infrastructure, with a certificate authority that signs short-lived identities and every hop validating them on its own.

That shape is what makes it safe to run at scale. Trust is central, but enforcement is decentralized: nothing has to be pushed to the machines you connect to, so there is no fleet of `authorized_keys` files to keep in sync and no container holding a credential that outlives your session. And each hop stays isolated, because it only ever receives the claims it needs. A container that gets compromised learns your role on that one project, not the shape of your organization.

Stock OpenSSH certificates, extended through the fields the format reserves for custom data, decoded by the same `ssh-keygen` you've used for years. If you're building something similar, the format leaves you the same room it left us.


# How to host a website that isn't publicly reachable
Source: https://developer.upsun.com/posts/how-it-works/how-to-host-a-website-that-isnt-publicly-reachable

Some applications should never answer a request from the open internet. Here are the ways to make one unreachable on Upsun, and how to pick between them.

<PostMeta />

Most of the effort around a website goes into making it reachable. Sometimes the requirement is the opposite one: the application has to run, be deployed, be maintained, and answer nobody who finds its address from the outside.

That comes up more often than it sounds. An internal admin panel or back office has no reason to accept traffic from anywhere but the office network. An origin behind a CDN should answer the CDN and nothing else, otherwise anyone who learns the origin address walks around the edge rules you pay for. A B2B API whose only clients are three partner systems doesn't need a public front door. Neither does a webhook receiver that only ever hears from one SaaS provider, a headless CMS backend that only a build job queries, a preview environment for a product that hasn't launched, an internal metrics dashboard, or a system under a compliance regime where public exposure is a finding on its own.

All of the mechanisms below exist on Upsun. They fall into two families, and picking the family is most of the decision.

## First, the constraint

Upsun is a cloud platform. Applications run on shared infrastructure in a public cloud region, which is what makes it affordable. Dedicated and on-premise setups exist, and they solve a different problem, but they carry the price of not sharing anything with anybody. For most teams that price is out of proportion to the actual requirement.

The requirement is almost never "run this on hardware nobody else touches". It's "make sure no unauthorized request reaches this application". Those are different problems, and the second one is solved by controlling reachability, not by owning the machine.

## Family one: a public route with a locked door

The common case keeps the route. A CDN needs an origin to pull from, a partner integration can't join your VPN, and somebody has to open the admin panel in a browser. The application stays addressable, and every request has to prove something before the router passes it through.

### Mutual TLS

[mTLS](/docs/routes/https#enable-mtls) turns the usual TLS handshake around. The server proves its identity to the client as always, and the client also presents a certificate that the server validates against a certificate authority you decide on:

```yaml title=".upsun/config.yaml" theme={null}
  routes:
    "https://{default}/":
      type: upstream
      upstream: "app:http"
      tls:
        client_authentication: "require"
        client_certificate_authorities:
          - !include
            type: string
            path: root-ca.crt
```

Requests without a valid client certificate are rejected at the router and never reach the application. Requests that pass arrive with `X-Client-Verify` and `X-Client-Cert` headers, so the application can log which client it was talking to or authorize per client on top.

The reason to reach for this over a shared secret is rotation. Plenty of organizations require credentials to be rotated on a schedule, and a shared secret in a header means coordinating both ends every time. With mTLS the rotating part is the client certificate, which the client rotates on its own, while the server side holds a CA certificate that contains a public key and no secret. Root CA certificates are commonly issued with lifetimes of 10 to 20 years, and public trust store roots sit at the top of that range. The part that rotates stays on the client side, and the route configuration goes untouched for years.

### A shared secret in a header

The simplest version of the locked door is a value the client has to send. Upsun's [HTTP access control](/docs/environments/http-access-control) implements this as HTTP basic authentication for a whole environment:

```bash theme={null}
  upsun environment:http-access -e main --auth ops:s3cret
```

Requests without the credentials get a 401 from the router. One detail matters if the application does its own token checking: on routes protected by HTTP access control, [the `Authorization` header is removed](/docs/development/headers) before the request reaches the application, because Upsun consumes those credentials itself. Application-level tokens belong in a header of your own, checked in application code.

That variant, a header the application requires and every other request rejected, is what most CDN setups use. Fastly or Cloudflare adds a secret header at the edge, the origin refuses anything without it, and the origin address stops being interesting to anyone who discovers it.

It works well and it has the rotation problem described above. Treat it as the pragmatic option, not the strong one, and prefer mTLS wherever the client can be made to hold a certificate.

### An IP allowlist

If the caller has a static, dedicated address, allow that address and deny the rest. [HTTP access control](/docs/environments/http-access-control#filter-ip-addresses) does this too:

```txt theme={null}
  198.51.100.0 allow
  0.0.0.0/0 deny
```

Two conditions decide whether this is worth anything. The address has to be static, or the allowlist becomes an on-call task. And it has to be dedicated, because an address shared with other tenants of some provider allows every one of those tenants along with your caller.

Note that basic authentication and IP filtering are alternatives in this setting, not layers. If both are configured, a request with valid credentials passes from any address at all.

## Family two: no public route at all

The stronger option, where the clients allow it, is an application the router never sends anything to. Nothing listens on the internet, so there's no endpoint to scan and no login page to brute-force. Access happens over a channel you set up yourself.

Start by making sure there's no route. This is the step people get wrong, because [omitting the `routes` key entirely gives you the default route](/docs/routes#default-route-definition), which sends all traffic to your app. To have no public entry point, define the key with nothing pointing at the application:

```yaml title=".upsun/config.yaml" theme={null}
  routes: {}
```

Everything else keeps working. The application builds and deploys, [cron jobs](/docs/configure-apps/image-properties/crons) run, [SSH](/docs/development/ssh) works, and logs flow. The only thing missing is the public path in.

Then pick how you get in.

### A VPN

Put the container on a private network and reach it from devices already on that network. [Tailscale on Upsun](/posts/hands-on/run-tailscale-on-upsun-secure-vpn-connections) covers the setup, including the part that trips people up: Upsun containers can't create a `tun` device, so Tailscale runs in userspace networking mode. That post uses the outbound direction, where the application reaches endpoints inside the tailnet. Exposing the application to the tailnet is the mirror image of it, with `tailscale serve` publishing the local port to the network instead.

The container dials out to join the tailnet. Nothing has to reach in for the connection to exist.

This is the option to reach for when the audience is people rather than machines. Access follows the identity and device policy you already run in the VPN, and revoking someone there revokes their access to the application at the same time.

### A tunnel

A VPN gives every device on the network a path to the application. A tunnel gives one process a path, which is less to keep track of.

[Chisel](/posts/hands-on/connect-multiple-projects-applications-or-services-together) carries TCP over HTTP, and the post above uses it to connect services across Upsun projects. Running over HTTP is what makes it convenient: the traffic looks like ordinary web traffic and travels wherever web traffic is allowed.

For a human at a terminal, the Upsun CLI already does this. [`upsun tunnel:open`](/docs/development/ssh#use-a-direct-tunnel) opens SSH tunnels to the services in an environment and prints local addresses to connect to, and `upsun ssh -L` forwards a local port to the application itself. Nothing to configure and nothing to deploy, which makes it the right answer for occasional access by someone who already has SSH access to the project.

The same commands work unattended. Add a dedicated account to the project with only the access it needs, give it an [API token](/cli/api-tokens), and a backup job or a reporting script opens the tunnel, does its work, and closes it. The token is a credential on a rotation schedule, which is the cost of this option, and the account is one you can revoke on its own without touching anyone else's access.

The tradeoff across this family is the same one. Removing the public route also removes the browser as a client. Anyone who needs the application has to be on the network or hold the tunnel open first, and that's a real cost for a tool used daily by non-technical colleagues.

## Layers, and how many are too many

Defense in depth is the reason to combine any of this: when one control fails, another one is still standing. The useful version has each layer covering a distinct failure, and the wasteful version stacks two controls against the same one.

An application on the VPN with no public route, plus an IP allowlist, plus a token, is the wasteful version. There's no public route for the allowlist to filter and no unauthenticated caller for the token to stop. What it adds is configuration to maintain and a way to lock yourself out during an incident.

Layers that pull in different directions are worth having. A CDN with a WAF in front handles volume and known attack patterns; mTLS at the origin handles anyone who bypasses the CDN; authorization inside the application handles an authenticated client asking for data belonging to a different client. Each of those catches something the others don't.

## Choosing

These options overlap more than the section headings suggest. A CDN origin can be locked with mTLS, with a shared secret header, with an IP allowlist, or with none of those and a tunnel between the CDN and the origin instead. Teams have shipped all four.

What usually decides it is who the client is and what it can be made to do. A client you control can hold a certificate. A partner integration written five years ago might only manage an extra header. People with browsers find tunnels tiring and a VPN they already use invisible, while a nightly job is the other way around. An IP allowlist needs a caller whose address is static and yours alone, which rules it out more often than expected.

The rotation question is worth asking early, because it's the one that gets expensive later. Where credentials have to rotate on a schedule, an option that keeps the rotating part on the client side costs less over the years than one that needs both ends changed together.

None of this is unusual infrastructure. It's a route definition, an access rule, or a process that dials out, and all of it lives in the project configuration and gets reviewed like any other change. Pick the wrong one and you edit the file and redeploy.


# How Upsun built stateless mesh networking for high-density containers
Source: https://developer.upsun.com/posts/how-it-works/how-upsun-built-stateless-mesh-networking-for-high-density-containers

Discover how Upsun's innovative stateless mesh networking architecture handles thousands of containers without databases or bottlenecks.

<PostMeta />

When you deploy across the Upsun grid with our distributed infrastructure -
capable of running tens of thousands of containers simultaneously -
networking becomes one of your biggest challenges. The grid consists
of three key components: orchestration machines that manage
deployments, compute nodes where your application containers run, and
a regional storage cluster that houses all project data including
files and databases.

At this scale, traditional networking approaches start to break down. Containers are created and destroyed constantly, often moving between hosts for efficiency or availability. Centralized systems quickly become bottlenecks or single points of failure, increasing the risk of unavoidable downtime.

To solve this, we built a stateless mesh networking system that embeds
routing information directly into IP addresses, eliminating the need
for databases while supporting up to 8,192 containers per VM across
the entire grid.

## The high-density challenge

Upsun's infrastructure operates at high density by design. Your
preview environments, production deployments, and service containers
all share the same network space for maximum efficiency. This creates
a complex networking scenario:

* Containers constantly appear and disappear as you push code
* Preview environments are created and destroyed dynamically
* Containers move between VMs for capacity planning and load balancing
* Maintenance rollovers relocate workloads during infrastructure upgrades
* Incident response triggers automatic failover to healthy nodes
* Service discovery must work instantly across the entire grid

Traditional networking approaches break down in this environment. A
central router holding all routes would create an obvious bottleneck
and single point of failure. You need direct VM-to-VM routing: a mesh
network.

## Why we built our own solution

Most mesh networking solutions rely on external databases or control
planes to track container locations. This approach introduces latency,
complexity, and potential failure points. We asked ourselves: what if
we could make routing completely stateless?

The answer came from an unexpected source: [IPv6's concept of
IPv4-mapped
addresses](https://datatracker.ietf.org/doc/html/rfc4291#section-2.5.5.2),
where IPv4 addresses get embedded within IPv6 space. We realized we
could embed VM addresses directly into container IP addresses.

## The magic of address mapping

Here's how our stateless routing works. Consider these network ranges:

* Physical network: `192.168.0.0/16`
* Overlay network: `10.0.0.0/8`

When a container gets the overlay IP 10.**16.32**.91, our system can instantly determine:

* The VM's physical IP is 192.168.**16.32** (extracted from the overlay address)
* This is the 90th container on that VM (the first IP of the subnet is for the VM itself)

No database lookups. No external queries. The routing information lives in the address itself.

```
Overlay IP:         10 . 16 . 32 . 91
                       |         |
                       |  VM IP  |  Container # + 1
                       |         |
Physical VM IP: 192.168. 16 . 32
```

## The technical implementation

When a packet needs routing between VMs, our custom
[ARP](https://man7.org/linux/man-pages/man7/arp.7.html) daemon:

* Extracts the target VM's IP from the destination overlay address
* Establishes a GRE tunnel to that VM if one doesn't exist
* Forwards the encapsulated packet directly

This happens using
[rnetlink](https://man7.org/linux/man-pages/man7/rtnetlink.7.html) to
define network neighbors, creating direct point-to-point connections
between VMs without routing through central infrastructure.

## Scaling beyond standard private networks

Initially, we considered using the standard `10.0.0.0/8` private network
for our overlay. But this only provides 256 addresses per
VM—insufficient for high-density deployments.

We found a creative solution in `240.0.0.0/4`, the "reserved for future
use" IPv4 space that became available when IPv6 development made it
redundant. This gives us:

* 4 bits for subnet identification
* 16 bits for physical IP mapping
* 12 bits for container addresses (8,192 per VM)

This addressing scheme provides massive scalability while maintaining
the stateless routing benefits.

[If you are the type of person that would love the challenge of moving
this to IPv6, you should join our team!](https://upsun.com/jobs/)

## Real-world benefits

This architecture delivers concrete advantages for your applications:

* **Instant service discovery**: new containers become routable
  immediately without propagation delays
* **Zero network bottlenecks**: direct VM-to-VM communication
  eliminates central routing points
* **Predictable performance**: network latency remains consistent
  regardless of infrastructure scale

## The result: Invisible infrastructure

Most container orchestrators require complex service meshes with
sidecar proxies, control planes, and configuration management. Upsun's
approach eliminates this overhead entirely.

When you create a preview environment, the networking configuration is
instant. Your containers can communicate immediately without waiting
for service discovery updates or configuration propagation.

This networking setup is part of why Upsun can spin up complete
production replicas in minutes. The network configuration happens
automatically, transparently, and instantly.

You get the benefits - fast preview environments, reliable service
communication, and predictable performance - without managing any of
the underlying complexity.

Your applications connect as if they're running on a single machine,
while actually being distributed across a high-availability mesh that
spans multiple servers.

## Conclusion: scaling without bottlenecks

To conclude, our stateless mesh networking system lets us scale
effortlessly with no databases, no bottlenecks and no drama. It’s a
big part of how the Upsun grid remains fast, reliable, and always
ready to handle tens of thousands of containers (without breaking a
sweat).

If you're curious about how it all works under the hood, join us on
our [community forum](https://community.upsun.com/) for a good
infrastructure chat. You can also [schedule a
demo](https://upsun.com/contact-us/) to see our platform in action,
or, better yet, [create a free Upsun account](https://upsun.com/) and
experience it for yourself.


# How Upsun provisions TLS certificates at scale
Source: https://developer.upsun.com/posts/how-it-works/how-upsun-provisions-tls-certificates-at-scale

Every Upsun environment gets HTTPS automatically. Here's how the certificate system works, from wildcards to Let's Encrypt automation.

<PostMeta />

Every environment on Upsun gets HTTPS. Production, staging, that branch you created 10 minutes ago to test a database migration. No configuration, no waiting. Certificates appear automatically.

Making that work across thousands of projects and tens of thousands of environments requires a layered system. It started with wildcard certificates, hit DNS limits we didn't anticipate, and ended up relying on per-project Let's Encrypt automation with its own constraints.

## The starting point: wildcard certificates on entrypoints

Each Upsun region has entrypoint nodes that handle incoming traffic. These entrypoints hold wildcard TLS certificates for the region's domain, something like `*.eu-5.platformsh.site`. When you create an environment, it gets a subdomain under that wildcard, and the certificate covers it automatically.

This works well for simple cases. If your environment URL is `main.eu-5.platformsh.site`, the wildcard matches and you get HTTPS with zero provisioning delay.

But wildcard certificates only match a single DNS label. `*.example.com` covers `foo.example.com` but not `foo.bar.example.com`. And DNS labels have a hard length limit. We ran into both constraints.

## Where the wildcard breaks down

Each environment gets a URL like `7smqkhc-abcdefgh1234567.eu-5.platformsh.site`. That's a single label before the region domain, and the wildcard covers it.

The problem is routes. In your `.upsun/config.yaml`, you can define routes like `https://api.{default}` or `https://admin.{default}`. These prepend an extra label to the environment URL, producing something like `api.7smqkhc-abcdefgh1234567.eu-5.platformsh.site`. The wildcard for `*.eu-5.platformsh.site` doesn't cover that because there are now 2 labels before the region domain, not 1.

There's also the label length limit. DNS labels (the parts between dots) can be at most 63 characters, per [RFC 1035](https://www.rfc-editor.org/rfc/rfc1035#section-2.3.4). Early on, we tried encoding more information into a single label using triple-dash separators: `feature-login-redesign---main---abcdefgh1234567.eu-5.platformsh.site`. This kept everything under the wildcard, but with longer branch names, we'd blow past the 63-character ceiling and DNS would refuse the domain entirely.

Both problems point to the same conclusion: we can't rely on a single wildcard certificate. We needed per-environment certificates that cover the exact set of domains each environment uses. That's where Let's Encrypt comes in.

## Per-project Let's Encrypt automation

We use [Let's Encrypt](https://letsencrypt.org/) to provision certificates for each project's environments. The mapping is straightforward: one Let's Encrypt account per project, one certificate per environment. When you deploy an environment, the system determines which domains that environment needs and provisions a certificate covering them.

The certificate selection process runs on every deployment. It follows a priority order:

1. If you've uploaded your own certificates (for custom domains), those are used first. The system picks certificates that cover the most domains, then favors longer validity.
2. If any domains remain uncovered, a new Let's Encrypt certificate is provisioned covering those domains.

The goal is one certificate per environment covering all its domains. When you provide your own certificate, only that certificate is used. If it doesn't cover all your environment's domains, the uncovered domains won't have a valid certificate. When no user-provided certificate is present, the system provisions a single LE certificate covering all the environment's domains. This matters because Let's Encrypt has hard limits on how many certificates you can request.

## Custom certificates and the expiration boundary

You can upload your own certificates for custom domains through the console or API. When you do, the system treats them differently from automatically provisioned ones.

The most important difference is that user-provided certificates are never automatically renewed or deleted. The system doesn't have access to your CA account or control over your DNS, so it has no way to request a replacement on your behalf. Renewal is your responsibility.

What the system does do is track expiration. A user-provided certificate is considered valid until 1 week before it expires. Once it crosses that threshold, the system treats the domain as uncovered and tries to provision a Let's Encrypt certificate for it. If your custom cert covers `shop.example.com` and it's about to expire, the system will automatically request an LE cert for that domain as a fallback. This acts as a safety net, but there are caveats. You'll get a Let's Encrypt DV certificate instead of your original one, which matters if you had an OV or EV certificate. And if your domain has a CAA record that doesn't include Let's Encrypt, the fallback provisioning will fail entirely.

For automatically provisioned certificates, the threshold is more conservative: 4 weeks before expiry. Let's Encrypt certificates are valid for 90 days (roughly 12 weeks), so we start renewal about a third of the way through the certificate's lifetime. That gives plenty of runway to handle transient failures, rate limits, or DNS propagation delays.

There's also a fallback of last resort. If Let's Encrypt provisioning fails entirely (ACME challenge can't complete, rate limits hit, DNS misconfigured), the system reuses an expired certificate rather than serving no certificate at all. An expired cert triggers a browser warning, which is bad, but it's better than a connection failure that gives the user nothing actionable.

## What goes into a certificate

A typical certificate for an Upsun environment covers multiple domains. Consider a project whose routes define both `https://{default}` and `https://www.{default}`, with a custom domain attached. The certificate for the production environment might list these domains in its Subject Alternative Names (SAN):

```
DNS: example.com
DNS: www.example.com
```

A preview branch with the same route configuration would get its own certificate covering the platform domains:

```
DNS: 4kxrats-abcdefgh1234567.eu-5.platformsh.site
DNS: www.4kxrats-abcdefgh1234567.eu-5.platformsh.site
```

All domains go into the SAN extension. The domains are sorted in reverse-DNS order (so `com.example` sorts before `com.example.www`) to keep related domains grouped together in the certificate.

One detail worth calling out: we don't set a Common Name (CN) at all. The CSR we send to Let's Encrypt has an empty subject. We used to pick the shortest domain from the certificate's SAN list as the CN. But the CN field is limited to 64 characters by the X.509 spec, creating the same length problem we saw with DNS labels. A domain like `www.7smqkhc-abcdefgh1234567.eu-5.platformsh.site` is already 52 characters, and longer environment hashes or region names could push past the 64-character CN limit.

This is fine because modern TLS clients determine the certificate's validity from the SAN extension, not the CN. The CN has been effectively deprecated for hostname matching since [RFC 6125](https://www.rfc-editor.org/rfc/rfc6125) in 2011, and Let's Encrypt [explicitly supports](https://community.letsencrypt.org/t/simplifying-issuance-for-very-long-domain-names/207924) certificates with an empty subject. Older clients that only check the CN would reject the certificate. In practice, that means software from before 2010 that has bigger problems than certificate validation.

The system caps each environment at 100 domains, matching the Let's Encrypt limit of 100 SANs per certificate. Most environments have fewer than 5, but projects with many custom domains and route configurations can accumulate more.

## The Public Suffix List and why it matters

Before getting into Let's Encrypt's rate limits, it's worth understanding a piece of internet infrastructure that makes our certificate provisioning viable at all: the [Public Suffix List](https://publicsuffix.org/) (PSL).

The PSL is a community-maintained list of domain suffixes under which people can register names. The obvious entries are things like `com`, `org`, and `co.uk`. Its original purpose is cookie scoping in browsers. Without it, a site hosted at `foo.co.uk` could set a cookie for all of `.co.uk`, affecting every other site under that suffix. The PSL tells browsers where the boundary is between "public suffix" and "registered domain," so cookies can only be set at the right level. But the PSL has found uses well beyond browsers. Any software that needs to determine domain ownership boundaries can rely on it, and Let's Encrypt is one of the most consequential examples.

Hosting providers can add their domains to the list. We have `*.platformsh.site` on the PSL.

Why does this matter? Let's Encrypt uses the PSL to determine what counts as a "registered domain" (the eTLD+1) when applying rate limits. The wildcard entry means that each region subdomain like `eu-5.platformsh.site` is itself a public suffix (an eTLD), treated the same way as `.com` or `.co.uk`. So `7smqkhc-abcdefgh1234567.eu-5.platformsh.site` is a registered domain in the same way that `example.com` is. Since all environments in a project share the same project ID in their URL, their certificate requests count against the same per-project budget.

Without the PSL entry, Let's Encrypt would treat `platformsh.site` as the registered domain. Every certificate request for every project across all regions would count toward a single rate limit bucket. With thousands of projects, we'd burn through the 50-per-week limit almost instantly.

With the PSL entry, each project gets its own rate limit budget. This is the difference between the system working and not working.

## Working within Let's Encrypt's constraints

Let's Encrypt is free and automated, but it comes with [rate limits](https://letsencrypt.org/docs/rate-limits/) that shape how we design the provisioning system.

The most relevant constraints:

* **100 names per certificate.** Each certificate can cover at most 100 domain names (Subject Alternative Names). An environment with many custom domains and route configurations can approach this limit.
* **50 certificates per registered domain per week.** This is a global limit across all accounts. Thanks to our PSL entry, the "registered domain" is at the per-environment level (e.g. `7smqkhc-abcdefgh1234567.eu-5.platformsh.site`), not `platformsh.site` itself. Since environments within a project share a project ID, each project effectively gets its own budget of 50 new certificates per week.
* **300 new orders per account per 3 hours.** Each account can submit up to 300 certificate orders in a 3-hour window, refilling at roughly one order every 36 seconds.
* **5 duplicate certificates per exact set of names per week.** If you request a certificate for the exact same list of domains repeatedly, you're limited to 5 per week.

As mentioned earlier, we use one Let's Encrypt account per project. This is an instance of [the natural scaling pattern](/posts/insights/the-third-way-to-scale-that-nobody-talks-about): instead of one shared account that needs to handle thousands of projects, each project gets its own isolated account. This doesn't help with the per-registered-domain limit, which is global regardless of account. But it isolates projects from each other on per-account limits. If one project is cycling through deployments rapidly and burning through its 300-order budget, that doesn't affect any other project. And since each environment gets its own certificate, a project with 10 active environments means 10 certificates under that project's account.

Even with the PSL giving each project its own rate limit bucket, the 50-per-week limit can still bite. A project with many active environments that are being frequently created and destroyed could approach it. In practice, this is rarely an issue because most certificate requests are renewals of existing certificates (which don't count against the limit) rather than net-new issuances. But we have hit rate limits in the past, typically during large-scale infrastructure events where many certificates need to be re-provisioned simultaneously. When it happens, the system backs off and retries, and certificates catch up within hours.

We also self-rate-limit our requests to the ACME server at 5 requests per second per project, using a token bucket. This isn't required by Let's Encrypt, but it's good citizenship. Hammering the ACME API with parallel requests from thousands of projects would create problems for both sides.

## Renewals

Let's Encrypt certificates are valid for 90 days. The system automatically renews certificates that will expire within 30 days. This runs as part of the deployment process, so a redeployment also triggers a certificate check.

For environments that don't see frequent deployments, the system still tracks certificate expiry and triggers renewal activities independently. You don't need to redeploy to keep your certificates valid.

The renewal process follows the same selection algorithm as initial provisioning. Any domain configuration change (adding or removing custom domains, changing routes) triggers a new deployment. The certificate is provisioned at deploy time with the correct domain set, so renewals always handle the same domains.

## Trade-offs

The wildcard-to-Let's-Encrypt evolution solved the DNS label problem and gave us more flexibility, but it introduced operational complexity.

Wildcard certificates are simple. One certificate per region, no provisioning delay, no external dependencies. But they can't handle multi-level subdomains, and they don't work for custom domains at all.

Per-project Let's Encrypt certificates handle arbitrary domain structures and custom domains. But they depend on an external CA, they're subject to rate limits, and they add latency to the first deployment. The ACME challenge needs to complete before the certificate is ready.

The certificate selection algorithm adds its own complexity. Greedy set-cover with multiple tiebreaker criteria isn't trivial to debug when a domain isn't getting the certificate you'd expect. But it handles the common cases well: most projects have a handful of domains, the algorithm picks the right certificates, and the entire process is invisible to the user.

## Every push gets HTTPS

The goal is that TLS is never something you think about. You push code, you get a URL, and that URL has a valid certificate. Behind the scenes, the system is checking domain coverage, selecting from existing certificates, provisioning new ones through ACME challenges, and renewing before expiry. It's not glamorous infrastructure, but it's the kind of thing that gets noticed when it breaks.


# How we caught a silent IO storm before it hit production
Source: https://developer.upsun.com/posts/how-it-works/how-we-caught-a-silent-io-storm-before-it-hit-production

A sysctl setting that worked fine for years caused over 500 MB/s of disk writes after migrating to Debian 12. MariaDB stalled on pending IO, Redis complained about slow fsync, and RBD-backed storage ground to a halt. The culprit: cgroup v2 changes how the kernel divides dirty page budgets across containers.


<PostMeta />

Upsun runs customer applications inside LXC containers. Hundreds of them per host, sometimes 400-500 on a single machine. After migrating hosts from Debian 10 to Debian 12, something alarming showed up on a region running Upsun's own projects: `systemd-journald` processes were collectively writing over 500 MB/s of sustained disk IO across all containers, and the hosts were reporting \~46% iowait as observed in `mpstat`. The same container images on Debian 10 hosts? \~22 MB/s total. No issues.

The configuration was identical. The container images were identical. The workloads were mixed and comparable. The only difference was the host OS version.

Because this was caught on infrastructure running Upsun's own services, there was time to investigate properly instead of scrambling during a customer-facing incident. But the impact was real: several services on the region were experiencing degraded disk performance, and it took several wrong turns before the real cause surfaced. The fix turned out to be a one-line sysctl change.

## The symptom

`iotop` on an affected Debian 12 host told the story. Over 25 `systemd-journald` processes, each writing tens of megabytes per second, totaling well over 500 MB/s.

```
TID    PRIO  USER  DISK READ  DISK WRITE  COMMAND
221105 be/4  root  0.00 B/s   64.08 M/s   systemd-journald
1346600 be/4 root  0.00 B/s   43.84 M/s   systemd-journald
221562 be/4  root  0.00 B/s   23.83 M/s   systemd-journald
291814 be/4  root  0.00 B/s   22.56 M/s   systemd-journald
134063 be/4  root  0.00 B/s   13.13 M/s   systemd-journald
30747  be/4  root  0.00 B/s    9.56 M/s   systemd-journald
228961 be/4  root  0.00 B/s    6.06 M/s   systemd-journald
30898  be/4  root  0.00 B/s    5.00 M/s   systemd-journald
212739 be/4  root  0.00 B/s    4.07 M/s   systemd-journald
136800 be/4  root  0.00 B/s    3.94 M/s   systemd-journald
26579  be/4  root  0.00 B/s    2.87 M/s   systemd-journald
...
```

A second sample a few seconds later showed the same picture with the numbers shuffled: the top process now writing 61 MB/s, another at 57 MB/s. The IO was continuous, not bursty.

On a Debian 10 host running the same container images with comparable workloads, the picture was completely different:

```
TID     PRIO  USER  DISK READ  DISK WRITE  COMMAND
2805782 be/4  root  0.00 B/s    5.90 M/s   systemd-journald
349145  be/4  root  0.00 B/s    3.31 M/s   systemd-journald
2256468 be/4  root  0.00 B/s    2.38 M/s   systemd-journald
2252895 be/4  root  0.00 B/s  758.44 K/s   systemd-journald
2976921 be/4  root  0.00 B/s  866.79 K/s   systemd-journald
...
```

The highest process at 5.9 MB/s. Most in the kilobytes. Normal.

## The red herrings

Before the real cause surfaced, several theories looked plausible. Each turned out to be wrong, but ruling them out narrowed the search.

The first suspect was crash-looping applications flooding the journal. A check for containers with high service restart counts came up empty. One container had only 2 log messages per minute, yet its journald was writing 64 MB/s. The IO had nothing to do with log volume.

Next was `ForwardToConsole` amplifying writes. The journald configuration forwards all messages to `/dev/console` at debug level (`ForwardToConsole=yes`, `MaxLevelConsole=debug`). This does add IO per message, but disabling it on a test container still left 64 MB/s of writes. Console forwarding was an amplifier, not the root cause.

Different VM writeback settings also seemed worth investigating. Both hosts had identical `dirty_bytes` and `dirty_background_bytes` values, the same loop device configuration (`DIO=0`, buffered IO), and the same XFS mount options. No difference at the filesystem or block layer.

Finally, broken rate limiting due to cgroup v2. The theory was that the container's fake cgroup v2 filesystem might prevent journald from identifying the originating systemd unit, breaking rate limiting. But verbose journal output showed `_SYSTEMD_UNIT=` metadata present on both platforms. Rate limiting was working fine.

## Where the IO actually comes from

Running `strace` on a journald process that was writing 64 MB/s showed almost nothing.

```
# 5 seconds of syscall tracing
openat: 72 calls
writev: 21 calls
```

72 file opens and 21 writes in 5 seconds. You don't get 64 MB/s from 21 writes.

The IO wasn't coming from journald's own syscalls. It was coming from the kernel.

journald stores logs in persistent journal files using [`mmap()`](https://man7.org/linux/man-pages/man2/mmap.2.html) with `MAP_SHARED`. When it writes a log entry, it modifies pages in the memory-mapped region. Those pages become "dirty" (modified in memory but not yet written to disk). The kernel's writeback subsystem is responsible for eventually flushing those dirty pages to the underlying filesystem. In `iotop`, this writeback IO gets attributed to the process that dirtied the pages.

In this setup, the journal files sit on XFS filesystems on loop devices. The path goes: dirty mmap'd pages in memory → XFS on loop device → backing file on host disk. All handled by the kernel, not by journald.

So the question became: why is the kernel writing back dirty pages so aggressively on Debian 12?

## The one real difference: cgroup v1 vs v2

Both hosts run modern kernels. Both have the same sysctl settings. Both use the same container images. But:

* Debian 10 host: **cgroup v1**
* Debian 12 host: **cgroup v2**

This is the only infrastructure-level difference between the two. And it changes everything about how the kernel handles dirty page writeback.

## How dirty page writeback works

When a process modifies a memory-mapped file, the kernel doesn't write the changes to disk immediately. Instead, it marks the page as "dirty" and lets dirty pages accumulate up to a configured threshold. Once that threshold is reached, the kernel starts flushing pages to disk. There are two thresholds:

* **Background threshold** (`vm.dirty_background_bytes` or `vm.dirty_background_ratio`): when dirty pages exceed this, the kernel starts writing them back in the background. The dirtying process can keep running.
* **Foreground threshold** (`vm.dirty_bytes` or `vm.dirty_ratio`): when dirty pages exceed this, the kernel forces the dirtying process to wait until some pages are written out. This is throttling.

The kernel function that enforces this is [`balance_dirty_pages()`](https://github.com/torvalds/linux/blob/v6.12/mm/page-writeback.c#L1830) in `mm/page-writeback.c`. It's called in the write path and decides whether to let the process continue or throttle it based on how many dirty pages exist relative to the configured limits.

The hosts had these set in `/etc/sysctl.d/vm.conf`:

```ini theme={null}
# As a baseline, allow 100MB of dirty buffers,
# and start background writing after 50MB.
vm.dirty_background_bytes = 52428800
vm.dirty_bytes = 104857600
```

These values were set years ago, when all hosts ran cgroup v1. They worked fine. On cgroup v2, they became a disaster.

## What cgroup v2 changes in the writeback path

On **cgroup v1**, `balance_dirty_pages()` is not cgroup-aware. The gate is the function [`inode_cgwb_enabled()`](https://github.com/torvalds/linux/blob/v6.12/include/linux/backing-dev.h#L172) in `include/linux/backing-dev.h`, which checks `cgroup_subsys_on_dfl(memory_cgrp_subsys)` and `cgroup_subsys_on_dfl(io_cgrp_subsys)`. Both return false on cgroup v1, disabling per-cgroup writeback entirely. This was introduced in commit [`9badce000e2c`](https://github.com/torvalds/linux/commit/9badce000e2c) ("cgroup, writeback: don't enable cgroup writeback on traditional hierarchies"). The 100 MB `dirty_bytes` setting is a single global pool. All processes, across all containers, share one 100 MB budget. When the global total is below 100 MB, writeback is lazy. Pages accumulate, get written in batches, and nobody notices.

On **cgroup v2**, `balance_dirty_pages()` enforces **per-cgroup dirty limits**. The function [`domain_dirty_limits()`](https://github.com/torvalds/linux/blob/v6.12/mm/page-writeback.c#L377) calculates each cgroup's dirty budget proportionally, based on the cgroup's memory allocation relative to total system memory. Three kernel features work together to make this happen:

1. **Cgroup-aware `balance_dirty_pages()`** (present since kernel \~4.2, but only active on cgroup v2): each cgroup gets its own dirty page budget, calculated as a fraction of the global limit. See [`wb_over_bg_thresh()`](https://github.com/torvalds/linux/blob/v6.12/mm/page-writeback.c#L2188) and [`wb_dirty_limits()`](https://github.com/torvalds/linux/blob/v6.12/mm/page-writeback.c#L1688) for the per-writeback-domain calculations.

2. **XFS cgroup writeback support** (added in kernel 5.3): before this, XFS didn't participate in cgroup writeback. All dirty pages from XFS filesystems were attributed to the root cgroup regardless of which container dirtied them. After 5.3, XFS fully participates.

3. **Loop device IO charging per-cgroup** (added \~kernel 5.15, [LWN coverage](https://lwn.net/Articles/851009/)): the loop driver gained per-cgroup worker threads, so IO to the backing file is charged to the container's cgroup, not to root.

On cgroup v1, all three of these mechanisms are inactive, even on modern kernels. On cgroup v2, all three activate simultaneously.

Here's the math for this setup:

```
Total host memory:       124 GB
Container memory limit:  768 MB (memory.max)
Global dirty_bytes:      100 MB

Per-cgroup dirty limit = 100 MB × (768 MB / 124 GB) = ~0.6 MB
Per-cgroup background  = 50 MB  × (768 MB / 124 GB) = ~0.3 MB
```

Each container got a dirty page budget of **0.6 MB**. On hosts running 400-500 containers, this budget would be even smaller.

## Why 0.6 MB is a catastrophe

Each container's journald has journal files open and memory-mapped. A typical container on the affected host had:

```
-rw-r----- root systemd-journal  8.0M system.journal
-rw-r----- root systemd-journal  8.0M system@...journal (archived)
-rw-r----- root systemd-journal  8.0M system@...journal (archived)
-rw-r----- root systemd-journal  8.0M user-10000.journal
-rw-r----- root systemd-journal   80M user-10000@...journal (archived)
-rw-r----- root systemd-journal   80M user-10000@...journal (archived)
```

Total mmap'd data: \~192 MB per container. Even with minimal log activity (2 messages per minute observed), the mmap regions have dirty pages from previous writes. With a dirty budget of 0.6 MB, each container is permanently at **4-5x its budget**. The kernel is in constant aggressive writeback mode, flushing pages as fast as they're dirtied.

Now multiply this by hundreds of containers. Each one is an independent cgroup with its own tiny dirty budget, each one continuously exceeding it, each one triggering its own aggressive writeback. Hundreds of independent writeback domains, all flushing simultaneously and competing for disk IO.

Here's a simplified view of what's happening:

```
                    cgroup v1 (Debian 10)
                    =====================

        ┌──────────────────────────────────────┐
        │     Global dirty_bytes = 100 MB      │
        │         (single shared pool)         │
        │                                      │
        │  Container A: 3 MB dirty  ─┐         │
        │  Container B: 1 MB dirty   │ = 8 MB  │
        │  Container C: 2 MB dirty   │ total   │
        │  Container D: 2 MB dirty  ─┘         │
        │  ...                                 │
        │                                      │
        │  Well below 100 MB → lazy writeback  │
        └──────────────────────────────────────┘

                    cgroup v2 (Debian 12)
                    =====================

        ┌────────────┐  ┌────────────┐  ┌────────────┐
        │ Container A│  │ Container B│  │ Container C│  ...
        │            │  │            │  │            │
        │ Budget:    │  │ Budget:    │  │ Budget:    │
        │   0.6 MB   │  │   0.6 MB   │  │   0.6 MB   │
        │            │  │            │  │            │
        │ Dirty:     │  │ Dirty:     │  │ Dirty:     │
        │   3.0 MB   │  │   1.0 MB   │  │   2.0 MB   │
        │   (5x!)    │  │   (1.7x!)  │  │   (3.3x!)  │
        │            │  │            │  │            │
        │  FLUSHING  │  │  FLUSHING  │  │  FLUSHING  │
        │ CONSTANTLY │  │ CONSTANTLY │  │ CONSTANTLY │
        └────────────┘  └────────────┘  └────────────┘

        × hundreds of containers per host = IO storm
```

## Proving it

Checking the per-cgroup dirty page accounting on both hosts confirmed this.

**Debian 12 (cgroup v2):**

```bash theme={null}
$ grep file_dirty /sys/fs/cgroup/lxc.payload.5gak.../memory.stat
file_dirty 3055616    # 2.9 MB, 5x the per-cgroup budget

$ cat /sys/fs/cgroup/lxc.payload.5gak.../memory.max
805306368             # 768 MB

$ cat /sys/fs/cgroup/lxc.payload.5gak.../cgroup.controllers
cpuset cpu io memory hugetlb pids rdma misc
# ↑ memory AND io controllers both active: per-cgroup writeback is enforced
```

The `file_dirty` value fluctuated between 16 KB and 3.6 MB over repeated samples. The kernel was aggressively flushing, but journald kept dirtying pages faster than they could be written out.

**Debian 10 (cgroup v1):**

```bash theme={null}
$ grep dirty /sys/fs/cgroup/memory/.../memory.stat
dirty 0
writeback 0
total_dirty 0
total_writeback 0

$ iotop -p $JOURNALD_PID
DISK WRITE: 0.00 B/s    # zero IO attributed to this journald process
```

On cgroup v1: zero per-cgroup dirty page tracking, zero per-PID writeback IO. The dirty pages exist, but the kernel doesn't track or enforce them per-cgroup. On cgroup v2: 2.9 MB tracked dirty pages (well above the 0.6 MB budget), and 7-11 MB/s of writeback IO per process.

Same kernel family. Same sysctl settings. Same containers. Completely different behavior.

## The fix

The fix was one file on the host:

```ini theme={null}
# /etc/sysctl.d/vm.conf (before)
vm.dirty_background_bytes = 52428800   # 50 MB
vm.dirty_bytes = 104857600             # 100 MB
```

```ini theme={null}
# /etc/sysctl.d/vm.conf (after)
vm.dirty_background_ratio = 5
vm.dirty_ratio = 10
```

Instead of an absolute byte count that gets divided across cgroups, this uses a percentage of total memory. The key difference: `dirty_ratio` and `dirty_background_ratio` are mutually exclusive with `dirty_bytes` and `dirty_background_bytes` in the kernel. Setting one pair to non-zero automatically zeroes the other ([documented in the kernel](https://docs.kernel.org/admin-guide/sysctl/vm.html#dirty-bytes)).

This works correctly on both cgroup versions:

* **cgroup v1**: 10% of 124 GB = \~12.4 GB global budget. More generous than the old 100 MB, but writeback on v1 is global anyway and doesn't enforce per-cgroup, so this is fine.
* **cgroup v2**: divided proportionally. Each 768 MB container gets 10% of 124 GB × (768 MB / 124 GB) = **\~77 MB** of dirty budget. Comfortable headroom for journal files.

These values are more conservative than the kernel defaults (`dirty_ratio=20`, `dirty_background_ratio=10`), so there's safety margin.

Applied live without any container restarts:

```bash theme={null}
sysctl -w vm.dirty_ratio=10 vm.dirty_background_ratio=5
```

The effect was immediate.

**Before:**

```
 221105 be/4 root  0.00 B/s   64.08 M/s   systemd-journald
1346600 be/4 root  0.00 B/s   43.84 M/s   systemd-journald
 221562 be/4 root  0.00 B/s   23.83 M/s   systemd-journald
 291814 be/4 root  0.00 B/s   22.56 M/s   systemd-journald
 134063 be/4 root  0.00 B/s   13.13 M/s   systemd-journald
```

**After:**

```
 221562 be/4 root  0.00 B/s  285.66 K/s   systemd-journald
  28065 be/4 root  0.00 B/s  231.25 K/s   systemd-journald
 107675 be/4 root  0.00 B/s  108.82 K/s   systemd-journald
 221105 be/4 root  0.00 B/s  108.82 K/s   systemd-journald
     455 be/4 root 0.00 B/s   68.01 K/s   systemd-journald
```

From megabytes per second to kilobytes per second. A \~100x reduction per process. The host iowait dropped from \~46% to normal levels.

## The collateral damage: it wasn't just journald

The journald writeback storm was the most visible symptom, but it wasn't the only one. The per-cgroup dirty page throttling affects every process that writes, not just journald. Any process in a container that dirties pages, whether writing to a local filesystem or to a Ceph RBD device, gets throttled by `balance_dirty_pages()` when the cgroup's tiny dirty budget is exceeded.

The containers use RBD-backed block devices for persistent storage. With a per-cgroup dirty budget of \~0.6 MB, the kernel was throttling RBD writes across hundreds of containers simultaneously. Services that depend on disk performance were visibly affected.

### MariaDB

InnoDB was logging hundreds of pending reads, sustained over minutes.

```
Apr 07 04:12:15 db.0 mysql-cluster.daemon[15424]: InnoDB: Pending IO count
                     Pending Read : 593
                     Pending Write: 1
Apr 07 04:12:29 db.0 mysql-cluster.daemon[15424]: InnoDB: Pending IO count
                     Pending Read : 508
                     Pending Write: 4
Apr 07 04:13:26 db.0 mysql-cluster.daemon[15424]: InnoDB: Pending IO count
                     Pending Read : 546
                     Pending Write: 3
```

Hundreds of pending reads is not normal InnoDB behavior. The database was starved of IO because the kernel was busy flushing dirty pages from the same cgroup's tiny writeback budget.

### Redis

AOF persistence was consistently falling behind.

```
Apr 02 08:56:18 dedup.0 redis-server[104]: Asynchronous AOF fsync is taking too long
    (disk is busy?). Writing the AOF buffer without waiting for fsync to complete,
    this may slow down Redis.
Apr 02 09:01:18 dedup.0 redis-server[104]: Asynchronous AOF fsync is taking too long
    (disk is busy?). Writing the AOF buffer without waiting for fsync to complete,
    this may slow down Redis.
Apr 02 09:07:25 dedup.0 redis-server[104]: Asynchronous AOF fsync is taking too long
    (disk is busy?). Writing the AOF buffer without waiting for fsync to complete,
    this may slow down Redis.
```

Redis prints this warning when `fsync()` on the append-only file takes longer than expected. The disk wasn't actually busy with useful work. It was busy with the kernel's aggressive dirty page writeback, starving other IO in the same cgroup.

The connection is straightforward: `balance_dirty_pages()` doesn't distinguish between journald's mmap'd pages and an InnoDB data file write or a Redis AOF fsync. They all share the same per-cgroup dirty budget. When journald's persistent mmap'd regions keep the cgroup permanently over budget, every other writer in that container pays the price.

## Why `dirty_bytes` worked for years

The `dirty_bytes=100MB` setting was never wrong for cgroup v1. On v1, `inode_cgwb_enabled()` returns false because the memory and IO controllers aren't on the default (v2) hierarchy, so per-cgroup writeback never activates. 100 MB was a reasonable global dirty page ceiling for any host size.

After moving to Debian 12 and picking up cgroup v2, the same number took on a completely different meaning. It went from "100 MB total across the host" to "100 MB divided proportionally across hundreds of containers." The sysctl didn't change. The kernel's interpretation of it did.

## Takeaways

This wasn't a theoretical risk. It was causing real slowness across containers on an entire region. MariaDB, Redis, and other services on RBD-backed storage were all degraded because the kernel was throttling their writes at the cgroup level. The journald writeback storm was the loudest symptom, but the per-cgroup dirty page starvation was silently hurting every IO-dependent service on every affected host.

If you run containers on cgroup v2 (the default on any modern Linux distribution), check your dirty page settings. Absolute byte values (`dirty_bytes`, `dirty_background_bytes`) that worked on cgroup v1 can cause IO storms on v2, because the kernel divides them proportionally across cgroups based on each cgroup's memory share.

The symptoms don't point to the cause. Databases log pending IO. Redis complains about slow fsync. `iotop` shows journald writing at absurd rates. `strace` shows almost no syscall activity. You'd investigate the application, the storage backend, the network, none of which are the problem. The actual cause is in the kernel's writeback subsystem, and you need to look at per-cgroup `memory.stat` (`file_dirty`, `file_writeback`) to see what's happening.

Ratio-based settings (`dirty_ratio` and `dirty_background_ratio`) avoid this problem entirely because they scale with total memory and divide proportionally in a way that gives each cgroup a usable budget. If you're running a multi-container host and have `dirty_bytes` or `dirty_background_bytes` set, switch to ratios.

This issue was caught on a region running Upsun's own services before it reached customer-facing hosts. The fix was one line. Finding it took considerably longer, and the blast radius was wider than the initial symptom suggested.

***

**Further reading:**

* [Writeback and control groups](https://lwn.net/Articles/648292/): LWN article on the design of cgroup-aware writeback
* [cgroup v2 and Page Cache](https://biriukov.dev/docs/page-cache/6-cgroup-v2-and-page-cache/): detailed walkthrough of per-cgroup dirty page accounting
* [Control Group v2 — Linux Kernel Documentation](https://docs.kernel.org/admin-guide/cgroup-v2.html): official docs on the memory controller and writeback
* [`balance_dirty_pages()` source](https://github.com/torvalds/linux/blob/v6.12/mm/page-writeback.c#L1830): the kernel function at the heart of dirty page throttling
* [`domain_dirty_limits()` source](https://github.com/torvalds/linux/blob/v6.12/mm/page-writeback.c#L377): where per-cgroup dirty thresholds are calculated
* [`inode_cgwb_enabled()` source](https://github.com/torvalds/linux/blob/v6.12/include/linux/backing-dev.h#L172): the gate that disables cgroup writeback on v1 hierarchies
* [Charge loop device IO to issuing cgroup](https://lwn.net/Articles/851009/): LWN article on per-cgroup loop device IO accounting
* [vm.dirty\_bytes kernel documentation](https://docs.kernel.org/admin-guide/sysctl/vm.html#dirty-bytes): sysctl knobs for dirty page limits


# How we've been hardening containers since before Docker made it cool
Source: https://developer.upsun.com/posts/how-it-works/how-weve-been-hardening-containers-since-before-docker-made-it-cool

Docker's hardened images are great, but we've been doing this for years. Here's the automated pipeline that's been securing hundreds of container images behind the scenes at Upsun.

<PostMeta />

When Docker [announced their hardened images](https://www.docker.com/blog/docker-hardened-images-for-every-developer/) in December 2025, making their enterprise-grade hardened container images free and open source, the developer community celebrated. Minimal attack surfaces, non-root by default, continuous CVE scanning, automated updates; finally, someone was taking container security seriously at scale.

Here's the thing: if you've been running on Upsun, you've had all of this since day one. Not as a new feature launch, not as a premium add-on, but as the invisible infrastructure that keeps hundreds of container images secure while you focus on shipping code.

This isn't us claiming we invented container hardening (we didn't). But we've been doing this work quietly, automatically, and at scale for years. Docker's announcement validates the approach we've been running in production. Let's talk about how it works.

## Why hundreds of images, not one "hardened" base

We run a Debian shop. Every service we support (MariaDB, PostgreSQL, Redis, PHP, Ruby, Python, and more) gets its own set of container images. But here's the complexity that Docker's unified hardened images don't address: each runtime needs separate images for every version we support.

Take PHP. We maintain dedicated images for PHP 8.5, 8.4, 8.3, 8.2, and older versions still in use. Why separate images instead of one hardened PHP image? ABI compatibility. If you're running PHP 8.5 with a compiled binary extension and we suddenly upgrade the base image's glibc version, your extension breaks. Same story for any language with native extensions.

This isn't a choice we made lightly. It's how we prevent your application from breaking during routine platform updates. But it means we're maintaining hundreds of container images, each needing security updates, package patches, and careful version management. This is where the real work happens.

## YAML as infrastructure (before infrastructure as code was everywhere)

Here's where our approach diverges from the Docker hardened images model. We don't maintain these images the traditional way. There's no `apt-get update` and `apt-get upgrade` running on each image. Instead, we use an internal YAML-based format that specifies every package and version installed in an image.

Think of it as a Software Bill of Materials (SBOM) that doubles as the source of truth for building images. Everyone talks about SBOMs now for supply chain security. We've been using them as our build system for years because it makes auditing straightforward and automation possible.

When we need to check if an image needs updating, we don't spin up containers. We parse the YAML, query the Debian repositories via HTTP, and compare versions. No packages changed? Nothing to do. New versions available? Build a new image with the latest packages.

This approach scales beautifully. Most of the time, there's nothing to update. When there is, it's just YAML parsing and HTTP requests to package repositories. No container orchestration, no build farms spinning up unnecessarily. The automation is boring, efficient, and runs every few hours without anyone noticing.

## Continuous updates (the unglamorous kind)

Every two to four hours, we scan every image version we maintain. For each one, we check its designated Debian repositories for newer packages. If updates exist, we trigger a build with the latest versions. This has been running in the background for years.

This means that within hours of a package appearing in a Debian repository, it's in our images. Docker's hardened images promise continuous scanning and updates. We've been doing exactly that, automatically, every few hours, for hundreds of images. But here's the part that takes real engineering: getting an image built and getting it to production safely are different problems.

## The testing gauntlet

Speed matters for security updates, but stability matters more, especially for databases. If we push a broken MariaDB update, you lose data. That's unacceptable.

Here's our process: We don't deploy every new image we build. Multiple images get built every day as packages update, but we don't immediately ship them to production.

Instead, once a week, we snapshot the latest versions of all our images and run them through our full testing suite. This includes internal testing environments where we validate that everything works as expected. The images that pass testing get scheduled for production deployment.

From build to production usually takes one to two weeks. The images hit our internal testing regions first, then roll out to production environments. This gives us confidence that updates won't break your applications.

## The CVE exception

There's one big exception to this measured cadence: critical CVEs. When a serious vulnerability drops in a package we use, we can fast-track images to production within hours.

This doesn't happen often. In Upsun's lifetime, we've needed emergency updates only a handful of times. But when we do, the fully automated pipeline makes it possible. We can identify affected images, build updates, run essential tests, and deploy; all in a compressed timeframe.

This capability exists because of Debian's technical design. The metadata, repositories, version resolution, and documentation are all standardized and reliable. We can programmatically query everything we need to know about package versions and dependencies.

## What this means for you (the actual value)

Here's the thing about Docker's hardened images announcement: it's great news for teams managing their own infrastructure. They now have free access to enterprise-grade container security. That's genuinely valuable.

But if you're on Upsun, you've never had to think about any of this. Not because we hide complexity (we're literally explaining it right now), but because this is what a proper Cloud Application Platform provides.

When Docker releases hardened images, you don't need to evaluate them for your stack. When a CVE drops in OpenSSL, you don't need to coordinate updates across your infrastructure. When Debian publishes security patches, you don't need to rebuild images and redeploy. This is all handled automatically, tested thoroughly, and deployed safely.

We handle the system packages. You handle your application dependencies: npm packages, Python libraries, Ruby gems. That's the division of labor. That's what "platform" actually means: not just hosting, but the invisible infrastructure work that keeps your application secure and running.

## The catch: version lifecycle

There's one thing you do need to think about: upgrading runtime versions. Because we tie each Debian version to a specific image version, old images eventually stop receiving updates.

Debian 7 and Debian 8 are no longer maintained by Debian. If you're running PHP 5.4 on one of those base systems, you're not getting security patches for the underlying OS. The application runtime is outdated, and so is everything underneath it.

This is why we encourage regular upgrades. It's not about chasing the latest features (though those are nice). It's about staying on supported base systems that still receive security updates.

## The validation nobody asked for (but we'll take it)

Docker's decision to make hardened images free and open source validates something we've known for years: container security at scale requires automation, continuous updates, and thorough testing. You can't manually manage hundreds of images and stay secure.

We weren't being visionary when we built this system. We were being practical. When you're running a platform that hosts thousands of applications, each with its own runtime version requirements, automation isn't optional. It's survival.

The boring, repetitive work of checking packages, building images, running tests, and deploying updates; that's the infrastructure work that matters. Docker's announcement doesn't change what we do. It just confirms we've been doing it right.


# Installers that don't suck
Source: https://developer.upsun.com/posts/how-it-works/installers-that-dont-suck

Learn how to create cloud-friendly web application installers that account for cloud-based environments and optimize the user experience.

<PostMeta />

<Tip>
  This post was originally published on the Platform.sh blog and reflects information from the time of publication.
</Tip>

The first part of your web application that users will see is its installer. It's a surprisingly important piece of your application, yet because it's only seen once, it's often an afterthought or doesn't get the same attention as the user experience of other parts of the system. When it does, however, there is a tendency to focus on a very specific new-user experience only, to the detriment of the multitude of ways that a web application could be deployed, installed, or set up.

At Platform.sh, the Developer Relations team maintains a catalog of ready-to-install templates ranging from stand-alone applications to CMSs to frameworks to example-only configurations. That means we get to see a *lot* of installers, running the full gamut from "pretty good" to "the installer is so bad we had to completely abandon it."

So what makes a good installer? Let's sweat the details.

## What does an installer do?

What exactly do we mean when we talk about an installer? It varies somewhat with the application, but there are a few general tasks that installers tend to be responsible for:

* Asking the user for necessary environment information (DB credentials, etc.).
* Asking the user for global configuration data, such as a site name, API keys, etc.
* Writing global configuration to wherever it gets stored.
* Populating data stores with initial data; that could be empty database tables, sample content, etc.
* Downloading additional data on the fly, such as sample content or translations.
* Downloading additional code extensions/plugins/modules/whatever the system calls them.
* Creating the administrative user.
* Creating the first non-admin user.

Not every application's installer does all of these, and some don't always apply, but that's largely what they will do. The goal of the installer is that, once it's done, the user is able to login (as either an admin or normal user) and start using the system.

## What's wrong with this picture?

That's all well and good, but there are several problems with this approach when running in a cloud-based environment like Platform.sh.

First, the file system is generally read-only. That's good for security, good for auditability, good for repeatable deployments, and completely incompatible with "write the global configuration to disk" if that configuration is some kind of generated code. Depending on the configuration, it could be written to a user-file part of the disk, but if it's executable code rather than JSON, YAML, or XML, then that's unwise from a security standpoint.

Second, in a cloud environment the user may not know what the database credentials are. Often it's provided through environment variables, or a magically named include file, or some variant on that. The whole point of a cloud environment is that services such as a database or search index can be created declaratively, not through manual setup. In addition, when your application needs to run in [multiple environments](https://devcenter.upsun.com/posts/best-practices-in-deploying-web-apps-updated-for-2020/) (either dev/stage/prod or a branch-is-environment setup like Platform.sh), the services you're connecting to may not even have existed when the installer runs, because it was run on a different branch.

Third, downloading additional modules or extensions may seem like a nice user-friendly feature, but it runs into the same writeable file system problem as before. It also means you cannot easily manage what extensions are installed through Git, which is a major flaw.

Fourth, while this isn't universal, I have seen systems that try to write their global configuration to the same directory as service credentials. A few even try to write them to the same file. That might seem simple at first, but as soon as you want to take advantage of any cloud-based capabilities at all, it can be a death-knell to your installer.

In general, most installer failings come down to assumptions: specifically, assuming that the application is being installed into the one and only place it will ever run, with a writable file system, by someone with root access, and without really thinking about future upgrades beyond "FTP new files over the old ones."

That assumption is increasingly very, very wrong.

## Better installers

Better installer design accounts for the fact that it may not be installed on The One True Server™ by someone with god-level server access. In fact, it’s optimized instead for needing to know as little as possible.

First off, the application should be able to read environment-specific configuration from environment variables. That includes database credentials, API keys, the installation path of the application, the domain name on which the application is running, and anything else that would be different between production and your local laptop. If those are different, they should be read from, or at least readable from, environment variables.

It's OK if your application can also read them from a file on disk, be it a `.env` file to override the environment directly or an application-specific file, as long as it can read from the environment. Java developers may be used to a `properties` file, which is fine as long as environment variables win over it if defined. That file can be used for local development, but should not be used in production.

It's also a good idea to have a place for host-specific glue code to be injected, in case the way your host exposes environment information needs to be mapped to the variable names your application expects. The mechanism will vary with every application and host, which is fine; just leave a place for that to happen.

Second, the installer should be able to detect if those environment variables are already populated. If so, and it can already connect to the database, just skip that step in the installer. The user doesn't have to be in the process at all. That also means there's nothing to write to disk, so it avoids that problem, too.

Third, any additional global configuration should be written to a non-executable target. The database is a fine place for it. If it must be written to a file, write it to a non-executable format (JSON is a good choice, or ini, or YAML, but not PHP or Javascript) in a directory specific for that purpose. Ideally it's a non-web-accessible directory separate from where user files go, for additional security. That directory may be writable, but not shared with any environment-dependent information.

And finally, don't download code in the installer. Virtually every language today has a standard package manager available for it, be it Composer, npm, Pip, Maven, Bundler, Cargo, or what have you. That's how extensions should be added and managed. That gives you all the same benefits for extensions as you get for your core system, mainly security, auditability, and repeatable deployments.

With those three simple changes—environment variable-based configuration, environment-aware installer steps, and avoiding disk writes—nearly any application can be made "<a href="/posts/unknown/6-things-to-do-to-make-your-application-cloud-friendly">cloud-friendly</a>." While there are other changes that could make an application fully "cloud native" (depending on which marketer you listen to on what that means), making your application ready for nearly any cloud-based host is really that simple. Not doing so, however, can make your application difficult, or even impossible, to install on a cloud-based host. And really, no one wants that.


# Keeping the peace: how ZooKeeper stops database nodes from fighting
Source: https://developer.upsun.com/posts/how-it-works/keeping-the-peace-how-zookeeper-stops-database-nodes-from-fighting

Learn how Upsun uses Zookeeper's sequences, watchers, and ephemeral nodes to coordinate MariaDB clusters and workers across distributed systems without breaking your application.

<PostMeta />

When you build an application, you expect your database to work: connect to an endpoint, run queries, and get results. That's the contract, and your expectation is completely reasonable. Your application should focus on business logic and features, not on distributed database coordination or handling cluster topology changes. That's what infrastructure does.

On Upsun's Dedicated Generation 2 (DG2) architecture, we run MariaDB in a three-node [Galera Cluster](https://galeracluster.com/). Galera is a multi-master setup where any node can accept writes, which provides high availability but creates coordination challenges.

Those challenges belong in the infrastructure layer. We provide you with a stable database endpoint, and behind it runs a resilient cluster. This is where ZooKeeper comes in.

## The coordination challenge

Galera uses a quorum system where transactions must commit to at least two of three nodes before succeeding, which provides strong consistency across the cluster.

The design follows the [CAP theorem](https://en.wikipedia.org/wiki/CAP_theorem), meaning Galera chooses consistency and partition tolerance over constant availability. In practice, transactions can occasionally fail because another node wrote conflicting data, network latency spiked, or the quorum wasn't reachable.

Multi-master databases like Galera are designed for applications to retry on transaction conflicts, but most applications don't implement this retry logic by default. Magento, Drupal, WordPress, and many custom applications connect to a database and expect consistent availability without having to handle these edge cases themselves.

You could solve this in two ways: build retry logic into your application or handle coordination at the infrastructure layer. Given our position, we've chosen to solve this problem at the infrastructure level so it works for most of our customers by default.

## Our approach with ZooKeeper

We handle the complexity at the infrastructure layer. When you provision a triple-redundant MariaDB cluster on Upsun DG2, we expose a single primary write node while the other two nodes serve as read replicas (though they remain capable of accepting writes for failover scenarios).

Your application connects to one stable endpoint, and behind the scenes all nodes stay synchronized through Galera's multi-master replication. This gives you read-after-write consistency and distributed system reliability through a simple interface.

But which node is the primary, and how do we handle transitions when a node becomes unavailable? ZooKeeper answers these questions.

[Apache ZooKeeper](https://zookeeper.apache.org/) is a coordination service originally developed at Yahoo!. It's a hierarchical key-value store that looks like a file system, where the root is `/` and you can create child nodes (called znodes) under any path. Written in Java, it's been doing this job reliably since 2008.

You might know [etcd](https://etcd.io/), which serves a similar purpose, but we chose ZooKeeper for its battle-tested stability and specific features for handling node failures gracefully.

## Three ZooKeeper features that make it work

ZooKeeper gives us three key capabilities that solve the coordination problem: sequences, watchers, and ephemeral nodes. Let's look at each one and how we use it.

### Sequences: Establishing node order

The first challenge is getting all nodes to agree on who's primary, and ZooKeeper solves this with sequential znodes.

When you create a sequential znode, ZooKeeper appends a monotonically increasing number that's consistent across all clients. Even if three nodes create znodes simultaneously, ZooKeeper assigns them an order that all clients see the same way.

Here's what it looks like in Python using the [kazoo](https://kazoo.readthedocs.io/) library:

```python theme={null}
from kazoo.client import KazooClient

zk = KazooClient(hosts='zookeeper:2181')
zk.start()

# Create a sequential znode
path = zk.create(
    '/mariadb/primary/node-',
    b'node-hostname',
    sequence=True,
    ephemeral=True
)

print(f"Created: {path}")
# Output: Created: /mariadb/primary/node-0000000001

# Get all nodes and sort them
children = sorted(zk.get_children('/mariadb/primary'))
primary = children[0]

print(f"Primary node: {primary}")
# Output: Primary node: node-0000000001
```

Each MariaDB node runs a local agent that creates a sequential znode in `/mariadb/primary/`. The first node in the sequence becomes the primary, and all nodes agree on this order because ZooKeeper guarantees consistency. The primary node gets traffic while the others stand by as read replicas.

### Watchers: Staying in sync

What happens when the primary node dies? The other nodes need to know immediately so they can promote a new primary.

ZooKeeper provides watchers, which are one-time notifications that fire when a znode changes. Each node sets a watch on `/mariadb/primary/`, and when nodes join or leave, those watchers fire.

Here's how it works:

```python theme={null}
from kazoo.client import KazooClient

zk = KazooClient(hosts='zookeeper:2181')
zk.start()

def primary_changed(children):
    """Called when the primary list changes"""
    if not children:
        print("No primary available!")
        return

    sorted_children = sorted(children)
    new_primary = sorted_children[0]

    print(f"Primary changed to: {new_primary}")

    # Reconfigure the local proxy to point to new primary
    configure_proxy(new_primary)

# Set up a watch on the primary path
@zk.ChildrenWatch('/mariadb/primary')
def watch_children(children):
    primary_changed(children)
    return True  # Keep watching

def configure_proxy(primary_node):
    """Update local proxy configuration"""
    # This would update iptables or HAProxy configuration
    # to redirect database traffic to the new primary
    pass
```

When the primary node dies, its znode disappears (we'll explain why in a moment), and all watching nodes get notified within seconds. They read the updated list, identify the new primary, and reconfigure their local proxies.

Your application keeps sending queries to the same connection string while we've redirected traffic to a new primary behind the scenes. This works seamlessly because Galera is multi-master, meaning every node can accept writes at any time. The failover happens without you noticing.

### Ephemeral nodes: Automatic cleanup

The third piece is ephemeral nodes, which are znodes tied to a client session that vanish when the client disconnects.

This solves the hardest problem in distributed systems: detecting failures. Did a node die, or did it temporarily lose network connectivity? ZooKeeper handles this through session timeouts.

Here's what an ephemeral node looks like:

```python theme={null}
from kazoo.client import KazooClient

zk = KazooClient(
    hosts='zookeeper:2181',
    timeout=10.0  # Session timeout in seconds
)
zk.start()

# Create an ephemeral sequential znode
path = zk.create(
    '/mariadb/primary/node-',
    b'node-hostname',
    sequence=True,
    ephemeral=True  # Disappears when session ends
)

# Keep session alive by sending heartbeats
while True:
    if not is_mariadb_healthy():
        # MariaDB is down, close connection
        # This removes our ephemeral node
        zk.stop()
        break

    time.sleep(10)

def is_mariadb_healthy():
    """Check if local MariaDB is responding"""
    try:
        # Run: mysql -e "SELECT 1"
        result = subprocess.run(
            ['mysql', '-e', 'SELECT 1'],
            capture_output=True,
            timeout=5
        )
        return result.returncode == 0
    except:
        return False
```

Each node runs an agent that monitors the local MariaDB instance every 10 seconds. If MariaDB responds, the agent keeps the ZooKeeper session alive. If MariaDB stops responding, the agent drops the session, the ephemeral node disappears, and the other nodes see the change through their watchers and reconfigure.

This handles different failure scenarios:

* **MariaDB crashes**: Health check fails, agent drops its session, and the node is removed
* **Network partition**: The node can't reach ZooKeeper, session timeout expires, and the node is removed
* **Entire VM dies**: Session times out and the ephemeral node vanishes

We don't need to distinguish between failure types because any problem that prevents the node from maintaining its ZooKeeper session triggers automatic removal. The cluster heals itself.

## Beyond databases: Worker management

We use the same ZooKeeper pattern for worker processes. Many applications run background workers to process queues, send emails, or generate reports, and while you want workers for high availability, running the same worker on multiple nodes creates problems.

Queue systems like RabbitMQ can coordinate multiple workers so each job gets processed once, but that's extra complexity. What if you could run the worker on one node at a time with automatic failover?

Same ZooKeeper pattern. Each node's agent creates an ephemeral sequential znode in `/workers/email-sender/`, the first node in sequence starts the worker, and the others wait. When that node dies, its ephemeral node disappears, the next node in sequence sees the change, and it starts its worker.

You get high availability without building distributed coordination into your worker code. The worker runs somewhere, and if that node dies, it runs somewhere else. Your application doesn't need to know which node.

## The takeaway

ZooKeeper provides a single source of truth for cluster coordination through three features that work together:

* **Sequences** establish consistent ordering across all nodes
* **Watchers** enable immediate coordination when cluster state changes
* **Ephemeral nodes** provide automatic cleanup when nodes become unavailable

This lets us provide the stable database interface your application expects while running a highly available three-node cluster underneath. You get both reliability and simplicity.

Your application connects to a database endpoint and it behaves as expected. When cluster state changes, a node becomes unavailable, or we perform maintenance, the infrastructure layer handles coordination. This is the robustness principle in practice: we accept applications with standard expectations and provide dependable service.

Infrastructure complexity belongs in the infrastructure layer. You build features for your users, and we'll handle distributed systems coordination.


# Beyond Tool Calling: Understanding MCP's Three Core Interaction Types
Source: https://developer.upsun.com/posts/how-it-works/mcp-interaction-types-article

Discover how prompts, resources, and tools work together in the Model Context Protocol to create richer AI application experiences beyond simple tool calling.


<PostMeta />

The Model Context Protocol (MCP) changes how AI applications connect to external data and services. While most developers have experience with tool calling, MCP offers three distinct interaction types that work together to create richer experiences: **prompts**, **resources**, and **tools**. Understanding these three primitives and when to use each one gives you more control over building AI-powered applications.

## The MCP interaction model

These three interaction types work together through what's known as the "MCP interaction model":

* **Prompts** are user-driven, typically exposed through slash commands or menu options
* **Resources** are application-driven, where the client decides how to use the data
* **Tools** are model-driven, where the AI chooses when and how to call them

This gives you coverage across all three major actors in an AI application: the user, the application, and the model itself.

```mermaid theme={null}
graph TB
    User[👤 User] --> Prompts[📝 Prompts<br/>User-driven]
    App[🖥️ Application] --> Resources[📁 Resources<br/>Application-driven]
    Model[🤖 AI Model] --> Tools[🔧 Tools<br/>Model-driven]
    
    Prompts --> MCP[MCP Server]
    Resources --> MCP
    Tools --> MCP
    
    MCP --> ExternalSystems[External Systems<br/>APIs, Databases, Services]
    
    style Prompts fill:#D0F302,color:#000
    style Resources fill:#6046FF,color:#fff
    style Tools fill:#D0F302,color:#000
    style MCP fill:#000,color:#fff
    style ExternalSystems fill:#fff,color:#000
```

<Note>
  Please refer to the [full Model Context Protocol specification](https://modelcontextprotocol.io/introduction) for more details.
</Note>

## Prompts: User-driven templates for AI interactions

Prompts in MCP are predefined templates that users can invoke directly. Think of them as shortcuts or examples that help users get started with your MCP server's capabilities.

### Why prompts matter

As the creator of an MCP server, you know best how your tools should be used. Prompts let you provide users with working examples they can invoke immediately, rather than expecting them to figure out the right way to phrase their requests.

### How prompts work

The prompt interaction follows a specific flow between the user, client application, and MCP server:

```mermaid theme={null}
sequenceDiagram
    participant User
    participant Client
    participant MCP as MCP Server
    participant API as External API
    
    User->>Client: Invoke prompt "analyze-project"
    Client->>MCP: prompts/get request
    MCP->>API: Fetch live data (logs, code)
    API-->>MCP: Return current data
    MCP->>MCP: Generate dynamic prompt with context
    MCP-->>Client: Return formatted prompt messages
    Client->>Client: Add to AI context
    Client->>User: Display AI response
```

### Dynamic prompt capabilities

Under the hood, prompts are just code, which means they can be dynamic. They can:

* Fetch live data from APIs
* Include current system state
* Offer autocomplete for arguments
* Adapt based on user context

Here's how you might implement a dynamic prompt in TypeScript:

```typescript theme={null}
const PROMPTS = {
  "analyze-project": {
    name: "analyze-project",
    description: "Analyze project logs and code",
    arguments: [
      {
        name: "timeframe",
        description: "Time period to analyze logs",
        required: true
      },
      {
        name: "fileUri", 
        description: "URI of code file to review",
        required: true
      }
    ]
  }
};

server.setRequestHandler(GetPromptRequestSchema, async (request) => {
  if (request.params.name === "analyze-project") {
    const timeframe = request.params.arguments?.timeframe;
    const fileUri = request.params.arguments?.fileUri;
    
    return {
      messages: [
        {
          role: "user",
          content: {
            type: "text",
            text: `Analyze these system logs and code file for issues:`
          }
        },
        {
          role: "user", 
          content: {
            type: "resource",
            resource: {
              uri: `logs://recent?timeframe=${timeframe}`,
              text: await fetchRecentLogs(timeframe),
              mimeType: "text/plain"
            }
          }
        }
      ]
    };
  }
});
```

### When to use prompts

Use prompts when you want to:

* Provide examples of how to use your MCP server
* Give users shortcuts for common workflows
* Include dynamic context that would be tedious to type manually
* Onboard new users with working examples

## Resources: Application-driven data exposure

Resources represent raw data that your MCP server can expose to client applications. Unlike prompts that users invoke or tools that models call, resources are consumed by the application itself.

### The power of application choice

Resources give applications complete freedom in how they use your data. A client might:

* Build embeddings for retrieval-augmented generation (RAG)
* Cache frequently accessed data
* Transform data for specific use cases
* Combine multiple resources in novel ways

```mermaid theme={null}
graph LR
    MCP[MCP Server] --> |exposes| Resources[📁 Resources]
    Resources --> App1[🔍 RAG System<br/>Build embeddings]
    Resources --> App2[💾 Cache Layer<br/>Store frequently used data]
    Resources --> App3[📊 Analytics<br/>Transform & analyze]
    Resources --> App4[🔄 Integration<br/>Combine multiple sources]
    
    style MCP fill:#000,color:#fff
    style Resources fill:#6046FF,color:#fff
    style App1 fill:#D0F302,color:#000
    style App2 fill:#D0F302,color:#000
    style App3 fill:#D0F302,color:#000
    style App4 fill:#D0F302,color:#000
```

### Resource types

MCP supports two types of resources:

**Direct resources** have fixed URIs and represent specific data:

```typescript theme={null}
{
  uri: "file:///logs/app.log",
  name: "Application Logs", 
  mimeType: "text/plain"
}
```

**Resource templates** use URI templates for dynamic resources:

```typescript theme={null}
{
  uriTemplate: "database://table/{tableName}/schema",
  name: "Database Schema",
  description: "Schema for any table",
  mimeType: "application/json"
}
```

### Implementing resources

Here's a Python example showing how to expose database schemas as resources:

```python theme={null}
@app.list_resources()
async def list_resources() -> list[types.Resource]:
    return [
        types.Resource(
            uri="database://schema/users",
            name="Users Table Schema",
            mimeType="application/json"
        ),
        types.Resource(
            uri="database://schema/orders", 
            name="Orders Table Schema",
            mimeType="application/json"
        )
    ]

@app.read_resource()
async def read_resource(uri: AnyUrl) -> str:
    if str(uri).startswith("database://schema/"):
        table_name = str(uri).split("/")[-1]
        schema = await get_table_schema(table_name)
        return json.dumps(schema)
    
    raise ValueError("Resource not found")
```

### When to use resources

Use resources when you want to:

* Expose raw data for the application to process
* Enable RAG implementations
* Provide data that applications might cache or index
* Support multiple data consumption patterns

## Tools: Model-driven actions

Tools are the most familiar MCP primitive—functions that the AI model can choose to call during conversations. They represent actions your MCP server can perform.

### Tool design principles

Effective tools should:

* Have clear, descriptive names
* Include comprehensive descriptions
* Define precise input schemas
* Return structured, helpful results

### Tool implementation

Here's a TypeScript example of a calculation tool:

```typescript theme={null}
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [{
      name: "calculate_sum",
      description: "Add two numbers together",
      inputSchema: {
        type: "object", 
        properties: {
          a: { type: "number" },
          b: { type: "number" }
        },
        required: ["a", "b"]
      }
    }]
  };
});

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === "calculate_sum") {
    const { a, b } = request.params.arguments;
    return {
      content: [
        {
          type: "text", 
          text: String(a + b)
        }
      ]
    };
  }
  throw new Error("Tool not found");
});
```

### How tools work in practice

Tools follow the familiar function calling pattern, but within the MCP framework:

```mermaid theme={null}
sequenceDiagram
    participant User
    participant Client
    participant Model as AI Model
    participant MCP as MCP Server
    participant System as External System
    
    User->>Client: "Calculate the sum of 5 and 3"
    Client->>Model: Send message with available tools
    Model->>Model: Decide to use calculate_sum tool
    Model->>Client: Tool call request
    Client->>MCP: tools/call calculate_sum
    MCP->>System: Perform calculation
    System-->>MCP: Return result
    MCP-->>Client: Tool result
    Client->>Model: Provide tool result
    Model->>Client: Generate response with result
    Client->>User: "The sum is 8"
```

### When to use tools

Use tools when you want the AI to:

* Perform actions on behalf of users
* Query external systems
* Transform or process data
* Make decisions about when to invoke functionality

## Bringing it all together: A GitHub issue tracker example

Here's how these three primitives work together in a GitHub issue tracker MCP server:

```mermaid theme={null}
flowchart TD
    User[👤 Developer]
    App[🖥️ AI Application]
    Model[🤖 AI Model]
    
    User --> Prompts[📝 Prompts<br/>Summarize recent issues<br/>Review PR feedback]
    App --> Resources[📁 Resources<br/>Repository metadata<br/>Issue lists & histories<br/>Pull request data]
    Model --> Tools[🔧 Tools<br/>Create issue<br/>Update labels<br/>Assign team members<br/>Search repositories]
    
    Prompts --> MCP[GitHub MCP Server]
    Resources --> MCP
    Tools --> MCP
    
    MCP --> GitHub[🐙 GitHub API]
    
    style Prompts fill:#D0F302,color:#000
    style Resources fill:#6046FF,color:#fff
    style Tools fill:#D0F302,color:#000
    style MCP fill:#000,color:#fff
    style GitHub fill:#fff,color:#000
```

**Prompts** provide shortcuts like "summarize recent issues" with autocomplete for project repositories and milestones, giving users an easy way to catch up on project status and outstanding work.

**Resources** expose repository metadata, issue lists, pull request data, and commit histories that applications can use for embeddings, caching, or building comprehensive project dashboards.

**Tools** handle actions like creating issues, updating labels, assigning team members, and searching across repositories that the AI can invoke as needed based on user requests.

This combination allows users to interact with GitHub repositories through natural language while giving applications the flexibility to process GitHub data in sophisticated ways.

By using all three interaction types together, you create a much richer experience than tool calling alone could provide.

## Building richer MCP experiences with Upsun

When you're building MCP servers that take advantage of these three interaction types, you need a platform that can handle the complexity. Upsun's Cloud Application Platform provides the infrastructure you need:

* **Preview environments** let you test MCP server changes in production-like environments
* **Multi-app architecture** supports complex MCP implementations with multiple services
* **Built-in observability** helps you monitor MCP server performance and usage
* **Git-driven infrastructure** ensures your MCP server deployments are consistent and version-controlled

The combination of prompts, resources, and tools gives you powerful building blocks for AI applications. With Upsun handling the infrastructure complexity, you can focus on creating innovative MCP servers that provide real value to users.

Ready to build your own MCP server? [Start with a free Upsun account](https://upsun.com/) and explore how these interaction types can transform your AI applications.


# Centralising Upsun Technical References with Meta-Upsun
Source: https://developer.upsun.com/posts/how-it-works/meta-reference-source-introduction

How Upsun centralised runtime, service, region, and PHP reference data into a single public API to improve consistency, automation, and documentation accuracy.


<PostMeta />

Keeping technical reference data accurate, up-to-date, and reusable across teams is harder than it looks—especially at scale.

<img alt="Meta-Upsun architecture" />

At Upsun, many parts of our platform rely on *reference information*: supported runtime versions, service images, PHP extensions, public regions, deprecated versions, and more. These data sets power our documentation, validation tools, internal workflows, and are increasingly consumed by ecosystem tooling. Our clients also need this information for their own business automation (business operations and therefore increased demand). Many customers ask for this kind of information, and Meta-Upsun allows us to provide such info in a broader format.

Over time, this information had grown fragmented.

This post explains **why we built Meta-Upsun**, what problems it solves, how it fits into the future of Upsun’s documentation and tooling ecosystem, and how the Upsun platform—through its agile-friendly features—enabled us to deliver this solution in a very short timeframe.

## The problem: reference data everywhere

Historically, Upsun’s technical reference data lived in multiple places:

* YAML and JSON files embedded directly in the documentation repository
* Registry files manually updated by Technical writers
* Data duplicated or reinterpreted by external tools
* Updates spread across several repositories, each with its own lifecycle

In total we were dealing with reference material scattered across 36 different Git repositories with branch variations for our internal images, plus 4 upstream API calls (including [endoflife.date](https://endoflife.date) and the [Upsun API](https://docs.upsun.com/api)) that fed version lifecycles and status.

This approach had several drawbacks:

* ❌ **Manual updates** were time-consuming and error-prone
* ❌ **Hard to find the source of truth** for technical writers
* ❌ **Inconsistent data** between docs, tooling, and internal usage
* ❌ **Poor reusability** for teams outside the documentation pipeline
* ❌ **Slow iteration** when adding or deprecating versions

As the number of supported services, runtimes, and regions increased, maintaining these files by hand simply didn’t scale anymore.

## Introducing Meta-Upsun: Upsun reference, centralised

To address this, we built **Meta-Upsun**, a publicly exposed infrastructure component designed to centralise Upsun’s technical reference data in a single place.

👉 [https://meta.upsun.com](https://meta.upsun.com)

Meta-Upsun acts as a **single source of information** for everything that defines *what Upsun supports*.

It provides:

* A unified registry for images, runtimes, regions, and extensions
* A **read-only API**, consumable by humans and machines
* Granular access to specific data (for example, only PHP image versions)
* Outputs in **JSON or YAML**, depending on your needs

The goal is simple: **one canonical location for reference data**, consumed everywhere else.

## A read-only, versioned API

Meta-Upsun exposes its data through a versioned REST API:

* 📘 OpenAPI / Scalar documentation
  👉 [https://meta.upsun.com/api-docs](https://meta.upsun.com/api-docs)

* 🔒 **Read-only by design**
  No write endpoints, no mutations from consumers.

* 🧩 **Granular access**
  You can fetch:
  * All images or a single runtime
  * Only versions
  * Regions filtered by provider or geographic zone
  * PHP extensions per version and distribution

If you just want the complete image registry, the main endpoint is:

* `GET /image` → [https://meta.upsun.com/api-docs#tag/images/GET/image](https://meta.upsun.com/api-docs#tag/images/GET/image)

<img alt="Meta-Upsun Scalar - Get Image screenshot" />

The Scalar UI lets you explore endpoints interactively and generate ready-to-run client snippets (`curl`, and other languages).

## Reliability and validation built-in

Accuracy is critical for reference data. Meta-Upsun enforces it at multiple levels:

* ✅ **Schema validation** of registry files (currently for `registry.json`, with more coming)
* ✅ **Human validation via pull requests**: all updates go through PRs
* ✅ **Versioned endpoints**, already used by the next generation of Upsun documentation
* ✅ **Consistent structure**, enforced by OpenAPI and runtime validation

This combination gives us confidence that the data exposed by Meta-Upsun is both **machine-safe and human-reviewed**.

## Aligning registry status with upstream support

In the early days the registry simply split versions into `supported` and `deprecated` buckets:

```json theme={null}
"versions": {
  "deprecated": [
    "5.0",
    "3.1",
  ],
  "supported": [
    "8.0",
    "7.0",
    "6.0"
  ]
}
```

Supported meant Upsun shipped the image, and deprecated meant Upsun no longer actively supported it. That naming did not match the official runtime/service version taxonomy, so Meta-Upsun now classifies every version according to the upstream lifecycle, most of which we track via endoflife.date.

* **Active / supported** – the version is still in upstream active support.
* **Deprecated** – active support has ended, only critical security updates land.
* **Retired** – the community considers the version end-of-life, we keep the image available “as-is” for roughly 180 days while customers switch, but we stop applying patches.
* **Decommissioned** – the image is removed and can no longer be built; projects both old and new will fail to build against it.

```json theme={null}
"versions": {
  "8.5": {
    "upsun": {
      "status": "supported"
    }
  },
  "8.3": {
    "upsun": {
      "status": "deprecated"
    }
  },
  "8.1": {
    "upsun": {
      "status": "retired"
    }
  },
  "5.3": {
    "upsun": {
      "status": "decommissioned"
    }
  },
```

We still make sure the highest upstream image we offer is fully supported by Upsun, but Meta-Upsun now mirrors the official naming so that anyone consuming `registry.json` (human or machine) understands exactly where a version stands.

We will cover this change in more depth in a follow-on episode that unpacks how [Meta-Upsun](https://meta.upsun.com) now exposes the registry structure and what consumers should expect.

## How Meta-Upsun fits into the ecosystem

Meta-Upsun is designed as a shared infrastructure layer. The typical consumers look like this:

<img alt="Meta-Upsun architecture" />

## Powering the next generation of documentation

Meta-Upsun is already used internally as a foundation for future-facing projects.

One concrete example:
we are currently migrating our documentation stack.
Instead of embedding reference data directly in Markdown files, the new documentation can consume Meta-Upsun’s API endpoints to display:

* Supported, deprecated and retired versions
* Runtime and service matrices
* PHP extensions per version
* Region availability

This ensures that the documentation always reflects the **current state of the platform**, without manual duplication.

> This topic is covered in more detail in a dedicated blog post, which we’ll link here once published.

## Leveraging Upsun’s agility

Upsun’s platform helped us move fast: we relied on its reusable infrastructure (CI/CD, environments, observability hooks, and deployment artifacts) to build Meta-Upsun iteratively, validate it in staging, and ship updates within days rather than weeks.
This solution is a direct benefit of Upsun’s focus on enabling agile delivery for internal and customer-facing tooling.
Several Upsun teammates contributed to this project, each bringing ideas or validations from their domain to help accelerate delivery.

## What’s next

Meta-Upsun is not just a backend for documentation.

It is designed to be consumed by:

* Internal tooling
* Validation pipelines
* External teams and ecosystem tools

In the next article, we’ll dive into **Meta-Upsun Version Updater**, the automation layer that keeps Meta-Upsun aligned
with upstream runtimes, service releases, and platform reality—without manual effort.
Another upcoming episode will focus on the registry structure changes on [Meta-Upsun](https://meta.upsun.com)
and how we now align the version categorisation with upstream lifecycle terminology.

## Links

* Upsun Docs: [https://developer.upsun.com/docs](https://developer.upsun.com/docs)
* Meta-Upsun: [https://meta.upsun.com](https://meta.upsun.com)
* API docs (Scalar): [https://meta.upsun.com/api-docs](https://meta.upsun.com/api-docs)
* Get Images: [https://meta.upsun.com/api-docs#tag/images/GET/image](https://meta.upsun.com/api-docs#tag/images/GET/image)
* Get Regions: [https://meta.upsun.com/api-docs#tag/regions/GET/region](https://meta.upsun.com/api-docs#tag/regions/GET/region)
* Get PHP Extensions: [https://meta.upsun.com/api-docs#tag/extensions](https://meta.upsun.com/api-docs#tag/extensions)
* `config.yaml` validation schema: [https://meta.upsun.com/api-docs#tag/validation](https://meta.upsun.com/api-docs#tag/validation)
* Upsun OpenAPI specification: [https://meta.upsun.com/api-docs#tag/openapi](https://meta.upsun.com/api-docs#tag/openapi)

***

To learn more about Upsun, visit our comprehensive [documentation](https://docs.upsun.com).


# Natural scaling for multi-country ecommerce
Source: https://developer.upsun.com/posts/how-it-works/natural-scaling-for-multi-country-ecommerce

Multi-country ecommerce is a textbook case for natural scaling. Instead of cramming every country into one store, give each its own. Here's why.


<PostMeta />

A few weeks ago, I wrote about [a third way to scale](/posts/insights/the-third-way-to-scale-that-nobody-talks-about) that doesn't get enough attention. The idea: instead of scaling one application up or out, you run many small, independent applications. Each one handles a subset of your users and never grows large enough to need scaling. I called it "natural scaling."

Since then, I keep running into the same example. One that fits natural scaling so well it's almost too perfect.

Multi-country ecommerce.

## Everything is different anyway

Here's what happens when you expand your online store to a new country. The product names change. The prices change. The VAT rates differ. The catalog itself might change because some products only make sense in certain markets.

You're not serving the same data with a different language pack on top. You're running a different store. The data is fundamentally different.

So why fight it? Why cram all of that into one application and build the complexity to manage it? You'd need multi-tenant data isolation, per-country pricing logic, catalog filtering, localized tax calculations, all layered on top of your existing store.

Or you could give each country its own store. Separate application, separate data, separate URL. The complexity doesn't disappear, but it moves from your application code to your operations. And that's a trade-off worth making.

## Beyond the application

The argument I hear most often: "My framework already supports multi-store setups. I can run 5 countries from one backend."

Fair. Most ecommerce frameworks do support this. But a store isn't an application in a vacuum. It's an application plus everything around it: backups, monitoring, deployment pipelines, infrastructure.

When all your countries share one backend, they share everything. That includes the constraints.

### Backup strategies

Regulations vary by country. Some have strict data residency requirements. Others don't. If all countries live in one database, your backup strategy has to satisfy the most demanding regulation. That means paying for compliance everywhere, even where it isn't required.

With separate stores, you match the backup strategy to each country's requirements. Strict regulations for the countries that need them. A lighter approach for those that don't. You spend money where it matters.

### Maintenance windows

Every application needs maintenance at some point. Database migrations, platform upgrades, the occasional "we need 10 minutes of downtime" situation.

If your store serves customers across multiple time zones from one backend, there's no 4 AM. Someone, somewhere, is wide awake and trying to buy something. You either accept that your maintenance window hits peak hours for some country, or you try to find the mythical window where everyone is asleep (spoiler: it doesn't exist).

Separate stores, separate maintenance windows. Your French store goes down at 4 AM CET. Your Australian store goes down at 4 AM AEST. Each country gets maintenance during their actual off-peak hours.

And yes, some countries span multiple time zones. The U.S. is the classic example. Nothing stops you from running separate stores for the East Coast and West Coast if that's what your traffic patterns justify. Natural scaling doesn't care about political boundaries. It cares about what makes operational sense.

### Data proximity

You want your data close to your customers. This is true for both sovereignty reasons and performance.

Everything should be behind a CDN at this point, that's table stakes. But a CDN doesn't solve the origin problem. Cart operations, checkout flows, account management, these are dynamic requests that hit your origin server. If that origin is in Virginia and your customer is in Tokyo, physics wins. The round trip adds latency that no amount of edge caching can fix.

With one store per country (or region), the origin server lives close to the customers it serves. When a request has to reach the origin, that origin is local. Every request is faster, not because you optimized your code, but because you shortened the wire.

## The honest drawback

I won't pretend this is free. Natural scaling trades application complexity for operational complexity. Instead of managing one store, you're managing many.

Deploying a change means deploying it to every store. A security patch has to roll out across your entire fleet. Configuration drift becomes a real concern if you don't have solid automation.

This is the part where you need to be comfortable operating at scale. You need reliable CI/CD pipelines, infrastructure-as-code, and the discipline to treat your stores as a fleet rather than a collection of snowflakes.

[Upsun](https://upsun.com) can help here. The platform is built around the idea that provisioning and managing many isolated environments should be straightforward, not a months-long infrastructure project. But even with good tooling, operating many stores is a different discipline than operating one. It's worth being honest about that.

## When this makes sense

If your multi-country expansion means localizing a landing page and swapping the currency symbol, you probably don't need separate stores. A single application with i18n support will do fine.

But if each country has its own catalog, its own pricing, its own tax rules, and its own regulatory requirements, you're already running different stores. You're running them on the same infrastructure and pretending they're one thing. That pretense has a cost in complexity, in deployment risk, and in operational constraints.

One thing to check before going down this road: your ecommerce platform's license model. Some vendors charge per installation or per instance. If that's the case, running 15 country-specific stores means 15 licenses. That can turn a reasonable software cost into a significant line item. It's worth checking how your vendor counts installations (by domain, by instance, by environment) before committing to this approach.

Natural scaling says: stop pretending. Let each store be what it already is. An independent application, with its own data, its own infrastructure, and its own operational lifecycle. They can share the same codebase. They probably should. But they run independently.

It's more stores to manage. But each one is simpler. And in my experience, many simple things are easier to operate than one complicated thing.


# Upsun and Elasticsearch: A tale of love, loss, and licensing roadblocks
Source: https://developer.upsun.com/posts/how-it-works/psh-elastic-love-loss-licensing



<PostMeta />

[Elasticsearch](https://www.elastic.co/) is a distributed **search engine designed for speed, scalability, and reliability**. Built on [Apache Lucene](https://lucene.apache.org/), it allows you to store, search, and analyze large volumes of data in near real-time.

Elasticsearch is widely used for applications like website and ecommerce search, making it a popular choice for enterprises needing robust search capabilities.

Elasticsearch is one of our most successful managed services, powering the search of hundreds of projects. Our products broadly support Elasticsearch, from version 1.4 to the latest 8.x releases.

<Note>
  For Upsun (and Platform.sh) customers , the current situation is unchanged:

  * All versions below 7.10 are available and deprecated.
  * Elasticsearch 7.17 and 8.5 come with an additional charge, as premium services.
  * Opensearch is a viable alternative to Elasticsearch.
  * New versions of Elasticsearch will be released as premium services.
</Note>

Feel free to join us on the [community forum](https://community.upsun.com/), or any other ways to discuss this with our team.

# The issue at hand

Over the years, the Elasticsearch licenses have evolved:

**Before 2021:** the majority of the code was under an Apache 2.0 license.\
**After 2021, dual-licensed:** The Apache 2.0 licensed code [changed](https://www.elastic.co/blog/why-license-change-aws) to a dual license under the Service Side Public License (SSPL) and the Elastic License (EL).\\

**In August 2024, triple-licensed:** The GNU Affero General Public License (AGPLV3) is [another option](https://www.elastic.co/blog/elasticsearch-is-open-source-again), alongside ELv2 and SSPL.

All our services are offered as managed services. From that perspective, here are the main differences between the four licenses:

* Apache 2.0: A permissive license that can be provided as a managed service.
* [SSPL](https://www.mongodb.com/legal/licensing/server-side-public-license): A server side public license that requires **releasing the source code for the entirety of the service**. This includes all "management software, user interfaces, application program interfaces, automation software, monitoring software, backup software, storage software and hosting software, all such that a user could run an instance of the service using the Service Source Code you make available". For Upsun, this means all our tooling must be released to manage the service. The SSPL is the license used by MongoDB and now Redis too.
* AGPLV3: This license is compatible with managed services and requires that any modifications made to softwares under the same license must also be published.
* Elastic License V2: a commercial license that is compatible with reselling Elasticsearch as a managed service.

That gives us the following landscape:

* All versions below 7.10: all of these versions have been deprecated for several years but are still available to be used with no additional charge.
* Elasticsearch 7.17 and 8.5: There is an additional charge when using Elasticsearch 7.17 and 8.5 as these are classed as premium services.

After the latest license change, we thought it was going to be a game changer for our customers, with several new AI features to be leveraged.

# The licensing issue to using new Elasticsearch releases

Our customers asked us to provide Elasticsearch 8.16, free of charge, so we started to do our homework to provide it.

At Upsun, services are built using internal tooling, driven by a configuration file with multiple attributes and the required packages. For elasticsearch "premium", it looks like this:

```yaml theme={null}
elasticsearch:
	url: https://artifacts.elastic.co/packages/8.x/apt

packages:
	elasticsearch: "= 8.5.3"
```

So for elasticsearch 8.16, we thought it would be as easy as replacing 8.5.3 by 8.16.x. That would be it. **But you need to pay attention to one sentence on the ["Elastic FAQ on Software Licensing"](https://www.elastic.co/pricing/faq/licensing) page**.

The sentence that caught our attention states the following: "Our releases will continue to be under the Elastic License.".
It should be noted that the Elastic FAQ page is the go-to page when you have questions about Elasticsearch Licensing. It has existed since the SSPL switch.
We verified the [download page](https://www.elastic.co/downloads/elasticsearch) and confirmed the distributed software uses Elastic License 2.0.

<img alt="Download Page for ES|654x399" />

It was also confirmed by a [post](https://discuss.elastic.co/t/elasticsearch-binaries-and-images-be-coverd-by-the-agpl-license/367084) in the Elastic forum that they: "do not currently offer any downloadable distribution that is covered by the AGPL."

At that point we knew that if we wanted to support Elasticsearch again, we would need to put in more effort as we can't use the prebuilt releases.

# Let's build it!

In the images team, we are a bit stubborn. If we can't use the available packages, we build our own. It's not because it's in Java, using Gradle that we can't do it.

We started by a nice discussion with our legal team, to discuss what we could do and agreed on:

* build Elasticsearch from the unmodified[ sources](https://github.com/elastic/elasticsearch)
* publish the resulting Debian package under AGPL V3 in a publicly accessible Github repository

Our engineering team cloned the repository and started triggering the Gradle tooling.

Surprisingly, they didn't create an AGPL V3 build. It appears that the code to build the OSS flavor of Elasticsearch has been removed, as confirmed by the following pull requests:

* Remove all OSS distribution references from Elasticsearch build [#68797](https://github.com/elastic/elasticsearch/issues/68797)
* Remove OSS specific distribution packaging [#69775](https://github.com/elastic/elasticsearch/pull/69775)

We dug a bit, and the original work was sent upstream in pull requests by AWS as explained[ here](https://aws.amazon.com/blogs/opensource/stepping-up-for-a-truly-open-source-elasticsearch/) and removed in the previous license change:

> "changes to Elasticsearch were sent as upstream pull requests ([#42066](https://github.com/elastic/elasticsearch/pull/42066),[ #42658](https://github.com/elastic/elasticsearch/pull/42658),[ #43284](https://github.com/elastic/elasticsearch/pull/43284),[ #43839](https://github.com/elastic/elasticsearch/pull/43839),[ #53643](https://github.com/elastic/elasticsearch/pull/53643),[ #57271](https://github.com/elastic/elasticsearch/pull/57271),[ #59563](https://github.com/elastic/elasticsearch/pull/59563),[ #61400](https://github.com/elastic/elasticsearch/pull/61400),[ #64513](https://github.com/elastic/elasticsearch/pull/64513)), and we then included the "oss" builds offered by Elastic in our distribution. This ensured that we were collaborating with the upstream developers and maintainers, and not creating a "fork" of the software."

So, it's not easy to build an AGPL v3 package for Elasticsearch; **the code simply doesn't have the tooling**.

# Let's modify the build tooling!

We went back to our legal team, to discuss what we could do, and agreed on:

* fork the Elasticsearch[ repository](https://github.com/elastic/elasticsearch)
* update the Gradle tooling to build an OSS distribution
* on a public repository, under AGPL V3:
* share all the code
* share the build artifacts
* send an email to Elasticsearch explaining what we did

The source code is not consistent in terms of license; some parts are under a triple license, including the open source license AGPL v3, and some are under the non-open source Elastic License 2.0. We are not allowed to provide a service with non-open source licenses, thus our only choice was to remove the following two folders from the build:

* [x-pack](https://github.com/elastic/elasticsearch/tree/main/x-pack)
* [apm](https://github.com/elastic/elasticsearch/tree/main/modules/apm)

## Have you met x-pack?

`x-pack` is an Elastic extension that provides various capabilities, including the security layer. It has been in Elasticsearch for a long time, as a paid extension, and it has a "turbulent" life of its own: ["Doubling Down on Open"](https://www.elastic.co/blog/doubling-down-on-open).

As previously mentioned, we had to remove the x-pack folder to build an open source package.

However, once we removed x-pack, Elasticsearch wouldn't start anymore; the code is coupled to x-pack's security features. You can't turn that off.

```bash theme={null}
root@644e331111:/mnt# /usr/share/elasticsearch/bin/elasticsearch
java.io.UncheckedIOException: java.nio.file.NoSuchFileException: /usr/share/elasticsearch/modules/x-pack-core
    	at org.elasticsearch.cli.CliToolProvider.loadJars(CliToolProvider.java:87)
    	at org.elasticsearch.cli.CliToolProvider.load(CliToolProvider.java:59)
    	at org.elasticsearch.server.cli.ServerCli.loadTool(ServerCli.java:262)
    	at org.elasticsearch.server.cli.ServerCli.autoConfigureSecurity(ServerCli.java:171)
    	at org.elasticsearch.server.cli.ServerCli.execute(ServerCli.java:91)
    	at org.elasticsearch.common.cli.EnvironmentAwareCommand.execute(EnvironmentAwareCommand.java:55)
    	at org.elasticsearch.cli.Command.mainWithoutErrorHandling(Command.java:95)
    	at org.elasticsearch.cli.Command.main(Command.java:52)
    	at org.elasticsearch.launcher.CliToolLauncher.main(CliToolLauncher.java:65)
Caused by: java.nio.file.NoSuchFileException: /usr/share/elasticsearch/modules/x-pack-core
    	at java.base/sun.nio.fs.UnixException.translateToIOException(UnixException.java:92)
    	at java.base/sun.nio.fs.UnixException.asIOException(UnixException.java:115)
    	at java.base/sun.nio.fs.UnixFileSystemProvider.newDirectoryStream(UnixFileSystemProvider.java:502)
    	at java.base/java.nio.file.Files.newDirectoryStream(Files.java:482)
    	at java.base/java.nio.file.Files.list(Files.java:3796)
    	at org.elasticsearch.cli.CliToolProvider.loadJars(CliToolProvider.java:78)
    	... 8 more
```

But as we investigated more, we found a way to tweak the code make it work without x-pack.

## Secure, very secure

We noticed Elasticsearch [sets up security before ](https://github.com/elastic/elasticsearch/blob/main/distribution/tools/server-cli/src/main/java/org/elasticsearch/server/cli/ServerCli.java#L90)executing the server. The code below calls `secureSettingsLoader.supportsSecurityAutoConfiguration()` to decide if it enables security or not.

```java theme={null}
try (
   var loadedSecrets = secureSettingsLoader.load(env, terminal);
   var password = (loadedSecrets.password().isPresent()) ? loadedSecrets.password().get() : new SecureString(new char[0]);
) {
   SecureSettings secrets = loadedSecrets.secrets();
   if (secureSettingsLoader.supportsSecurityAutoConfiguration()) {
   	env = autoConfigureSecurity(terminal, options, processInfo, env, password);
   	// reload or create the secrets
   	secrets = secureSettingsLoader.bootstrap(env, password);
   }
```

However, the [implementation](https://github.com/elastic/elasticsearch/blob/1bcb68d03f0d3d8cf24365bb705a44d4febafd1b/distribution/tools/server-cli/src/main/java/org/elasticsearch/server/cli/KeyStoreLoader.java#L42) of the method could not be anything but a surprise. The method always returns true! Elasticsearch is very secure, indeed.

```java theme={null}
public boolean supportsSecurityAutoConfiguration() {
   return true;
}
```

We were not ready to give up yet. It seemed just a simple matter of overriding it to return false.
Well, after preventing the security configuration, all hell broke loose again. The Elasticsearch server [expects secrets to be in place](https://github.com/elastic/elasticsearch/blob/fd25d3bd8228fae46a09b9895dddfaa1bc7a5537/server/src/main/java/org/elasticsearch/bootstrap/ServerArgs.java#L57). It does not even let you pass secrets as null, as we can see from the code snippet below.

```java theme={null}
public ServerArgs {
   assert pidFile == null || pidFile.isAbsolute();
   assert secrets != null;
}
```

The assert does not allow secrets to be `null`. Unfortunately, when security is not configured, the `secrets` ends up being `null`!

Finding ourselves at a crossroads again, we realized something.

# Wait, are we really forking Elasticsearch?

At that point, we took a step back, looking at what we were doing. We realized that "we are forking Elasticsearch":

* We forked the repository
* We deeply modified the code, involving complicated maintenance and version upgrades
* We were proposing a new build

It probably can't be named Elasticsearch anymore; it's more than just different tooling, it's a different software altogether.

# Let's not fork it?

We stopped our efforts and decided to publish this blog post, communicating openly about the current status.

It's not our business to maintain a fork of Elasticsearch; it will require a new name and the maintenance cost will be huge: for each version, an engineer needs to update the code.

And honestly, we do not want to fork it.

It's not the end of the journey; the team is ready to reopen the project at any time. The distribution license may change, or the OSS build added back to the repository.

**And remember: Upsun ❤️ Elasticsearch**


# How repeatable deployments work
Source: https://developer.upsun.com/posts/how-it-works/repeatable-deployments

Platform.sh ensures predictable, repeatable deployments by controlling the key inputs to your application and guaranteeing code consistency.

<PostMeta />

One of the key selling points of Platform.sh is predictable, repeatable deployments. We view the read-only production
file system as a key advantage for our customers. But why is that, and how do we manage it? Just how repeatable and
predictable is it?

The key to reliability is predictability. If I know my code works in testing, I should be able to predict, with a
very high degree of confidence, that it will work in production, too. To do that, we need to minimize the number of
variables that differ between staging and production. Zero is ideal, but anything close to zero is generally good
enough.

At Platform.sh, the build process for all environments, production or not, is exactly the same. And the inputs to that
build process are all consistent and largely predictable.

Overall there are four inputs to any running application:

* Your code, as tracked by Git. That includes any configuration directives in Platform.sh configuration files, your
  php.ini file, etc.
* Any 3rd party dependencies that are downloaded at build time, such as from Composer, npm, or Ruby gems.
* Any configuration variables defined in a project via the UI.
* The underlying container image we provide.

If those inputs are all the same, the output should be identical. (Functional programming DevOps?) So when can those
change?

## Your container

First of all, let’s clarify exactly how an application container works. There are three parts to every container: The
container image, the application image, and the writeable file system.

The container image is provided by us, and contains nginx, the runtime appropriate for your application (PHP, Python,
etc.), and custom tools we built to manage our orchestration. It is shipped as a read-only file system, using squashfs.
It gets mounted at  `/`.

The application image is the result of running your build hook on the code in your git repository. The resulting files
are compressed into a read-only file system, using squashfs, and mounted at `/app`.

The writeable file system is specified by your [`.platform.app.yaml`](https://docs.platform.sh/overview/yaml/what-is-yaml.html) file, and can be zero or more locations that get mounted as writeable disks at a directory (under `/app`) that you specify.

When Platform.sh “deploys” your container, it means we:

* “Close” the application container so it doesn’t accept new requests
* Shutdown the container
* Replace the container image with a new version, if there is one
* Replace the application image
* Mount the writeable file system
* Inject any configured environment variables
* Run user-specified deploy hooks
* ”Open” the application container to accept requests again

## Assembling the container

Now that we know how a container works, let’s look at those inputs again.

### Your code

Your code in Git, of course, only changes when you tell it to. That’s the point of Git. It changes only when you want it
to change. It changes only on the branch you want to change. You can merge to another branch, at which point that branch
has changed because you wanted it to change. It’s entirely under your control.

### 3rd party code

3rd party dependencies depend primarily on the configuration in your code, in Git. Most package managers these days
support a lock file (such as `composer.lock` for PHP) that will ensure that the exact same code is downloaded every
time, even if a newer version is available. That’s why you should always check your lock file into your Git repository
for an application. That way, your 3rd party dependencies are entirely under your control.

### Environment variables

Environment variables are configured by you, through either the Platform CLI or the web interface. They can be any
values you want, but are mostly useful for things like API keys, login credentials, and other values that should not be
in Git (either for security reasons or because they need to be different between a Platform.sh environment and your
local environment). Because these are set by you, the user, they’re entirely under your control.

### The container image

The container image is the only input that is controlled by Platform.sh, not by the user. We currently have over a dozen
container images for various languages and language versions. We only release new versions of these when there’s a new
version of our integration software available or there’s a bug or security fix in one of the tools we include. That
means new bugfix or security releases of PHP or Python, or an update to nginx, for instance. We will never change your
container type out from under you (say, switching from PHP 5.5 to 7.0), but we may update the type as needed (such as
the monthly security release of PHP 7.0.x).

## The guarantee

Of particular note is that everything that goes into the application image (your code and 3rd party code) is controlled
by Git, and Git is controlled by you, thus the application image is based exclusively on things within your control. It
also means it’s predictable for us, too: If the hash of all files in a given branch already exists, and we’ve already
built a container image for it, then we know, with certainty, that the resulting application image would be the same,
too. That means we don’t even rebuild it, saving time and resources. (We don’t use the git hash directly for that, as if
you have multiple application containers we want to treat them separately.)

It also guarantees consistency for your deployment. Suppose you have a branch `feature-x` on which you’ve done some
development and deployed it to a Platform.sh dev environment. That means we’ve built an application image out of it. Now
you merge it back to `master`. As long as the merge is a fast-forward merge in Git, the files that were at the HEAD of
the `feature-x` branch will now be identical to the `master` branch. Identical files means we can reuse the existing
application image.

Your application image in production isn’t just like the one that was in your feature branch. It *is* the one that was
in your feature branch. The same exact bits.

## What can still vary

While the application image is reused as-is, the container image may get a new version if one is available. That will
only be different from the dev branch if a new version has been released between when you last pushed to that branch and
when you merged it to `master`. The odds of that are low, but if you want to be certain you can always
add an empty commit to the dev branch to trigger a deploy, which would pick up a new container image if one exists. If
all is well, merge to `master` with confidence.

The writeable file system may also vary between production and a development environment. When a new environment is
created its data is cloned from production, but depending on how long your dev environment lives before getting merged
the two could diverge. Again, if you want to be sure just click the “Sync” button in the UI to copy production’s data to
your dev environment and check it over. It only takes a minute or two, regardless of how much data you have.

Your environment variable configuration may also vary between environments, but in that case it’s generally because you
want it to; you don’t want your development instance sending purchase orders with real credit cards against a real
payment gateway. (At least, we assume not.)

So there you have it: Absolutely identical code between development and production, and usually absolutely identical
environments (that can be guaranteed identical if you want them to be). It’s as close to functional programming as
DevOps can get, and it’s just another day at the office around here.

Happy deploying!


# How we host an RPM repository on AWS S3
Source: https://developer.upsun.com/posts/how-it-works/rpm-repo-s3

Learn how to host an RPM repository entirely on AWS S3 with no active components, minimal cost, and authenticated access using IAM.


<PostMeta />

If you've read the post about [hosting Debian repositories on S3](/posts/how-it-works/debian-repo-s3), you already know the trick: static files on a bucket, no server in sight. Turns out, the same approach works for RPM repositories. But the format is different enough that it deserves its own walkthrough.

Our servers run Debian, so this isn't about our production fleet. But we distribute tools (our CLI, internal utilities) that people on Fedora or RHEL need to install too, and a proper RPM repository beats telling everyone to `curl | rpm -i` from a random URL.

If you've ever configured `yum` or `dnf`, you've probably edited a `.repo` file. That's the starting point.

## What's in a `.repo` file

A typical entry in `/etc/yum.repos.d/` looks like this:

```ini theme={null}
[internal-packages]
name=Internal Packages
baseurl=https://rpm-repo.platform.sh/el9/
enabled=1
gpgcheck=1
gpgkey=https://rpm-repo.platform.sh/el9/RPM-GPG-KEY-internal
```

The structure is pretty flat. The `baseurl` points to the root of the repository, and everything (package lists, metadata, signatures) lives under that path in a predictable layout. No nested concepts like distributions or components to worry about.

## How `dnf` fetches packages

When `dnf` (or `yum`, same idea) processes a repository, it does roughly this:

1. It fetches `$baseurl/repodata/repomd.xml`. This is the entry point. It contains references to all the metadata files and their checksums.
2. From `repomd.xml`, it learns the paths to `primary.xml.gz`, `filelists.xml.gz`, and `other.xml.gz`. The important one is `primary.xml.gz`, which contains the actual list of packages.
3. If GPG checking is enabled, it verifies `repomd.xml` against `repomd.xml.asc`.

The `primary.xml.gz` file contains entries like this:

```xml theme={null}
<package type="rpm">
  <name>nginx</name>
  <arch>x86_64</arch>
  <version epoch="0" ver="1.24.0" rel="1.el9"/>
  <checksum type="sha256">a1b2c3d4...</checksum>
  <summary>A high performance web server</summary>
  <location href="Packages/nginx-1.24.0-1.el9.x86_64.rpm"/>
  <size package="623104" installed="1843200"/>
</package>
```

Checksums ensure integrity, transitively trusted through the signed `repomd.xml`. And the `location` field points to the actual `.rpm` file relative to `baseurl`. A signed index that references checksummed packages.

## Generating the metadata

The standard tool for this is `createrepo_c`. You point it at a directory full of `.rpm` files:

```bash theme={null}
createrepo_c /path/to/repo/
```

It produces the entire `repodata/` directory with all the XML metadata, checksums, and (if configured) GPG signatures. One command, everything generated.

The resulting folder structure:

```
repodata/
  repomd.xml
  repomd.xml.asc
  primary.xml.gz
  filelists.xml.gz
  other.xml.gz
Packages/
  nginx-1.24.0-1.el9.x86_64.rpm
  redis-7.0.12-1.el9.x86_64.rpm
```

All static files. Our CI jobs build this structure on local disk, then `aws s3 sync . s3://...`. Done.

(Side note: we ended up building [repogen](https://github.com/ralt/repogen), a CLI tool that handles this metadata generation for RPM, Debian, Pacman, etc repositories all at once. But `createrepo_c` works perfectly fine on its own if RPM is all you need.)

... well, almost.

## Authentication

These are internal repositories. Public S3 buckets are not an option.

The `yum`/`dnf` ecosystem handles this with plugins. Which one you use depends on your package manager:

* [`yum-s3-iam`](https://github.com/seporaitis/yum-s3-iam) for `yum`-based systems (RHEL 7 and older). It's yum-only and doesn't work with DNF.
* [`dnf-plugin-s3transport`](https://github.com/ashi009/dnf-plugin-s3transport) is the one for `dnf`-based systems (RHEL 8+, Fedora). If you're setting this up today, this is most likely the one you want.

With the right plugin installed, your `.repo` file becomes:

```ini theme={null}
[internal-packages]
name=Internal Packages
baseurl=s3://internal-rpm-repository/el9/
enabled=1
gpgcheck=1
s3_enabled=1
```

The plugin handles AWS authentication using IAM roles or instance credentials. No access keys in config files, no credentials to rotate and distribute. Machines authenticate based on *what they are* (their instance role), not based on credentials someone has to manage.

## Versioning with separate repositories

If you want different streams of packages (per Git tag, per release channel), you create separate repositories. Each one is its own `baseurl`, its own `repodata/`, its own S3 prefix.

```
s3://internal-rpm-repo/el9/stable/
s3://internal-rpm-repo/el9/testing/
s3://internal-rpm-repo/el9/v2.3.1/
```

Each prefix is a self-contained repository. You point your `.repo` file at the one you want, run `dnf update`, and you get exactly the packages from that tag. Upgrades are deterministic, and rollbacks are a config change.

***

If you're running a fleet of RHEL-based systems and you've been thinking about hosting your own RPM repository, consider skipping the server entirely. S3 (or blob storage in general) does the job, `createrepo_c` generates the metadata, and an IAM plugin handles auth. The whole thing is a CI pipeline and a bucket.


# SPF, DKIM, DMARC, what are those for anyway?
Source: https://developer.upsun.com/posts/how-it-works/spf-dkim-dmarc-what-are-those-for-anyway

Finally understand what SPF, DKIM, and DMARC actually do, why email needs them, and how to set them up without wanting to flip a table.

<PostMeta />

If you're anything like me until a few weeks ago, you've heard of SPF, DKIM, and DMARC. You know they're "email things." You know that without them, your emails end up in spam. And that's about where your knowledge stops.

Most guides online take the helpful approach of "here's how to set up SPF" without ever explaining *why* it exists. Congratulations, you've copy-pasted a DNS record. Do you understand what it does? Of course not. But it works, so who cares?

Well, I finally cared enough to figure it out. And since you're hosting applications and sending emails from them, you probably should too.

## The fundamental problem with email

Here's the thing about email that makes all of this necessary: it's asynchronous and decentralized.

When you visit a website, *you* initiate the connection. You type the domain, TLS kicks in, certificates get verified, and you know you're talking to who you think you're talking to. The whole authentication flow is baked into the protocol.

Email doesn't work that way. With email, some random server connects to *your* server and says "hey, I have a message for you from bank.com." And your server has to decide whether to believe it or not.

Without any verification, anyone could claim to be sending email from your bank, your employer, or that Nigerian prince who's been trying to reach you. This is the problem SPF, DKIM, and DMARC try to solve.

## SPF: "Is this server even allowed to talk?"

SPF (Sender Policy Framework) answers a straightforward question: is the server sending this email actually authorized to send email for this domain?

It's a DNS TXT record that says "these IP addresses and these servers are allowed to send email on behalf of my domain." When an email arrives claiming to be from `example.com`, the receiving server checks the SPF record for `example.com` and verifies that the sending server is on the list.

Think of it as a bouncer with a guest list. No list, no entry.

## DKIM: "Has this email been tampered with?"

DKIM (DomainKeys Identified Mail) solves a different problem. Even if an email comes from an authorized server, how do you know the content hasn't been modified in transit?

DKIM adds a cryptographic signature to each email. You publish the public key in a DNS record, and every email gets signed with the private key. The receiving server can then verify that the email content is exactly what the sender intended.

It's like a wax seal on a letter. If the seal is broken, you know someone's been messing with it.

## DMARC: "What should I do when things fail?"

DMARC (Domain-based Message Authentication, Reporting, and Conformance) ties the other two together with a policy layer. It tells receiving servers what to do when an email fails SPF or DKIM checks.

Your options are:

* **none**: Do nothing (useful for testing)
* **quarantine**: Put suspicious emails in spam
* **reject**: Drop them entirely

You can enable reports alongside any of these policies. The reporting feature is genuinely useful. When other mail servers receive emails claiming to be from your domain, they check SPF and DKIM. If those checks fail, they send you a report. This means you get notified when someone is trying to spoof your domain, or when you've misconfigured something and your legitimate emails are failing authentication.

Without DMARC reports, you'd have no idea that someone's been sending phishing emails pretending to be you. With them, you can see exactly which IPs are sending mail on your behalf (legitimately or not) and whether your authentication is working as intended.

## The practical bit: multiple email providers

Here's where this gets relevant for actual application development.

Most applications need to send different types of email. You have transactional emails (password resets, order confirmations) and marketing emails (newsletters, promotions). These typically come from different providers because transactional email services don't want you sending bulk marketing through them.

So you end up with at least two email providers, both needing to send from your domain. Your SPF and DKIM records need to authorize both.

But here's the pro tip: use different domains for different email types. Why? Reputation isolation.

If your marketing provider does something weird (or gets used by spammers on the same IP range), it can tank your sender reputation. If that reputation is shared with your transactional emails, suddenly your password reset emails aren't getting delivered. Your users can't log in. Support tickets pile up. Your weekend is ruined.

Keep `transactional.example.com` separate from `marketing.example.com`. If one reputation takes a hit, the other survives.

## DKIM on Upsun

If you're hosting on Upsun and want DKIM for emails sent from your application, the process is straightforward. Open a support ticket requesting DKIM activation for your domain, and support will provide you with the DNS records you need to add (a CNAME and TXT record).

Once your DNS is configured, validation checks run every 15 minutes. After validation completes, Upsun automatically signs your outgoing emails with DKIM through SendGrid's infrastructure. You don't manage the keys yourself; it's handled for you.

See the [Upsun email documentation](https://docs.upsun.com/development/email.html#3-optional-validate-your-email) for the full setup process.

## Wrapping up

That's it. Three DNS records:

* **SPF**: Which servers can send email for your domain
* **DKIM**: Cryptographic proof that emails haven't been tampered with
* **DMARC**: What to do when the first two fail

All three exist because email is fundamentally a "stranger walks up to you" protocol, and we need ways to verify they are who they claim to be. Unlike HTTPS, where you initiate the connection, email authentication is a series of workarounds for the fact that someone else is connecting to you.

Now you actually know what those acronyms mean. You're welcome.


# The Platform.sh build-and-deploy pipeline
Source: https://developer.upsun.com/posts/how-it-works/the-platformsh-build-and-deploy-pipeline

Learn how Platform.sh simplifies the build and deploy pipeline for web applications, ensuring consistency and repeatability with Git-based semantics.

<PostMeta />

<Tip>
  This post was originally published on the Platform.sh blog and reflects information from the time of publication.
</Tip>

**A repeatable and consistent build-and-deploy pipeline is an essential part of any modern web application. Platform.sh has this philosophy at the heart of it’s design, tying configuration, code and build artifacts together using Git semantics.**

## Build? What Build? This is not C++?!

Part of what explains the huge success of web technologies is the simplicity and low barrier to entry presented by the model of dynamic script languages. With Ruby, Python and PHP you could just upload files to a server (and in PHP’s case you didn’t even need to start a daemon) and it would just work. But that model introduced a number of problems...

> “I know PHP! How hard could running an exchange be?” never goes anywhere good.

As David Gerard notes about the [Mt. Gox bitcoins exchange heist](https://davidgerard.co.uk/blockchain/2017/09/17/kim-nilsson-of-wizsec-how-the-bitcoins-were-stolen-from-mt-gox/), without structure and method bad stuff happens. No serious developer would develop an application these days without having some tooling. First and foremost dependency management: you want a consistent process to pull updated versions of 3rd party libraries that your project uses, with as little friction and effort as possible, so you can quickly apply any and all security fixes. If you can’t apply security hotfixes as soon as they are out, you are going to get hacked. It’s not an “if” question, it is a “when” question. ”When” usually being sooner than you’d like. Without that... well you get an Equifax (and you don’t want to be an Equifax).

But often it doesn’t end there. More and more technologies, even dynamic scripty ones, rely on a compile/build phase. This is true not only for front-end applications but also for things like NodeJS backends, where TypeScript, CoffeeScript and a billion other things transpile into other things.

> Javascript is a compile target not a programming language
>
> — Nick Main ? (@\_nickmain) [September 3, 2017](https://twitter.com/%5Fnickmain/status/904451179844845568)

We also see how much compiled languages are gaining traction; languages like Golang (which you can run on Platform.sh now too), Crystal, or Elixir.

## In the modern world go Build Or Go Bust!

Build artifacts are components of your web application that are generated when you compile it. While some applications have compilation at the heart of their design, many popular web languages eschewed this approach in favour of dynamic runtimes and generally only use this approach with external shared components or libraries.

With Platform.sh, you don’t just get a few build artifacts in your project directory, [your entire application is an artifact of development](/posts/unknown/production-artifact) . This artifact is stored and reused wherever the same git commit is deployed to a new environment, so simply by using Platform.sh’s standard build tools, you get a consistent and repeatable build on every git branch.

Understanding this pipeline and how it works will help you build better web applications on Platform.sh, and is also the key to knowing how to integrate with other services that you use (as well as when you no longer need them).

## How it works

When you push a new change to Platform.sh, we take your code in Git and move it through a number of steps to turn it into a running, “built” application. These steps can be broadly broken down into two phases, the build phase, and the deploy phase.

The build process will run the “build flavor” (if present), install dependencies, then run the user-provided build hook.

The deploy process will run the deploy hook.

All these properties are defined in the \`.platform.app.yaml\` file, and documented in our [online documentation](https://docs.platform.sh/configuration/app-containers.html), and there’s also a [screencast of this build process in action](https://www.youtube.com/watch?v=iHJZIWnv-2s\&index=3\&list=PLn5EpEMtxTCmNh4eEG52JdxHP6qBV69Ux).

## The Build phase

The Build phase is where we do all the heavy lifting to prepare your [application for deployment](https://devcenter.upsun.com/posts/best-practices-in-deploying-web-apps-updated-for-2020/). It’s where we load external resources, pack assets, add dependencies and do any tasks which require the filesystem to be writable. During the build phase, your application can access the network, for example for doing a \`*composer install*\` but is not remotely accessible or available on the internet, and does not have any of its running Services (databases, search indexes) attached.

In the build phase we do three things:

1. Install any [listed system-level dependencies](https://docs.platform.sh/configuration/app/build.html#build-dependencies).
2. For PHP and NodeJS projects, run [tasks defined for the build flavor](https://docs.platform.sh/configuration/app/build.html#build), for example \`*composer install*\`. All other project types currently ignore this step.
3. Run a build hook, defined in your [build hook](https://docs.platform.sh/configuration/app/build.html#hooks) in your .platform.app.yaml file.

The build hook is where you perform steps that require dynamic code generation or file system access, for example:

* Installing dependencies, e.g using npm, yarn, composer, bower, or pip
* Compiling static assets that won’t change, e.g. sass, through gulp or grunt
* Running static code tests, e.g. phpunit

Here's the [build hook from our example Symfony repository](https://github.com/platformsh-templates/symfony3/blob/master/.platform.app.yaml#L19)...

hooks:
build: |
rm web/app\_dev.php
bin/console --env=prod assets:install --no-debug

At the end of the build phase, your application should be completely built and ready to deploy. At this point, it will be made read-only.

## The Deploy phase

The deploy phase is run after the application container has been started. You can access other services at this stage (database, search service, etc.). The disk where the application lives is read-only at this point. Incoming requests are paused while the deployment runs.

During the Deploy phase we run only one user-definable step:

1. Run a deploy hook, if provided in your .[platform.app.yaml file](https://docs.platform.sh/overview/yaml/what-is-yaml.html).

Deploy hooks are where you run commands that prepare your applications services and dynamic assets. For example:

* Clear your caches
* Run database migrations and updates
* Build dynamically generated assets that are stored on file mounts
* Hook into third-party testing tools

Here's the deploy hook from our example Symfony repository...

hooks:
deploy: |
bin/console --env=prod cache:clear

If everything goes well and your hooks execute correctly, your environment is now moved into place and replaces the running environment, and you can see the results of the deploy hook in the */var/log/deploy.log* file when logged in to the environment via SSH. (If everything doesn’t go well, be glad that it was so simple for you to test out this deploy process in a development branch before merging into production)

## Summary

With Platform.sh, you get powerful, easy-to-use [WebOps](https://platform.sh/blog/webops/) and [continuous deployment tools](https://platform.sh/blog/what-the-heck-is-ci-cd/) that allow you to manage complex pipelines easily from git commit through to a running environment. The Build and Deploy phases are the key to understanding how you can get the maximum value from this pipeline, and where to add your own integrations and code.

In future guides we’ll look at how to integrate with third-party testing tools, how to run tests in the build pipeline, and other integrations.

## Further reading

* [Platform.sh Documentation on Build and Deploy Tasks](https://docs.platform.sh/configuration/app/build.html)


# Upsun deployment hooks and commands: which one to use, and when
Source: https://developer.upsun.com/posts/how-it-works/upsun-deployment-hooks-and-commands-which-one-to-use-and-when

Build hooks, deploy hooks, pre_start, start, and post_start all shape how Upsun deploys your app. Learn what each one does and when to reach for it.

<PostMeta />

Have you ever stared at an Upsun configuration file wondering whether your migration belongs in the `deploy` hook or the `post_deploy` hook? You're not alone.

Upsun gives you 6 places to run a command during a deployment: a `build` hook, `pre_start`, `start`, `post_start`, a `deploy` hook, and a `post_deploy` hook. Each one has its own page in the [docs](/docs/configure-apps/hooks), and each page is good. The part the docs can't answer for you is the one you actually care about: which one do you reach for, for the task in front of you?

That answer depends on context. It depends on when the command needs to run, whether it needs a database, whether it should block traffic, and even on the kind of mount you write to. None of that jumps out when you read the reference pages one at a time. So this post walks through each command and hook, then shows how they fit together with a few real examples.

## Two phases: build, then deploy

Every deployment has 2 parts: a [build, then a deploy](/docs/core-concepts/build-deploy). They run in different worlds, and that split explains most of the rest.

The build runs in isolation. No database, no services, no other containers. Upsun checks out your code, installs dependencies, runs the build flavor for your language, runs your `build` hook, then freezes the result into a read-only image.

The deploy takes that frozen image and makes it live. Now services are reachable, mounts are attached, and the file system is read-only apart from those mounts. If you use [zero-downtime deployments](/docs/core-concepts/build-deploy#zero-downtime-deployments), Upsun starts the new container next to the old one and removes the old one only once the new one is ready, so live traffic never drops.

Keep that one line in mind: the build is isolated and reusable, the deploy is live and connected. Where a command belongs almost always comes down to which side of that line it sits on.

## The build hook has nothing to do with runtime

The `build` hook, your [build dependencies](/docs/configure-apps/app-reference/single-runtime-image#dependencies), and the build flavor all affect build time, not runtime. They run while your app is being assembled, before any database exists.

Good fits: compiling assets, installing packages, generating code, bundling a frontend. Anything that turns your source into the artifact you want to ship and needs nothing more than your code plus write access to disk.

The `build` hook is also the one hook that can stop a deploy. If it fails, the build is aborted and nothing ships. The other hooks don't behave that way: if they fail, the deploy still happens. Add `set -e` at the top so the hook fails on the first failing command instead of only the last.

```yaml {filename=".upsun/config.yaml"} theme={null}
applications:
  app:
    type: "nodejs:22"
    source:
      root: "/"
    hooks:
      build: |
        set -e
        npm ci
        npm run build
```

One more thing the build buys you: the result is tied to your commit and reused. If a container has no changes, Upsun skips its build entirely. The `build` hook is the cheapest place to do expensive, deterministic work, because you pay for it once per commit, not once per deploy.

## pre\_start, start, and post\_start run every time your app starts

These 3 commands wrap your app process, in order: `pre_start`, then `start`, then `post_start`. Here's the part that's easy to miss: unlike the hooks, which run once per deploy, this trio runs every time the `start` process starts. And it starts again every time it's restarted, after a deploy, after host maintenance, and any time `start` exits and the supervisor brings it back. You configure them under [`web.commands`](/docs/configure-apps/image-properties/web#web-commands).

### start: the supervised one

[`start`](/docs/configure-apps/image-properties/web#start-command) launches your app and keeps it running. Upsun supervises it: if it ever exits, it gets restarted right away. That's the detail that matters. `start` is not a script that runs once and finishes, it's a long-running process expected to stay up.

Two things follow from that. Don't background it with `&`: the supervisor reads a terminating command as "start another copy", and you land in a loop until the container crashes. And `start` has to *be* that long-running process, so setup work that needs to run and then finish belongs in `pre_start` instead.

On most languages you write a `start` command. On PHP you can leave it out, and Upsun runs PHP-FPM for you.

### pre\_start: setup that runs and then finishes

[`pre_start`](/docs/configure-apps/image-properties/web#pre_start-command) runs right before `start`, every time the app starts. The difference from `start` is semantic, not about how often each runs: `pre_start` is a command you expect to run to completion and exit, while `start` is the supervised process that stays up. So `pre_start` is where setup that has to finish before your app launches goes.

Take a PHP app. You want the default PHP-FPM start command, but you also want to clear and warm the cache first, so OPcache loads the right code from the first request. You can't do that inside `start` without replacing the default with a wrapper script. `pre_start` lets you keep the default `start` and still run the prep beforehand. Same idea for a Python app that generates templates before serving: generate in `pre_start`, run the app in `start`.

```yaml {filename=".upsun/config.yaml"} theme={null}
applications:
  app:
    type: "php:8.3"
    source:
      root: "/"
    web:
      commands:
        pre_start: "php bin/console cache:warmup"
        # start is omitted: PHP-FPM is the default
```

### post\_start: wait until the app is actually ready

[`post_start`](/docs/configure-apps/image-properties/web#post_start-command) runs after `start`, before the container is added to the router. Its job is to make the orchestration wait until your app is genuinely ready to serve, not merely started.

This matters most during zero-downtime deployments and horizontal scaling. When you add an instance, you don't want traffic routed to it before it can answer. A `post_start` that polls `localhost` until the app responds holds the handover until then, so the old container stays up and requests aren't sent too early. The payoff is no dropped requests while scaling.

Whether you need it depends on your stack. A `start` command returns almost instantly: the process is up, but the app inside may still be warming. PHP serves on the first request, so it rarely needs `post_start`. Python apps tend to start fast enough to skip it. Java apps are the classic case where it earns its place: the JVM takes a moment to come up, and `post_start` gives it that moment before traffic arrives.

```yaml {filename=".upsun/config.yaml"} theme={null}
applications:
  app:
    type: "java:21"
    source:
      root: "/"
    web:
      commands:
        start: "java -jar target/app.jar"
        post_start: |
          curl -sS --retry 20 --retry-delay 1 --retry-connrefused localhost -o /dev/null
```

## The deploy hook runs once, before traffic

The [`deploy` hook](/docs/configure-apps/hooks/hooks-comparison#deploy-hook) runs after the container has started but before it accepts requests. It runs once, on a single web instance, with services reachable and the file system read-only apart from mounts. While it runs, incoming requests are held.

That makes it the right home for work that has to happen exactly once and exclusively, against code that matches what's on disk. Database schema migrations are the textbook case. You don't want live requests hitting the database mid-migration unless your app was built specifically for that, and if it was, you already know to go for it. For everyone else, the `deploy` hook is where migrations belong.

Keep it short. Held requests can wait out a few seconds, but a long `deploy` hook turns into dropped connections. Anything that can run safely while requests flow should move to `post_deploy` instead.

## The post\_deploy hook runs once, after traffic

The [`post_deploy` hook](/docs/configure-apps/hooks/hooks-comparison#post-deploy-hook) is the `deploy` hook's mirror image: same once-only, services-available behavior, but it runs after the app is open to the world and alongside live traffic. Reach for it when the work doesn't need exclusive access and can happen in a lazy fashion: clearing a CDN cache, warming caches that tolerate concurrent reads, kicking off a content import.

It comes with one rule. `post_deploy` is the only hook that runs on a redeploy with no code changes, so its scripts need to be idempotent, or safe to run more than once. Write them as if they will run twice, because eventually they will.

## Your mount type changes the answer

Here's the part that catches people out, and it's worth slowing down for. The kind of [mount](/docs/configure-apps/image-properties/mounts) you write to influences which command you should pick.

A `storage` mount is shared across all instances of your app over the network. An `instance` mount is local to each instance: with 3 instances behind horizontal scaling, each gets its own local disk with nothing shared between them.

That distinction decides where a file-generating command belongs:

* If you write to an `instance` mount, a `deploy` hook only populates one node, because it runs on a single instance. Files generated there never reach the others. To put per-instance files on every node, generate them in `pre_start` or `post_start`, which run on each instance.
* If you write to a `storage` mount, the `deploy` or `post_deploy` hook works, because every instance sees the same shared directory. Pick between the two based on whether the work should block traffic.
* If you rely on `/tmp` or other ephemeral storage, plan for it to be empty when the container starts again. The `deploy` and `post_deploy` hooks run once per deploy, but a container can restart on its own without a new deploy, and only `pre_start`, `start`, and `post_start` run on those restarts. So anything you need in ephemeral storage has to be regenerated in `pre_start`, or it won't be there.

Disk performance pulls in the same direction. Local instance disks are faster than the shared network storage. If you generate something heavy, say an e-commerce catalog rendered for a dozen languages across a million products, doing it once on a shared mount in a `deploy` hook can drag out the deployment. Generating it on the fast local disk in `pre_start` can be the better trade. It isn't micro-optimization, it's infrastructure optimization, and at that scale it adds up.

## A quick decision guide

When you're not sure, these questions usually settle it:

| If you need to... | Reach for |
| - | - |
| Compile, bundle, or install, with no services | [`build`](/docs/configure-apps/app-reference/single-runtime-image#build) hook |
| Set up something per instance, on every start | [`pre_start`](/docs/configure-apps/image-properties/web#pre_start-command) |
| Run and keep your app process alive | [`start`](/docs/configure-apps/image-properties/web#start-command) |
| Wait until the app is ready before routing traffic | [`post_start`](/docs/configure-apps/image-properties/web#post_start-command) |
| Run something once, before traffic, with exclusive access | [`deploy`](/docs/configure-apps/hooks/hooks-comparison#deploy-hook) hook |
| Run something once, after traffic, that's safe to repeat | [`post_deploy`](/docs/configure-apps/hooks/hooks-comparison#post-deploy-hook) |

There's no single right configuration. Each application makes its own calls based on what it needs. If you run Symfony, its Upsun integration already wires up sensible defaults for all of these, so you may rarely touch them by hand. For everything else, the questions above are the ones to ask.

Once you can map a task to the moment it should run, the configuration writes itself. That's the part the reference pages leave to you, and it's the part worth getting right.

Want to put this into practice? [Create a free Upsun account](https://upsun.com) and read the full [build and deploy hooks guide](/docs/configure-apps/hooks) to see each one in context.


# Using the Upsun API
Source: https://developer.upsun.com/posts/how-it-works/using-the-upsun-api



<PostMeta />

## Automate management of your Upsun projects

> Anything you can do, API can do better!

An interesting fact about the Upsun hosting and deployment system, is that all the important actions are done via an API (Abstract Programming Interface) that you also have access to.
The changes you make and the actions that you invoke through the web console can also be triggered programmatically by authenticated HTTP requests.

This means that anything you can do in the Web UI console, you can also automate or trigger remotely!

<Note>
  **Note:**

  Some documentation links may still refer to "Platform.sh", the `platform` CLI tool, and `PLATFORM_*` named environment variables.
  In most cases, you can imagine that the `upsun` CLI tool acts identically to the `platform` CLI tool, so you may read the docs as if they are interchangeable.
</Note>

## The CLI is mostly an API wrapper

We provide the [`upsun` CLI](https://docs.upsun.com/administration/cli.html) to make this easier ( not least because the authentication stuff is annoying to do by hand ) but all that usually does is make an API request on your behalf.

You can see that in action by using `UPSUN_CLI_DEBUG` (a flag that makes the `upsun` CLI tool more verbose). That will log the actual request being made to the API.

```bash {filename="Terminal"} theme={null}
export UPSUN_CLI_DEBUG=1
upsun project:info
```

```{filename="Logs"} theme={null}
Selected project: Client test Upsun (y3fni4nqxhyfa)
> Making HTTP request #1: GET /api/projects/y3fni4nqxhyfa HTTP/1.1
> Host: api.upsun.com
```

Actions and edits are triggered in the same way - via POST.

```bash {filename="Terminal"} theme={null}
upsun environment:pause --environment=feature-ZD12345
```

```{filename="Logs"} theme={null}
...
Making HTTP request #1: POST /api/projects/i4nqxhyy3fnfa/environments/feature-ZD12345/pause HTTP/1.1
> Host: api.upsun.com
...
< Received response for #1 after 1378 ms: HTTP/1.1 200 OK
```

The full API is open and documented for inspection and experimentation at [api.upsun.com](https://api.upsun.com/docs/).
This makes it possible for you to do anything to your project - even create, branch, or change resource allocations - from your own pipelines.

## API requests are authenticated

The [authentication that is used for API access](https://api.upsun.com/docs/#section/Authentication) controls what you can do based on the projects and permissions that are assigned to your user account.

> Note that it is recommended to [create a "machine user" with its own token](https://docs.upsun.com/administration/cli/api-tokens.html#1-create-a-machine-user) if you are intending to delegate tasks to an environment where the token or keys may be shared or visible to others.

* When you use **the web console**, a temporary certificate has been given to your browser when you authenticated -
  usually when you went through `auth.upsun.com` to do your login. This allows the web console in your browser to talk directly to `api.upsun.com` for you.
* When you use **the CLI**, it may require you to "Log in via a browser" window in the same way.
  and a temporary certificate becomes available to your shell environment once you are "Successfully logged in".
* You can also avoid logging in each time you use the CLI by [authenticating using an API token](https://docs.upsun.com/administration/cli/api-tokens.html)
  This is more convenient if you use the CLI a lot.
  * To create an API token, go to the "API Tokens" section of the "Account Settings" tab [on the Console](https://console.upsun.com/), and make that available as a variable named `UPSUN_API_TOKEN` in your shell environment.
* For making requests directly via **the API**, or **for automation and delegation of tasks**, you would also use an API token in this same way.
  * To use the token, the `UPSUN_API_TOKEN`  variable must be set in the environment for the CLI, or passed explicitly in an API request header.
  * You can experiment with semi-raw API requests but still use the CLI to manage authentication via the `upsun api:curl` command.
    For inline documentation on `api:curl` enter `upsun help api:curl` in your terminal.

## Ways of interacting with the API

It's possible to make raw http requests directly to the API endpoint, but it's usually better to use a wrapper of some sort.

### Use `upsun project:curl`

The CLI has an embedded utility that provides direct access to the http requests, and handles the project selection and authentication for you.
See `upsun help project:curl`

```bash {filename="Terminal"} theme={null}
upsun project:curl /environments
```

^ Lists the available environments ([API ref](https://api.upsun.com/docs/#tag/Environment/operation/list-projects-environments)) . Equivalent to `platform environment:list`, but the JSON response may be more useful for automation.

<Note>
  `project:curl` is a shortcut for `api:curl` that pre-selects the project for you, and is easier to use for normal operations.
  They both really are just very thin wrappers around [the documented endpoints](https://api.upsun.com/docs/#section/Introduction/Using-the-REST-API) that format the `curl` command options for you.
</Note>

### Use `curl` directly

```bash {filename="Terminal"} theme={null}
export UPSUN_API_URL=https://api.upsun.com
export UPSUN_PROJECT=ywxgbkce4rmdp
export UPSUN_BRANCH=master
export UPSUN_TOKEN=$(upsun auth:token)

curl -s -H "Authorization: Bearer ${UPSUN_TOKEN}" "${UPSUN_API_URL}/projects/${UPSUN_PROJECT}/environments/${UPSUN_ENVIRONMENT}" \
  | jq "del(.[]._links)"
```

```json {filename="Logs"} theme={null}
[
  {
    "id": "master",
    "_embedded": {
      "deployments": [
        {
          "id": "local",
          "type": "local",
          "name": "local",
          "hosts": null,
          "use_dedicated_grid": false,
          "storage_type": null
        }
      ]
    },
    "created_at": "2024-08-20T10:16:27.324395+00:00",
    "updated_at": "2024-08-20T10:20:49.806440+00:00",
    "name": "master",
    "machine_name": "master-7rqtwti",
    "title": "Master",
    "attributes": {},
    "type": "production",
    "parent": null,
    "status": "active",
    "http_access": {
      "is_enabled": true,
      "addresses": [],
      "basic_auth": {}
    },
    "enable_smtp": true,
    "restrict_robots": true,
    "edge_hostname": "master-7rqtwti-ywxgbkce4rmdp.au.platformsh.site",
    "deployment_state": {
      "last_deployment_successful": true,
      "last_deployment_at": "2024-08-20T10:20:49.805910+00:00",
      "crons": {
        "enabled": true,
        "status": "running"
      }
    },
    "resources_overrides": {},
    "last_active_at": "2024-09-20T03:42:58.347107+00:00",
    "last_backup_at": "2024-09-19T04:11:29.560749+00:00",
    "project": "ywxgbkce4rmdp",
    "is_main": true,
    "is_dirty": false,
    "has_code": true,
    "head_commit": "b1620160b763d1d2314af935d3c0cd23b8a141dc",
    "merge_info": {
      "commits_ahead": 0,
      "commits_behind": 0,
      "parent_ref": null
    },
    "has_deployment": true
  }
]
```

### Use `postman`

The [API support documentation](https://api.upsun.com/docs/#section/Introduction/Using-the-REST-API) also provides an OpenAPI specification which can be imported into tools like Postman for inspection and testing.

* [Install the Postman API explorer](https://www.postman.com/downloads/)
* "Import" the API schema from `https://api.upsun.com/docs/openapispec-platformsh.json`
* Update the "Variables" to set the `baseUrl` to `{{schemes}}://api.upsun.com`
* Update the "Authorization" section to set "Auth Type" type "Bearer Token"
* Generate a token with `upsun auth:token` and paste that into the "Token" field
* Test a request by running the simple "GET" "me" operation

## Use automation to manage your project

With access to this toolset now, you may be able to see some possibilities for management.

* As Upsun resources are charged for pro-rata (usage based), you could cut the RAM and CPU costs for all your preview environments in half by automating a `cron` task them to "pause" every night and weekend.
* You can upscale and downscale the resources in realtime to match demand and traffic on the website.

As an example, you can use [scalsun](https://github.com/upsun/scalsun) to [automatically upscale Upsun resources](/posts/how-tos/configuring-an-autoscaler).


# We made our infrastructure read-only and never looked back
Source: https://developer.upsun.com/posts/how-it-works/we-made-our-infrastructure-read-only-and-never-looked-back

Learn why read-only infrastructure eliminates entire classes of security attacks, improves reproducibility, and simplifies compliance while enabling predictable deployments.

<PostMeta />

If you've used Upsun, you've likely noticed something unusual when SSH'ing into your container: the filesystem is read-only. You deploy an application, log in to investigate, attempt to create a directory, and encounter this error:

```bash theme={null}
mkdir: cannot create directory 'foo': Read-only file system
```

This can be frustrating at first. What kind of platform won't let you create folders?

The answer lies in a deliberate architectural decision. Read-only infrastructure provides significant security, reliability, and compliance benefits that outweigh the operational adjustments required. Let's examine these benefits and the trade-offs involved.

## Security: eliminating entire attack vectors

Read-only filesystems eliminate entire classes of security vulnerabilities. Common attack patterns become impossible:

Consider CMS vulnerabilities where attackers upload malicious executables and compromise websites. With read-only filesystems, these attacks fail at the most fundamental level. Container escape vulnerabilities that rely on writing to host filesystems—such as [CVE-2019-5736](https://nvd.nist.gov/vuln/detail/CVE-2019-5736), which allowed attackers to overwrite the host container runtime binary—cannot succeed when the filesystem rejects all write operations.

Without write access, attackers cannot:

* Upload backdoors or web shells
* Modify application code to inject malicious functionality
* Install persistence mechanisms
* Alter system binaries for privilege escalation

This security boundary exists at the kernel level. Even when an attacker successfully compromises your application, the read-only filesystem significantly constrains their capabilities and prevents lateral movement.

## The trade-off: managing multiple filesystem layers

This architecture does introduce complexity. We maintain separate filesystems for `/app` (your application code) and `/` (the base operating system). We don't rebuild your application every time we patch a Debian package on the root filesystem. This requires managing different SquashFS images for each layer.

This approach demands strict ABI (Application Binary Interface) stability. Breaking the ABI would cause applications to fail. That's why specific versions of container images remain on the same Debian version permanently. Once you're running `type: python:3.11` with Debian 11, that combination stays locked to Debian 11 throughout its lifecycle. This constraint ensures compatibility but reduces flexibility in base system updates.

## Reproducibility: what you deploy is what you get

Upsun environments map directly to git branches. What you deploy is precisely what runs on the server. Files cannot be modified because they're read-only. This guarantees reproducibility and integrity.

When you merge code from staging to production, you're deploying the identical filesystem image. There's no configuration drift, no manual modifications, no "works on my machine" discrepancies. The code that passed testing is byte-for-byte identical to what runs in production.

## Explicit state management: declaring what changes

Read-only infrastructure requires explicit declaration of writable directories. Rather than allowing arbitrary filesystem writes, you specify which directories need write access for uploads, cache, or temporary data. This intentionality makes application behavior predictable and state management explicit.

Configure writable mounts in your `.upsun/config.yaml`:

```yaml theme={null}
mounts:
  'var/cache':
    source: tmp
    source_path: cache
  'var/uploads':
    source: storage
    source_path: uploads
```

This configuration makes state location transparent. When you clone data from production to staging, mount contents transfer with it, enabling reliable reproduction of the complete environment—both code and state.

## Infrastructure benefits: platform-wide read-only design

The entire Upsun infrastructure operates on read-only filesystems. This eliminates an entire category of operational problems: in-place system upgrades.

Distribution upgrades and live system patching are notoriously difficult. Package conflicts, dependency resolution failures, configuration file drift, and partial upgrade states create unpredictable system behavior. When managing infrastructure at scale, these issues multiply—each host becomes a unique snowflake with its own upgrade history and potential failure modes.

Read-only infrastructure sidesteps this complexity entirely. We don't run `apt-get upgrade` on live systems. We build new VM images with updated packages, test them thoroughly, and replace running VMs wholesale. This approach requires solving different technical challenges (particularly safe VM replacement under load), but once implemented, it eliminates the fragility and unpredictability inherent in in-place upgrades.

The operational benefits scale significantly. When managing thousands of VMs across multiple cloud providers, knowing that every VM is identical eliminates entire classes of debugging sessions. Configuration drift between hosts becomes impossible. When functionality is verified on one VM, it functions identically on all VMs running that image.

## Compliance: simplified security scanning

Read-only infrastructure reduces compliance complexity significantly. Runtime antivirus scans on system directories become unnecessary—immutable filesystems cannot be infected with malware during operation.

Security scanning shifts to build time. You catalog deployed packages and their versions, scan the filesystem image once during creation, and subsequently monitor for newly disclosed CVEs affecting your deployed versions. This eliminates continuous filesystem monitoring and runtime scanning overhead while maintaining security posture.

Audit trails become more straightforward. Application code changes are tracked through git history. Infrastructure changes are documented as image replacements in your deployment pipeline. The immutability eliminates ambiguity about what changed and when, simplifying compliance reporting and incident investigation.

## Getting started with read-only infrastructure

Ready to implement these security and operational benefits? [Create a free Upsun account](https://auth.upsun.com/register) and deploy your first application with read-only infrastructure built in.

For guidance on configuring writable directories or adapting applications to immutable infrastructure, consult our [documentation on writable mounts](https://docs.upsun.com/create-apps/app-reference/single-runtime-image.html#mounts) to learn how to explicitly declare directories requiring write access.


# We switched from LVM to... sparse files?!
Source: https://developer.upsun.com/posts/how-it-works/we-switched-from-lvm-to-sparse-files

How we eliminated 90% of VM evacuation time by replacing LVM with sparse files for temporary storage. A tale of inertia, performance bottlenecks, and surprisingly effective solutions.


<PostMeta />

When 9 out of 10 minutes of VM evacuation time consists of waiting for LVM (Logical Volume Manager) volumes to delete, something's clearly wrong. We fixed it with a solution so basic it sounds ridiculous: sparse files.

## The problem: inertia and performance bottlenecks

Years ago, we used LVM for all container volumes, including `/tmp` volumes. It made sense at the time, with LVM providing snapshots, thin provisioning, and various enterprise features we thought we needed. Eventually, we migrated persistent volumes to Ceph, but `/tmp` volumes stayed on LVM. Not because we needed LVM's features for temporary storage, but because we'd always done it that way. Classic inertia.

The real problem revealed itself during work on failover and evacuation optimization. Since our [infrastructure is read-only](/posts/how-it-works/we-made-our-infrastructure-read-only-and-never-looked-back), upgrades mean spinning up new VMs, evacuating containers from old VMs to new ones, then shutting down the old infrastructure. When we looked at the timeline, the numbers were striking: out of 10 minutes total evacuation time, 9 minutes were spent waiting for LVM volumes to delete. That's 90% of our time wasted on cleanup. The irony wasn't lost on us.

As it turns out, we weren't alone in this struggle. Our friends at [fly.io](https://fly.io) [ran into the same LVM performance issues](https://go.news.fly.io/deliveries/dgSN7QkDAIHCDYDCDQGZlxEIn10bamOvwxVnx0I=). They took a different approach to solving it, but they had different requirements.

## The solution: sparse files

Looking at our `/tmp` volumes, we realized they're genuinely temporary. No need for snapshots, no long-term persistence requirements, none of LVM's advanced features actually mattered. We needed three things: fast creation, fast deletion, and thin provisioning so disk space only gets used when data is actually written.

Sparse files deliver all of that with remarkable simplicity:

```bash theme={null}
fallocate -l 8G tmp-volume.img
losetup --find --show tmp-volume.img
```

Two commands give you a thinly-provisioned block device ready for a filesystem. The sparse file starts as 8GB of zeros but only consumes actual disk space as you write data to it, functionally identical to thin-provisioned LVM volumes.

The impact was immediate. After switching to sparse files, deletion time essentially disappeared from our evacuation metrics. It's no longer even a measurable part of the process. But this raised an important question: what about runtime performance? Could LVM-backed volumes be significantly faster during actual use?

We ran extensive filesystem benchmarks comparing both approaches with thousands of file operations, various I/O patterns, and real-world workloads. The performance differences were negligible. Both LVM and sparse files were tested on the same [fast NVMe disks](/posts/how-it-works/cut-aws-bandwidth-costs-95-with-dm-cache), and at those speeds, the choice of abstraction layer didn't make a meaningful difference.

## When this approach makes sense

This solution works well for us because we're dealing with temporary storage that gets created and destroyed frequently. The simplicity matches the use case perfectly. That said, if you need LVM's features like snapshots, volume resizing, or complex storage management, those capabilities still have value. But if you're using LVM out of habit for temporary storage, it's worth questioning whether you actually need it.

Sparse files are particularly well-suited when you have temporary storage requirements, fast underlying disk I/O where the abstraction layer overhead becomes negligible, and frequent creation and deletion cycles like our regular VM evacuations during upgrades. If you're facing similar performance bottlenecks in temporary storage management, sparse files might be worth testing in your environment. The implementation is straightforward, and the performance gains can be substantial.


# When php-fpm runs out of workers: a 502 error field guide
Source: https://developer.upsun.com/posts/how-it-works/when-php-fpm-runs-out-of-workers-a-502-error-field-guide

Your PHP site keeps throwing 502 errors. Your CDN shows 503s. Learn why PHP-FPM workers get exhausted and how to diagnose and fix the real problems.

<PostMeta />

Your site is down. Fastly says 503. Your logs say 502. Your boss says "fix it." But what's actually happening?

The error message in your nginx error log looks something like this:

```
2025/10/28 22:56:52 [error] 207#0: *8050 recv() failed (104: Connection reset by peer) while reading response header from upstream, client: 81.122.114.94, server: , request: "GET /foo/bar HTTP/1.1", upstream: "fastcgi://unix:/run/app.sock:", host: "foo.bar", referrer: "https://foo.bar/baz-com"
```

This isn't a PHP error. It's nginx telling you it tried to talk to php-fpm and something went wrong. Let's figure out what.

## How requests actually flow through your stack

When a request hits your Upsun project, it takes this path:

1. Upsun gateway (you don't need to worry about this part)
2. nginx (your web server)
3. php-fpm (your PHP runtime using the FastCGI Process Manager)

nginx handles static files on its own. But when you're requesting a PHP script, nginx doesn't know how to execute PHP code, so it hands the request to php-fpm. A php-fpm worker executes your code, gets the result, and sends it back to nginx, which sends it to the client.

The key detail here: when you see a 502 error, it's usually coming from nginx. It means nginx tried to send a request to php-fpm and couldn't get a response in time. If you have a CDN in front of your site, the CDN might show this as a 503 gateway timeout instead, because from its perspective, the entire origin timed out.

## The highway analogy

Think of php-fpm workers like highway lanes. If you have four workers, you have a four-lane highway. Each lane can handle one car (request) at a time, moving in the same direction.

Unlike some other runtimes (Python with ASGI, Node.js), php-fpm workers handle one request at a time. When a worker is busy executing your PHP code, it can't do anything else until that request finishes.

The math is straightforward: if you have 4 workers and each request takes 0.5 seconds to process, you can handle 8 requests per second (4 workers ÷ 0.5 seconds per request = 8 requests/second).

If you don't have any workers available, new requests have to wait. nginx won't immediately return a 502 error - it'll wait for a worker to become available, up to its configured timeout. But if workers stay busy too long, nginx gives up and returns that 502 error you're seeing.

## Why workers get exhausted

There are two main reasons workers get exhausted, and they love working together to take your site down.

### Slow requests

Here's the death spiral: you get a lot of requests, so your database gets busy. When your database gets busy, each PHP request has to wait longer for query results. When requests take longer, fewer requests can be processed per second. When fewer requests can be processed, the queue builds up. The queue building up makes everything slower.

If your average request time goes from 0.5 seconds to 5 seconds, your throughput drops by 10x. Those 4 workers that could handle 8 requests/second? They're now handling less than 1 request/second.

This is why you don't want to run your workers at 100% utilization all the time. If you have 10 workers and they're all busy constantly, any small increase in traffic or any small slowdown in request processing will tip the entire system over.

### External API calls without timeouts

Another common culprit: your code calls an external API using `libcurl`, and that API is slow or down.

Here's the problem: `libcurl` in PHP doesn't have a timeout by default. If you're calling an external API and it never responds, your worker waits forever. That worker is now stuck, doing nothing, unable to process any other requests.

You can spot this in your `php.access.log` by looking at the CPU percentage. PHP requests are supposed to spend CPU time processing things. If the CPU % usage is low in the logs, PHP is waiting most of the time - probably on an external service.

Here's what that looks like in practice:

```bash theme={null}
web@app.0:~$ cat /var/log/php.access.log | grep -Fa "$(date +%Y-%m-%d)" | sort -n -k 4 | tail -n 25
2024-04-25T01:43:53Z GET 404 9069.887 ms 14336 kB 1.43% /foo/bar/baz
2024-04-25T00:01:46Z GET 200 9603.032 ms 36864 kB 3.02% /baz/bar/qux
```

These requests took 9+ seconds but used only 1.43% and 3.02% CPU. That's not normal - sub-50% CPU usage generally indicates the request spent most of its time waiting, not processing.

If you have 4 workers and an external service goes down, you might see your request times go from 0.5 seconds to 30 seconds or more. Suddenly your site that could handle 8 requests/second can barely handle 1 request every 10 seconds, and you're getting 502 errors even though your traffic hasn't increased at all.

The fix: set sensible timeouts on every single API call. Think about what a reasonable response time is from the perspective of a user waiting on a page to load. If a third-party API takes more than 3 seconds to respond, that's probably too long for a synchronous page load.

Bonus tip: write code with the assumption that calls can timeout and react accordingly - retry the request, show an error message, or silently ignore the failure, depending on how critical that data is.

## The deadlock scenario: when your app calls itself

An even worse version of the missing timeout issue happens when your application calls its own API over HTTP. Here's how the deadlock unfolds:

1. User A's request comes in
2. **Worker 1** spins up to process request A (worker count: 1)
3. User B's request comes in
4. **Worker 2** spins up to process request B (worker count: 2)
5. **Worker 1** makes a `libcurl` call to your own website during processing
6. Request C comes in (originally from Worker 1), but can't be processed because both workers are already busy
7. **Worker 1** waits for a worker to become available
8. **Worker 2** makes a `libcurl` call to your own website during processing
9. Request D comes in (originally from Worker 2), but can't be processed because both workers are already busy
10. **Worker 2** waits for a worker to become available

Now both workers are waiting for workers to become available. Nobody can proceed. You have a deadlock.

Every new request that comes in now just adds to the pile. nginx starts timing out and returning 502 errors. Your site is effectively down until you restart php-fpm.

The telltale sign: you have a customer who says "I have to redeploy every few hours to bring the site back up."

### Diagnosing self-requests

You can check if your workers are calling themselves with this snippet:

```bash theme={null}
ofs=$(lsof)
for pid in $(ps faux|grep 'php-fpm: pool'|grep -v grep|awk '{print \$2}'); do
  echo "===== $pid =====" &&
  ps faux|grep $pid|grep -v grep|awk '{print \$2 "\t" \$13 "\t" \$14}' &&
  fds=$(ls /proc/$pid/fd -l|sed '1d'|awk '{print \$9 " " \$10 " " \$11}'|sort -n) &&
  echo "$fds" &&
  for fd in $(echo "$fds"|grep socket|cut -d'[' -f2| sed 's/]$//'); do
    echo "$ofs"|grep $pid|grep $fd|awk '{print \$5 " " \$6 " " \$8 " " \$9}';
  done;
done | less
```

This shows you what connections each php-fpm worker has open. You'll see normal stuff like:

* Connections to your database
* Connections to Redis
* Connections to external APIs (Stripe, AWS, etc.)

But sometimes you'll see a TCP connection to an IP address you recognize - the IP of Upsun's gateways. That means your worker is making an HTTP request back to your own application. If you see this pattern across multiple workers, you've found your problem.

For example, this output shows a connection to `18.200.179.139`, which is one of [Upsun's gateway IPs](https://docs.upsun.com/development/regions.html#ireland-eu-4-eu-4):

```
===== 38288 =====
38288   pool    web
...
IPv4 2516326193 TCP app.0:59654->ec2-18-200-179-139.eu-west-1.compute.amazonaws.com:https
```

That worker is calling itself.

### The fix

Don't call your own API over HTTP when you're already inside the same container. If you need data, query the database directly. If you absolutely must call your own API, you need to either:

1. Refactor to call the data layer directly instead of going through HTTP
2. Increase your worker count significantly to reduce the chance of deadlock
3. Set aggressive timeouts so the deadlock eventually breaks (not recommended)

Option 1 is always the right answer.

## Quick fixes when your site is down

If your site is currently down with 502 errors, here's what to do:

**Look for self-requests:**
Run that diagnostic snippet above and see if workers are connecting back to your own gateways. This is often the smoking gun.

**Check for external API timeouts:**
Search your codebase for `libcurl` calls and make sure every one has a timeout set. Look at your `php.access.log` for requests with low CPU % - that indicates waiting on external services.

**Monitor your request times:**
Check your PHP access logs to see if request times are spiking. If you're consistently seeing requests that take 5+ seconds, you need to optimize those endpoints or offload work to background jobs.

**Restart your application (last resort):**
If you've run out of time to debug and need to get back online immediately:

```bash theme={null}
systemctl --user restart app
```

This kills all php-fpm workers and starts fresh. It doesn't fix the underlying problem - the issue will come back - but it buys you time to investigate properly.

## Understanding the problem is half the battle

502 errors from php-fpm worker exhaustion happen for predictable reasons: slow requests, external APIs without timeouts, and self-requests creating deadlocks. Once you understand what's happening, you can fix the immediate problem.

But there's another half to this: configuring your workers properly so you don't run out in the first place. That involves understanding memory limits, sizing hints, and the relationship between workers and container resources. Stay tuned for an upcoming article diving into these details!


# Why Let's Encrypt certificate renewals fail
Source: https://developer.upsun.com/posts/how-it-works/why-lets-encrypt-certificate-renewals-fail

Certificate renewals fail for a handful of recurring reasons. Here's how the HTTP-01 challenge works and what breaks it, from IPv6 records to CDN rules.

<PostMeta />

You attach a domain, you get HTTPS, and 90 days later you get a fresh certificate without touching anything. [The provisioning system behind that](/posts/how-it-works/how-upsun-provisions-tls-certificates-at-scale) handles per-project Let's Encrypt accounts, and rate limits.

What that article didn't cover is what happens when a renewal fails. The failure is rarely in the certificate authority or in the provisioning code. It's almost always in the path between Let's Encrypt and your application, and the error message you get back is short on detail. Here are the causes that come up most often.

## How the challenge works

Before a certificate authority issues a certificate for `example.com`, it has to confirm that whoever asked for it controls that domain. That confirmation step is called a challenge.

Upsun mostly uses the [HTTP-01 challenge](https://letsencrypt.org/docs/challenge-types/#http-01-challenge). The flow has three steps:

1. Upsun asks Let's Encrypt for a certificate covering your domains, and Let's Encrypt replies with a random token for each domain.
2. Upsun serves each token at `http://<your-domain>/.well-known/acme-challenge/<token>`, for the duration of the certificate activity only.
3. Let's Encrypt resolves your domain in public DNS, sends an HTTP request to that URL, and reads the response.

If the response body matches the token it handed out, the domain is validated and the certificate is issued. If it doesn't match, or the request never arrives, the challenge fails and there's no certificate.

The tokens exist only while that activity runs. Once it finishes, the path stops serving them, which is why requesting a challenge URL yourself returns a 404 even on a project whose certificates are working.

Two properties of that flow explain nearly every failure. Let's Encrypt resolves your domain from public DNS, not from anything Upsun tells it. And the request has to travel all the way to the origin, through every layer you've put in front of it.

## The DNS record doesn't point to Upsun

This is the most common cause by a wide margin. If your `A` record points somewhere else, Let's Encrypt sends the validation request somewhere else, and the token it's looking for isn't there.

It sounds too obvious to be worth checking first, which is why it stays at the top of the list. The usual shape is a domain attached to a project before the DNS cutover, or a route defined for `www.example.com` when only the apex has a record. Both produce the same error:

```text theme={null}
  E: Error validating domain www.example.com: Couldn't complete challenge [HTTP01: pending | DNS01: pending | TLSALPN01: pending]
  Unable to validate domains www.example.com, will retry in the background.
```

Every domain in your [routes configuration](/docs/routes) goes into the certificate, and every domain in the certificate needs its own challenge. One unresolvable route fails the whole renewal.

## The AAAA record you forgot about

Here's the variant that costs people the most time. The `A` record is correct, the site loads fine in a browser, and the renewal still fails.

The reason is the `AAAA` record. If your domain has one, Let's Encrypt tries IPv6 first, and it doesn't fall back to IPv4 the way a browser would. Upsun doesn't publish `AAAA` records, so any IPv6 address on a domain pointed at your project sends the validation request to a server that has never heard of the token.

Nobody looks at `AAAA` records by default, which is what makes this one persistent. Check both families explicitly:

```bash theme={null}
  dig +short A www.example.com
  dig +short AAAA www.example.com
```

If the second command returns anything at all, that's your renewal failure. There's no Upsun IPv6 address to point it at instead, so the fix is to delete the record.

## A CAA record that excludes Let's Encrypt

A CAA record is your DNS zone declaring which certificate authorities are allowed to issue for the domain. If the record exists and Let's Encrypt isn't in it, issuance is refused before the challenge even runs.

```bash theme={null}
  dig +short CAA example.com
```

This is working as designed. Someone, often a security team consolidating on a single CA, decided that only that CA can issue certificates for the domain. It's a good control to have. It also means an automated Let's Encrypt renewal has no path forward until `letsencrypt.org` is added to the record, or until you upload your own certificates instead. Let's Encrypt's [CAA documentation](https://letsencrypt.org/docs/caa/) covers the record format, the value to add, and how it checks the record at issuance time.

The same applies to the fallback path. If a custom certificate you uploaded gets close to expiry, Upsun treats the domain as uncovered and tries to provision a Let's Encrypt certificate for it. With a CAA record that excludes Let's Encrypt, that safety net doesn't work either.

## Your CDN never forwards the challenge

When a CDN sits in front of your project, the validation request hits the CDN, and the CDN decides whether it reaches the origin. If `/.well-known/acme-challenge/` is cached, rewritten, or blocked at the edge, Let's Encrypt gets a response that Upsun didn't produce.

On Fastly, this usually comes from custom VCL. A rule that serves a static response for unknown paths, or a caching rule broad enough to cover `/.well-known/`, is enough to break it. Tokens are single-use and short-lived, which makes any cached response the wrong one.

Upsun's gateway checks the challenge path before handing validation over to Let's Encrypt, which is where this error comes from:

```text theme={null}
  W: Failed to verify the challenge at the gateway for the domain 'www.example.com'
  E: Error validating domain www.example.com: Couldn't complete challenge [HTTP01: The client lacks sufficient authorization]
```

Whatever you have at the edge, `/.well-known/acme-challenge/` has to reach the origin uncached, and the response has to be the one your application generated. See the [Fastly](/docs/domains/cdn/fastly) and [Cloudflare](/docs/domains/cdn/cloudflare) setup pages for the requirements.

Redirects are less of a problem here than people expect. Let's Encrypt follows up to 10 of them, to ports 80 and 443, and it doesn't check the certificate on an `https` target. That last detail is deliberate: it's what stops an expired certificate from blocking its own renewal. Forcing HTTPS at the edge is fine, and so is a `www` to apex redirect, as long as the request still ends up at your application. What breaks is a redirect that ends somewhere else, on a marketing site, a maintenance page, a redirect loop, or a chain longer than 10 hops.

## The Fastly snippet somebody cleaned up

There's a related failure worth separating out, because it's about the CDN's own certificate rather than the origin's.

If you're on Upsun's [managed Fastly integration](/docs/domains/cdn/managed-fastly), the setup adds a VCL snippet that lets Fastly's certificate renewals complete. It looks like leftover configuration from whoever set the service up. Delete it and nothing breaks, which is the problem: the edge certificate stays valid for weeks.

Then it comes up for renewal, the renewal fails, and visitors get a certificate warning on a site nobody deployed to in months. If you're auditing VCL, leave the ACME snippet alone.

## Cloudflare Bot Fight Mode

Cloudflare's Bot Fight Mode answers suspicious requests with a challenge page. Let's Encrypt's validation client is, by any reasonable definition, a bot. It gets the challenge page, doesn't solve it, and reports that the response didn't match the token.

The fix depends on your plan. On paid plans, add a WAF custom rule that skips bot protection for `/.well-known/acme-challenge/`, and the renewal completes. On the free plan there's no rule engine to add that exception to, which leaves turning Bot Fight Mode off. If bot protection is the reason you're on Cloudflare, that's not much of a choice, so an uploaded certificate or a paid plan is the practical answer.

## Too many domains for one certificate

Let's Encrypt allows at most 100 names per certificate, and Upsun provisions one certificate per environment covering all of that environment's domains.

The 100 sounds generous until you count the way routes actually work. A project with 50 custom domains that also serves each one under `www` needs 101 names, and the request is rejected. Fleet setups hit this most, since every site added to the fleet adds two names.

If you're near the limit, the options are to drop the `www` variants you don't need, or to split the domains across environments.

## Anything else in the request path

The pattern behind all of the above is the same. Let's Encrypt's request has to reach your application and come back with an exact string, and every hop in between is a chance for something to answer on your behalf.

Multiple CDNs stacked in front of each other, a redirect chain that ends on a maintenance page, a WAF rule blocking paths that start with a dot, an edge rule serving a static response for unknown paths: all of them produce the same unhelpful failure. When you're debugging, request the challenge path yourself from outside your network:

```bash theme={null}
  curl -I http://www.example.com/.well-known/acme-challenge/test
```

A 404 from your application is the expected result. Anything else, a cached page, a bot challenge page, a 403, or a redirect that doesn't end at your application, tells you which layer to look at. The [certificate checker](https://certcheck.upsun.com/) is a faster way to see where a domain currently points, and [the troubleshooting guide](/docs/domains/troubleshoot#ownership-verification) lists the errors alongside the DNS records they map to.

## Report the failure somewhere you'll see it

None of the above helps if the failure only exists in an activity log nobody opens. Renewals emit their own activity type, `environment.certificate.renewal`, and every activity carries a `result` field that's either `success` or not. That's all you need to alert on.

Point a [webhook integration](/docs/integrations/activity/webhooks) at the event, scoped to completed activities:

```bash theme={null}
  upsun integration:add --type webhook \
    --url https://alerts.example.com/upsun \
    --events environment.certificate.renewal \
    --states complete
```

Your endpoint gets a POST for every renewal, and you raise an alert when `result` isn't `success`. If you'd rather not host a receiver, an [activity script](/docs/integrations/activity) runs the same check on Upsun and posts to Slack or Discord directly:

```javascript theme={null}
  if (activity.result !== "success") {
    sendSlackMessage("Certificate renewal failed", activity.log);
  }
```

The `activity.log` property holds the same provisioning output shown earlier, which means the alert arrives with the error message already in it. Scope the integration to the events you care about rather than all of them, or every push becomes a notification.

## Renewals fail early, on purpose

Upsun starts renewing Let's Encrypt certificates four weeks before they expire, and retries in the background until they succeed. That window exists for exactly this class of problem. Today's failed challenge doesn't take your site down, and the retries give you weeks to find the `AAAA` record or the VCL rule.

The window only helps if the failure reaches a human. A certificate that expires in production has usually been failing its renewal for weeks, which is why the webhook is worth the 10 minutes it takes to set up.


# Why we moved from LVM to Ceph for container storage
Source: https://developer.upsun.com/posts/how-it-works/why-upsun-moved-from-lvm-to-ceph

Upsun migrated from LVM to Ceph for container storage to separate compute from storage, enable instant volume migration, and make VMs disposable again.

<PostMeta />

Data cloning is one of Upsun's core features. When you create a [preview environment](https://developer.upsun.com/docs/glossary#preview-environment), we clone your production disk, including your database, your files, everything. This has to be fast (seconds, not minutes), and it has to be correct. The entire capability depends on the storage layer underneath.

We started with LVM. We eventually moved to Ceph. The reasons tell you a lot about what it takes to run containers at scale.

## The feature that drives everything: data cloning

Preview environments are only useful if they have real data. A staging environment with an empty database doesn't tell you much about how your application behaves in production.

Copy-on-write (CoW) cloning makes this practical. Instead of copying hundreds of gigabytes of data, you create a logical snapshot that shares the underlying blocks with the original. New writes go to new blocks. Reads fall through to the shared data. The clone is instant and costs almost no additional storage until changes accumulate.

LVM supports this through LV snapshots. When you create a preview environment, we'd snapshot the production logical volume and hand the snapshot to the new container. Fast, efficient, and it worked well for years.

## LVM: what worked and what didn't

Our LVM setup ran on AWS at the time (we're multi-cloud now, but we'll use EBS terminology here since that's what we were working with).

LVM did the job initially. LV snapshots gave us CoW cloning, and we could provision volumes quickly on a single VM. But as we scaled, several problems became hard to ignore.

The most fundamental issue was that volumes were tied to a specific VM. Each logical volume lived on a specific host's EBS storage. Moving a container to a different VM meant stopping it, detaching the EBS volume, reattaching it to the new host, and restarting. This took minutes, not seconds, and created downtime.

This also meant all clones had to live on the same VM as production. LV snapshots exist within the same volume group, so your preview environments had to run on the same physical host as your production environment. No isolation between production and development workloads.

VM death was catastrophic, and in the cloud, VMs die. Not constantly, but regularly enough that you have to design for it. This isn't dedicated hardware sitting in a rack for five years. If a VM went down, every container on it went down with it. Recovery was slow and sequential: bring the VM back, check the file systems, restart containers one by one. You couldn't spin them up elsewhere because the data was physically attached to that host.

Backup granularity was another pain point. You couldn't surgically restore one customer's volume from an EBS snapshot. Restoring a single volume meant restoring the entire disk.

Adding storage capacity was also painful. You had to expand the EBS volume, then resize the physical volume, the volume group, and the logical volume. Multiple steps, each with its own failure modes, and you had to do it per VM.

All of this made VMs into pets. Each one had unique, irreplaceable data on its local storage. You couldn't terminate one and replace it with a fresh instance. Every host was special, and that's the opposite of what you want in a cloud-native infrastructure.

## Why Ceph

[Ceph](https://ceph.io/) (specifically Ceph RBD, not CephFS) checked most of our boxes. It supports CoW cloning natively, replicates data across nodes, and on top of that gives you network-attached block devices that can be mapped to any VM in under a second.

Storage and compute become separate concerns. Ceph runs on dedicated storage nodes, and compute VMs don't store any persistent data. You can optimize each fleet independently: storage-optimized instances for Ceph OSDs, compute-optimized instances for running containers. With EBS, you're technically not paying for storage compute directly, but it's baked into the price and you don't control it. With Ceph, you manage it yourself, which is more work but also means you can tune it to your actual workload.

Because volumes live on the Ceph cluster and not on any particular VM, you can map and unmap them from any host instantly. Container migration becomes trivial. Need to move a workload? Unmap the RBD image, map it on the new VM, start the container. The data doesn't move because it was never on the VM in the first place.

CoW cloning still works. Ceph RBD supports snapshots and cloning natively. There's a depth limit (we flatten at 16 parent levels) for clone chains to keep performance predictable. The cloning itself is still instant.

Since volumes aren't tied to hosts, your preview environment can run on a completely different VM than production. Better isolation, better resource allocation. Production and development workloads no longer compete for the same host resources.

Ceph also replicates data across multiple storage nodes. Losing one storage VM doesn't lose data. The cluster heals itself by re-replicating from surviving copies. And if a compute VM dies, you spin up the containers on another VM and map their volumes. No data recovery, no file system checks. The volumes were never on the failed host.

Scaling storage capacity is also straightforward. Need more space? Add new storage nodes to the cluster. Ceph rebalances automatically. No per-VM EBS resizing, no pv/vg/lv dance.

The net result is that VMs become cattle again. Compute VMs are stateless and disposable. You can terminate any of them and replace them with fresh instances. Auto-scaling becomes straightforward.

## Trade-offs

Ceph isn't free of downsides.

The blast radius shifts. With LVM, a VM failure affected only the containers on that VM. With Ceph, a storage cluster issue can potentially affect every container using that cluster. The failure mode is different: less frequent, but wider.

Operational complexity also increases. Running a Ceph cluster requires specific expertise. Monitoring, capacity planning, OSD management, placement group tuning. It's a meaningful operational investment.

The risk-to-reward ratio is worth it. The ability to treat compute VMs as disposable, to migrate containers quickly, and to scale storage independently of compute changes the operational model fundamentally.

For details on how we handle backups on top of Ceph, see how Ceph snapshots enable incremental full backups.

## The storage layer shapes everything

The choice of storage architecture isn't a background infrastructure decision. It directly determines what features you can offer and how reliably you can offer them. Preview environments with instant data cloning, fast container migration, self-healing after hardware failures: all of these trace back to the storage layer.

LVM worked until it didn't. Ceph gave us the flexibility to treat compute and storage as independent concerns, and more importantly, it let us treat our infrastructure as cattle, not pets. VMs come and go, containers move between hosts, and nothing breaks. That's the foundation everything else is built on.


# Write a Git server with per-branch permissions in five minutes
Source: https://developer.upsun.com/posts/how-it-works/write-a-git-server-with-per-branch-permissions-in-five-minutes

Upsun's most basic API is a Git server. Build one in Python with Dulwich and Paramiko, and add per-branch read permissions in a single method.

<PostMeta />

Every time you deploy on Upsun, you use a Git server. You run `git push`, and something on the other end receives your code and turns it into a running application. Strip away the dashboards and the CLI, and that push is the most basic API we offer.

A Git server sounds like a big thing to operate. It isn't. You can write one that serves real clones and pushes in about as long as it takes to read this post. And once you have, one feature that sounds trivial turns out to be the interesting part: showing different branches to different users.

That last part deserves a second look. When you `git clone` a repository from GitHub, you get every branch. You don't pick a subset. The client asks for the repository and the server hands over its full set of refs. How would a server ever hide a branch from someone? The answer lives in a corner of Git most people never open.

## A Git server is an SSH server that runs two commands

When you clone over SSH, Git opens an SSH connection and runs a single command on the far side. The URL you typed is really an instruction to execute a program on the server:

```bash theme={null}
$ git clone ssh://git@example.com/myrepo.git

# under the hood, Git runs this over SSH:
$ ssh git@example.com "git-upload-pack '/myrepo.git'"
```

Two commands matter. `git-upload-pack` serves fetches and clones. `git-receive-pack` serves pushes. The names read from the server's point of view, which is why they feel inverted the first time you meet them. When you clone, the server uploads objects to you, so it runs upload-pack. When you push, the server receives objects from you, so it runs receive-pack.

SSH is only the transport. On top of it, the client and server speak a protocol Git defines. The server advertises its refs, the branches and tags it holds and the commit each one points at. The client replies with the object IDs it wants. The server works out which objects the client is missing and streams them back as a packfile, a compressed bundle of Git objects.

One step in that exchange is where branch permissions live. The server advertises its refs first, and the client can only ask for what it has been shown. Control the advertisement, and you control what a user can see and fetch. That is the whole trick.

## The pieces

Two Python libraries do the heavy lifting. [Dulwich](https://www.dulwich.io/) is a pure-Python implementation of Git that already speaks the protocol on the server side. [Paramiko](https://www.paramiko.org/) is a pure-Python SSH implementation that can act as a server. Your job is to connect the two and slip your own authorization in between.

```bash theme={null}
$ pip install dulwich paramiko
```

Start with authentication, and keep it to a bare minimum: the username. A real server maps an SSH public key to a user account. Here you take whatever username the client connects as and trust it, so the code stays about permissions rather than credentials.

<Warning>
  This server authenticates nobody. It trusts the username the client claims and accepts a connection with no key and no password. That is fine for reading the code and running it on your laptop, and completely unfit for anything reachable by other people. Wire in public-key authentication before this touches a network you don't control.
</Warning>

The SSH side is a Paramiko `ServerInterface`. It records the username, accepts the session, and captures the command Git asks to run:

```python theme={null}
import shlex
import socket
import threading

import paramiko
from dulwich.repo import Repo
from dulwich.server import (
    FileSystemBackend,
    ReceivePackHandler,
    UploadPackHandler,
    serve_command,
)

host_key = paramiko.RSAKey.generate(2048)


class GitServer(paramiko.ServerInterface):
    def __init__(self):
        self.username = None
        self.command = None
        self.exec_event = threading.Event()

    def get_allowed_auths(self, username):
        return "none"

    def check_auth_none(self, username):
        self.username = username
        return paramiko.AUTH_SUCCESSFUL

    def check_channel_request(self, kind, chanid):
        if kind == "session":
            return paramiko.OPEN_SUCCEEDED
        return paramiko.OPEN_FAILED_ADMINISTRATIVELY_PROHIBITED

    def check_channel_exec_request(self, channel, command):
        self.command = command.decode()
        self.exec_event.set()
        return True
```

When Git connects, it opens a channel and asks to execute `git-upload-pack` or `git-receive-pack`. You parse that command, pick the matching Dulwich handler, and hand the channel's input and output to Dulwich's `serve_command`, which runs the whole protocol conversation:

```python theme={null}
HANDLERS = {
    "git-upload-pack": UploadPackHandler,
    "git-receive-pack": ReceivePackHandler,
}

REPO_ROOT = "/srv/git/"


class ChannelWriter:
    def __init__(self, channel):
        self.channel = channel

    def write(self, data):
        self.channel.sendall(data)

    def flush(self):
        pass


def handle(client):
    transport = paramiko.Transport(client)
    transport.add_server_key(host_key)
    server = GitServer()
    transport.start_server(server=server)
    channel = transport.accept(20)
    if channel is None:
        return
    server.exec_event.wait(20)

    argv = shlex.split(server.command)
    handler_cls = HANDLERS.get(argv[0])
    if handler_cls is None:
        channel.close()
        return

    argv[1] = argv[1].lstrip("/")
    backend = FileSystemBackend(REPO_ROOT)
    serve_command(
        handler_cls,
        argv,
        backend=backend,
        inf=channel.makefile("rb"),
        outf=ChannelWriter(channel),
    )
    channel.send_exit_status(0)
    channel.close()
    transport.close()


def main():
    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
    sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
    sock.bind(("0.0.0.0", 2222))
    sock.listen()
    while True:
        client, _ = sock.accept()
        threading.Thread(target=handle, args=(client,), daemon=True).start()


if __name__ == "__main__":
    main()
```

Point `REPO_ROOT` at a directory of bare repositories and run it. That is a working Git server. You can clone from it, push to it, and it behaves like any other. Every user sees every branch, because `FileSystemBackend` advertises whatever refs the repository holds. That is exactly the behavior you now want to change.

## The feature: per-branch permissions

To hide a branch from a user, change what counts as "the refs" for that user. Dulwich reads a repository through a `Repo` object, and the ref advertisement flows through its `get_refs` method. Subclass `Repo`, override that one method, and filter the result by the connected user:

```python theme={null}
PERMISSIONS = {
    "alice": {"refs/heads/main", "refs/heads/dev", "refs/heads/secret"},
    "bob": {"refs/heads/main"},
}


def is_allowed(username, ref):
    return ref.decode() in PERMISSIONS.get(username, set())


class PermissionedRepo(Repo):
    username = None

    def get_refs(self):
        refs = super().get_refs()
        visible = {
            ref: sha
            for ref, sha in refs.items()
            if ref != b"HEAD" and is_allowed(self.username, ref)
        }
        head = refs.get(b"HEAD")
        if head in visible.values():
            visible[b"HEAD"] = head
        return visible
```

A small backend hands Dulwich this repo class instead of the default one, carrying the username through:

```python theme={null}
class PermissionedBackend(FileSystemBackend):
    def __init__(self, root, username):
        super().__init__(root)
        self.username = username

    def open_repository(self, path):
        repo = PermissionedRepo(self.root + path)
        repo.username = self.username
        return repo
```

Swap the `backend` line in `handle` to build a `PermissionedBackend(REPO_ROOT, server.username)`, and the filtering is in force.

The `HEAD` handling earns its two extra lines. `HEAD` tells the client which branch is the default, and a clone needs it. You drop it during the filter, then add it back only when it points at a branch the user is allowed to see. A user with no access to the default branch gets no `HEAD`, which is the right outcome.

## Trying it out

The server hands out bare repositories, the kind without a working tree. You can turn any repository you already have into one with `git clone --bare`, which copies its full set of branches:

```bash theme={null}
$ git clone --bare /path/to/some/repo /srv/git/myrepo.git
Cloning into bare repository '/srv/git/myrepo.git'...
done.

$ git -C /srv/git/myrepo.git branch
  dev
* main
  secret

$ python gitserver.py &
```

On the client side, skip host-key prompts so the demo stays quiet, then ask each user what they can see:

```bash theme={null}
$ export GIT_SSH_COMMAND='ssh -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null'

$ git ls-remote ssh://alice@localhost:2222/myrepo.git
6a86220cc92fe113ead0a10056cf1da5a3a1fb4e	HEAD
26ce3be07260bac0cd3f976bf4c10cf7851743a0	refs/heads/dev
6a86220cc92fe113ead0a10056cf1da5a3a1fb4e	refs/heads/main
629d16e9a78f0c46a6695e11b4dc2ed50de3aa4d	refs/heads/secret

$ git ls-remote ssh://bob@localhost:2222/myrepo.git
6a86220cc92fe113ead0a10056cf1da5a3a1fb4e	HEAD
6a86220cc92fe113ead0a10056cf1da5a3a1fb4e	refs/heads/main

$ git ls-remote ssh://carol@localhost:2222/myrepo.git
```

Alice is allowed all three branches, so she sees all three. Bob is allowed only `main`, so `dev` and `secret` never reach him. Carol is in nobody's permission list, so the repository looks empty to her. A clone as Bob pulls exactly one branch:

```bash theme={null}
$ git clone ssh://bob@localhost:2222/myrepo.git
$ git -C myrepo branch -r
  origin/HEAD -> origin/main
  origin/main
```

This is not only about what gets advertised. If Bob learns the commit ID of the `secret` branch some other way and asks for it directly, the server refuses the request. Dulwich checks every requested object ID against the refs it advertised to that user, so a branch Bob can't see is a branch Bob can't fetch.

## Where this stops being a toy

The core idea scales further than the code does. A production Git server built on this shape still needs a few things this one skips.

* Real authentication. Map SSH public keys to user accounts, and reject unknown keys.
* Write permissions. The same idea applies to `git-receive-pack`. Check the user against the refs they are trying to update before accepting a push, and reject the ones they aren't allowed to change.
* Reachability rules. This server advertises no capability that lets clients request arbitrary commits by ID, which keeps hidden history hidden. A larger server has to stay deliberate about that.
* Auditing, quotas, and the hooks that run your actual deploy.

The shape holds underneath all of it. A Git server is an SSH server that runs `git-upload-pack` and `git-receive-pack`, plus whatever policy you insert at the ref advertisement.

This isn't a toy stack, either. Upsun runs Dulwich in production. The Git server that receives your `git push` and turns it into a deployment is built on the same library you used here, wired to real accounts, real infrastructure, and the policy checks this version leaves out. When you push code and only see the environments you're allowed to see, that's the ref advertisement doing its job at scale. The version you built is the version that's running.


# Your WAF is buffering. Ours is streaming.
Source: https://developer.upsun.com/posts/how-it-works/your-waf-is-buffering-ours-is-streaming

Most WAFs buffer your entire request before validating it. That's slow. Upsun's technical WAF validates requests while streaming them to your backend, so you don't pay a latency tax for security.


<PostMeta />

Web Application Firewalls (WAFs) have a reputation problem. They sit in front of your application, inspect every request, and add latency. The security folks love them. The performance folks tolerate them. Everyone accepts this tradeoff because what's the alternative?

Here's the thing: that tradeoff isn't inevitable. The latency comes from how most WAFs work, not from what they do.

## The buffering problem

Traditional WAFs follow a simple pattern:

1. Receive the entire request
2. Validate it
3. If valid, forward it to the backend
4. If invalid, reject it

This means your backend sits idle while the WAF buffers and inspects. For a small JSON payload, you might not notice. For a large file upload, you will.

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant WAF
    participant Backend

    Client->>WAF: Request body (streaming)
    Note over WAF: Buffering entire request...
    Note over WAF: Validating...
    WAF->>Backend: Forward complete request
    Note over Backend: Now processing can begin
```

Your backend doesn't see anything until the WAF finishes its job. The latency adds up.

## What if we validated while streaming?

Upsun runs a technical WAF as part of its infrastructure. "Technical" because it focuses on protocol-level validation rather than application-layer attacks like SQL injection. It checks that your JSON is actually JSON, that your request headers make sense, and that the HTTP protocol is being followed correctly.

The key insight: you don't need the entire request to start validating it. And you don't need validation to finish before you start forwarding.

Upsun's edge layer forwards incoming requests to both the WAF and your backend simultaneously. The backend receives the data as it arrives. The WAF validates it at the same time. If validation passes, the backend already has everything it needs. If validation fails, the edge layer cuts the connection before the backend processes anything.

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant Edge
    participant WAF
    participant Backend

    Client->>Edge: Request body (streaming)
    Edge->>WAF: Forward (streaming)
    Edge->>Backend: Forward (streaming)
    Note over WAF,Backend: Both happen in parallel
    WAF->>Edge: Validation passed
    Edge->>Backend: End-of-stream marker
    Note over Backend: Processing begins
```

The trick is that "end-of-stream marker" at the end. The backend receives data but doesn't start processing until it knows the request is complete. The edge layer only sends that marker after the WAF confirms validation passed.

## HTTP/2 makes this elegant

HTTP/2 works in frames, and one of those frames is an explicit end-of-stream marker. This is exactly what we need.

The edge layer receives frames from the client and immediately forwards them to both the WAF and backend. Both process the incoming data in parallel. When the client finishes sending, the WAF completes validation. If everything checks out, the edge layer forwards the end-of-stream frame to the backend. The backend, which already has all the data buffered, starts processing immediately.

If validation fails? The edge layer closes the connection to the backend. The backend never received that end-of-stream marker, so it discards the partial request.

Most requests are valid. This means most of the time, by the moment validation completes, your backend is ready to go. The latency tax drops to nearly zero.

## HTTP/1.1 is trickier

HTTP/1.1 doesn't have built-in stream markers, but chunked transfer encoding provides something similar. With chunked requests, you send data in pieces, and a zero-length chunk signals the end.

So the same pattern works: stream chunks to the backend, validate in parallel, send the final chunk only after validation passes.

But there's a catch.

## PHP-FPM doesn't support chunked requests

If your backend is PHP-FPM, you're out of luck. It doesn't understand chunked transfer encoding. It can't buffer incoming chunks and wait for that final marker before processing. It just doesn't.

The workaround: Nginx buffers the request before passing it to PHP-FPM. This means PHP applications don't get the streaming benefit. They still get the security validation, but they pay the latency cost of buffering.

For most PHP applications, this is fine. Typical web requests are small, and the buffering overhead is minimal.

## But what about WebSockets?

Some applications genuinely need streaming. WebSocket connections, for example, are long-lived and bidirectional. Buffering them would break everything.

The good news: if your backend isn't PHP-FPM, the streaming WAF works fine. Node.js, Go, Python, and most other runtimes handle chunked requests without issues. You get both streaming and WAF validation.

Upsun provides [configuration options to disable request buffering](https://docs.upsun.com/create-apps/image-properties/web.html#request-buffering) for routes that need it.

## The takeaway

WAF latency isn't a law of physics. It's an implementation choice. By streaming requests to the backend while validating in parallel, you can have security without the performance penalty.

The approach works best with HTTP/2 or HTTP/1.1 chunked encoding. PHP-FPM applications need buffering as a workaround, but that's a limitation of the runtime, not the architecture.

Most of this happens invisibly. Your requests get validated, your backend processes them, and you don't notice the WAF sitting in the middle. Which is exactly how security infrastructure should work.


# How to automate load tests with Gatling
Source: https://developer.upsun.com/posts/how-tos/automate-with-gatling-1



<PostMeta />

When I was on your side of the keyboard, developing cool and funny applications (more or less :D), load tests were (most of the time) executed a few days before going live.
We sometimes discover rabbits in the hole, doing too much stuff, and then, we switch to firefighter mode to solve all of the issues. That was not a great experience.

All applications should be load tested, from the beginning and along the way, as a default.
We will see in this guide how to set up your Upsun project for running automatic load tests on each push on your Upsun preview environments.

In this article, we'll add an [Activity Script](https://docs.upsun.com/integrations/activity/reference.html) [integration](https://docs.upsun.com/integrations/activity.html), that will in turn call a [runtime operation](https://docs.upsun.com/create-apps/runtime-operations.html), which will then execute a [Gatling](https://gatling.io/) simulation to load test our environment.
Gatling CORP is a french company and they provide tools to load test your application, with two versions of their product: a Community (free) and Cloud (Enterprise) version of their product.

<Note>
  **Note:**

  If you want to learn more about what and why it is important to load test your application, please see [this blog post](https://gatling.io/blog/why-we-test-the-beginners-guide-to-why-load-testing-is-important) from Peter Dukta (Gatling), you will find everything you want.
</Note>

## Gatling and load tests

<Note>
  **Assumptions:**

  * You already have a project hosted on Upsun.
  * You have the Upsun CLI installed.
</Note>

### Install the Javascript SDK

First step is to install the Javascript SDK from Gatling documentation.
To install it locally, run the following commands:

```bash {filename="Terminal"} theme={null}
wget https://github.com/gatling/gatling-js-demo/archive/refs/heads/main.zip
unzip gatling-js-demo-main.zip 
mv gatling-js-demo-main gatling
rm -Rf gatling-js-demo-main.zip
git add gatling && git commit -m “Add Gatling SDK”
```

### Install dependencies

To install Gatling libraries during the build hook, add the following in your `.upsun/config.yaml` file:

```yaml {filename=".upsun/config.yaml",hl_lines=["5-7", "12-14"],linenostart=1} theme={null}
applications:
  app:
    mounts:
      # ...
      "/.gatling": { source: storage, source_path: "gatling" }
      "/.cache": { source: storage, source_path: "node-cache" }
      "/gatling/javascript/target": { source: storage, source_path: "gatling-target" }
    hooks:
      build: |
        set -x -e
        # ...
        cd gatling/javascript
        npm install
        npx gatling install --gatling-home $(pwd)
```

Then add your config.yaml file to your Git history:

```bash {filename="Terminal"} theme={null}
git add .upsun/config.yaml && git commit -m "install Node + Gatling dependencies"
```

### Define a simulation

Create a new `gatling/javascript/src/myfirstsimulation.gatling.js` file with the following source code:

```js {filename="gatling/javascript/src/myfirstsimulation.gatling.js"} theme={null}
import {scenario,simulation,constantUsersPerSec} from "@gatling.io/core";
import {http} from "@gatling.io/http";
import { getParameter } from "@gatling.io/core";

const uri = getParameter(
   "uri", // Dynamic uri of your preview environment
   "localhost" // Default value for your local testing (optional)
);

export default simulation((setUp) => {
   // Add the HttpProtocolBuilder:
   const httpProtocol =
       http.baseUrl(uri)
           .acceptHeader("application/json")
           .contentTypeHeader("application/json");
   // Add the ScenarioBuilder:
   const homepageScenario = scenario("Scenario Homepage")
       .exec(http(uri).get("/"));

   // Add the setUp block:
   setUp(homepageScenario.injectOpen(constantUsersPerSec(2).during(60))).protocols(httpProtocol);
});
```

<Note>
  For your homepagescenario scenario to load test your dynamic preview environment url, we will inject an uri parameter (line 6) during the [run command call ](https://docs.gatling.io/reference/integrations/build-tools/js-cli/#running-your-simulations)(see next steps).
</Note>

Then add your `myfirstsimulation.gatling.js` file to your Git history:

```bash {filename="Terminal"} theme={null}
git add gatling/javascript/src/myfirstsimulation.gatling.js && git commit -m "Create Gatling simulation"
```

### Get environment URI

To dynamically get the current environment URI, from the `PLATFORM_ROUTES` environment variable, you can use an `.environment` file that will dynamically build it.
Create a new `.environment` file, at the root of your application with the following lines:

```bash {filename=".environment"} theme={null}
export URI=$(echo $PLATFORM_ROUTES | base64 --decode | jq -r 'to_entries[] | select (.value.upstream == "app") | .key')
```

Then add this `.environment` file to your Git history.

```bash {filename="Terminal"} theme={null}
git add .environment && git commit -m "Add URI envVar"
```

### Define runtime operation

[Runtime operations](https://docs.upsun.com/create-apps/runtime-operations.html) allow you to trigger one-off commands or scripts on your application (preview) container. We will then be able to execute it using an Activity script integration.
Update your `.upsun/config.yaml` file with the following:

```yaml {filename=".upsun/config.yaml",hl_lines=["4-11"],linenostart=1} theme={null}
application:
  app:
    operations:
      gatling_myfirstsimulation:
        role: admin
        commands:
          start: |
            if [ "$PLATFORM_ENVIRONMENT_TYPE" != production ]; then
              cd gatling/javascript
              npx gatling run --simulation="myfirstsimulation" --gatling-home $(pwd) uri=$URI   
            fi
```

<Note>
  The `npx gatling run` command has a `uri=$URI` parameter, using the previously created URI environment variable.
</Note>

Then add your `.upsun/config.yaml` file to your Git history.

```bash {filename="Terminal"} theme={null}
git add .upsun/config.yaml && git commit -m "Add Gatling runtime operation"
```

### Create activity script

Create a new Javascript file (our Activity script file) at the root of your source code, `gatling-worker.js` ([source here](https://github.com/upsun/snippets/blob/main/src/gatling/gatling-worker.js)) with the following command line:

```bash {filename="Terminal"} theme={null}
curl -L https://raw.githubusercontent.com/upsun/snippets/main/src/gatling/gatling-worker.js > gatling-worker.js
git add gatling-worker.js && git commit -m "Add Activity Script gatling-worker.js"
upsun push
```

This activity script uses an [API Token](https://docs.upsun.com/administration/cli/api-tokens.html#2-create-an-api-token), as an [environment variable](https://docs.upsun.com/development/variables.html), to connect to the current environment and execute the previously defined [runtime operation](https://docs.upsun.com/create-apps/runtime-operations.html) using the Upsun API. We need to define this environment variable for the integration of our activity script, and later add an API Token environment variable.

<Note>
  You will be able to run this runtime operation on demand from both command line (CLI) and the Console.
</Note>

### Add integration

Let say we would like to load tests our environment, each time we push new source code on it (corresponding event is `environment.push`).

```bash {filename="Terminal"} theme={null}
upsun integration:add --type script --file ./gatling-worker.js --events environment.push \
    --states complete --environments *
```

<Note>
  A complete list of possible events is available as the [Activity script type definition](https://docs.upsun.com/integrations/activity/reference.html#type). Any of those Activity Script types can be added as an event list in the `--events event1,event2,...` option.
</Note>

### API tokens

First, get the previous integration ID using the following command:

```bash {filename="Terminal"} theme={null}
upsun integration:list
```

Then, create a new [API Token from the Console](https://docs.upsun.com/administration/cli/api-tokens.html#2-create-an-api-token), keep the value in your hand, and replace it in this terminal command:

```bash {filename="Terminal"} theme={null}
upsun project:curl /integrations/<INTEGRATION_ID>/variables -X POST \
    -d '{"name": "api_token", "value": "<API_TOKEN>", "is_sensitive": true, "is_json": false}'
```

<Note>
  Replace `<INTEGRATION_ID>`and `<API_TOKEN>` with the corresponding values previously create
</Note>

You can verify that the variable has been created with this command:

```bash {filename="Terminal"} theme={null}
upsun project:curl /integrations/<INTEGRATION_ID>/variables
```

### Time to test

To test it, create a new feature branch and push an update to your preview environment, you will see an activity script event that will contain logs of your load tests.
When opening the log of the `gatling_myfirstsimulation`  runtime operation, you will see the full load test report.

### Online report

At the end of this report, you will see that Gatling simulation generates a local HTML report to get the full view of the simulation.

```txt {filename="Logs from gatling_myfirstsimulation runtime operation"} theme={null}
Reports generated, please open the following file: file:///app/gatling/javascript/target/gatling/jssimulation-20240912123722990/index.html
```

To allow remote access to this HTML report file, you just need to allow a new routes by adding a new `web.locations` rule to your application.
To generate in your report the corresponding report url, you will also need to change your runtime operation to display it.

In your `.upsun/config.yaml` file, update the following:

```yaml {filename=".upsun/config.yaml",hl_lines=["6-8", "15-24"],linenostart=1} theme={null}
applications:
  app:
    web:
      locations:
        #...
        "/gatling":
          root: "gatling"
          passthru: true

    operations:
      gatling_myfirstsimulation:
        role: admin
        commands:
          start: |
            if [ "$PLATFORM_ENVIRONMENT_TYPE" != production ]; then
              cd gatling/javascript
              echo "Gatling simulation myfirstsimulation in progress, please wait."
              return=$(npx gatling run --simulation="myfirstsimulation" uri=$URI --gatling-home $(pwd))
              echo "$return"
              
              # adding online link
              filepath=$(echo $return | sed 's/.*file:\/\/\/app\///')
              echo "To access online report, follow this link: $URI$filepath"
            fi
```

Then deploy this change:

```bash {filename="Terminal"} theme={null}
git add .upsun/config.yaml && git commit -m "adding Gatling web rule" && upsun push -y
```

When deploy is finished, you will find, at the end of the runtime operation logs, the generated url of your Gatling load test report and you just need to copy/paste it to your browser, something like:

<img alt="Gatling Community Edition view, running on an Upsun environment at /gatling, showing response time ranges for 120 requests to the homepage as defined by simulation myfirstsimulation." />

### Troubleshooting

If during deployment, when installing Gatling, you get an error telling that the process has been killed, this means that your container is not having enough RAM.

```bash theme={null}
2:22:54 PM Downloading GraalVM Community Edition 22.0.2 to /app/.gatling/tmp/download/graalvm.tar.gz
Unpacking GraalVM to /app/.gatling/graalvm/22.0.2
W: Killed
```

As the Gatling javascript SDK is using [Graalvm JDK](https://www.graalvm.org/) to run load tests locally on the application container, resources (RAM) needs to be adjusted.
By default, PHP containers use a `HIGH_CPU` container profile, which means 0.5 CPU and 224MB of RAM.\
We need to increase the allocated RAM by updating the container profile of our application container to `BALANCED` (0.5CPU & 1088MB RAM)

```yaml {filename=".upsun/config.yaml",hl_lines=["4"],linenostart=1} theme={null}
applications:
  app:
    #...
    container_profile: BALANCED
```

## Conclusions

Load testing your application is crucial if you are running applications with a lot of
traffic spikes or if you’re facing TV show effects.

In this guide, we took a look at how to set up an on-demand set of load tests with Gatling community edition that could be triggered (and observed) on a new Upsun preview environment using a runtime operation.
Some next steps could include automatically triggering these operations when preview environments (merge/pull requests) are opened.

An additional caveat to consider is that load testing in this way -- running Gatling within Upsun application containers -- will consume resources in your projects.
In a follow-up posts, we will see how to use the Gatling Cloud (and so, external resources) to run load tests.

Remain up-to-date on the latest from us over on our social media and community channels: [DEV.to](https://dev.to/upsun),
[Reddit](https://www.reddit.com/r/upsun/), and the [Upsun Community Forum](https://community.upsun.com/).


# Automated encrypted backups to Amazon S3 | Upsun
Source: https://developer.upsun.com/posts/how-tos/automated-encrypt-backups-amazon-s3

Learn how to configure Duplicity, GPG keys, and cron on Upsun to send incremental, encrypted backups of your application to AWS S3 for reliable restores


<PostMeta />

A secure, automated backup solution for applications hosted on Upsun can be implemented using Duplicity with GPG encryption to back up data to Amazon S3. This approach ensures data integrity, confidentiality, and recoverability. The following guide outlines how to set up such a system.

## Why this backup strategy?

Traditional backup methods often fall short in cloud-native environments: they may lack encryption, require manual intervention, or fail to integrate cleanly with immutable infrastructure. An S3-based backup solution using Duplicity and GPG encryption addresses these gaps through the following design choices:

### End-to-end encryption:

All backups are encrypted at rest using GPG before leaving the application container. Even if S3 credentials are compromised, data remains protected by a strong passphrase and private key. Private keys and passphrases should never be stored in plaintext on the platform.

### Efficient incremental backups

Duplicity uses incremental syncing, meaning only changed files are uploaded after the initial full backup. This reduces bandwidth, storage costs, and backup windows. Critical for large Drupal sites with frequent file uploads.

### Cloud-native and portable

By using AWS S3 (a durable, versionable, and globally available object store) and boto3 (the official AWS SDK), avoid vendor lock-in while leveraging battle-tested infrastructure. The same backup can be restored anywhere, like Upsun, local dev, or another cloud.

### Declarative and reproducible

Thanks to Upsun’s composable Nix stack, every dependency (Duplicity, GnuPG, Python packages) is versioned and immutable. There’s no “works on my machine” problem. Your backup environment is identical across all deployments.

### Fully automated

With cron-driven execution and deploy-time key setup, backups run without human intervention. Combined with environment-based toggles (S3\_BACKUP=On), it’s easy to enable/disable per environment (on for prod, off for dev).

## How to set up:

### 1. Configure the composable stack

[Upsun’s composable images](https://docs.upsun.com/create-apps/app-reference/composable-image.html) (based on Nix) let you declaratively define your runtime environment. To support encrypted S3 backups, add the required packages to your

```yaml {filename=".upsun/config.yaml"} theme={null}
applications:
  drupal:
    type: 'composable:25.05'
    stack:
      - gnupg
      - duplicity
      - python3
      - python3Packages.numpy
      - python3Packages.boto3
      # Other required packages...
```

#### Why these packages?

* Duplicity: Handles incremental, encrypted backups.
* gnupg: Manages GPG key operations.
* boto3: Enables Duplicity to communicate with AWS S3.
* python3 & numpy: Runtime dependencies for Duplicity and boto3.

### 2. Generate GPG keys locally

Backups are encrypted using GPG. Generate a dedicated key pair on your local machine:

```yaml {filename="Terminal"} theme={null}
gpg --full-generate-key
```

* Choose RSA and RSA (default)
* Set key size to 4096 bits.
* Set a strong passphrase (you’ll store this securely)
* Use a descriptive name/email ([devops+upsun-backup@example.com](mailto:devops+upsun-backup@example.com))

**After creation, note the Key ID (ABC123DEF456):**

#### Export the keys in ASCII-armored format:

```bash {filename="Terminal"} theme={null}
# Public key
gpg --armor --export ABC123DEF456 > public.key

# Private key
gpg --armor --export-secret-keys ABC123DEF456 > private.key
```

**Tip**: Store the passphrase, Key ID, and both key files in your secret storage or password manager.

### 3. Set environment variables

Upsun has a 4096-byte limit on environment variable values. Since GPG private keys often exceed this, split the private key into two parts:

```bash theme={null}
GPG_PASSPHRASE=your_strong_passphrase
GPG_KEY_ID=ABC123DEF456
GPG_PUBLIC_KEY=-----BEGIN PGP PUBLIC KEY BLOCK-----...
GPG_KEY_PART1=-----BEGIN PGP PRIVATE KEY BLOCK-----... (first half)
GPG_KEY_PART2=... (second half)-----END PGP PRIVATE KEY BLOCK-----
AWS_ACCESS_KEY_ID=your_aws_key
AWS_SECRET_ACCESS_KEY=your_aws_secret
AWS_REGION=us-east-2
AWS_DEFAULT_REGION=us-east-2
S3_BACKUP=On
```

**Tip**: When adding environment variables or keys in Upsun, especially long ones such as SSH keys or encrypted tokens, it’s generally easier to use the Upsun Console UI rather than the CLI.\
The Settings > Variables section in UI allows you to paste or edit long multi-line values directly without worrying about formatting issues or line breaks.

### 4. Create an S3 bucket

Create a dedicated S3 bucket in your preferred region (us-east-2):

```bash theme={null}
aws s3api create-bucket \
    --bucket your-unique-backup-bucket-name \
    --region us-east-2 \
```

Security note: The bucket does not need to be publicly accessible. Ensure your AWS credentials have s3:PutObject, s3:GetObject, and s3:ListBucket permissions only.

Set the bucket name via the **AWS\_S3\_BUCKET** environment variable.

### 5. Automate backups with a cron job

Add a cron task to .upsun/config.yaml to run incremental backups every 30 minutes:\
You can adjust the schedule to match your preference.

```yaml {filename=".upsun/config.yaml"} theme={null}
crons:
  backup:
    spec: '*/30 * * * *'
    commands:
      start: |
        if [ "$S3_BACKUP" = "On" ]; then
          PASSPHRASE="$GPG_PASSPHRASE" GNUPGHOME=/tmp/gnupg \
          duplicity incremental \
            --encrypt-key "$GPG_KEY_ID" \
            /app \
            boto3+s3://$AWS_S3_BUCKET
        fi
```

| Cron Expression | Meaning |
| - | - |
| \*\*\*/30 \* \* \* \*\*\* | Every 30 minutes |
| \*\*0 2 \* \* \*\*\* | Daily at 2 AM (for full) |
| **0 1 \* \* 0** | Weekly at 1 AM on Sunday |

#### What’s backed up?

By default, the entire /app directory (containing the application codebase and files) is backed up incrementally. Additional directories can be included as needed.

### 6. Import GPG keys on deploy

During deployment, import your GPG keys into a temporary keyring:

```yaml {filename=".upsun/config.yaml"} theme={null}
hooks:
  deploy: |
    set -e
    if [ "$S3_BACKUP" = "On" ]; then
      export GNUPGHOME=/tmp/gnupg
      mkdir -p /tmp/gnupg
      chmod 700 /tmp/gnupg

      # Reconduct the keys
      echo "$GPG_PUBLIC_KEY" > /tmp/gnupg/public.key
      echo "$GPG_KEY_PART1$GPG_KEY_PART2" > /tmp/gnupg/private.key
      # Secure the keys
      chmod 600 /tmp/gnupg/public.key
      chmod 600 /tmp/gnupg/private.key
      # Import public key
      gpg --batch --import /tmp/gnupg/public.key
      # Import private key
      gpg --batch --import /tmp/gnupg/private.key
      # Trust the key fully
      echo -e "trust\n5\ny\n" | gpg --command-fd 0 --edit-key "$GPG_KEY_ID"
      # Delete the key files
      rm -f /tmp/gnupg/public.key
      rm -f /tmp/gnupg/private.key
    fi
```

This ensures Duplicity can encrypt (and later decrypt) backups.

### 7. Test Your first backup

After deployment, trigger a manual full backup to verify the setup:

```bash {filename="Terminal"} theme={null}
# SSH into your environment
upsun ssh

# Run full backup
PASSPHRASE="$GPG_PASSPHRASE" GNUPGHOME=/tmp/gnupg \
duplicity full --encrypt-key "$GPG_KEY_ID" /app boto3+s3://$AWS_S3_BUCKET
```

Then check your S3 bucket. You should see encrypted .gpg files and a signature file.

```bash theme={null}
Bucket: platform-s3-backup-demo
│
├── duplicity-full-signatures.20250405T100000Z.sigtar.gpg
├── duplicity-full.20250405T100000Z.manifest.gpg
├── duplicity-full.20250405T100000Z.vol1.difftar.gpg
├── duplicity-inc.20250405T103000Z.to.20250405T110000Z.manifest.gpg
├── duplicity-inc.20250405T103000Z.to.20250405T110000Z.vol1.difftar.gpg
└── ...
```

### 8. Restoring from backup

Need to restore? Since Upsun is a read-only environment, use a local or a Cloud Server to restore backups.

* Spin up a recovery environment on a cloud server or on a local server.
* Re-import GPG keys
* Use duplicity restore with your S3 URL and passphrase
* Sync files back to Upsun

## Conclusion

This setup provides secure, automated, and incremental backups of Upsun-hosted applications directly to AWS S3 with end-to-end GPG encryption. By combining Upsun’s composable Nix stack with Duplicity’s robust backup logic, it ensures data resilience while maintaining operational simplicity.


# Add context on your Blackfire timeline from a Google Alerts RSS Feed
Source: https://developer.upsun.com/posts/how-tos/blackfire-google-alert-markers



<PostMeta />

Observing your application is essential to be able to find what needs (and what does not need) to be optimized.
Understand your traffic spike is key but when an external source lead to those traffic spikes, that's not any easy path to find out the exact reason.

As an example, your CEO talks about your brand on a TV show, this automatically leads to a raise of your traffic few seconds later and by ricochet, potential performance issues: that's what I call in this article the `TV show effect`.
Other names can be found for these external events leading to traffic spikes: [Slashdot effects](https://en.wikipedia.org/wiki/Slashdot_effect) or [Hug of death](https://nordvpn.com/fr/cybersecurity/glossary/hug-of-death/).
Of course, most of the requests on your website would be absorbed by your reverse proxy in front (Varnish, Faslty,...), but some of those requests won't and would lead to an increase of the resource consumption.

[Blackfire](https://blackfire.io) is a great Application Performance Monitoring (APM) tool to observe and gather data about consumed server resources like memory, CPU time, and I/O operations.
On the Monitoring section of your Blackfire dashboard, the [timeline](https://docs.blackfire.io/profiling-cookbooks/understanding-timelines) helps you to analyse the behavior of your application, by giving a lot of metrics in a specific timeframe of your traffic.
[Blackfire](https://blackfire.io) also provides a great (and not so well known) feature to spot markers on this timeline.
These markers are a way to add more context for your observers to better understand what's going on (when and why?).

We saw in a previous tutorial [How to automatically spot markers on your Blackfire timeline for any occuring Upsun infrastructure processes](https://dev.to/upsun/how-to-get-notifications-when-an-upsun-infrastructure-event-occurs-2257).
In this current tutorial, I will showcase how you can import any new [Google alerts](https://www.google.fr/alerts) that pops up and spot markers on your Blackfire timeline.
As a summary for this tutorial, we will import, via a cron, any new RSS Feed entries in a [Symfony](https://www.symfony.com) database (SQLite), and spot corresponding markers on your Blackfire timeline.

<Note>
  🚨 **Please note:**
  I choose to use [Google alerts](https://www.google.fr/alerts) (RSS Feed) as it's an easy way to get notification when a new article/page is added in their index
  but that's just an example.
  Everything related to Google alerts in this article can easily be adapted to another RSS Feed structure.
  You would just need to adapt the PHP code to import RSS entries (function `createFeed` from class `src/Services/BlackfireGoogleAlert.php`) to your new RSS Feed structure.
</Note>

## Google alerts and Blackfire markers

<Note>
  **Assumptions:**

  * You already have a [Google Account](https://www.google.com)
  * You already have a [GitHub account](https://github.com/)
  * You already have an Upsun account. If you don’t, [please register for a trial account](https://auth.upsun.com/register). You can sign up with an email address or an existing GitHub, Bitbucket, or Google account. If you choose one of these accounts, you can set a password for your Upsun account later.
  * You have the [Upsun CLI](https://docs.upsun.com/administration/cli.html) installed locally.
  * (optional) Your local environment is compatible with [Symfony requirements](https://symfony.com/doc/current/setup.html)
</Note>

### Create a new Google alert RSS Feed

The first step is to create a new RSS Feed alert.

To do so, connect to your Google account and go on [Google alerts](https://www.google.fr/alerts) page and follow this [official tutorial](https://support.google.com/websearch/answer/4815696?hl=en).
Please fill it with the following options:

<img alt="Google alert form with RSS Feed options" />

### Create a fork of the `blackfire-google-alert-example` repository

To ease your work, I already developed a small Symfony application that contains the minimum codebase for importing all feeds from a Google Alert RSS Feed in your database and spotting corresponding markers on your Blackfire timeline, using a [cron](https://docs.upsun.com/create-apps/app-reference/single-runtime-image.html#crons).

You can start by [creating a fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo) of this [`blackfire-google-alert-example` GitHub repository](https://github.com/upsun/blackfire-google-alert-example) in your own GitHub organization for later usage.

<Note>
  🚨 **Please note**: for this tutorial, we use a [Symfony](https://www.symfony.com) application but feel free to reuse the business logic and come up with a solution using any other framework you like.
</Note>

The source code in this GitHub repository is already Upsun-ready.
After creating a fork, you can clone it locally and [create an empty Upsun project](https://docs.upsun.com/get-started/here/create-project.html).
Use the 3 following command lines from the root of your source code, and follow prompts:

```bash {filename="Terminal"} theme={null}
git clone git@github.com:<OWNER/REPOSITORY>
cd <REPOSITORY>
upsun project:create
```

Final output should be:

```bash {filename="Terminal"} theme={null}
  ...
  The Upsun Bot is activating your project

      ▄     ▄  
      ▄█▄▄▄█▄  
    ▄██▄███▄██▄
    █ █▀▀▀▀▀█ █
       ▀▀ ▀▀   

  The project is now ready!
  <PROJECT_ID>
```

* `<OWNER/REPOSITORY>` is your forked `<REPOSITORY>` in GitHub.
* `<PROJECT_ID>`: keep this project ID in mind for later use

At this step, your Upsun project is not deployed yet.

We need first to pass to the application your previously created RSS Feed uri via an environment variable.

### Define your RSS Feed uri in an environment variable

Before deploying, please note that this `blackfire-google-alerts` app need you to define an environment variable for your RSS Feed uri (`<GOOGLE_RSS_ALERT_URI>`).

For local usage of this application, you can define this `GOOGLE_RSS_ALERT ` environment variable in a `.env` file:

```shell {filename=".env"} theme={null}
GOOGLE_RSS_ALERT=<GOOGLE_RSS_ALERT_URI>
```

As Upsun projects does not import `.env` file (local Symfony server), there are 3 ways to define environment variables for your Upsun environment/project.
<br />You can either:

* use an [`.environment` file](https://docs.upsun.com/development/variables/set-variables.html#testing-environment-scripts)
  ```shell {filename=".environment"} theme={null}
  GOOGLE_RSS_ALERT=<GOOGLE_RSS_ALERT_URI>
  ```
  Then you need to add this file to your Git history
  ```
  git add .environment && git commit -m "adding GOOGLE_RSS_ALERT envVar"
  ```

* use the [Upsun CLI](https://docs.upsun.com/administration/cli.html).

```bash {filename="Terminal"} theme={null}
upsun variable:create --level project --name GOOGLE_RSS_ALERT --prefix env --value <GOOGLE_RSS_ALERT_URI>
```

* define it from the [Upsun Console](https://console.upsun.com): to do so, please follow steps described in the [corresponding documentation page](https://docs.upsun.com/development/variables/set-variables.html#create-project-variables) (`In the Console` tab)

### Add a source integration to your fork

Then, you need to [add a source integration](https://docs.upsun.com/integrations/source/github.html) to sync your Upsun project with your new forked GitHub repository.

```bash {filename="Terminal"} theme={null}
upsun integration:add --type github --repository <OWNER/REPOSITORY> --token <GITHUB_ACCESS_TOKEN> [--project <PROJECT_ID>] 
```

* `<PROJECT_ID>` is the ID of your new `blackfire-google-alert` project ID (from `upsun project:create` command).
* `<GITHUB_ACCESS_TOKEN>` is your [generated GitHub API Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens).

<Note>
  For more information about source integration, please refer to the [enable source integration documentation page](https://docs.upsun.com/integrations/source/github.html#2-enable-the-integration).
</Note>

### Blackfire Timeline testing

From the [Upsun Console](https://console.upsun.com) of your project, wait for the first deploy to be completed (\~3 minutes) and then click on `Launch Blackfire` button on the left menu.

<img alt="Launch Blackfire button in the Upsun Console" />

<Note>
  🚨 **Please note**: If you would like to automatically open your current project Console dashboard from your terminal, you can use this command from the root of your source code:

  ```bash {filename="Terminal"} theme={null}
  upsun web
  ```
</Note>

You then land on the Blackfire dashboard (Health report).
CLick on the `Monitoring` menu item on the left.
Markers should appear on the timeline, such as:

<img alt="Google Alert markers displayed on the Blackfire timeline" />

<Note>
  🚨 **Please note**: The `blackfire-google-alerts` app imports RSS Feed entries via a cron that runs every 5 minutes, so depending on the timing, you probably need to wait a bit for the first import to take place.
  <br />If you want to manually trigger the first import, you can also execute this command:

  ```bash {filename="Terminal"} theme={null}
  upsun ssh 'php bin/console blackfire:import-google-alerts'
  ```
</Note>

## Conclusion

Adding more context to your Observability timeline is crucial if you are running applications with a lot of traffic and if you want to be able to detect what i called `TV show effects`.

In this guide, we took a look at how to automatically add context to your Blackfire timeline using an external source (here, Google Alert RSS Feed).
Some next steps could include importing any other external source of information that could explain traffic spikes on your application,
or give a way for your marketing team to manually spot incoming events on your Blackfire timeline?

* In 2 weeks, your CEO is willing to be at a TV show, talking about your brand?
* A new 1 month nurturing campaign is planned in 3 weeks (start|end markers?)?

Possibilities are infinite, and all of these features to add context on your Blackfire timeline would help a lot your observers/developers to analyse your traffic and understand why and when a performance bottleneck is happening.

I keep you posted, I will soon write another episode to go further on contextualisation of your observability strategy.

Remain up-to-date on the latest from us over on our social media and community channels:
[DEV.to](https://dev.to/upsun), [Reddit](https://www.reddit.com/r/upsun/),
and the [Upsun Community Forum](https://community.upsun.com/).


# Import multiple RSS Feeds on your Blackfire timeline + extra interfaces
Source: https://developer.upsun.com/posts/how-tos/blackfire-google-alert-markers-interfaces



<PostMeta />

We saw in the [previous episode](/posts/how-tos/blackfire-google-alert-markers) how to automatically add context on your Blackfire timeline from an RSS Feed (Google Alert),
spotting markers for every new article indexed in Google from chosen keywords.
A limitation of this first episode application is that you can manage only one Google Alert RSS Feed.

To go further, I improved the existing [`blackfire-google-alert-example` repository](https://github.com/upsun/blackfire-google-alert-example/) with a new branch [`feed-dashboard`](https://github.com/upsun/blackfire-google-alert-example/tree/feed-dashboard).
In this new branch, you will find all the necessary source code to get a Symfony admin interface allowing you to manage your RSS Feeds and your Blackfire markers.

I started from an empty Symfony Demo application and changed the source code to add 2 dashboards to the admin interface:

* `RSS Feed List`: manage all Google Alert RSS Feeds you want to automatically import on your Blackfire timeline (via the existing cron).
* `Blackfire Marker List`: an overview of your imported feeds, and you can also manually add markers on your Blackfire timeline.

Let's dive deeper in this `feed-dashboard` branch and see how to use it.

## Manage your RSS Feeds and Blackfire markers

<Note>
  **Assumptions:**

  * You've already created an Upsun project with a source integration to your own fork of the [`blackfire-google-alert-example` repository](https://github.com/upsun/blackfire-google-alert-example/), from the [previous post](/posts/how-tos/blackfire-google-alert-markers).
</Note>

### Get the Symfony Demo dashboards

After following the [previous episode](/posts/how-tos/blackfire-google-alert-markers), you end up with an Upsun project having a source integration enabled to your forked repo of the [`blackfire-google-alert-example` repository](https://github.com/upsun/blackfire-google-alert-example/).
Thanks to this source integration, every new branches on your forked GitHub repo would create a corresponding Upsun [preview environment](https://docs.upsun.com/glossary.html#preview-environment).

<Note>
  If the `feed-dashboard` branch does not exist yet in your forked repo, you need to [sync your forked GitHub repo](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork)
  with the original [`blackfire-google-alert-example` repository](https://github.com/upsun/blackfire-google-alert-example/), directly from the GitHub interface.
  As soon as it's done, the source integration will do the rest by creating corresponding environment and initialize the SQLite database (using a Symfony migration file).
</Note>

<img alt="Blackfire integration shown in the Upsun Console" />

Then, wait for this new preview environment to be deployed, and you would be able to access to the Symfony Demo admin interface by clicking on the URL of your Upsun preview environment in the [Console](https://console.upsun.com).

<img alt="Blackfire marker list in the Upsun Console" />

<Note>
  When connecting to the Admin interface, please use `jane_admin` account as all features require you to be an `admin` to access them.
</Note>

### RSS Feed management

From the [previous episode](/posts/how-tos/blackfire-google-alert-markers), on the `main` branch, we use an environment variable `GOOGLE_RSS_ALERT` to define which Google Alert RSS Feed (only one) needed to be imported via a cron.
That was a good start to showcase how to do it.

But as it was not convenient to manage many Google Alert RSS Feeds. So, I develop this `RSS Feed List` dashboard for you to add as many Google Alert RSS Feed as you want.
You can also switch on/off the import of your RSS Feeds (`active` field).

<Note>
  If you want to import other RSS Feed than the Google Alerts one, you would just need to adapt the PHP code to import RSS entries (function `createFeed` from class `src/Services/BlackfireGoogleAlert.php`) to your new RSS Feed structure.
</Note>

### Blackfire Marker List

At first, this interface gives you an overview of the latest imported feeds.

The major feature here is to also give your team (Marketing team?) the possibility to manually add markers on your Blackfire timeline by using the `Create a New Blackfire Marker` button on the right column.

Doing so, you will be able to add marker for any incoming events, with a message and a date (it can be in the future).

* Your CEO plan to participate in a TV show to talk about your brand? Spot it!
* Your Marketing team starts a long term nurturing campaign next week? Spot it!
* You want to spot a marker for a major code release (with a lots of new features)? Spot it!

<Note>
  As there is (yet) no way, using [Blackfire marker API](https://docs.blackfire.io/monitoring-cookbooks/events), to delete existing markers on the Blackfire timeline,
  So, manuals markers or automatic ones (from the Google Alert RSS Feeds) can't be deleted.
</Note>

## Conclusion

Adding more context to your Observability timeline is crucial if you are running applications with a lot of traffic and if you want to be able to detect what I previously called `TV show effects` in the previous episode.

Possibilities are infinite, and all of these features to add context on your Blackfire timeline would help a lot your observers/developers to analyse your traffic and understand why and when a performance bottleneck is happening.

I keep you posted, I will soon write a third episode to go further and push markers from your Google Alert RSS Feeds on your Google Analytics timeline.

Happy spotting!

Remain up-to-date on the latest from us over on our social media and community channels:
[DEV.to](https://dev.to/upsun), [Reddit](https://www.reddit.com/r/upsun/),
and the [Upsun Community Forum](https://community.upsun.com/).


# Composer 1 is dead – Upgrade to Composer 2 now
Source: https://developer.upsun.com/posts/how-tos/composer1-rip

Composer 1 has reached end of life and is no longer available on Upsun and Platform.sh. Learn why it’s no longer possible to rely on Composer 1, what errors you’ll see, and how to safely upgrade your project to Composer 2.


<PostMeta />

[Composer](https://getcomposer.org/) has long been the de-facto dependency manager for PHP projects.
It powers millions of applications, frameworks, and libraries by providing a reliable way to manage dependencies.

However, **Composer 1 reached its end of life** and [is
no longer maintained](https://blog.packagist.com/shutting-down-packagist-org-support-for-composer-1-x/).
If your project or CI pipeline is still using Composer 1, it’s time to upgrade.

## What happens if your project still requires Composer 1?

If your `composer.json` specifies a constraint like `^1` for the Composer runtime, your build
on [Upsun](https://www.upsun.com) or [Platform.sh](https://platform.sh) will fail.\
Here’s the kind of error you’ll see:

```bash {filename="Logs"} theme={null}
      Building application 'app' (runtime type: php:8.3, tree: 7760752)
        Generating runtime configuration.

        Installing build dependencies...
          Installing php build dependencies: composer
          W: Changed current directory to /app/.global/composer
          W: No composer.lock file present. Updating dependencies to latest instead of installing from lock file. See https://getcomposer.org/install for more information.
          W: Loading composer repositories with package information
          W: Updating dependencies
          W: Your requirements could not be resolved to an installable set of packages.
          W:
          W:   Problem 1
          W:     - Root composer.json requires composer ^1, found composer[2.8.11] but it does not match the constraint.
```

## How to check your Composer version

To check your current Composer version, execute the following:

```bash {filename="Terminal"} theme={null}
composer --version
```

If you see `Composer version 1.x.x`, you are running the deprecated version.

## How to upgrade your project to Composer 2

Upgrading is straightforward:

### 1. Update globally (recommended)

If Composer is installed globally on your system:

```bash {filename="Terminal"} theme={null}
composer self-update --2
```

This will switch you directly to the latest stable Composer 2 release.

### 2. Install via Package Manager

For example, on macOS with Homebrew:

```bash {filename="Terminal"} theme={null}
brew update
brew upgrade composer
```

### 3. Use the official installer

If you installed Composer manually:

```bash {filename="Terminal"} theme={null}
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php composer-setup.php --2
php -r "unlink('composer-setup.php');"
```

This will download Composer 2 locally into your project. You can move it globally if needed:

```bash {filename="Terminal"} theme={null}
mv composer.phar /usr/local/bin/composer
```

## Actions to take in your project

<Tabs>
  <Tab title="using Upsun">
    1. Update your `composer.json`

       Update the required PHP version and add a runtime API requirement to enforce Composer 2:

       ```json {filename="composer.json"} theme={null}
       {
           "require": {
             "php": ">=8.2",
             "composer-runtime-api": "^2"
           }
       }
       ```

       <Note>
         **Your current PHP version is maybe outdated?**<br />
         Composer 2 requires **at least PHP 7.2.5**, but many modern packages no longer support versions below **PHP 8.1**.
         To ensure long-term compatibility, security, and access to the latest ecosystem improvements, we strongly recommend upgrading to **PHP 8.2 or higher**.
       </Note>

    2. Check your `.upsun/config.yaml`
       Ensure you declare Composer 2 in your `.upsun/config.yaml` configuration, or, as Composer version 2 is now the
       default version installed on every project, completely remove the Composer dependency:
       ```yaml {filename=".upsun/config.yaml"} theme={null}
       applications:
         app:
           dependencies:
             php:
               composer: "^2" # or remove this dependency as Composer v2 is the default
       ```

    3. Test dependency resolution
       Run `composer update` with Composer 2 and commit the updated `composer.lock`. In rare cases, some legacy
       packages may need adjustments:
       ```bash {filename="Terminal"} theme={null}
       composer update
       git add .upsun/config.yaml composer.lock
       git commit "Update Composer to version 2"
       upsun push
       ```

    4. **Update your CI/CD pipelines**\
       Check your Docker images, GitHub Actions, or other CI jobs. Many older PHP images still ship with Composer 1 by
       default.
       * For Docker, use the `composer:2` official image.
       * For GitHub Actions, specify a step to upgrade Composer.

    5. **Communicate the change**\
       Update your project’s documentation to state that Composer 2 is required.
  </Tab>

  <Tab title="using Platform.sh">
    1. Update your `composer.json`

       Update the required PHP version and add a runtime API requirement to enforce Composer 2:

       ```json {filename="composer.json"} theme={null}
       {
           "require": {
             "php": ">=8.2",
             "composer-runtime-api": "^2"
           }
       }
       ```

       <Note>
         **Your current PHP version is maybe outdated?**<br />
         Composer 2 requires **at least PHP 7.2.5**, but many modern packages no longer support versions below **PHP 8.1**.
         To ensure long-term compatibility, security, and access to the latest ecosystem improvements, we strongly recommend upgrading to **PHP 8.2 or higher**.
       </Note>

    2. Check your `.platform.app.yaml`
       Ensure you declare Composer 2 in your `.platform.app.yaml` (or `.platform/applications.yaml`) configuration, or, as
       Composer version 2 is now the
       default version installed on every project, completely remove the Composer dependency:
       ```yaml {filename=".platform.app.yaml"} theme={null}
       name: app
       dependencies:
         php:
           composer: "^2" # or remove this dependency as Composer v2 is the default
       ```

    3. Test dependency resolution
       Run `composer update` with Composer 2 and commit the updated `composer.lock`. In rare cases, some legacy
       packages may need adjustments:
       ```bash {filename="Terminal"} theme={null}
       composer update
       git add .platform.app.yaml .platform/applications.yaml composer.lock 
       git commit "Update Composer to version 2"
       platform push
       ```

    4. **Update your CI/CD pipelines**\
       Check your Docker images, GitHub Actions, or other CI jobs. Many older PHP images still ship with Composer 1 by
       default.
       * For Docker, use the `composer:2` official image.
       * For GitHub Actions, specify a step to upgrade Composer.

    5. **Communicate the change**\
       Update your project’s documentation to state that Composer 2 is required.
  </Tab>
</Tabs>

## Troubleshooting common migration issues

Upgrading from Composer 1 to 2 is usually seamless, but you may encounter issues:

* **API Rate Limits (GitHub, GitLab, etc.)**\
  Composer 2 uses parallel downloads which can trigger API rate limits. Solution: configure OAuth tokens for GitHub or
  GitLab in your `auth.json`.

* **Plugins Not Compatible**\
  Some Composer plugins written for v1 may not work on v2. Ensure you update plugins to their latest version, or replace
  them if no update is available.

* **Stricter Dependency Checks**\
  Composer 2 is stricter about dependency resolution. If you encounter errors, check your `composer.json` for
  constraints that need adjusting.

* **CI/CD Caching Issues**\
  Clear your Composer cache in CI/CD environments (`composer clear-cache`) if builds fail after upgrading.

## Conclusion

Composer 1 is officially unsupported.
By upgrading to Composer 2, you get:

* Faster dependency resolution
* Modern PHP compatibility
* A safer, future-proof environment

Don’t wait until a dependency breaks or your pipeline fails—**upgrade today**.


# Adding an autoscaler to Upsun projects
Source: https://developer.upsun.com/posts/how-tos/configuring-an-autoscaler



<PostMeta />

In this post we will describe a small configuration that will
monitor your project resource usage,
and upscale or downscale the allocated resources for it
based on demand and some thresholds you can define.

> This post follows on from the [introduction to the Upsun API](/api/index#upsun-api)

<Info>
  This is an example intended to illustrate how it's possible to leverage the API to manage your projects and horizontaly scale your application on demand.
  If you have any feedback to make or require assistance feel free to open an issue on the related [github repositories](https://github.com/upsun/scalsun/issues) or to contact the Activation team at the following address: [activation@platform.sh](mailto:activation@platform.sh).
</Info>

## Requirements:

* A working, running Upsun project, and access to its code.
* An API key you can publish to the project. This token provides permissions to change your project properties.
* A script or utility that checks the project status and reacts to high or low stress conditions by upscaling or down-scaling as appropriate.

We can use [a tool from Mickael Gaillard called scalsun](https://github.com/upsun/scalsun) to do the last step, and use cron inside the project itself to do the monitoring.

Instructions for installation are in [the `scalsun` README](https://github.com/upsun/scalsun/blob/master/README.md) and should be easy to follow. To summarize:

1. Install the utility at build time.
2. Add a cron job to periodically run the tool.
3. Add your token to the project environment.

With this in place, your project will periodically poll the resource usage, and automatically adjust the project sizing when thresholds are passed.
When this happens can be observed in the Activity logs. You may also want to add your own notifications to alert you when this is going on.

### About upscaling

Since it is *horizontal* scaling, there is no rebuild triggered. See [Horizontal scaling on Upsun](https://docs.upsun.com/manage-resources/adjust-resources.html#horizontal-scaling).
Additional instances of the app container are added, and inserted into the routing rules.
This means that capacity can be increased or decreased in real time without interruption.

This only applies to the *application* behind the web server - not the data services.
Database, cache or search services are not suitable for horizontal scaling like this, as data replication is a much deeper challenge, and needs to be engineered for.

### Behaviour under load

Here is a graph of a load test simulating a surge of activity over time.
The load test was done using the `k6` tool,
and a scenario of roughly bell-shaped traffic,
building to a peak of 200 requests per second.

**HTTP traffic during an artificial load test**

<img alt="HTTP traffic during a load test" />

* The vertical lines indicate events where infrastructure changes were made (more info can be seen on mouseover on the real thing).
  In this case, each of the lines at the beginning of the surge denote the upscaler being triggered and adding an application instance.
* The same is seen at the end, and it depicts how the cool down in traffic takes some extra lag time before the additional instances are scaled down.
* The valley and the roughness in the graph is just an anomaly, possibly because the URL requests were being randomized and producing uneven load results.

**Upsun CPU instances being added to the pool in response to increased load**

<img alt="Upsun CPU instances being added to the pool in response to increased load" />

* Here we see the CPU load increasing as the HTTP requests went up.
* This is followed by additional instances of the application - indicated here as new lines - being brought online one after the other.
* Each spike is followed by a dip as a new instance succeeds in bringing the load average down.
* The reverse is seen as the traffic eases off - each time the average CPU load goes down enough for an instance to be removed from the pool, the average spikes again for a bit as the remaining instances take up the load.

In this case, the load was not memory-intensive, but the memory graph looks similar to the CPU one, as each new application container instance also adds allocations of memory.

The database graph shows an increase in activity, but was *not* scaled or duplicated in response to demand. In this example, database scaling was not necessary.

## About the parameters

The parameters are [documented in the README](https://github.com/upsun/scalsun/blob/master/README.md), so start there for the most up-to-date options.

* `name`

  If no `name` is defined, then all apps and services are polled.
  This might not be what you want, as some apps or services (like Redis cache) are designed to operate at capacity and self-regulate,
  and may trigger upsizes inappropriately.
  It's best to explicitly name the app that you wish to monitor.

* `max_host_count`

  This is the maximum number of **instances** of the application that will be deployed when needed.
  There is a regional hard upper limit as well, as the horizontal scaling will be distributed over different locations where possible.

* `min_cpu_usage_upscale`, `max_cpu_usage_downscale`, `min_mem_usage_upscale`, `max_mem_usage_downscale`

  The upscale/downscale usage parameters are compared against an average of the last 5 minutes (or duration as defined).

  As described, these are *thresholds* that determine when the upscale or downscale action is triggered.
  The buffer between the two thresholds is to prevent too much 'flapping' - it will add an extra application instance when CPU usage is averaging above 75% for 5 minutes,
  but only remove that instance when the total usage of the active instances is averaging below 60% for 5 minutes.

  Both CPU and memory usage are polled and either going over the `max_` value may trigger an upscale.
  A downscale should only happen when both metrics are below the safe threshold.

## Under the hood

As discussed in [using the upsun-api](/api/index#upsun-api), the `scalsun` utility makes these changes by leveraging the tools that you already have access to.
Looking at the activity logs that record a successful upscale event,
you may see what is actually happening.

```bash {filename="Terminal"} theme={null}
upsun metrics:all -p yd00gnuspu --environment=staging --interval=1m --format=csv --columns=service,cpu_percent,mem_percent --no-header --no-interaction --yes
upsun resources:get -p yd00gnuspu --environment=staging --format=csv --columns=service,instance_count --no-header --no-interaction --yes
upsun resources:set -p yd00gnuspu --environment=staging --no-interaction --yes --no-wait --count app:2
```

You can observe that it is just using the `upsun metrics:all` command to check the current status, but it will not take into account (at the moment there is a boolean set to false by default to exclude service) the services metrics
and the `upsun resources:` commands to request infrastructure changes in response to your own rules or heuristics.

Hopefully you can imagine how you may extend this to enhance it with your own logic if you have more interesting use-cases!

## Looking forward

This demonstration is not a fully featured enterprise level autoscaling solution,
it is a demonstration of what abilities and features you could use to automate your own resource management in response to demand.

Following are a few suggestions of ways this could be extended...

### This demonstration uses `cron`

For convenience, this demonstration of the `scalsun` tool works by running as a `cron` job every 5 minutes.
This is just easier to set up, and doesn't invoke any extra new concepts or services.

Running cron so frequently could be sub-optimal for a number of reasons.

* The `cron` activity may fill up the logs really fast and make it harder to spot real issues.
* `cron` intervals are limited by default to 5 minutes for normal accounts on the Upsun servers.
* On the other hand, for some business cases, every 5 minutes may not be enough. Standard Upsun accounts cannot run a cron more frequently than that (though this can be arranged for Enterprise plans if needed).

### This utility could run as a worker

If you wanted continuous control and continuous monitoring, then maybe this would be better suited to being an always-on [worker process](https://docs.upsun.com/create-apps/workers.html#workers-vs-cron-jobs) within your project.

This could be slightly more sensible than a cron job, and could be better at spotting or predicting trends to react to - depending on the tasks you expect to perform.

Adding a worker requires to set dedicated resources on your main project, so it's not always the best solution to run a separate application container just for it.

Using a worker also means that the monitoring and management of your infrastructure resides on the infrastructure itself.
In extreme cases, this could mean that it is unable to bootstrap its own responses.

### You could run your monitoring from outside the infrastructure

For resilience, it could make sense for your monitoring, alerts and responses to be in an altogether different location.
If you want to have monitoring that still works even if the site is down, or actions that trigger hard redeploys or provisioning, or the ability to wake from sleep, then your monitoring tool should probably live elsewhere - not inside the infrastructure that it is actually managing.

### Vertical scaling is also possible

As mentioned above, this example only does horizontal scaling by adding extra instances of the application container to meet demand, and this can't be applied to databases (easily).
If your needs required it, then you could consider automated [vertical scaling on Upsun](https://docs.upsun.com/manage-resources/adjust-resources.html#vertical-scaling).
The logic would apply in much the same way, though vertical scaling is likely to require a small downtime for the redeployment of the modified container.


# Upsun documentation is now available via the Context7 MCP
Source: https://developer.upsun.com/posts/how-tos/context7-mcp

Access Upsun documentation directly from your AI workflows using Context7's Model Context Protocol integration


<PostMeta />

We're excited to announce that Upsun documentation is now accessible through Context7 using the Model Context Protocol (MCP). This integration enables developers to access up-to-date Upsun documentation directly from their AI coding assistants, streamlining the development workflow and reducing context switching.

## What is the Model Context Protocol (MCP)

Our team just published an article on using MCP to connect your LLM to an Upsun database where we also introduce the protocol. [Go take a look at the article](/posts/hands-on/postgres-mcp-on-upsun) or browse [the official MCP documentation](https://modelcontextprotocol.io).

## What is Context7?

Context7 is a powerful documentation tool that delivers up-to-date, version-specific documentation and code examples directly to AI-powered coding assistants. Instead of relying on potentially outdated information in an AI model's training data, Context7 fetches current documentation from the source and injects it into the model's context.

## How to Access Upsun Documentation via Context7

Accessing Upsun documentation through Context7 is straightforward once you've set up the Context7 MCP server with your preferred AI coding assistant. Here's how to get started:

### 1. Install the Context7 MCP Server

Context7 MCP can be installed with various AI-powered coding tools that support the Model Context Protocol, including:

* Cursor
* VS Code (with MCP Extension)
* Claude Desktop
* Claude Code
* Windsurf
* Zed

For most environments, you can use the following installation methods:

**For Cursor:**

1. Navigate to Settings → Cursor Settings → MCP → Add new global MCP server
2. Add the following configuration to your `~/.cursor/mcp.json` file:

```json {filename="~/.cursor/mcp.json"} theme={null}
{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    }
  }
}
```

**For VS Code:**

1. Install the MCP extension
2. Add the following to your VS Code MCP configuration file:

```json {filename="settings.json"} theme={null}
{
  "servers": {
    "Context7": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    }
  }
}
```

**For Claude Desktop:**
Add this configuration to your `claude_desktop_config.json` file:

```json {filename="claude_desktop_config.json"} theme={null}
{
  "mcpServers": {
    "Context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    }
  }
}
```

**For Claude Code:**
Run the following claude command:

```bash theme={null}
❯ claude mcp add --transport stdio context7 --scope user -- npx -y @upstash/context7-mcp
```

which will add it to your `.claude.json` file in your home directory, allowing Claude Code to access it during
any Claude Code session.

For other platforms or alternative runtime options like `bunx` or `deno`, check the [Context7 GitHub repository](https://github.com/upstash/context7) for detailed installation instructions.

### 2. Query Upsun Documentation

Once you've set up Context7 MCP, you can access Upsun documentation by simply adding `use context7` to your prompts. For example:

* "How do I deploy a Next.js application on Upsun? use context7"
* "Explain Upsun's preview environments and how they work. use context7"
* "Show me how to configure a PostgreSQL database service on Upsun. use context7"

<Note>
  As Upsun and Platform.sh are sharing the same public documentation repository for now, you may need to specify in your prompt to look for the Platform.sh library in Context7.
</Note>

<img alt="Context7 Valkey demo" />

The Context7 server will detect that you're asking about Upsun or Platform.sh, fetch the relevant documentation, and inject it into your AI assistant's context, ensuring you receive accurate, up-to-date information.

## Example Use Cases

Here are some practical examples of how you can leverage this integration:

1. **Troubleshooting Deployment Issues**:\
   Ask your AI assistant about specific error messages or deployment problems, and it will have access to current troubleshooting guidance from Upsun's documentation.

2. **Setting Up Services**:\
   Get step-by-step guidance on configuring databases, caching layers, or other services with your Upsun project, all without leaving your coding environment.

3. **Learning Platform Features**:\
   New to Upsun? Ask your AI assistant to explain key concepts like Git-driven infrastructure, preview environments, or multi-app architecture with accurate, current information.

4. **Configuration File Assistance**:\
   Get help creating or modifying your `.upsun/config.yaml` files with the most up-to-date syntax and options.

## Benefits for Developers

This integration brings several key advantages to developers working with Upsun:

* **Reduced Context Switching**: Access documentation without switching between your editor and browser
* **Always Current Information**: Get the latest documentation rather than potentially outdated information from AI training data
* **Streamlined Learning Curve**: New Upsun users can get up to speed more quickly with contextual documentation accessible through familiar AI tools
* **Increased Productivity**: Spend less time searching for information and more time building

## Conclusion

This integration is part of our ongoing commitment to provide developers with the tools and resources they need to work efficiently and confidently on our platform. We believe that reducing friction in accessing documentation is key to helping developers focus on what matters most: building great applications.

We encourage you to try this integration and share your feedback with us. Your input helps us continue to enhance the Upsun developer experience.

For more information on Context7 and the Model Context Protocol, visit the [Context7 GitHub repository](https://github.com/upstash/context7) and the [Model Context Protocol documentation](https://modelcontextprotocol.io/).


# Creating Custom Reports using the Upsun Cloud CLI
Source: https://developer.upsun.com/posts/how-tos/creating-custom-reports-using-cli



<PostMeta />

# Creating Custom Reports using the Upsun CLI

## *Does X exist?*

Someone recently asked me

> Does a tool / report exist for the last deployment date for production sites - this will help find out if our sites are… out of date?

There isn't a single pane in the console that list all the sites in your organization with the last date of a push to
the production branch. **But**, one of the amazing things about Upsun is that our product is API-first. Whether you are
performing an action in the [Console](https://console.upsun.com/), or using the [CLI](https://docs.upsun.com/anchors/cli/),
they're both just calling the API for you. The [Upsun API](https://docs.upsun.com/api/) itself is extensive and
gives you everything you need in order to build just about anything you can imagine.  And a report showing this
information is entirely achievable!

The [Upsun CLI](https://docs.upsun.com/administration/cli.html) is really just a convenient wrapper for you to access
the API from the command line, so for this example, I'll use the CLI, but you can accomplish the exact same task using
the API directly (or the recent [Upsun PHP SDK](/posts/releases/upsun-php-sdk-announcement)).

The other nice thing about the CLI is that it has a built-in
[`multi` command](https://docs.upsun.com/administration/cli/reference.html#multi) that allows you to perform the same
command against multiple projects at once. To use it, you hand it a comma separated list of project IDs and then the
command you want to perform on each one.

## First we need IDs

For this example, I want the date of the last deployment
(or [`push` activity event](https://docs.upsun.com/integrations/activity/reference.html#environment-activity-types))
for my projects that start with the title “Template | ”.  Since I know `multi` needs a list of project IDs, I'll need to
get those first. To grab a list of projects by their title, I can use the
[`project:list` command](https://docs.upsun.com/administration/cli/reference.html#projectlist) with the `--title`
parameter to filter on the project title.

```{filename="Terminal"} theme={null}
❯ upsun project:list --title="Template |"
```

This will produce something like

```{filename="Terminal"} theme={null}
+---------------+--------------------------------------+------------------+-----------------+----------+
| ID            | Title                                | Region           | Org name        | Org type |
+---------------+--------------------------------------+------------------+-----------------+----------+
| qcelmtcwrzasy | Template | Akeneo                    | eu-3.platform.sh | devrel-projects | flex     |
| rmsh4dvlxfzoq | Template | Apache TomEE MicroProfile | eu-3.platform.sh | devrel-projects | flex     |
| 2kykonmslzfw2 | Template | ASP.NET Core              | eu-3.platform.sh | devrel-projects | flex     |
| bf6tpupauqym2 | Template | Backdrop                  | eu-3.platform.sh | devrel-projects | flex     |
<snip>
+---------------+--------------------------------------+------------------+-----------------+----------+
```

I don't need anything besides the IDs, so I'll adjust the command to only include the ID column, no header and a plain output:

```{filename="Terminal"} theme={null}
❯ upsun project:list --title="Template |" --columns=id --format=plain --no-header
qcelmtcwrzasy
rmsh4dvlxfzoq
2kykonmslzfw2
bf6tpupauqym2
<snip>
```

I need to convert this into a comma separated list to use with the `multi` so I'll pipe the output from this command to
[`tr` (translate)](https://man7.org/linux/man-pages/man1/tr.1.html) to transform newlines to commas.

**Note**: I'm going to limit the number of projects to 5 using the `--count` parameter just to make this easier to show.

```{filename="Terminal"} theme={null}
❯ upsun project:list --title="Template |" --count=5 --columns=id --format=plain --no-header | tr '\n' ','
qcelmtcwrzasy,rmsh4dvlxfzoq,2kykonmslzfw2,bf6tpupauqym2,cpxnqz5mjulbe,
```

## Finding the date of the last deploy

Now that we have the list of project IDs, we can pass this information to the `multi` command. But before we do that, we
need to know how to get the date of the last deployment of a project. Every time you push a change to an active
environment, Upsun will deploy that change, rebuilding the containers if necessary. With that in mind, we need to find
when the last `push` occurred to project's default environment. For purposes of this example, we're going to assume that
all of our projects are using the same production branch name of `main`.

One of the things the API exposes about your project is every
[activity](https://docs.upsun.com/increase-observability/logs/access-logs.html#activity-logs) that occurs to the
project. In the CLI, we can use the
[`activity:list` command](https://docs.upsun.com/administration/cli/reference.html#activitylist) to retrieve all
activities in a project.

```{filename="Terminal"} theme={null}
❯ upsun activity:list --project bf6tpupauqym2 --environment main
Activities on the project Template | Backdrop (bf6tpupauqym2), environment main (type: production):
+---------------+---------------------------+-----------------------------------------------------------------+----------+----------+---------+
| ID            | Created                   | Description                                                     | Progress | State    | Result  |
+---------------+---------------------------+-----------------------------------------------------------------+----------+----------+---------+
| gth4nqryisjmu | 2025-11-12T04:19:54+00:00 | Platform.sh Bot deleted backup o5bcracgspyejya6k6k7udtb6y       | 100%     | complete | success |
| i22xaywuudqmw | 2025-11-12T04:19:45+00:00 | Platform.sh Bot created a backup of Main                        | 100%     | complete | success |
| 5qbh7ajrtrmxw | 2025-11-11T04:19:54+00:00 | Platform.sh Bot deleted backup wwgnegtoybnkxho4re5lckqsm4       | 100%     | complete | success |
| vnzlijtgdycqa | 2025-11-11T04:19:45+00:00 | Platform.sh Bot created a backup of Main                        | 100%     | complete | success |<snip>
<snip>
+---------------+---------------------------+-----------------------------------------------------------------+----------+----------+---------+
```

We're only interested in `push` activities so let's add the `--type` parameter to limit the returned activities to only
`push` events.

```{filename="Terminal"} theme={null}
❯ upsun activity:list --project bf6tpupauqym2 --environment main --type=push
Activities on the project Template | Backdrop (bf6tpupauqym2), environment main (type: production):
+---------------+---------------------------+-------------------------------------+----------+----------+---------+
| ID            | Created                   | Description                         | Progress | State    | Result  |
+---------------+---------------------------+-------------------------------------+----------+----------+---------+
| xohtyme4hdcvc | 2025-10-24T19:14:01+00:00 | GitHub integration pushed to Main   | 100%     | complete | success |
| zzt2ri5gzccx6 | 2025-10-23T14:30:56+00:00 | GitHub integration pushed to Main   | 100%     | complete | success |
+---------------+---------------------------+-------------------------------------+----------+----------+---------+
```

<Note>
  **Note**: The actual activity type name for a push activity event is
  [`environment.push`](https://docs.upsun.com/integrations/activity/reference.html#environment-activity-types). However,
  the CLI allows us to
  [omit the first part of an activity's name](https://docs.upsun.com/administration/cli/reference.html#options-9) for
  convenience.
</Note>

We only want the most recent `push` event AND we only want the date, so let's add in a `--limit` of `1` (the default is to
sort by activity date - `Created` - descending) and select only the `Created` column. We also don't need the table
format or header, so let's use `--format=plain` and `--no-header` to remove those.

```{filename="Terminal"} theme={null}
❯ upsun activity:list --project bf6tpupauqym2 --environment main --type=push --columns=created --limit=1 --format=plain --no-header
2025-10-24T19:14:01+00:00
```

Perfect! We now have the exact command we need to retrieve the last `push` activity to hand to the `multi` command!

## Combing the commands to generate our report

Let's combine this command with the `multi` command and use the command to retrieve our project IDs from earlier to get
a complete report on the last time each project had a push event!

```{filename="Terminal"} theme={null}
❯ upsun multi --projects=$(upsun project:list --title="Template |" --count=5 --columns=id --format=plain --no-header | tr '\n' ',') -- activity:list --environment main --type=push --columns=created --limit=1 --format=plain --no-header
Running command on 5 projects:  'activity:list' '--environment' 'main' '--type=push' '--columns=created' '--limit=1' '--format=plain' '--no-header'
# Project: Template | Akeneo (qcelmtcwrzasy)
2025-10-27T13:26:28+00:00
# Project: Template | Apache TomEE MicroProfile (rmsh4dvlxfzoq)
No activities found
# Project: Template | ASP.NET Core (2kykonmslzfw2)
No activities found
# Project: Template | Backdrop (bf6tpupauqym2)
2025-10-23T14:30:56+00:00
# Project: Template | Beego (cpxnqz5mjulbe)
2025-11-11T19:31:12+00:00
```

I now have a report where I can see the last time each of my projects were pushed to, and surprise: I now see that for
at least two projects, it has been long enough since they received a push that the push event activity
log has expired!

## Go forth and report

I hope this has given you some ideas on the flexibility and power the Upsun API possesses and how you can utilize this
to create your own reports catered to your unique business needs, even when what you need doesn't already exist.

## Bonus items

### Date Format

It's possible you'll need that activity date in a different format. Don't worry: we've got you covered. The
`activity:list` command accepts a `--date-fmt`
[parameter](https://docs.upsun.com/administration/cli/reference.html#options-9) allowing you to alter the date format
using a [PHP date format string](https://www.php.net/manual/en/datetime.format.php#refsect1-datetime.format-parameters).

### Limit to successful pushes

In the example above, the person asking for the report wanted *any* push events to the project. It's possible though
in your situation that you only want those where the push (and build) was successful. To filter to those events where
the result of a push was successful, we can add the `--result` parameter with a value of `success` to our `activity:list`
command.

### Simplified command option if you want everything

In the example I used, I needed to limit the number of IDs returned from the `project:list` command to just 5 to make
the example easier to read.  If you don't need to limit the number of projects to a smaller amount than what matches,
you can simplify the `project:list` command by using the
[`--pipe` parameter](https://docs.upsun.com/administration/cli/reference.html#options-101), which returns a simple list
of project IDs, disabling any pagination in the returned results. In our example, adding the `--pipe` parameter would
result in a much more succinct command:

```{filename="Terminal"} theme={null}
❯ upsun project:list --title="Template |" --pipe
qcelmtcwrzasy
rmsh4dvlxfzoq
2kykonmslzfw2
bf6tpupauqym2
<snip>
```

### My projects don't all use the same production branch name

While standardization is great and should be the ideal, reality isn't always so cooperative. Perhaps you inherited a
project, or some projects were set up before you standardized on the production name. In order to accomplish the example
above, we need some ability to retrieve the production branch name in order to pass that to the `upsun multi` command.
We could perform a preliminary `upsun multi` command that retrieves each project's `default_branch` using the
`upsun project:info` command. However, this adds significant complexity to what we're trying to achieve. Our CLI
attempts to be very accommodating and make things easier on our users. That includes the ability to use a period (`.`)
to represent a project's default environment!  This allows us to update our previous command to work with all our
projects even if they do not use the same `default_branch` name!

```{filename="Terminal"} theme={null}
❯ upsun multi --projects=$(upsun project:list --title="Template |" --count=5 --columns=id --format=plain --no-header | tr '\n' ',') -- activity:list --environment . --type=push --columns=created --limit=1 --format=plain --no-header
Running command on 5 projects:  'activity:list' '--environment' '.' '--type=push' '--columns=created' '--limit=1' '--format=plain' '--no-header'

# Project: Template | Akeneo (qcelmtcwrzasy)
Selecting default environment (indicated by .)
Selected environment: main (type: production)
2025-10-27T13:26:28+00:00

# Project: Template | Apache TomEE MicroProfile (rmsh4dvlxfzoq)
Selecting default environment (indicated by .)
Selected environment: main (type: production)
No activities found

# Project: Template | ASP.NET Core (2kykonmslzfw2)
Selecting default environment (indicated by .)
Selected environment: main (type: production)
No activities found

# Project: Template | Backdrop (bf6tpupauqym2)
Selecting default environment (indicated by .)
Selected environment: main (type: production)
2025-10-23T14:30:56+00:00

# Project: Template | Beego (cpxnqz5mjulbe)
Selecting default environment (indicated by .)
Selected environment: main (type: production)
2025-11-11T19:31:12+00:00
```


# Speed vs. Security? Why not both: The Fastly CDN and WAF on Upsun
Source: https://developer.upsun.com/posts/how-tos/fastly-cdn-and-waf

Learn how to pair Fastly’s CDN for speed with its Next-Gen WAF for security on Upsun. Optimize global performance while protecting your infrastructure from threats.


<PostMeta />

They share a name, but play different roles. Here is how Fastly’s delivery and security layers work together in your Upsun environment.

When aiming for global reach, the **Fastly Content Delivery Network (CDN)** is essential: It caches content at the edge to slash application load times. But speed needs a partner: the **Fastly Next-Gen Web Application Firewall (WAF)**, which protects your origin from threats.

### **The Airport Analogy: Two Desks, One Terminal**

The **Fastly CDN** and **Fastly WAF** aren’t separate stops on a journey; they're two different jobs handled by the same server at the network’s edge.

In airport terms, think of them as two specialized desks inside the same terminal:

* The Fastly CDN is the terminal: Its job is to get passengers (requests) to their gates as quickly as possible using moving walkways and clear signage (routing).
* The Fastly WAF is the security checkpoint: Before a passenger reaches the gate, the security checkpoint (WAF) inspects them for threats (like SQL injection or malicious bots) and stops them before they reach the "secure area" (your Upsun application code, database, and files running on Upsun servers).

### The Division of Labor

They work in tandem, but you manage them differently within the Upsun ecosystem:

| Feature | Fastly CDN (Self-Service) | Fastly WAF (Specialized) |
| :- | :- | :- |
| Primary goal | Performance and delivery | Security and threat mitigation |
| Where to manage | Directly in the Upsun console | Upsun Support or a dedicated WAF dashboard |
| Common tasks | Purging cache, managing IP allowlists (ACLs), Edge Dictionaries | Configuring security rules, tuning false positives |

***

### Where They Meet: Visibility and Insights

Even though you don't configure WAF rules in the Upsun console, the CDN integration is your window into WAF performance.

The CDN Insights tab logs every request the WAF blocks. This correlation is vital for troubleshooting:

* **Identify Attacks:** If you see a spike in "403 Forbidden" errors in your CDN logs, the WAF is successfully defending you.
* **Debug Blocks:** If a legitimate user is blocked, the CDN’s granular logs help you identify which rule was triggered so you can ask Support to tune it.

### Get Started

To get both services running on your project:

**1.** Activate the Fastly CDN.

1. [Install the Fastly plugin](https://console.upsun.com/-/add-plugin?manifest=https%253A%252F%252Ffastsun.plugins.pltfrm.sh%252Fmanifest.json) directly within the Upsun console.
2. On the **Integrations** or **Fastly CDN** tab that was added after the previous step, connect your service by using your Fastly Service ID and API Token (which you can find by running `upsun ssh "printenv | grep FASTLY"` in your terminal).\
   For details about using Edge Dictionaries to manage dynamic configuration, see [Fastly CDN](https://docs.upsun.com/integrations/fastly-cdn.html) in the Upsun product docs.

**2.** Enable the WAF.

Because WAF rules are highly specialized, enablement is a managed process:

1. **Choose your offer:** Upsun offers **Basic** (managed by Upsun Support) or **Basic Configurable** (adds a dedicated security dashboard). For details, see [Fastly WAF](https://docs.upsun.com/security/fastly-waf.html) in the Upsun product docs.
2. **[Contact our sales team](https://upsun.com/contact-us/)** to add the chosen offer to your Upsun plan. They will handle the initial onboarding and rule configuration to ensure your application is protected without blocking legitimate traffic.

### Summary: Better Together

Ultimately, the Fastly CDN and WAF on Upsun provide a unified front:

* The CDN ensures legitimate users get a fast experience and provides the dashboard where you monitor overall traffic health.
* The WAF ensures malicious requests never touch your infrastructure, keeping your Upsun resources dedicated to serving real customers.

By using the Upsun console as your visibility bridge, you can confidently run applications that are fast, secure, and globally scalable.


# Streamline Your CDN Management with Fastly CDN Plugin App [BETA]
Source: https://developer.upsun.com/posts/how-tos/fastlycdn-pluginapp-activation



<PostMeta />

Managing Content Delivery Network (CDN) configurations alongside your application deployments can be a complex task, often requiring developers to switch between multiple interfaces and tools. The Fastly CDN plugin app bridges this gap by bringing Fastly CDN management directly into your Upsun console, creating a seamless workflow for developers who want to manage their CDN configurations without leaving their primary development environment.

*This plugin represents the ongoing commitment of the Upsun community to create tools that improve developer experience and workflow efficiency. While experimental, it demonstrates the potential for deeper integrations between platform services and CDN management.*

## Key Features of Fastly CDN plugin \[BETA]

The Fastly CDN plugin offers a comprehensive set of features that make CDN management intuitive and efficient:

### 📊 Service Overview & Monitoring

* View CDN service details and configuration summaries
* Monitor real-time statistics and performance metrics
* Track service activity and recent events history
* View current VCL (Varnish Configuration Language) version and service status

### 🛡️ Access Control Lists (ACLs) Management

* View and manage Access Control Lists for your service
* Browse ACL entries including IP addresses and CIDR blocks
* Update ACL configurations to control traffic access
* Manage security rules and restrictions

<img alt="fastly cdn acl panel" />

### 🔧 VCL Configuration

* Browse VCL versions and configurations
* View generated VCL content
* Monitor configuration changes

### 🧹 Cache Purging

* **Purge All**: Clear entire CDN cache with one click
* **Selective Purging**: Purge specific URLs or content
* Real-time purge status and confirmation
* Currently supports read-only operations and purging all application URLs

### 🔐 Security & Credentials

* Secure credential storage (stored locally in browser only)
* Encrypted token management for enhanced security
* No third-party credential sharing

### 📈 Real-time Analytics

* Access real-time CDN performance data
* Monitor traffic patterns and cache hit rates
* Track bandwidth usage and request metrics

<img alt="fastly cdn history diagram panel" />

## Installing Fastly CDN plugin app in Your Upsun Console

Getting started with Fastly CDN is straightforward.

### Upsun Console Integration

Here is how to install the Fastly CDN plugin directly into your Upsun console

1. **One-Click Installation**: Use this [installation link](https://console.upsun.com/-/add-plugin?manifest=https%253A%252F%252Ffastsun.plugins.pltfrm.sh%252Fmanifest.json) to add Fastly CDN plugin to your Upsun console
2. **Access via Console**: Once installed, our plugin will appear as a plugin within your Upsun console interface
3. **Unified Experience**: Manage your CDN alongside your application deployments in a single interface

## Prerequisites and Setup

Before using Fastly CDN plugin, ensure you have:

* **Fastly Account**: An active [Fastly account](https://www.fastly.com/signup) with CDN services configured
* **Service ID**: Your Fastly Service ID (found in your Fastly dashboard)
* **API Token**: A Fastly API token with appropriate permissions for your service

To obtain your Fastly API credentials if you have your own subscription:

1. Log into your Fastly account
2. Navigate to Account → Personal API Tokens
3. Create a new token with the necessary permissions for your CDN service
4. Note your Service ID from your service configuration

## Getting Started with Fastly CDN plugin

Once you have it installed and your credentials ready:

1. **Launch the Plugin**: Access the plugin through your Upsun console or directly via the web interface
   <img alt="fastly cdn history plugin console" />
2. **Enter Credentials**: Input your Fastly Service ID and API Token
3. **Explore Your Service**: Use the service overview to familiarize yourself with your current CDN configuration
4. **Manage Your CDN**: Begin using the various features to monitor and manage your Fastly service

## Use Cases and Benefits

This plugin is particularly valuable for development teams who:

* **Deploy frequently** and need quick cache purging capabilities
* **Manage multiple environments** and want consistent CDN management workflows
* **Prefer consolidated interfaces** rather than switching between multiple tools
* **Need real-time monitoring** of CDN performance alongside application metrics
* **Want to integrate CDN management** into their existing Upsun-based development workflow

## Technical Architecture

It is built with modern web technologies:

* **Frontend**: [Vue.js](https://vuejs.org/) with TypeScript for type safety
* **Build Tool**: [Vite](https://vite.dev/) for fast development and building
* **Testing**: [Vitest](https://vitest.dev/) for unit testing
* **Linting**: [ESLint](https://www.npmjs.com/package/eslint) for code quality
* **API Integration**: Direct integration with [Fastly's official API](https://www.fastly.com/documentation/reference/api/)

The plugin follows security best practices by storing all credentials locally in your browser and never sharing them with third parties.

## Community and Support

As an open-source project, our Fastly CDN plugin welcomes community contributions and feedback. You can:

* **View the source code** on [GitHub](https://github.com/upsun/fastsun)
* **Report issues** or suggest features through GitHub Issues
* **Join the discussion** on the [Upsun Community Forum](https://community.upsun.com/)
* **Contribute** to the project development

## Getting Started Today

Ready to streamline your CDN management workflow? Install the Fastly CDN plugin  in your Upsun console and experience the convenience of managing your Fastly CDN alongside your application deployments.

Remember to always test any CDN changes in a non-production environment first, and keep your API credentials secure.

***


# Get more control over your environments with build variables
Source: https://developer.upsun.com/posts/how-tos/get-more-control-over-your-environments-with-build-variables

Discover the visible-build flag on Platform.sh, enabling environment-specific build variables for more control over your development process.

<PostMeta />

<Note>
  Pre-release announcement: We’re making the `--visible-build` flag available as an option for environments.
</Note>

[Environment variables](https://platform.sh/blog/we-need-to-talk-about-the-env/) are one of the primary ways to ensure
repeatable builds on Platform.sh. They make it possible to reuse a previous build on a new branch, connecting to the
current environment's services and other backend resources.

Today we announce that the `--visible-build` flag, previously only available at the project level, is now an option for
environments, letting you tie your environment-specific variables to the build itself.

## A new option for making environment variables available during build

Environment-level variables have always been restricted to runtime. If you wanted a variable at build time, you needed
to set a project-level variable with the CLI or commit it in your
[.platform.app.yaml](https://docs.platform.sh/overview/yaml/what-is-yaml.html) file. In both cases, visibility at build
time meant that it was a part of the build image, something that should be considered almost like code. The build image
is at its core environment-agnostic, and it can be reused and moved to new environments freely until you change the
build process in some way, which gives you a lot of confidence when merging.

But there are times where you want a variable specific to one environment, such as distinguishing whether a Node.js s
erver should run in `production` or `development`, available at build time. For this reason, we've enabled the
`--visible-build` flag for variable creation [at the environment level](https://docs.platform.sh/development/variables.html).
If we continue with the Node.js example, we can consider the following commands:

```bash {filename="Terminal"} theme={null}
$ platform variable:create -l environment -e main --prefix env: --name NODE_ENV --value production --visible-build true --inheritable false
$ platform variable:create -l environment -e staging --prefix env: --name NODE_ENV --value development --visible-build true --inheritable true
```

In the first command, we’ve set `NODE_ENV` to `production` for the default branch, which makes sense for our production
application. In the second command, however, the variable is set to `development` for the `staging` environment, and it
will be inherited into each development environment that branches from it. This can be useful for running a much larger
test suite than you would run in production on each development environment, for
[enabling incremental builds](https://platform.sh/blog/headless-but-this-time-live-decoupled-drupal-with-gatsby/) with your
[decoupled applications](https://platform.sh/blog/time-to-breakup-three-reasons-to-decouple-your-application/), or for
providing write access at runtime for a backend headless CMS like Strapi (where it's forbidden in production).

## What’s changed

Introducing the `--visible-build` flag to environment-level variables is just one part of this release. There is another
potentially breaking change that you should keep in mind going forward. In the past, if you wanted to trigger a rebuild
on your app, you could simply add a small change, even a white space change, to your `.platform.app.yaml` file.

With this release, this is no longer the case. The `.platform.app.yaml` file itself is not a part of the build slug
reused across environments, nor is it available at all during builds. Instead, it’s only a subset of the values included
in that file—those attributes relevant to builds rather than runtime—that are tied to the slug.

For example, changing the version of Node.js your app uses will cause a full rebuild, whereas modifying the `post_deploy`
hook will not. Runtime keys that will no longer trigger rebuilds (but still trigger redeploys) when updated include:

* everything under `resources`
* `size`
* `disk`
* everything under `access`
* everything under `relationships`
* everything under `firewall`
* `hooks.deploy` and `hooks.post_deploy`
* everything under `web` except `web.mounts`
* everything under `workers` except `workers.X.mounts`
* everything under `crons`

While the `.platform.app.yaml` file isn’t available at build time anymore, you can still retrieve that information from
the `PLATFORM_APPLICATION` environment variable. But it will only include those attributes included in the build slug,
and none of those listed above (that is, until deploy time).

(The `.platform.app.yaml` file not being available during build means that it is not part of the tree of the application,
which also influences how the `PLATFORM_TREE_ID` variable is generated. If you compute this value yourself somewhere—we
never documented it, so you know who you are—you will now need to exclude the `.platform.app.yaml`. This should
otherwise not be of concern for most people.)

You can read about these changes in more detail in our updated
[variables documentation](https://docs.platform.sh/development/variables.html#variables-available-during-builds-and-at-runtime).

## An example: Using build environment variables to trigger a rebuild through a source operation

Build environment variables can change a lot of things for your apps. These variables now can become a part of the build
image, the same as project variables. This option opens up some interesting possibilities for fleets by creating a kind
of `platform rebuild` command if set up right.

In a previous article, I described a few options for maintaining a
[content delivery fleet](https://platform.sh/blog/source-operations-sorcery-summoning-the-multiheaded-gatsby-fleet/) on Platform.sh. The
example I used was a Drupal content store, decoupled from any number of frontend Gatsby presentation apps, that would
consume and present content across afleet. Thee apps could customize how the content was presented—such as whether it
was displayed on a mobile, desktop, gaming, or any other device—and then get triggered from the backend
[regularly via cron or automatically using a custom Drupal module](https://www.youtube.com/watch?v=qe_kXyruPYc) to
rebuild themselves using new content.

Build environment variables provide another method for triggering a rebuild through a
[source operation](https://docs.platform.sh/configuration/app/source-operations.html). The Drupal store example used a
dummy commit to a file in the repository root using the current date:

```yaml {filname=".platform.app.yaml"} theme={null}
source:
  operations:
    update:
      command: |
        echo Last Content Update:  $(date) > counter.txt
        echo "Create dummy commit to force rebuild for updated content."
        git commit -am "Source Operation: Updated content from backend."
```

If instead we create a `FRONTEND_REBUILD_COUNTER` variable for our presentation app:

```bash {filename="Terminal"} theme={null}
$ platform variable:create -l environment -e main --prefix env: --name FRONTEND_REBUILD_COUNTER --value 1` --visible-build true --inheritable false
```

We can redefine the source operation to increment the environment variable instead:

```yaml {filname=".platform.app.yaml"} theme={null}
source:
  operations:
    update:
      command: |
        platform variable:update FRONTEND_REBUILD_COUNTER $((FRONTEND_REBUILD_COUNTER+1))
```

Build variables are a part of the build slug, so simply updating their value will trigger a rebuild of, in this case,
the frontend Gatsby app with the latest content.

No doubt you have many ideas for additional places where the `--visible-build` flag will be useful. Feel free to share
them with us on the [Upsun Community Forum](https://community.upsun.com/).


# How to manage the `.well-known` directory on Upsun and Platform.sh
Source: https://developer.upsun.com/posts/how-tos/handling-well-known-directory



<PostMeta />

## Introduction

If you have ever tried to enable
[Apple Pay on a website](https://developer.apple.com/documentation/applepaywebmerchantregistrationapi/preparing-merchant-domains-for-verification),
or needed to verify you control a domain to generate a Let's Encrypt certificate, or noticed numerous requests to
`well-known/traffic-advice` in your access log, then you've probably found yourself working with the `.well-known`
directory at the root of your site. As defined in [RFC 8615](https://datatracker.ietf.org/doc/html/rfc8615),
`.well-known` is a special, standardized location at the root of a website that serves as a place where applications,
services, or security protocols can find important metadata or configuration files.

In the examples earlier, Apple Pay requests the file `apple-developer-merchantid-domain-association` inside the
`.well-known` directory in order to
[verify your merchant domain](https://developer.apple.com/documentation/applepaywebmerchantregistrationapi/preparing-merchant-domains-for-verification).\
Let's Encrypt uses `.domain-verification` inside `/.well-known/acme-challenge` in order to
[verify domain control](https://letsencrypt.org/docs/challenge-types/#http-01-challenge) before generating a
certificate. The Chrome browser retrieves `traffic-advice` from inside `.well-known`  in order to determine if the
[site allows pre-fetching](https://buettner.github.io/private-prefetch-proxy/traffic-advice.html), and if so, how much.

But this is just the tip of the iceberg. There are
[numerous](https://www.iana.org/assignments/well-known-uris/well-known-uris.xhtml)
[items](https://en.wikipedia.org/wiki/Well-known_URI#List_of_well-known_URIs) that can be placed inside
the `.well-known` directory. And as the number of types of applications, services, and protocols continues to grow, so
will the number of files that will be requested from this "well known location".

## The challenge

You may be thinking:

> "Can't I just create a `.well-known` directory in my repository, add my files, commit, push to
> Platform.sh/Upsun and be done?"

Yes... and no. The challenge is some of the files that you might need to place
in `.well-know` are extension-less (e.g. `apple-app-site-association` and `traffic-advice`), even though they contain
specific types of data (json in the two previous examples). If you place an extension-less in your project, the web
server is unable to determine the mime type and defaults to `content-type: application/octet-stream`

```bash {filename="Terminal"} theme={null}
❯ curl -I https://example.com/.well-known/apple-app-site-association
HTTP/2 200
accept-ranges: bytes
cache-control: no-cache
content-type: application/octet-stream
```

So then how can we configure our project to contain extension-less files but also serve the correct mime-type? Luckily,
we have a couple of options to utilize to solve this challenge.

### Option 1 - Rewrite the Request

The first method is to include the proper extension on the file so the web server knows how to set the correct mime type
, and then add a rewrite rule in our locations for requests to the extension-less version that "pass(es)thru" to our
version with the extension.

<Note>
  **Please Note**: After each change below, make sure you `git add`, and `git commit` your changes and then push the
  changes to your project.
</Note>

First, add the file to the `.well-known` directory *with the extension* in your project:

```bash {filename="Terminal"} theme={null}
❯ tree web/.well-known/
web/.well-known/
└── apple-app-site-association.json

```

Next we'll adjust the root (`/`) location in our `.platform.app.yaml` (Platform.sh) or `.upsun/config.yaml` (Upsun)
configuration file to include the [rule](https://docs.platform.sh/create-apps/app-reference/single-runtime-image.html#rules):

```yaml theme={null}
  locations:
    "/":
      passthru: "/index.php"
      root: "web"
      rules:
        '^/.well-known/apple-app-site-association$':
           allow: true
           passthru: '/.well-known/apple-app-site-association.json'
```

Now when a request is made for [https://example.com/.well-know/apple-app-site-association](https://example.com/.well-know/apple-app-site-association) the web server will rewrite
the request to `web/.well-known/apple-app-site-association.json`, and since it know the file is json, will return the
correct mime type:

```bash {filename="Terminal"} theme={null}
❯ curl -I https://example.com/.well-known/apple-app-site-association
HTTP/2 200
accept-ranges: bytes
cache-control: no-cache
content-type: application/json
```

### Option 2 - Manually set the Header Response

The second option is when you need even more flexibility in controlling the mime type that is returned. With the example
of `traffic-advice` earlier, not only is the request for an extension-less file, Chrome *expects* the mime-type to be
a specific mime type of
[`application/trafficadvice+json`](https://buettner.github.io/private-prefetch-proxy/traffic-advice.html#iana-mime-type).
If not, Chrome will reject it. It is entirely possible that other services also require a specific mime type in the
server response, or others may be added in the future with similar requirements. To tackle this challenge we'll take a
similar approach of using rules, but take advantage of some additional properties that are available in the rules
section.

Just like [Option 1](#option-1---rewrite-the-request), go ahead and add your file. Given we're going to manually set the
header response for the mime type, you can leave the file extension-less.

```bash {filename="Termninal"} theme={null}
❯ tree web/.well-known/
web/.well-known/
├── apple-app-site-association.json
└── traffic-advice

```

Without adding the rules, a request to the `traffic-advice` will return the wrong mime type causing Chrome to reject the
response:

```bash {filename="Terminal"} theme={null}
❯ curl -I https://example.com/.well-known/traffic-advice
HTTP/2 200
accept-ranges: bytes
cache-control: no-cache
content-type: application/octet-stream
```

<Note>
  **Please Note**: Since I'm now in need of multiple rules for a single location, I've added a location specifically for
  `.well-known` to my `web.locations`. This allows me to shorten my rules definitions as I no longer have to include the
  full paths.
</Note>

Let's then adjust our location in our `.platform.app.yaml` (Platform.sh) or `.upsun/config.yaml` (Upsun)
configuration file to respond with a [custom header](https://docs.platform.sh/create-apps/web/custom-headers.html) of
`application/trafficadvice+json` when the `traffic-advice` file is requested:

```yaml theme={null}
  locations:
    "/":
      passthru: "/index.php"
      root: "web"
    "/.well-known":
      root: "web/.well-known"
      rules:
        'apple-app-site-association':
          allow: true
          passthru: '/.well-known/apple-app-site-association.json'
        'traffic-advice':
          headers:
            Content-Type: application/trafficadvice+json
```

After pushing our change, now when something requests our `traffic-advice` file, the server not only responds with the
contents of the file, but is able to send the correct mime type:

```bash {filename="Terminal"} theme={null}
❯ curl -I https://example.com/.well-known/traffic-advice
HTTP/2 200
accept-ranges: bytes
cache-control: no-cache
content-type: application/trafficadvice+json
```

### Option 3 - Use a Mount

If desired, or you don't want to include these types of files in your repository, you could
[create a mount](https://docs.upsun.com/create-apps/app-reference/single-runtime-image.html#mounts) for `.well-known`,
[upload the needed files](https://docs.upsun.com/development/file-transfer.html#transfer-a-file-to-a-mount), and then
use any combination of the rules with `passthru` or custom headers to serve those files exactly as needed.

## Conclusion

Platform.sh and Upsun provide exceptional flexibility when configuring your projects, enabling developers to not only
fine-tune how extension-less files are served while maintaining correct MIME types, but also any other unexpected item
in your day-to-day. Whether leveraging rewrite rules to map requests to explicitly defined files, customizing response
headers for specialized formats, or accommodating future services with unique demands, by offering multiple
configuration strategies, Platform.sh and Upsun make it easy to scale and maintain high-performance applications without
sacrificing control over crucial web protocols.

***


# Help reduce resource consumption: Put your preview environments on pause
Source: https://developer.upsun.com/posts/how-tos/help-reduce-resource-consumption-put-your-preview-environments-on-pause

You can now manually pause your idle preview environments or have them automatically paused after 14 days of being idle to minimize your resource usage.

<PostMeta />

With Platform.sh, every Git branch maps to a preview environment which is an exact and isolated copy of your live
application—including all data, services, and files. They are usually created to build new features, apply security
patches, or upgrade dependencies in full isolation and before deploying to production.

Although there is a catch—preview environments are often left idle waiting for someone to review and approve any changes
made. And while they are idle, they continue to use CPU and RAM which both consume electricity and emit CO2.

That’s why we wanted to put you back in control of your resource usage and help you reduce your carbon footprint, as
well as our own.

In the coming weeks you will be able to **pause your idle preview environments** to limit that resource consumption
instantly. We’re also going to automate this process for preview environments which have been idle for 14 days or more
without being redeployed to minimize resource usage across the thousands of projects we host. Dramatically reducing the
number of machines required to run our infrastructure across all of our regions—hooray!

### Understanding the 14-day pause for preview environments

You might be curious to know why we chose 14 days as our timeframe for a preview environment to be paused automatically.
It’s mostly due to the very positive feedback we received from the paused crons we released last year with the same
timeframe.

Our assumption is that most of the time, preview environments will automatically resume via a deployment, and that only
a few will require manual reactivation. Of course, we will monitor that assumption closely and make any changes needed
to this process accordingly following feedback.

## Managing preview environments: How pausing works

All preview environments (development or staging) can be manually and automatically paused, while production environments can only be manually paused.

When an environment is paused, all routes will redirect to a static web page explaining that the environment is paused and a button to resume the environment.

<img alt="Resume Paused Environment" />

When a preview environment is paused, all the containers are paused and stop consuming resources. Pausing an environment does not delete any data, and all disks remain and become available again when the environment is resumed.

## How to pause an environment

To pause an environment, follow these steps:

<Tabs>
  <Tab title="Using the CLI">
    ```bash theme={null}
    upsun environment:pause --environment <environment-name>
    ```
  </Tab>

  <Tab title="In the Console">
    1. Navigate to your project and click **Settings**.
    2. Under **Environments**, select the environment you want to pause.
    3. In the **General** tab, click **Pause environment**.
  </Tab>
</Tabs>

## How to resume an environment

When all of your changes have been approved and you’re ready to redeploy once again there are a couple of ways in which you can resume a paused environment:

1. Make a change that triggers a deployment, such as: push the code or trigger a redeployment.
2. [Trigger the resume action from the Console or the CLI](https://docs.platform.sh/environments.html#paused-environments).

### What do you think?

We rely on the feedback of our users to make our PaaS as great as possible, so please don’t be shy—let us know what you
think of this new function!

Feel free to share your feedback through our [portal](https://next.platform.sh/c/312-paused-development-environments) or
open a support ticket if you experience any issues and we’ll be sure to help.

In the meantime, you can also learn more about our greener hosting commitments on
[our dedicated page](https://platform.sh/greener-hosting/).


# Up(sun) and ready with Pandoc
Source: https://developer.upsun.com/posts/how-tos/install-pandoc-on-upsun



<PostMeta />

With the recent growth in enthusiasm for AI assistants, you may be looking for how these assistants can provide technical information about your product.
After years of remarkable achievements through web 2.0 and its famous `robots.txt`, `security.txt`, and `humans.txt`,
a new standard has been proposed to the web ecosystem and will soon become essential for the web: [`llms.txt`](https://llmstxt.org/).
`llms.txt` was conceived by [Jeremy Howard](https://github.com/jph00), co-founder of [Answer.AI](https://answerai.pro/), to address a fundamental challenge in AI-human interaction.

When AI assistants attempt to process standard web pages, they struggle with non-essential elements like navigation menus, scripts, and styling.
These elements consume valuable context space without contributing to the actual content understanding.
`llms.txt` provides an elegant solution: it delivers precisely curated information in a format that AI systems can efficiently process and understand.

If you need to convert files from one markup format to another, [Pandoc](https://pandoc.org/) is your swiss-army knife.
Developed by [John MacFarlane](https://github.com/jgm), Pandoc is a [Haskell](https://www.haskell.org/) library for converting from one markup format to another
and John provides in [this `pandoc` repo](https://github.com/jgm/pandoc) a command-line tool that uses this Pandoc library.
Easy to install and ready to convert.

In this How-to guide, we will see how to install this `pandoc` command line tool on your Upsun project.

<Note>
  **Assumptions:**

  * You already have an Upsun account. If you don’t, [please register for a trial account](https://auth.upsun.com/register). You can sign up with an email address or an existing GitHub, Bitbucket, or Google account. If you choose one of these accounts, you can set a password for your Upsun account later.
  * You have the [Upsun CLI](https://docs.upsun.com/administration/cli.html) installed locally.
  * You have the [Git CLI](https://github.com/git-guides/install-git) installed locally.
</Note>

For this tutorial, we will start with a basic HTML application.
The main goal of this tutorial is to showcase how to install `pandoc` on your project and quickly generate a `llms.txt` file from your HTML pages.

## Prepare your local HTML project

In order to quickly showcase the strength of Pandoc, we will simulate a simple HTML application that could be obtained using a static website generator like [Hugo](https://hugo.io/).
The proposed structure will be:

```
.upsun/
    config.yaml
  public/
    learn/
      api.html
      applications.html
    index.html
```

To do so, in your Terminal, execute the following commands:

```shell {filename="Terminal"} theme={null}
mkdir my-html-app
cd my-html-app
mkdir public
curl -L https://raw.githubusercontent.com/upsun/snippets/refs/heads/main/src/llms/html-app-example.tar.gz | tar -xvz - -C public
git init && git add . && git commit -m "init HTML app"
```

<Note>
  🚨 **Please note**: This `html-app-example.tar.gz` file contains all HTML files (`index.html`, `./learn/*.html`) in this [`llms` folder](https://github.com/upsun/snippets/tree/main/src/llms).
</Note>

## Give Pandoc a try

To showcase the power of [Pandoc](https://pandoc.org/), let's give it a try locally and convert our HTML to an `llms.txt` file.

### Install Pandoc locally

To install Pandoc locally, please follow the official [Installation Guide](https://pandoc.org/installing.html).

### Use Pandoc for HTML to Markdown conversion

You should now have access to `pandoc` tool and we will use it to generate a `public/llms-test.txt` file that will concatenate all the HTML pages of the project in Markdown.
Let's execute this command line that will look for all HTML files in the `public` folder and concat them in a single file `./public/llms-test.txt`:

```bash {filename="Terminal"} theme={null}
pandoc $(find ./public -iname "*.html" -type f | sort -d) -f html -s -o "./public/llms-test.txt" -t markdown
open public/llms-test.txt
```

Now that you can see the power of Pandoc, feel free to check the [Official Manual](https://pandoc.org/MANUAL.html) for more advanced usage.

## Use Pandoc in your Upsun project

Generating this `llms.txt` file locally and pushing it in your source code is not convenient.
We would like this generation to be dynamic, each time you update your website content.

### Init your Upsun config

Upsun CLI provides a command to initialize a basic config for your local code.
As it is a simple HTML app, we will generate a minimum configuration file using the following command:

```shell {filename="Terminal"} theme={null}
➜  my-html-app git:(main) upsun project:init
Welcome to Upsun!
Let's get started with a few questions.

We need to know a bit more about your project. This will only take a minute!

What language is your project using? We support the following: [JavaScript/Node.js]

Tell us your project's application name: [app]

                       (\_/)
We’re almost done...  =(^.^)=

Last but not least, unless you’re creating a static website, your project uses services. Let’s define them:

Select all the services you are using: []

You have not selected any service, would you like to proceed anyway? [Yes]

┌───────────────────────────────────────────────────┐
│   CONGRATULATIONS!                                │
│                                                   │
│   We have created the following files for your:   │
│     - .environment                                │
│     - .upsun/config.yaml                          │
│                                                   │
│   We’re jumping for joy! ⍢                        │
└───────────────────────────────────────────────────┘
         │ /
         │/
         │
  (\ /)
  ( . .)
  o (_(“)(“)
```

Please select

* `Javascript/Node.js`
* application name: `app`
* no service selected

Your HTML application is almost ready to be deployed on Upsun, one more step to go.

Update this config line into the newly created `.upsun/config.yaml` file for the router to point to your `public` folder:

```yaml {filename=".upsun/config.yaml",linenos=table,hl_lines=["6-7"],linenostart=1} theme={null}
applications:
  app:
    web:
      locations:
        "/":
          root: "public"
          index: ["index.html"]
          passthru: true
```

and then commit your updates:

```shell {filename="Terminal"} theme={null}
git add .upsun/config.yaml && git commit -m "change locations.root to the public folder"
```

### Create an Upsun project

You then need to create an Upsun project by executing these commands and follow the prompts:

```shell {filename="Terminal"} theme={null}
upsun project:create
upsun push
```

### Install Pandoc

There is to ways to install `pandoc` on your project:

* [using a shell script](#using-a-shell-script)
* [using Composable Image](#using-composable-image)

#### Using a shell script

[John MacFarlane](https://github.com/jgm) provides in his [Pandoc repo](https://github.com/jgm/pandoc) a quick and easy way to install Pandoc.

We've prepared a shell script for you ([source](https://github.com/upsun/snippets/blob/main/src/install-github-asset.sh)) that can be used to install the latest version of Pandoc.
Update your `.upsun/config.yaml` file and add this curl call in your `applications.app.hooks.build` step:

```yaml {filename=".upsun/config.yaml",linenos=table,hl_lines=["9-10"],linenostart=1} theme={null}
applications:
  app:
    type: "nodejs:20"
    #...
    hooks:
      build: |
        set -x -e
        #...
        curl -fsS https://raw.githubusercontent.com/upsun/snippets/refs/heads/main/src/install-github-asset.sh | bash /dev/stdin "jgm/pandoc" 
        pandoc -v
```

The [`install-pandoc.sh`](https://github.com/upsun/snippets/blob/main/src/install-github-asset.sh) script installs the `pandoc` binary from [Pandoc repo](https://github.com/jgm/pandoc) in the `/app/.global/bin` folder of your application container.

#### Using Composable image

The Upsun [Composable image](https://docs.upsun.com/create-apps/app-reference.html#composable-image-beta) provides enhanced flexibility when defining your app.
It allows you to install several runtimes and tools in your application container, in a “one image to rule them all” approach.

The composable image is built on [Nix](https://nix.dev/) and the good is [Pandoc package](https://search.nixos.org/packages?channel=24.11\&from=0\&size=50\&sort=relevance\&type=packages\&query=pandoc) is available.

Update your `.upsun/config.yaml` by commenting default `type` parameter and by adding the following lines:

```yaml {filename=".upsun/config.yaml",linenos=table,hl_lines=["3-5", "10"],linenostart=1} theme={null}
applications:
  app:
    #type: "nodejs:20"
    stack: 
      - pandoc
    #...
    hooks:
      build: |
        set -x -e
        pandoc -v
```

And then, deploy your updates:

```shell {filename="Terminal"} theme={null}
git add .upsun/config.yaml .environment && git commit -m "install Pandoc"
upsun push
```

### Use Pandoc dynamically

You can now use `pandoc` in your project to dynamically generate a `public/llms.txt` file that will concatenate all the HTML pages in Markdown, as [tested locally before](#give-pandoc-a-try).
Update your `.upsun/config.yaml` by adding the following lines:

```yaml {filename=".upsun/config.yaml",linenos=table,hl_lines=["8"],linenostart=1} theme={null}
applications:
  app:        
    #...
    hooks:
      build: |
        set -x -e
        #...
        pandoc $(find ./public -iname "*.html" -type f | sort -d) -f html -s -o "./public/llms.txt" -t markdown
```

And then, deploy your updates:

```shell {filename="Terminal"} theme={null}
git add .upsun/config.yaml && git commit -m "Use Pandoc to generate a public/llms.txt file"
upsun push
```

Test it works by accessing the file by adding `/llms.txt` to your environment URL:

```shell {filename="Terminal"} theme={null}
upsun env:url --primary
```

## Conclusion

Et voilà, we saw how to use `pandoc` to convert all existing HTML pages into a single Markdown `public/llms.txt` file. Now, perhaps the next step would be to train an AI Assistant with the file `llms.txt`...

Stay tuned.

Discover how to deploy a personal [Chainlit](https://github.com/Chainlit/chainlit) AI assistant on Upsun by reading this great blogpost: [Experiment with Chainlit AI interface with RAG on Upsun](https://devcenter.upsun.com/posts/hands-on/deploying-chainlit-with-rag)


# Measuring Deployment Success with GitHub Actions
Source: https://developer.upsun.com/posts/how-tos/measuring-the-success-of-a-deployment-with-githubactions

Learn how GitHub actions can streamline your Platform.sh deployments for faster and more efficient development workflows

<PostMeta />

Last week, we took a look at how [shareable activities](https://platform.sh/blog/share-your-failures-fix-them-faster/) - specifically the
link made available to a particular activity’s logs in the management console - could be surfaced as a part of a
[GitHub integration](https://docs.platform.sh/integrations/source/github.html) using
[GitHub actions](/posts/unknown/share-your-activities-with-robots-surfacing-activities-with-github-actions). It was a nice bit
of fun playing around with [GitHub actions](https://github.com/features/actions) for the first time, and it let me make
something new and useful for my team's work.

But I caught a little bit of the curiosity bug. What else could I link up to my workflow, now that I can trigger events
in response to a Platform.sh environment deployment? Well, since I linked an activity’s logs to a failed deployment, it
only makes sense to trigger some things in response to a successful one.

## Using GitHub actions to monitor Platform.sh deployment status

Take a moment to check out
[the previous post centered around GitHub actions](/posts/unknown/share-your-activities-with-robots-surfacing-activities-with-github-actions).
It’ll provide a little context, plus go into much more detail about how the status of a Platform.sh deployment can
actually be used to trigger workflows on GitHub. Plus, we’re going to build additional jobs in the same
`post-deploy.yaml` file we started in that post.

Let’s take a look at the file, ignoring the `displaylogs` job we made previously, and instead focusing on the `build`
job that sets everything else up:

```yaml {filename="post-deploy.yaml"} theme={null}
---
name: Post-deploy
on:
  push:
    branches-ignore:
      - "master"
env:
  PLATFORMSH_CLI_TOKEN: ${{ secrets.CLI_TOKEN }}
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

jobs:
  build:
    runs-on: ubuntu-latest
    name: "Get environment URL"
    outputs:
      commit_status: ${{ steps.status.outputs.env_status }}
      env_url: ${{ steps.url.outputs.env_url }}
      integration_status: ${{ steps.wait.outputs.integration }}
    steps:
      - uses: actions/checkout@v2
      - name: "Await deployment"
        id: wait
        run: |
          COMMIT_STATUS="pending"
          sleep 10
          STATUSES=$(curl -s https://api.github.com/repos/$GITHUB_REPOSITORY/statuses/$GITHUB_SHA  | jq -r 'length')
          if [ $STATUSES == 0 ]; then
              echo "Not on a Platform.sh integrated environment. Skipping."
              echo "::set-output name=integration::none"
          else
              until [ "$COMMIT_STATUS" == "success" ] || [ "$COMMIT_STATUS" == "failure" ]; do
                sleep 10
                ENV_URL=$(curl -s https://api.github.com/repos/$GITHUB_REPOSITORY/statuses/$GITHUB_SHA  | jq -r '.[0].target_url')
                COMMIT_STATUS=$(curl -s https://api.github.com/repos/$GITHUB_REPOSITORY/statuses/$GITHUB_SHA  | jq -r '.[0].state')
              done
              echo "Environment deployed. Finished."
              echo "::set-output name=integration::platformsh"
          fi
      - name: "Pass status"
        id: status
        if: steps.wait.outputs.integration == 'platformsh'
        run: |
          COMMIT_STATUS=$(curl -s https://api.github.com/repos/$GITHUB_REPOSITORY/statuses/$GITHUB_SHA  | jq -r '.[0].state')
          echo "::set-output name=env_status::$COMMIT_STATUS"
      - name: "Pass URL"
        id: url
        if: steps.wait.outputs.integration == 'platformsh'
        run: |
          ENV_URL=$(curl -s https://api.github.com/repos/$GITHUB_REPOSITORY/statuses/$GITHUB_SHA  | jq -r '.[0].target_url')
          echo "::set-output name=env_url::$ENV_URL"
```

This job (`build`):

* Is triggered by all push events that don’t occur on the default branch.
* Places requests on the Status API, until Platform.sh informs GitHub that the environment has either succeeded or
  failed to deploy the new commits.
* Passes both that final status and the environment’s URL to any subsequent jobs that define `needs.build` in their
  configuration.

## Github actions status checks ensures deployment ease and success

One of the great things about GitHub actions is that I don’t have to write them. If I, for example, wanted to make a
quick status check on the environment, I can leverage the generous work of
[another published action](https://github.com/marketplace/actions/http-status) in my workflow pretty easily.

```yaml {filename="post-deploy.yaml"} theme={null}
test:
  name: "Status tests"
  runs-on: ubuntu-latest
  needs: build
  if: needs.build.outputs.commit_status == 'success'
  steps:
    - name: "Application should deploy successfully"
      uses: lakuapik/gh-actions-http-status@v1
      with:
        sites: '["${{ needs.build.outputs.env_url }}"]'
        expected: "[200]"
```

In this case, I’ve written a new job called `test` which will:

* Only run if the output of the `build` job (and the status of my Platform.sh environment) is successful.
* Will `use` the `lakuapi/gh-actions-http-status` public action to place a request on the environment URL also retrieved
  from the `build` job.
* Apply an expected status to that request. If the statuses match, the step will pass, adding another check to my pull
  request. Should it receive a 404 or 503, the step fails and we can go investigate where the deployment fell short.

This snippet only covers the homepage of the development environment, but I could also include more endpoints in the
`sites` array, with matching `expected` statuses that will show up as separate steps in my final workflow for the push.

### Configuring Lighthouse with GitHub actions to monitor user experience

Status checks for GitHub actions are great, but what I really want to know is whether a pull request is modifying the
experience a user has when they visit my application in some negative way. Once again, I can add a job that uses a
publicly available GitHub action - in this case, to perform a
[Lighthouse](https://developers.google.com/web/tools/lighthouse/) audit on my environment URL.

To start, we can add a few workflow-level environment variables to `post-deploy.yaml`

```yaml {filename="post-deploy.yaml"} theme={null}
env:
  PLATFORMSH_CLI_TOKEN: ${{ secrets.CLI_TOKEN }}
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  ACC_MIN: 0.90
  BPR_MIN: 0.90
  PRF_MIN: 0.90
  SEO_MIN: 0.95
```

These variables are going to set a few thresholds for the four main audits we’d want to keep high on our homepage:
Accessibility, Best Practices, Performance, and SEO.

Here’s what the Lighthouse report looks like for our Platform.sh homepage:

<img alt="Success GitHub Status" />

Not too shabby!

Let’s add a new job called `audit` which uses the
[`jakejarvis/lighthouse-action`](https://github.com/marketplace/actions/lighthouse-audit) GitHub action, first focusing
on the Accessibility audit.

```yaml {filename="post-deploy.yaml"} theme={null}
audit:
  name: "Lighthouse Audit"
  runs-on: ubuntu-latest
  needs: build
  if: needs.build.outputs.commit_status == 'success'
  steps:
    - name: Audit live URL
      uses: jakejarvis/lighthouse-action@master
      with:
        url: ${{ needs.build.outputs.env_url }}
    - name: Upload results as an artifact
      uses: actions/upload-artifact@master
      with:
        name: report
        path: "./report"
    - name: Accessibility test
      run: |
        REPORT=$(ls report | grep \.json$)
        SCORE=$(cat report/$REPORT | jq -r '.categories.accessibility.score')
        if [ 1 -eq "$(echo "${SCORE} < ${{ env.ACC_MIN }}" | bc)" ]; then
            echo "Threshold Failed:"
            echo "  - Score:     $SCORE"
            echo "  - Threshold: ${{ env.ACC_MIN }}"
            exit 1
        else
            echo "Passed:"
            echo "  - Score:     $SCORE"
            echo "  - Threshold: ${{ env.ACC_MIN }}"
        fi
```

This `audit` job will:

* Only run on pushes to a branch associated with a pull request integrated with a Platform.sh environment that has
  successfully deployed. (See `build` above)
* Use the [`jakejarvis/lighthouse-action`](https://github.com/marketplace/actions/lighthouse-audit) action with the
  environment URL passed along from the `build` job.
* Upload the full report as a workflow artifact, so that we can inspect individual recommendations in detail later.
* The action will also save a local copy of the report in two formats - html and JSON - in a `report` subdirectory. We
  can then use the [`jq`](https://stedolan.github.io/jq/manual/) tool to retrieve the accessibility score.
* Run a simple test based on the Accessibility audit using the `ACC_MIN` threshold we set previously. In this case, if
  the accessibility score for our environment is below 90%, the step and workflow will fail for the push.

Using this same logic we can add tests for Best Practices:

```yaml {filename="post-deploy.yaml"} theme={null}
- name: Best practices test
  run: |
    REPORT=$(ls report | grep \.json$)
    SCORE=$(cat report/$REPORT | jq -r '.categories."best-practices".score')
    if [ 1 -eq "$(echo "${SCORE} < ${{ env.BPR_MIN }}" | bc)" ]; then
        echo "Threshold Failed:"
        echo "  - Score:     $SCORE"
        echo "  - Threshold: ${{ env.BPR_MIN }}"
        exit 1
    else
        echo "Passed:"
        echo "  - Score:     $SCORE"
        echo "  - Threshold: ${{ env.BPR_MIN }}"
    fi
```

Performance

```yaml {filename="post-deploy.yaml"} theme={null}
- name: Performance test
  run: |
    REPORT=$(ls report | grep \.json$)
    SCORE=$(cat report/$REPORT | jq -r '.categories.performance.score')
    if [ 1 -eq "$(echo "${SCORE} < ${{ env.PRF_MIN }}" | bc)" ]; then
        echo "Threshold Failed:"
        echo "  - Score:     $SCORE"
        echo "  - Threshold: ${{ env.PRF_MIN }}"
        exit 1
    else
        echo "Passed:"
        echo "  - Score:     $SCORE"
        echo "  - Threshold: ${{ env.PRF_MIN }}"
    fi
```

and SEO.

```yaml {filename="post-deploy.yaml"} theme={null}
    - name: SEO test
      run: |
          REPORT=$(ls report | grep \.json$)
          SCORE=$(cat report/$REPORT | jq -r '.categories.seo.score')
          if [ 1 -eq "$(echo "${SCORE} < ${{ env.SEO_MIN }}" | bc)" ]; then
              echo "Threshold Failed:"
              echo "  - Score:     $SCORE"
              echo "  - Threshold: ${{ env.SEO_MIN }}"
              echo "Download the full report under *Artifacts* at: https://github.com/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID"
              exit 1
          else
              echo "Passed:"
              echo "  - Score:     $SCORE"
              echo "  - Threshold: ${{ env.SEO_MIN }}"
              echo "Download the full report under *Artifacts* at: https://github.com/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID"
          fi

```

### Streamline your Platform.sh deployments with GitHub actions

There’s two more things down that can be connected to Platform.sh deployments using GitHub actions. You can find the
full [Gist](https://gist.github.com/chadwcarlson/96d6c4cb8c6b371ab04e256554dde728) for the workflow described above on
GitHub.

Goodbye for now - until I can think of something else interesting to play with here. If you have a custom workflow, or
if you’d like to share tips and tricks of your setup, let us know by sharing your actions with the rest of our
[Upsun Community Forum](https://community.upsun.com/).


# Automating Runtime and Service Tracking with Meta Version Updater
Source: https://developer.upsun.com/posts/how-tos/meta-version-updater-introduction

Meta is Upsun’s shared reference layer for runtimes, services, regions, and
extensions. Learn why we built it, how it works, and how it powers the next
generation of Upsun documentation and tooling.


<PostMeta />

From our previous article about [Meta reference source introduction](https://devcenter.upsun.com/posts/meta-reference-source-introduction/), once you centralise reference data, the next challenge is keeping it accurate.

Upsun supports a large and evolving ecosystem of runtimes, services, and regions. Tracking upstream releases, supported versions, and deprecated images manually quickly becomes unsustainable.

This is where our internal tool named **Meta Version Updater** comes in.

## The challenge: staying in sync with reality

Today, Upsun manages:

* **23 services**
* **9 runtimes**
* **15 public regions**
* **PHP extensions** from PHP 5.4 up to PHP 8.5

Each of these evolves independently, driven by:

* Official upstream releases
* Security and maintenance policies
* Internal build pipelines
* Git branches representing supported versions

Before Meta Version Updater:

* Engineers manually cross-checked multiple sources
* Updates required hand-edited files
* Documentation changes meant additional pull requests
* Drift between reality and documentation was hard to detect

## Introducing Meta Version Updater

**Meta Version Updater** is an internal automation tool designed to continuously reconcile *what exists* with *what we support*.

<img alt="Screenshot of the Meta Version Updater interface" />

At a high level it:

* Collects **official upstream versions**
* Compares them with **Upsun-supported images** (Git branches)
* Detects missing, outdated, or deprecated versions
* Updates Meta and documentation through automated pull requests

Beyond automating version management, this tool enables us to keep track of official releases. By monitoring new versions as they become available, we can make informed decisions about where to invest our efforts to provide timely access to the most valuable updates for our users.

## Technical stack

Meta Version Updater relies on a modern and efficient technical stack:

* **Node.js v24**: The main engine of the application, providing speed and compatibility with the latest JavaScript features.
* **PostgreSQL 18**: A robust relational database to store metadata, versioning, and update history.

**Allocated resources:**

* **Application**: 0.5 CPU, 0.218 GB RAM, 500MB disk space
* **Database**: 0.5 CPU, 1.375 GB RAM, 500MB disk space

This configuration ensures smooth operation, fast data ingestion, and the ability to scale as Upsun's ecosystem grows.

<img alt="Resources used by the Meta Version Updater tool" />

By leveraging Upsun, we were able to deliver this tool much faster and with greater agility.
The platform's flexibility and automation capabilities allowed us to focus on core features and respond quickly to evolving requirements.

## Nightly ingestion pipeline (high level)

Every night, Meta Version Updater ingests data from multiple sources:

1. **Official upstream versions**
   * Runtime and service release sources
   * Used as the reference for what *could* be supported

2. **Upsun internal repositories**
   * Git branches represent supported versions
   * Missing branches highlight unsupported or pending versions

3. **Upsun APIs**
   * Regions are fetched directly from the Upsun API
   * IP addresses are added manually where required

```mermaid theme={null}
flowchart TB
  S[Scheduler: nightly run] --> A[Fetch upstream versions: runtime and service releases]
  S --> B[Fetch internal branches: branch to version]
  S --> C[Fetch Upsun regions: Upsun API]
  A --> D[Compare and detect gaps: missing versions, candidates]
  B --> D
  C --> E[Enrich regions: manual addition of IPs]
  D --> F[Generate updates: registry.json and derived data]
  D --> G[Update PHP extension data: php_extensions.yaml]
  E --> H[Update region data: regions.yaml]
  F --> I[Open PRs: upsun/meta and platformsh/docs]
  G --> I
  H --> I
```

## What gets updated automatically

The tool produces structured updates for:

* **`registry.json`**
  * Supported and deprecated service/runtime versions
  * Used by:
    * [https://docs.upsun.com/add-services.html](https://docs.upsun.com/add-services.html)
    * [https://docs.upsun.com/languages.html](https://docs.upsun.com/languages.html)

* **`php_extensions.yaml`**
  * Default and available PHP extensions per version
  * Displayed here:
    * [https://docs.upsun.com/languages/php/extensions.html](https://docs.upsun.com/languages/php/extensions.html)

* **Region data**
  * Public regions and metadata
  * Displayed here:
    * [https://docs.upsun.com/development/regions.html#regions](https://docs.upsun.com/development/regions.html#regions)

***

## Human review stays in the loop

Automation does not remove humans from the process.

For every detected change, Meta Version Updater:

* Opens **pull requests automatically**
* Targets:
  * `upsun/meta`
  * `platformsh/docs`
* Highlights diffs and version changes clearly

This guarantees:

* Reviewability
* Traceability
* Intentional changes only

***

## Detecting drift before it hurts

One of the most valuable outcomes is early drift detection:

* Official versions exist but no internal branch → missing support
* Supported versions without upstream maintenance → deprecation candidates
* Documentation inconsistencies → caught before release

This gives teams a clear, actionable view of platform support.

## What’s coming next: Slack summaries via n8n

We’re extending the workflow further.

An **n8n-based automation** is currently in development to:

* Send Slack notifications when a PR with image updates is opened
* Post a human-friendly summary of changes
* Improve visibility across internal teams

The goal is straightforward:
make changes visible, understandable, and actionable—without manual coordination.

## Links

* Meta API docs (Scalar): [https://meta.upsun.com/api-docs](https://meta.upsun.com/api-docs)


# How to update your PostgreSQL database without downtime
Source: https://developer.upsun.com/posts/how-tos/no-downtime-postgres-updates



<PostMeta />

## Some background

On paper, releasing a new version of your application that requires upgrading the schema of the database is straightforward. But, changes of code and schema can not be updated in an atomic way, you only need to take care that old code is not performing a query against new schema, and reciprocally.

The simple solution is to stop the old version during the schema’s upgrade:

1. Upload the new source code
2. Stop the old version of the application
3. Upgrade the schema of the database (a.k.a execute migrations), if needed
4. Start the new version of the application
5. Celebrate

This can be represented like this:

<img alt="Initial plan" />

This is simple but requires stopping the application, which means that during the deployment, users will get an error page (or in the best case a pretty maintenance page). Your application is down, you are not selling anything, you are losing money, and users are angry.

To avoid the downtime, you can tell your router (or load balancer) to hold the HTTP connections during the deployment -- this is how Platform.sh and Upsun handle your deployments.

This works well, but requires a complex infrastructure setup (that Platform.sh takes care of for you). It also has a drawback: While updating, visitors get a “loading spinner”. When the update is really fast, it’s not an issue, but when it takes several seconds, it starts to be noticeable, and if it reaches a timeout it might lead to an error page.

This is the problem zero-downtime deployment solves, by defining how and in which order you should perform individual tasks to avoid down time.

The topic is wide, and for simplicity, this article will focus only on database schema updates. It will not cover other parts like the deployment strategy (blue/green, canary, …), NoSQL/Schema less database migration, API compatibility (mobile devices, SDK, …), stateful storage (shared cache / session / cookies, queues, …), etc.

Whatever the deployment strategy you are using (blue/green, canary, rolling update, …), the goal is always the same: you have at any time, **at least** one running version of the application. The important word here is “at least”, because the application’s versions can not toggle, flip, or upgrade in an atomic way: at some point in time, you are running **multiple versions** of your application in **parallel**.

Even with a toggle strategy (like blue/green), there is a chance that your application starts handling a request in version 1, then the deployment switches to the new version, and a second request starts on version 2 while the first one is not finished yet. It does not matter if it’s a few seconds or hours, we have to deal with that.

So let’s update our strategy and start version 2 before stopping version 1. Now the question:

> “Should I run the database migration **before**, or **after** updating the code?”

<img alt="Sequence considerations" />

Running the migration before the deployment has a great advantage: the new code knows that the schema is up to date, and can use it. You can put code and database changes into the same release.

The drawback: to run the migration you need the files that contain the queries. And, if your code and migration files are packaged together, to get these files, you need to deploy the new code. So you kinda started deploying the application and you’re not really running the migration BEFORE the deployment.
Also, if the migration fails, your deployment should stop/revert and prevent exposing the new code to users.

To solve this issue, it’s simpler to separate code release from migration release. In that way, you don’t care if the migration is run before or after the code’s update. Changes are just not related to each other.
It’s easier to separate the 2 deployments and understand changes step by step, which also allows you to fix and rerun failed migrations.

So, our previous strategy can now be updated to something like this:

<img alt="Updated strategy" />

## Generate a BC schema

In order to not break the running application, the most important thing to understand is that the code running in production must be compatible with the next version of the schema of the database. That means you can not drop or rename a table or column if it’s still used, you cannot add a non-nullable column, and so on.

If you need to update your application in a way that requires changing the schema of the database, you’ll need to split the changes and perform intermediate releases to prepare the schema before updating the code, then clean the schema in the final form.

To reduce the cognitive load, we’ll use an ORM pattern, where code is tightly coupled to the database schema.
The code uses `entities` (represented by a class) mapped to a database’s `table`.
Each `entity` has `properties` (represented by class’ variables) mapped to a table’s `column`.

Here are the main different situations you have to deal with:

* [Adding a new entity/table](#adding-a-new-entitytable)
* [Deleting an entity/table](#deleting-an-entitytable)
* [Renaming an entity/table](#renaming-an-entitytable)
* [Adding a new property/column](#adding-a-new-propertycolumn)
* [Removing a property/column](#removing-a-propertycolumn)
* [Renaming a property/column](#renaming-a-propertycolumn)

<Info>
  **Disclaimer:**

  The below recommendations concern a PostgreSQL database, and relies on PostgreSQL’s internal capabilities (like transaction in schema modifications, partial locking mechanism). Most of rules can be applied to other RDBMS (MySQL, …) or Database (Elasticsearch, MongoDb) but should be adapted to their specificities and capabilities.
</Info>

### Adding a new entity/table

Probably the easiest case, you need 2 releases, first create the table and then use it in the code.

1. \[migration] Create the table
2. \[code] Create the entity and use it

### Deleting an entity/table

You first need to stop using the entity in your application, which might require removing relationship properties (ie. one-to-many, …). In such a situation, first follow `Delete a property` ([see below](#removing-a-propertycolumn)) to drop them.

1. \[code] Delete entity from code
2. \[migration] Drop the table

### Renaming an entity/table

You can not rename a table without breaking the code running in production, you need to perform the migration in multiple steps, create a new table, fill it, and then delete the old one

1. \[migration] Create the table
2. \[code] Update the code to insert/update/delete in both tables (alternatively use triggers for this)
3. \[migration]
   1. Backfill missing value by using data from the OLD table  (⚠️ beware of perf, see next chapter)
   2. Alter all foreign keys to target the NEW table  (⚠️ beware of perf, see next chapter)
4. \[code] Update code to read from the NEW table, and remove usage of OLD table
5. \[migration] Drop the OLD table

### Adding a new property/column

This case depends if the property can be nullable or not. Because you can not add a non-nullable column to the table, the code in production is not aware of the property and might perform insert statements without the column: the database will try to use a null value, breaking the constraint and leading to an exception. This can be avoided with `DEFAULT` values, but this should be treated with caution (see next chapter about locks)

#### Adding a nullable property

1. \[migration] Alter the table to add the column with **nullable** option
2. \[code] Add the property in the entity and use it

#### Adding a non-nullable property with a known default

1. \[migration] Alter the table to add the column with **default value** option  (⚠️ beware of perf, see next chapter)
2. \[code] Add the property in the entity and use it

#### Adding a non-nullable property without default

1. \[migration] Alter the table to add the column with **nullable** option
2. \[code] Add the property in the entity (type hint nullable)
   1. getter value should return NULL (when fetching old data)
   2. But ensure new values will not be null (type-hint setter, assert, form validation, …)
3. \[migration]
   1. Backfill missing values with opinionated values  (⚠️ beware of perf, see next chapter)
   2. Alter the table and add a **not-null** constraint if needed (⚠️ beware of perf, see next chapter)
4. \[code] Remove nullable logic on property and getter

### Removing a property/column

Similar to adding a new property, depending on whether the property was nullable or not, and whether the property has a default value or not, the strategy will be different. Because, you first need to stop using this property, but you can not do it until the database allows you to perform `insert` statements without a required column.

#### Removing a nullable property

1. \[code] Remove the property from the code base
2. \[migration] Alter the table to drop the column (⚠️ beware of perf, see next chapter)

#### Removing a non-nullable property

1. \[migration] Make the column nullable or default to an opinionated constant value
2. \[code] Remove the property from the code base
3. \[migration] Alter the table to drop the column (⚠️ beware of perf, see next chapter)

### Renaming a property/column

You can not rename the column without breaking the code running on production, you need to perform the migration in multiple steps to create a new property and delete the old.

1. \[migration] Alter the table to add the NEW column with **nullable** option
2. \[code] Update the code to insert/update in both columns BUT still read on the old column. Alternatively, you can use a BEFORE INSERT / BEFORE UPDATE trigger for this
3. \[migration]
   1. Backfill missing value by using data from the OLD column  (⚠️ beware of perf, see next chapter)
   2. Alter table to add not-null constraint to the NEW column (⚠️ beware of perf, see next chapter)
4. \[code] Update code to read from the NEW column, and remove usage of OLD column
5. \[migration] Drop the OLD column from the DB (⚠️ beware of perf, see next chapter)

## Can I safely release my code in production?

In order to guarantee non-breaking changes are released, you should set your CI to run the test suite in a backward and forward manner.

1. **Backward compatibility:**

   The purpose of this test is to assert that the schema of the database in production is compatible with upcoming code modification.

   Such CI job would look like:

   ```bash theme={null}
   # set the table schema in the “running production” format  
   git checkout origin $CI_PROD_BRANCH  
   composer install  
   ./bin/console doctrine:migration:migrate

   # go back to feature branch and run tests  
   git checkout origin $CI_PULL_REQUEST_HEAD  
   composer install  
   ./vendor/bin/phpunit  
   ```

2. **Forward compatibility:**

   The purpose of this test is to assert that the code in production will be compatible with upcoming schema update.

   Such CI job would look like:

   ```bash theme={null}
   # stay on feature branch and setup the database schema  
   composer install  
   ./bin/console doctrine:migration:migrate

   # switch to the “running production” code and run tests  
   git checkout origin $CI_PROD_BRANCH  
   composer install  
   ./vendor/bin/phpunit  
   ```

## Do not lock other queries while migrating

Under normal circumstances, the production application is running select queries in parallel. But when a transaction containing a change to the schema is running, in most of the cases, everything else is **blocked** until the end of the transaction. This can have an impact on the pending query leading to timeout, and thus downtime.

### The double impact of `ACCESS EXCLUSIVE` locks

When altering the schema of a table, PostgreSQL will lock the table to prevent race conditions on concurrent access.\
For schema update (DDL), PostgresSQL uses 3 differents locks:

* **`ACCESS EXCLUSIVE`**: That prevents other DDL changes, but also prevents writes (insert, delete, update) and reads (select).
* **`SHARE ROW EXCLUSIVE`**: That prevent other DDL changes and writes (insert, delete, update), but allows concurrent reads (select)
* **`SHARE UPDATE EXCLUSIVE`**: That prevents other DDL changes, but allows writes (insert, delete, update) and reads (select).

| | `ACCESS EXCLUSIVE` | `SHARE ROW EXCLUSIVE` | `SHARE UPDATE EXCLUSIVE` |
| :- | :-: | :-: | :-: |
| DDL | ⛔ | ⛔ | ⛔ |
| insert/update/delete | ⛔ | ⛔ | ✅ |
| select | ⛔ | ✅ | ✅ |

The important thing to understand with locks is that a lock prevent the next query from executing, but the operation that asks the lock is also blocked by previous unfinished queries.

So the duration of an exclusive lock is not the duration of the operation, but the duration of the operation *plus* the duration of slowest currently running queries:

<img alt="Query history" />

In the above schema, the `add column` query (in red) requires an access exclusive lock. The query is queued until all previous queries finish, then it starts to be executed and maintains the lock until the end of its execution. During this time (queued time + running time) all following queries are queued.

To safe guard the situation, the best practice is using a lock timeout, which makes the migration fail but prevents impacting the other queries. When the migration fails, it can be retried later.

Also, another thing to keep in mind is that the lock is acquired during the entire transaction. If the migration contains changes on multiple tables, or even multiple changes, it’s safer to split the migration into multiple individual transactions. This will release the lock between each step and reduce the chance of deadlocks.

### Is it a fast or slow operation?

Some operations just update the catalogue (internal schema) of the table, and are fast. Having an `ACCESS EXCLUSIVE` lock during this situation is acceptable.
But some operations require rewriting data on all tables or perform a full table scan which are slow. Having an `ACCESS EXCLUSIVE` lock should be avoided in these situations.

To prevent locking the table for too long, you can split the operation into multiple queries and each query could acquire a `ACCESS EXCLUSIVE` or be slow, but not both.

### Run in multiple transactions

Because locks are acquired and maintained during the entire transaction, when your migration executes a query that requires a lock, the lock will be maintained until the execution of the last query and the `COMMIT`/`ROLLBACK`. Therefore, you should split the query in multiple transactions. Beware in case of failure and retry of the migration, when the migration contains multiple queries, some of them might have been committed, and some not. So your migration should be able to recover and skip previously executed query.

An alternative is to split your queries in multiple migrations. In that way each migration contains a single transaction and won’t be replayed.

### ⚠️ Updating / Inserting / Deleting a lot of rows

If you need to change a lot of rows, split the job in multiple chunks and execute each chunk in an individual transaction. This will prevent locking the table for too long.

```pseudo theme={null}
while (true) {  
    BEGIN TRANSACTION  
    UPDATE customers SET location=’france’ WHERE id IN (  
        SELECT id FROM customers WHERE location IS NULL LIMIT 1000  
    )  
    COMMIT  
}  
```

### ⚠️ VACUUM (FULL)

The command `VACUUM` and `VACCUM (FULL)` clean up rows that have been marked as deleted.
The first one (`VACCUM`) allows future reuse of the freed space without locking the table, but keep space on the physical disk.
The second one (`VACCUM (FULL)`) is more aggressive and physically compacts the database files. The operation might recover a lot of space on your physical disk, but the operation is extremely slow and requires an `ACCESS EXCLUSIVE` lock\
Therefore, never run `VACCUM (FULL)`.

### Creating a table

Creating a table is fast and requires a `SHARE ROW EXCLUSIVE` lock.

### Dropping a table

Dropping tables use `ACCESS EXCLUSIVE` lock, and requires to delete files on the FileSystem which should be acceptably fast

### ⚠️ Adding, Dropping, Reindexing an INDEX

Manipulating INDEX uses a `ACCESS EXCLUSIVE` lock and has to scan the full table and write index which can be slow.\
When possible you can use the  `CONCURRENTLY` option. The query will be slow but use a `SHARE ROW EXCLUSIVE` lock instead of `ACCESS EXCLUSIVE` lock.

1. `CREATE INDEX CONCURRENTLY` …

### Adding a COLUMN

Adding a column uses an `ACCESS EXCLUSIVE` lock.

#### Adding a COLUMN without default or constant default

If the column does not have a default value or uses a constant default, the operation is fast.

#### ⚠️ Adding a COLUMN with volatile default

If the column has a volatile default value (i.e. clock\_timestamp), the operation requires updating all the existing rows, which can take a non-negligible time. You should split the operation into multiple transactions

1. `ALTER TABLE table ADD COLUMN name `
2. `ALTER TABLE table ALTER COLUMN name DEFAULT=’clock_timestamp()’  `
3. `WHILE (true) UPDATE table SET name = clock_timestamp() WHERE name IN (SELECT … LIMIT 1000)`

### Alter COLUMN (nullable, default)

We are not talking about changing the type of value that is required to convert and rewrite all the rows, here we’ll focus on adding/dropping nullability or default.
This operation uses an `ACCESS EXCLUSIVE` lock.

#### Drop null or Drop default

Super fast, it just updates the schema of the table.

#### SET default

This operation is fast because, opposite to the `ADD COLUMN` statement, this operation does not update previous lines, it just sets a default for the new insert lines.

#### ⚠️ SET NOT NULL

There is a caveat here, because postgresql will perform a full table scan to check if there is no null value in the table. Instead you should add a (temporary) not valid constraint that will be used by PostgreSQL to skip the table scan when altering the column, then validate the constraint using a SHARE UPDATE EXCLUSIVE lock.

* `ALTER TABLE table  ADD CONSTRAINT check_name CHECK (name IS NOT NULL) NOT VALID`
* `UPDATE table SET name = … WHERE name IS NULL`
* `ALTER TABLE table  VALIDATE CONSTRAINT check_name`
* `ALTER TABLE table ALTER column SET NOT NULL`

### ⚠️ Drop COLUMN

Dropping a column uses an ACCESS EXCLUSIVE lock. The operation by itself is fast, but PostgreSQL first need to drop all indices which can be slow. So drop indices using the CONCURRENTLY option first

1. `DROP INDEX CONCURRENTLY …  `
2. `DROP INDEX CONCURRENTLY …  `
3. `ALTER COLUMN table DROP COLUMN name`

### ⚠️ Adding a ForeignKey constraint

ForeignKey operations use “`SHARE ROW EXCLUSIVE`” lock on both tables (the source and the target).\
It requires a full table scan to assert all reference keys exist on both sides. To reduce the lock duration, you can use a (temporary) `NOT VALID` constraint, then validate it. The validate operation will use a `SHARE UPDATE EXCLUSIVE` lock

1. `ALTER TABLE table ADD CONTRAINT name FOREIGN KEY … NOT VALID  `
2. `UPDATE table SET name = … WHERE name IS NOT IN (SELECT DISTINCT ref … FROM …)  `
3. `ALTER TABLE table VALIDATE CONSTRAINT name`

### Summary

| | SLOW | ACCESS EXCLUSIVE | SHARE ROW EXCLUSIVE | SHARE UPDATE EXCLUSIVE |
| :- | :-: | :-: | :-: | :-: |
| Create table | | | ✅ | |
| Drop table | ⚠️ | ✅ | | |
| Add column null | | ✅ | | |
| Add column default constant | | ✅ | | |
| Add column default volatile ⛔ | ⚠️ | ✅ | | |
| Alter column default | | ✅ | | |
| Drop column without index | | ✅ | | |
| Create index ⛔ | ⚠️ | ✅ | | |
| Create index CONCURRENTLY | ⚠️ | | ✅ | |
| Drop index ⛔ | ⚠️ | ✅ | | |
| Drop index CONCURRENTLY | ⚠️ | | ✅ | |
| Alter column drop not null | | ✅ | | |
| Alter column add not null ⛔ | ⚠️ | ✅ | | |
| Add constraint ⛔ | ⚠️ | ✅ | | |
| Add constraint NOT VALID | | ✅ | | |
| Validate constraint | ⚠️ | | | ✅ |
| Add FK | ⚠️ | | ✅ × 2 | |
| Add FK NOT VALID | | | ✅ × 2 | |
| Add constraint unique using index | | ✅ | | |
| Alter column unique ⛔ | ⚠️ | ✅ | | |


# Planning your Upsun migration: the 6-9 week roadmap
Source: https://developer.upsun.com/posts/how-tos/planning-your-upsun-migration-the-6-9-week-roadmap

Learn why 6-9 weeks is the ideal timeline for Upsun migrations, with expert insights on planning, testing, and avoiding common pitfalls.

<PostMeta />

We've seen migrations take a week. We've seen them take three years. Here's why 6-9 weeks is the sweet spot.

You've signed with Upsun. You're excited about the infrastructure-as-code approach, the preview environments, and the developer experience. There's just one small thing standing between you and all that goodness: the migration.

If you're a technical lead or manager responsible for planning this transition, you're probably asking yourself: How long will this take? What could go wrong? And more importantly, how do we avoid those things that could go wrong?

I sat down with Lucas Stil, Senior Manager of Onboarding & Migration at Upsun, to answer exactly these questions. Lucas has guided hundreds of migrations over the years, from the well-planned to the "developer's leaving for a kayak trip on Saturday, we need to go live Thursday" variety. Here's what he's learned.

## The timeline question

**Let's start with the obvious: How long does a migration actually take?**

**Lucas:** We generally suggest 6 to 9 weeks. That's our ideal timeline, and there's a reason for it. You can break it down nicely: 2 weeks for building and configuration, 2 weeks for testing, and 2 weeks for preparation and go-live.

Now, is that timeline set in stone? No. Recently, we had a client who had a single developer, and that developer was leaving on vacation on Saturday. Their old hosting was ending. So we got it done in a week, went live on Thursday so the developer could be available Friday, and then he went off to kayak in the middle of nowhere with no phone service for two weeks.

But do we recommend that? Absolutely not.

**What makes 6-9 weeks work better than, say, doing it in a week or spreading it over a year?**

**Lucas:** The 6-9 week timeline gives you room to test properly, room to iterate when things don't work the first time (and they won't, that's normal), and room to turn around if you need to adjust something. It's not so long that you're dealing with a moving target where people are developing new features in parallel and you're trying to migrate and keep up with changes on the old system at the same time.

The migrations that take years? Those are usually because the team is trying to do the migration alongside regular feature development. You don't have someone whose job is to migrate. You have someone who's also got tickets in their sprint, and they're trying to juggle both. That's when it drags out.

## Phase 1: Understanding Your Infrastructure (Week 1-2)

Before you write a single line of configuration or touch any deployment settings, you need to take a photograph of what you have now. Not what you think you have. Not what the infrastructure might theoretically handle on your worst Black Friday ever. What you actually have, right now, running in production.

**Lucas on why this matters:**

> "We've had clients tell us 'Oh yeah, I forgot to mention: my MariaDB runs on a dedicated machine with 8GB of RAM.' That changes everything. You need to know these things before you start planning, not discover them halfway through the migration."

Yes, Upsun makes it easy to scale up later. But that's not the point. The point is avoiding surprises. When you know what you have upfront, you can size things correctly from day one and skip the "why is our bill so high?" conversation later.

### Your infrastructure photography checklist

Start by documenting everything. Here's what you need to capture:

* **Services inventory**: Every service your application currently uses (databases, search engines, message queues, cache layers, etc.)
* **Current resource allocations**: How much CPU, memory, and storage each service actually uses under normal load
* **Custom configurations**: Any non-default settings, especially for databases (think custom MariaDB configurations for Magento, for example)
* **Dependencies map**: Which services depend on which other services
* **External connections**: Any third-party services you connect to that care about IP addresses (and some do). You're switching infrastructure, which means new IPs, which means updating allowlists before migration day
* **File storage patterns**: How many files, in what structure, and whether they're organized or all dumped in one directory

**A word on sizing:** Here's a trap that catches a lot of people.

**Lucas explains:**

> "Clients often fall into this pattern: they look at their worst day ever, the day when traffic went crazy and everything was stressed to the limit, and they say 'let's provision for that.' And then they're disappointed because yes, it's very performant, but it's also very expensive. Unless Black Friday is your daily reality, you don't need to size for peak. Size for a normal day plus 10-15%. That's a good target."

### Creating your configuration files

Once you know what you're working with, you need to translate that into Upsun configuration. You have a few tools to help:

1. **Templates**: Check if there's an official template for your stack (Drupal, WordPress, Symfony, etc.). These are well-maintained and give you a solid starting point.

2. **[config.upsun.com](https://config.upsun.com)**: This tool can connect to your repository and generate configuration for you. It's not perfect (you'll need to review and adjust), but it works well as a first pass.

3. **Documentation**: When in doubt, the [Upsun docs](https://docs.upsun.com) are your friend. You're defining infrastructure as code, which means you're writing `.upsun/config.yaml` files. Take the time to understand the structure.

The goal at the end of this phase: you should have configuration files that represent your current setup, even if they're not optimized yet.

## Phase 2: Get an MVP Running (Week 3-4)

Here's where many migrations get their first real test. Before you worry about copying production data, before you stress about load testing, before you do anything else: get a minimal version of your application working on Upsun.

**Lucas on the importance of the MVP:**

> "This is critical. Even if you're missing static resources, even if you don't have the full database, even if workers or email sending isn't configured yet: get the site running. If you can log into your admin interface and click around, move an article or two, that's your MVP. This step determines the velocity of everything that comes after."

### What "working" means

Your MVP doesn't need to be perfect. It needs to prove that:

* Your application code deploys correctly
* The basic services (web server, primary database) are configured properly
* You can access the application
* The fundamental structure is sound

Missing pieces at this stage are fine:

* Background workers
* Mail sending
* Full production data
* Static assets
* Advanced features

### Getting familiar with the tools

If you're new to Upsun, this is where you'll start learning the CLI and SSH access. These aren't just for migration; they're how you'll interact with your environments going forward.

**Lucas notes:**

> "There's a learning curve here. The Upsun CLI, SSH access to your environments: you'll need these during migration, especially for file copying. But if you already know the platform, this becomes a non-issue."

Think of this as optional-but-recommended time. The more comfortable you are with the tooling now, the smoother migration day will be.

## Phase 3: Load Testing with Production Data (Week 5-6)

This is the phase that many clients skip, and according to Lucas, that's a mistake. This is where you find the problems that matter, not in theory but in practice.

**Lucas on why load testing is essential:**

> "Clients often don't take the time to do this, and that's unfortunate. You need to import all the production resources: the full database, all the static files, everything. Then you run a load test. Not sized for your worst day ever, but for a normal day plus 10-15%."

### Setting up your test environment

Before you can test, you need production-like conditions:

1. **Import the full production database**: Not a subset. Not sample data. The whole thing.

2. **Copy all static assets**: Every image, every PDF, every uploaded file. Use `rsync` (we'll talk about file organization in a moment).

3. **Configure all services**: Even if you're not testing them specifically, having Redis, Elasticsearch, or whatever else you use in place means you're testing the real setup.

### The read-only filesystem trap

**Lucas explains the scenario:**

> "On Upsun, the filesystem is read-only by default. So if clients test lightly with a few users, everything seems fine. But then they haven't realized their file-based cache is disabled because they don't have Redis configured, and there's no cache at all. When you test alone, it works great. Then you run a load test and it falls apart."

You want problems to show up during the load test, not after you go live. If you discover that your caching strategy doesn't work with a read-only filesystem, this is the time to find out.

### What to monitor during load tests

While your tests are running, keep an eye on:

* **Metrics in the Upsun console**: Watch for bottlenecks at the container or service level
* **Blackfire**: Use it to identify performance issues in your application code
* **Response times**: Are they comparable to your current setup?
* **Error rates**: Any 500s, 502s, or other failures under load?

**Lucas on iteration:**

> "You'll iterate here. That's expected. Maybe you didn't size something right, maybe there's a configuration issue like the cache example. That's the point of this phase: find those issues and fix them before they're production problems."

### Generating load test scenarios

Here's the annoying part about load testing: writing realistic test scenarios. You need scripts that actually mimic what users do, not theoretical perfect paths through your application.

This is where tools like Claude Code come in handy. Instead of hand-crafting k6 or Locust scripts, you describe what users actually do ("browse catalog, add to cart, check out" or "search products, filter, view details"), and Claude Code writes the test code for you.

If you're curious how this works in practice, we've got a [detailed walkthrough on generating load test scenarios with Claude Code](https://devcenter.upsun.com/posts/hands-on/ai-use-case-generate-load-test-scenarios).

### The file organization problem

Here's a real-world example that affects migration speed. Lucas shared this story:

**Lucas on file organization:**

> "We had a client with all their files in one folder. No organization, no structure. PDFs, images, everything from multiple contributors, all in one directory. I think it was 15,000 to 20,000 files in a single folder. And that takes time to process, even with rsync doing differential copies. Even though there were few changes, rsync still had to count and verify every file, and that's slow."

The solution? **Create a directory structure before migration if you can:**

* By file type (images, documents, etc.)
* By date or category
* Using a hash-based structure (first two characters of SHA-256 hash as folder, next two as subfolder)

The hash-based approach is cleanest if you have a lot of files. It's a bit of work to set up initially, but it makes finding files programmatically easy and keeps rsync fast.

## Common pitfalls and how to avoid them

Let's talk about the patterns that cause problems, based on Lucas's experience with dozens of migrations.

### Pitfall 1: The Moving Target

**The problem:** You're migrating to Upsun while simultaneously developing new features on your old platform. Now you're trying to keep two systems in sync, test features on both sides, and everything takes twice as long.

**Lucas's take:**

> "The moving target is what makes migrations drag out. You test a feature on the new infrastructure, but you also need to push it to the old system, and maybe it doesn't work quite right on the old system so you have to adjust. You're running in circles."

**The solution:** Dedicate resources. Have someone whose job during these 6-9 weeks is the migration, not someone who also has a sprint full of feature tickets.

### Pitfall 2: Skipping the Load Test

**The problem:** Everything works fine with you clicking around the site, so you figure you're good to go.

**Lucas's warning:**

> "If you skip load testing, you're gambling. Sure, the site loads. But does it load under your normal traffic? Does it handle concurrent users? Does your checkout flow work when 50 people are buying things simultaneously? You don't know until you test."

**The solution:** Make load testing with production data a non-negotiable part of the plan.

### Pitfall 3: Discovering Infrastructure Details Too Late

**The problem:** You're deep into the migration when you discover "oh, by the way, our Redis setup is custom" or "did we mention the database has some special configuration?"

**Lucas's advice:**

> "This is why we start with the infrastructure photograph. Get it all written down before you start. Special configurations, custom setups, anything that's not default—document it first."

**The solution:** The checklist from Phase 1 is your insurance policy. Do it thoroughly.

## Your pre-migration checklist

By the end of your 6-9 weeks, before you even think about scheduling migration day, here's what should be in place:

### Configuration and setup

* Complete infrastructure documentation (services, sizes, configurations)
* `.upsun/config.yaml` created and tested
* MVP deployed and validated on Upsun
* All required services configured (databases, cache, search, queues)
* Environment variables and secrets configured

### Testing and validation

* Full production database imported and tested
* All static assets copied to Upsun
* Load testing completed with production-scale data
* Performance metrics comparable to current setup
* Any discovered issues resolved or understood

### Preparation for migration day

* File replication strategy defined (rsync with differential copies)
* Database replication set up (if supported for your database)
* DNS/CDN strategy determined (TTL reduction or backend switch)
* Maintenance page ready (both CDN and application-level if needed)
* Team trained on Upsun CLI and SSH access
* Rollback procedure documented (even if you don't plan to use it)

### Timeline and communication

* Migration day scheduled
* Team availability confirmed
* Stakeholders notified of timeline
* User communication plan prepared

## What's next

You've got your plan. You've tested everything. Your team knows the platform. Now it's time for the actual migration day.

In the next article, we'll walk through the cutover process itself: maintenance windows, the sequence of operations, verification steps, and what to do in those first critical 24 hours after you flip the switch.


# Replicate your production outage on staging
Source: https://developer.upsun.com/posts/how-tos/replicate-your-production-outage-on-staging

After fixing a production outage, you need to prove the fix works under the same traffic. Here's how to replicate real production traffic on an Upsun staging environment using the observability API and k6.


<PostMeta />

Your production site went down. Too much traffic, something in your code couldn't handle it, and your users got errors instead of pages. It happens.

Maybe the traffic subsided on its own. Maybe you threw more resources at it. Maybe you did both and called it a night. Either way, the immediate fire is out.

Now comes the harder question: how do you make sure it doesn't happen again?

## The fix is the easy part

You dig into your application and find the problem. Maybe you used [Blackfire](https://blackfire.io/) to find the bottleneck and fix it. Maybe you weren't using your cache layer and every request was hitting the database. Maybe you had a loop running individual queries when a single SQL statement would have done the job. Maybe a specific page was doing something expensive on every render that should have been precomputed.

You fix it. You deploy to staging. You feel good about it.

But feeling good isn't the same as knowing. You need to prove that if the same traffic hits your application again, it won't fall over the same way.

## Load testing isn't the same as traffic replication

The instinct here is to run a load test. Pick a tool, throw a bunch of concurrent requests at your staging environment, see if it holds up.

The problem is that a standard load test doesn't reproduce what actually happened. Your outage wasn't caused by "a lot of requests." It was caused by a specific pattern of requests hitting specific pages with specific data behind them. Maybe 1 page out of 200 was responsible for 80% of your CPU usage because of a particularly expensive query. Maybe the combination of 3 pages being hit simultaneously caused lock contention in your database. A uniform load test across your homepage won't surface any of that.

What you need isn't a generic load test. You need to replay the traffic that caused the outage, against an environment that matches production, and see what happens.

## The ingredients for a real replay

To replicate a production outage with confidence, you need 3 things:

1. **The traffic pattern.** The distribution of your most-hit URLs and their relative request rates from the incident. You won't replay every single request (the observability API gives you the top 10 URLs, not a full access log), but those top URLs are where the pressure was, and that's what matters.
2. **The same data.** Your staging database needs to contain the same records as production. A page that's slow because it renders 50,000 products won't be slow if your staging database has 12.
3. **The same resources.** If production runs on 2 CPUs and 4 GB of RAM, your staging environment needs to match. Testing your fix on a beefier machine proves nothing about production.

Getting all 3 in the same place is harder than it sounds. Most setups give you maybe 1 of these. Upsun gives you all 3.

## How to do it on Upsun

### Clone your environment

Start by creating a staging environment that's an exact copy of production. On Upsun, this is a single operation. When you [clone an environment](https://docs.upsun.com/environments.html), you get a byte-for-byte copy of your production data in an isolated environment. Same database records, same files, same everything.

Then give that environment the same [resources](https://docs.upsun.com/manage-resources/adjust-resources.html) as production. If production has dedicated CPU and memory allocations, match them on staging. You want the hardware to be identical so that the only variable is your code change.

### Get your traffic data

[Upsun's observability API](https://docs.upsun.com/api/#tag/Http-Traffic/operation/http_metrics_overview) exposes the top 10 URLs by traffic volume and bandwidth for any given time window.

You can pull this data through the Upsun CLI for the time range that covers your outage:

```bash {filename="Terminal"} theme={null}
upsun p:curl 'environments/main/observability/http-metrics/overview?from=<timestamp>&to=<timestamp>'
```

Replace `<timestamp>` with the start and end of your outage window. If you don't want to figure out the timestamps yourself, open the Upsun Console's metrics page for your environment, select the time range you care about, and grab the timestamps from the URL in your browser. What you get back is a breakdown of the most-requested URLs and their relative traffic volume.

### Generate a k6 load test with Claude

Here's where it gets interesting. Take that observability data and hand it to Claude. Ask it to generate a [k6](https://k6.io/) load test script that replicates the traffic distribution from your outage window.

k6 is a JavaScript-based load testing framework that's well-suited to this kind of thing. You define scenarios with different virtual users, request patterns, and timing. Claude can translate the observability data into a k6 script that matches the real traffic proportions, hitting the same URLs at the same relative rates.

A prompt along these lines works:

```text {filename="claude"} theme={null}
Run this command and use the output to generate a k6 load test
script that replicates the traffic distribution:

upsun p:curl 'environments/main/observability/http-metrics/overview?from=<timestamp>&to=<timestamp>'

The target URL is https://staging-abcdefgh1234567.us.platformsh.site.
Scale the virtual users so that the total request rate matches
what we saw in production.
```

Claude generates the k6 script. You run it against your staging environment. That environment has the same data and the same resources as production, and the traffic pattern reflects what your application was dealing with during the outage.

### Interpret the results

If your staging environment handles the replicated traffic without issues, you have high confidence that your fix works. Not certainty, because real production always has surprises, but a level of confidence that a generic load test can't provide.

If it still falls over, you know your fix wasn't sufficient, and you know it before deploying to production. That's worth a lot.

## Why this matters

The value here isn't in any single piece. Load testing tools exist. Staging environments exist. Observability dashboards exist.

The value is in combining all 3 into a workflow that answers a specific question: "If the same thing happens again, will my fix hold?" Most teams can't answer that question with confidence because their staging environment doesn't match production closely enough, or because their load test doesn't match the real traffic pattern.

When your staging is an exact clone of production, running on the same resources, and your load test replays the traffic from the incident, the gap between "I think it's fixed" and "I've verified it's fixed" gets very small.

That confidence changes how you operate. You deploy fixes faster because you've already validated them under realistic conditions. You sleep better because you've seen your application handle the exact scenario that woke you up last time. And when someone asks "are we sure this won't happen again," you have a better answer than "we think so."


# Scheduling resources
Source: https://developer.upsun.com/posts/how-tos/schedule-resource-availability



<PostMeta />

As Upsun does purely usage-driven billing,
rapid provisioning, and no-downtime scaling,
you have the ability to turn things off when they are not being used.
In this example, we will look at a way to scale down your development environments
and take them offline overnight when they are not in use.
This has the potential to reduce your hosting costs significantly.
...And reduce needless energy consumption also!

> [Platform.sh is committed to "Green Hosting" and better environmental sustainability.](https://platform.sh/blog/b-corp-certification/)

## Overview

To keep things simple to start with,
We will set up two small cron jobs
that will put your development environments to sleep at the end of the day,
and wake them up again before you start work.

The ability to turn things on and off requires access to an API key that can be used to invoke the `upsun` CLI utility.

<Note>
  **Assumptions:**

  * You already have a project hosted on Upsun.
    * with at least one development environment
    * and resources to add one more
  * You have the Upsun CLI installed.
</Note>

## Steps

### Create a feature branch environment

We will be adding and testing this new work in a feature branch.

Open a CLI in the project root and:

```bash {filename="Terminal"} theme={null}
FEATURE_BRANCH='pauseSun'
git checkout -b $FEATURE_BRANCH
git push --set-upstream upsun $FEATURE_BRANCH
upsun environment:activate -y --environment=$FEATURE_BRANCH 
```

> Upsun also [provides the equivalent of these git commands](https://docs.upsun.com/administration/cli.html#choose-between-the-cli-and-git-commands) - that can useful.

### Create an API token

You can do this either [via the console](https://docs.upsun.com/administration/cli/api-tokens.html#2-create-an-api-token), or with the CLI as outlined below:

<Info>
  Generating a new token cannot be done using a CLI token.
  Need to force browser login to make this work.
</Info>

```bash {filename="Terminal"} theme={null}
unset UPSUN_CLI_TOKEN
upsun auth:logout
upsun auth:browser-login
new_token_response=$(upsun api:curl users/"$(upsun auth:info id)"/api-tokens --json '{"name":"pauseSun runner"}')
new_token=$(echo $new_token_reponse | jq -r ".token")
```

### Embed the token into the feature branch environment

Do this the easy way [by setting an environment variable in the console](https://docs.upsun.com/administration/cli/api-tokens.html#authenticate-in-an-environment).

... or the hard way

```bash {filename="Terminal"} theme={null}
upsun variable:create \
   -e $FEATURE_BRANCH \
   --level environment \
   --prefix 'env' \
   --name UPSUN_CLI_TOKEN \
   --sensitive true \
   --value "$new_token" \
   --inheritable false \
   --visible-build true \
   --no-interaction
```

### Install `upsun` CLI

Now [add a build hook to your app configuration](https://docs.upsun.com/administration/cli/api-tokens.html#authenticate-in-an-environment) to install the CLI as part of the build process.

```yaml {filename=".upsun/config.yaml",hl_lines=["7-8"],linenostart=1} theme={null}
applications:
  app:
    hooks:
      #...
      build: |
        set -e
        echo "Installing Upsun CLI"
        curl -fsSL https://raw.githubusercontent.com/platformsh/cli/main/installer.sh | VENDOR=upsun bash
```

### Verify

If you push the code with the build hook now, you should see the message
`Upsun CLI has been installed successfully.` in your build log.

You can also `upsun ssh` into the environment and ensure that running `upsun` commands there works as expected and the token is valid.

```bash {filename="Terminal"} theme={null}
me@Platform Upsun-Tools-Demo % upsun ssh
 _   _                   
| | | |_ __ ____  _ _ _  
| |_| | '_ (_-< || | ' \ 
 \___/| .__/__/\_,_|_||_|
      |_|                

 Welcome to Upsun.
Environment: pausesun-varzi3y
Branch: pauseSun
Project: ce4ywrmdpxgbk

web@app.0:~$ upsun

Warning:
An API token is set. Anyone with SSH access to this environment can read the token.
Please ensure the token only has strictly necessary access.

Welcome to Upsun!

Project: Drupal10-Platformsh (ce4rmdpywxgbk)
Environment: pauseSun (type: development)
Application name: static
```

### Write the script

This could be done in any language you are comfortable with, but seeing as we are mostly just running commands on the CLI, I will stay in `bash`.

<Info>
  The default shell in `upsun` environments is actually `dash`, but that won't make a difference here.
</Info>

This script will be stored in a `scripts/` directory *inside your app folder*. So in my case with my application in  a folder called `app/`, this will be `app/scripts/` in the repository, but just `scripts/` from the runtime environment application root.

It's very easy to ask the API for the list of environments.
I want only `active`, `development` environments - don't want to touch the `production` environment!

```bash {filename="Terminal"} theme={null}
upsun environment:list --columns=ID --no-header --format=plain --type=development --status=active
```

Then, use the API to turn environments on and off within a script:

```bash {filename="scripts/pause_environments"} theme={null}
#!/usr/bin/env bash
# Pause all development environments

ENVIRONMENTS=$(upsun environment:list --no-interaction --columns=ID --no-header --format=plain --type=development --status=active)

for ENVIRONMENT in $ENVIRONMENTS; do
  # Exclude self.
  if [ "$ENVIRONMENT" != "$PLATFORM_BRANCH" ]; then 
    echo "$0 is pausing $ENVIRONMENT.."
    upsun environment:pause --no-interaction --no-wait --environment="$ENVIRONMENT"
  fi
done
```

Here I use `--no-wait` and loop through all the environments. This will result in the activities being queued by the orchestration system, while this command returns immediately.
If you have a number of environments, it may take a few minutes for them to all process sequentially.
Check out the activity log to watch the queue in action.

We can set this script to be executable now, and `git add`, `commit`, `push`, and test it.

```bash {filename="Terminal"} theme={null}
chmod a+x app/scripts/pause_environments
git add app/scripts/pause_environments
git commit -m "Added script to pause all environments"
git push
```

### Optional - publish this as a runtime operation

This will make it easy to turn everything on or off with one button!

```yaml {filename=".upsun/config.yaml",hl_lines=["5-9"],linenostart=1} theme={null}
application:
  app:
    operations:
      #...
      pause_environments:
        role: admin
        commands:
          start: scripts/pause_environments
```

<img alt="You can now trigger the runtime operation from the Web Console" />

### Set a schedule

This is as simple as [adding a line in the `crons` section](https://docs.upsun.com/create-apps/app-reference/single-runtime-image.html#crons) of your `.upsun/config.yaml`

```yaml {filename=".upsun/config.yaml",hl_lines=["5-9"],linenostart=1} theme={null}
application:
  app:
    crons:
      #...
      pause_environments_at_7pm:
        spec: '0 19 * * *'
        commands:
          start: scripts/pause_environments
```

<Info>
  Take care for time zones!!
  [`cron` will run on the system timezone. Adjust as needed.](https://docs.upsun.com/create-apps/app-reference/single-runtime-image.html#cron-job-timing)
</Info>

Once you `git add`, `commit`, and `push` this to your environment, all should be ready to run.

You can test the operation immediately by invoking it from the console via "Run runtime operation"

### Repeat this for turning back on in the morning

Almost the same additions can be made to reverse the process.

We use `upsun environment:resume` (not `environment:activate`) so as to not accidentally turn on new environments.

```bash {filename="scripts/resume_environments"} theme={null}
#!/usr/bin/env bash
# Wake up all development environments

ENVIRONMENTS=$(upsun environment:list --no-interaction --columns=ID --no-header --format=plain --type=development --status=paused)

for ENVIRONMENT in $ENVIRONMENTS; do
  if [ "$ENVIRONMENT" != "$PLATFORM_BRANCH" ]; then 
    echo "$0 is activating $ENVIRONMENT.."
    upsun environment:resume --no-interaction --no-wait --environment="$ENVIRONMENT"
  fi
done
```

In `upsun/config.yaml`, add the cron job and runtime operation to turn things on:

```yaml {filename=".upsun/config.yaml"} theme={null}
application:
  app:
    operations:
      #...
      resume_environments:
        role: admin
        commands:
          start: scripts/resume_environments

    ...
 
    crons:
      #...
      resume_environments_at_7am:
        spec: '0 7 * * 1-5'
        commands:
          start: scripts/resume_environments 
```

DONE!

## Conclusions

You now have a short, simple way to schedule downtime for your development environments when you are not using them.

This simple example doesn't contain much business logic, though I do try to leave things off over the weekend also.
For real use you may want to maybe adjust the schedule to be more selective about which environments really have to be turned on every day.

In this example, I developed and tested in a dedicated branch environment.
For real use, I could now merge this addition into the `production` branch, and have the schedule running from there.
This is because the `production` is expected to be always-on, and we can't put the scheduler into an environment that might itself become paused.

You could even put this script (and the corresponding `upsun` CLI and token) in a separate hosting environment altogether. This tutorial is an example of the building blocks that you can adjust to your own workflows.


# Supply chain attacks in the AI era, and what to do about them
Source: https://developer.upsun.com/posts/how-tos/supply-chain-attacks-in-the-ai-era-and-what-to-do-about-them

AI agents are reading code at scale, including your dependencies. Why supply chain risk just changed, plus a build-time fix to add on Upsun.


<PostMeta />

AI agents are getting really good at reading code. Yours, your dependencies, the ones you forgot you depend on. The barrier to finding an exploitable bug in some random library 3 levels deep in your `package.json` keeps dropping.

That's a problem if your strategy for supply chain security is "I'll patch when I hear about it". You won't hear about all of them, and you won't hear in time.

This post is about one small, concrete thing you can do today: fail your Upsun deployment when a high-severity vulnerability shows up in your dependencies. The mechanism is the [build hook](/docs/configure-apps/image-properties/hooks#build-hook). This example uses [Snyk](https://snyk.io/), which has a free tier that's enough for this, but any equivalent scanner works the same way.

It's not the whole answer. We'll get to that. But it's a real check that runs every time you push.

## Why build-time matters

Dependency vulnerability scans usually live in 1 of 2 places: your CI pipeline, or your IDE. Both are fine, both are also avoidable. A developer can push a branch that skipped CI. A vulnerability database can publish a new advisory the day after your last green build.

A build hook on Upsun runs on every deploy. If the scan fails, the deploy fails, and the new code never reaches an environment. That's a different posture from "we hope someone runs the scan".

It's also the same hook your `npm install` already runs in, so the cost of adding it is tiny.

## Set up Snyk

You'll need a Snyk account and an authentication token. The free plan is enough for this (capped at 200 scans per month though). Paid plans also scan your own application code, not only dependencies. Look at what each tier covers and pick what fits.

1. Sign up at [snyk.io](https://snyk.io/) and connect a personal account.
2. Generate a personal access token (PAT) from your account settings.
3. In Upsun, set the token as a project-level environment variable:

```bash theme={null}
upsun variable:create --level project --name env:SNYK_TOKEN --value <YOUR_TOKEN> --visible-runtime false --sensitive true
```

The `env:` prefix exposes the value to your build container as a real environment variable. `--visible-runtime false` keeps it out of the runtime environment, since the build hook is the only place that needs it. `--sensitive true` hides the value in the Console and CLI output.

## Add the scan to the build hook

Open your `.upsun/config.yaml` and add the scan to the `hooks.build` step:

```yaml .upsun/config.yaml theme={null}
applications:
  app:
    type: "nodejs:20"
    hooks:
      build: |
        set -x -e
        npm install
        npx snyk test --all-projects --severity-threshold=high
```

A few things worth saying out loud:

* `npx` is bundled with `npm`, which is bundled with the `nodejs` runtime. No separate install step.
* `--all-projects` walks your repo and picks up every supported manifest it finds (`package-lock.json`, `requirements.txt`, `composer.lock`, and so on).
* `--severity-threshold=high` is the lever that decides what counts as a deploy-blocking vulnerability. Drop it to `medium` if you want to be stricter, raise it to `critical` if you want to be quieter.
* No explicit `snyk auth` call. The CLI picks up `SNYK_TOKEN` from the environment.

If the scan finds something at or above the threshold, `snyk test` exits non-zero, `set -e` kills the build, and your deploy fails. That's the behavior you want.

If you want to scan but not block (useful for the first week, while you triage what's already in there), append `|| true`:

```yaml theme={null}
npx snyk test --all-projects --severity-threshold=high || true
```

That makes the scan informational. Less useful as a permanent setting.

## What this catches

Push a deploy with a known-bad dependency and Snyk reports something like this in your build log:

```
Tested 89 dependencies for known issues, found 1 issue, 1 vulnerable path.

Issues to fix by upgrading:

  Upgrade next@15.5.15 to next@16.1.5 to fix
  ✗ Allocation of Resources Without Limits or Throttling [High Severity]
    introduced by next@15.5.15
```

The build fails. The activity in the Upsun console shows the failure. You bump `next`, push again, deploy succeeds. Boring. Boring is the goal.

## What this does not catch

A build-time scan only tells you what was vulnerable when you deployed. The hook runs at deploy time, not continuously. New CVEs land all the time, and the dependency you shipped on Monday can have an advisory published on Wednesday. If you don't deploy in the meantime, your already-running production stays exposed until your next push.

This check is necessary, not sufficient. You also want at least:

* A scheduled scan against your production dependencies that notifies you when something new shows up. Snyk does this for projects you import into its dashboard. GitHub does it via Dependabot for repositories on GitHub. Pick whichever fits your setup.
* A patching cadence. The scan finding a CVE only helps if someone actually upgrades the dependency. "We have alerts" without "we have an owner" is noise.
* A view of your runtime stack, not only your application code. Base images, system packages, and runtime versions are part of your supply chain too. On Upsun, base images and system packages are bundled into the runtime versions themselves, and we [keep them hardened and patched](/posts/how-it-works/how-weve-been-hardening-containers-since-before-docker-made-it-cool).

The build hook closes the door on shipping a known-bad version. Continuous monitoring catches the new known-bad versions of things you've already shipped. They're different jobs.

## Wrapping up

If you do nothing else after reading this, add 3 lines to your build hook and 1 project variable. That alone blocks a real category of deploys, and it costs you maybe 10 minutes.

Then set up the alerting side. The half of supply chain security that runs on a schedule is the half that protects you tomorrow.


# Making .upsun/config.yaml easier to edit with IDE autocomplete and validation
Source: https://developer.upsun.com/posts/how-tos/validate-yaml-config

Boost your productivity and eliminate configuration errors with real-time autocompletion and validation for your .upsun/config.yaml — discover how to enhance your IDE experience in just a few simple steps!  
  


<PostMeta />

Working with `.upsun/config.yaml` files can be tedious if your editor doesn’t help you catch errors early or suggest valid keys as you type.
Fortunately, you can get schema-based validation and autocompletion in popular editors like VSCode and PhpStorm — making your configuration faster, safer, and less error-prone.

In this article, we’ll show you how to set up this support using the official Upsun schema from [SchemaStore.org](https://www.schemastore.org/),
which IDEs like PhpStorm can automatically detect: [upsun.json](https://raw.githubusercontent.com/platformsh/platformify/refs/heads/main/validator/schema/upsun.json) schema

With just a few steps, you’ll get autocomplete for YAML config keys, inline documentation, and real-time error highlighting — all from your editor.

Let’s dive in! 🛠️

## Schema Available on SchemaStore

The [validation schema for `.upsun/config.yaml`](https://raw.githubusercontent.com/platformsh/platformify/refs/heads/main/validator/schema/upsun.json) is published on [SchemaStore](https://www.schemastore.org/), a centralized catalog of widely used JSON and YAML schemas.

Because it’s listed on SchemaStore:

* most IDEs, like [**VSCode**](https://code.visualstudio.com/), [**PhpStorm**](https://www.jetbrains.com/phpstorm/), [**WebStorm**](https://www.jetbrains.com/webstorm/), and [**IntelliJ IDEA**](https://www.jetbrains.com/idea/) (complete list [here](https://www.schemastore.org/#editors)), automatically detect and apply the schema when you open a `.upsun/config.yaml`.
* You benefit from autocompletion, inline errors, and context-aware editing — out of the box.

## Result with VSCode

<Info>
  If you're using Visual Studio Code, consider installing the [**Upsun VSCode extension**](https://marketplace.visualstudio.com/items?itemName=Upsun.upsun).
  It brings powerful features, including:

  * Schema-based autocompletion
  * Real-time configuration validation
  * Helpful inline documentation on hover
  * Project-aware interactions (more on this in an [upcoming blog post](/posts/releases/vscode-extension))

  Just install it from the [Marketplace](https://marketplace.visualstudio.com/items?itemName=Upsun.upsun) and start editing your `.upsun/config.yaml` — no extra setup required.
</Info>

### Autocomplete

If you’re unsure which settings are available at any level, just start typing — or press Ctrl+Space (or Cmd+Space on macOS) — to see a list of available parameters.

<img alt="Type less, discover more: Autocomplete every valid setting" />

And see possible values instantly:

<img alt="Let your IDE guide you: Autocomplete for fixed values" />

### Info on settings

When you hover your mouse over any YAML setting, helpful information and documentation links are displayed.

<img alt="Get instant info and documentation on any Upsun YAML setting" />

### Deprecated settings

As our product evolves, some settings have been deprecated and are now marked with an orange underline.
Hover your mouse over the setting to see a tooltip with helpful information about the deprecation and suggested alternatives.

<img alt="Deprecated settings are clearly marked" />

## Result with PhpStorm

<Info>
  Using PhpStorm, to ensure you're always using the latest version of the configuration schema,
  enable the **Always download the most recent versions of schemas** option under
  `Settings > Languages & Frameworks > Schemas and DTDs > Remote JSON Schemas`:

  <img alt="PhpStorm settings dialog showing Remote JSON Schemas configuration" />

  After enabling this option, restart your IDE to refresh all cached schemas.
</Info>

### Autocomplete

If you’re unsure which settings are available at any level, just start typing — or press Ctrl+Space (or Cmd+Space on macOS) — to see a list of available parameters.

<img alt="Type less, discover more: Autocomplete every valid setting" />

And see possible values instantly:

<img alt="Let your IDE guide you: Autocomplete for fixed values" />

### Info on settings

When you hover your mouse over any YAML setting, helpful information and documentation links are displayed.

<img alt="Get instant info and documentation on any Upsun YAML setting" />

### Deprecated settings

As our product evolves, some settings have been deprecated and are now marked with an orange underline.
Hover your mouse over the setting to see a tooltip with helpful information about the deprecation and suggested alternatives.

<img alt="Deprecated settings are clearly marked" />

## Best practices

* Always validate your config before committing or deploying.
* If you're using CI/CD, consider adding schema validation as a pre-check.
* Keep your IDE schema mappings up to date — most modern IDEs do this automatically.

With the right tools in place, validating `.upsun/config.yaml` becomes seamless — and ensures your configuration is always predictable, stable, and ready for production.

**Happy deploying!** 🚀

If you need assistance with setting up validation in your specific IDE or integrating it into your CI/CD pipeline, feel free to reach out on the [Upsun Community Forum](https://community.upsun.com/).


# Blog
Source: https://developer.upsun.com/posts/index

Articles, guides, and deep dives from the Upsun team.

<div>
  <div>
    <div>
      # Blog

      <p>
        Technical articles, deep dives, and announcements from the Upsun team and community.
      </p>
    </div>

    <div>
      <h2>Recent</h2>

      <div>
        <a href="/posts/insights/session-storage-gets-complicated-faster-than-you-think">
          <img alt="Session storage gets complicated faster than you think" />

          <div>
            <div>
              <span>Insights</span>
              <span>Sep 30, 2026</span>
            </div>

            ### Session storage gets complicated faster than you think

            <p>
              Explore session storage tradeoffs across files, PostgreSQL, Redis, and Valkey, from expiration and cleanup to memory limits. Test your options on Upsun Cloud.
            </p>
          </div>
        </a>

        <a href="/posts/how-it-works/airflow-on-a-locked-down-platform">
          <div>
            <div>
              <span>How It Works</span>
              <span>Sep 22, 2026</span>
            </div>

            ### Airflow on a locked-down platform

            <p>Running Apache Airflow on Upsun's hardened containers takes 30 lines of C and a decision about how much task isolation you actually want back.</p>
          </div>
        </a>

        <a href="/posts/ai/prompts-are-the-new-legacy-code">
          <div>
            <div>
              <span>AI</span>
              <span>Sep 10, 2026</span>
            </div>

            ### Prompts are the new legacy code

            <p>Dispatch's code review agent lost 80% of its prompt and four sub-agents. Same model, same quality, cost more than halved, 25% faster. Here's the method.</p>
          </div>
        </a>
      </div>
    </div>

    <div>
      <h2>Browse by Category</h2>

      <div>
        <a href="/posts/articles/index">
          <svg>
            <path />
          </svg>

          <span>All Articles</span>
        </a>

        <a href="/posts/articles/ai">
          <svg>
            <path />
          </svg>

          <span>AI</span>
        </a>

        <a href="/posts/articles/releases">
          <svg>
            <path />
          </svg>

          <span>Releases</span>
        </a>

        <a href="/posts/articles/how-tos">
          <svg>
            <path />
          </svg>

          <span>How-tos</span>
        </a>

        <a href="/posts/articles/how-it-works">
          <svg>
            <path />

            <path />
          </svg>

          <span>How it works</span>
        </a>

        <a href="/posts/articles/insights">
          <svg>
            <path />
          </svg>

          <span>Insights</span>
        </a>

        <a href="/posts/articles/hands-on">
          <svg>
            <path />
          </svg>

          <span>Hands-on</span>
        </a>
      </div>
    </div>

    <div>
      <h2>All Posts</h2>

      <ShowMore>
        <a href="/posts/insights/session-storage-gets-complicated-faster-than-you-think">
          <div>
            <h3>Session storage gets complicated faster than you think</h3>
          </div>

          <span>Wednesday, September 30th 2026</span>
        </a>

        <a href="/posts/how-it-works/airflow-on-a-locked-down-platform">
          <div>
            <h3>Airflow on a locked-down platform</h3>
          </div>

          <span>Tuesday, September 22nd 2026</span>
        </a>

        <a href="/posts/ai/prompts-are-the-new-legacy-code">
          <div>
            <h3>Prompts are the new legacy code</h3>
          </div>

          <span>Thursday, September 10th 2026</span>
        </a>

        <a href="/posts/discussions/give-your-ai-agent-a-system-that-is-safe-to-break">
          <div>
            <h3>Give your AI agent a system that is safe to break</h3>
          </div>

          <span>Tuesday, September 8th 2026</span>
        </a>

        <a href="/posts/how-it-works/how-to-host-a-website-that-isnt-publicly-reachable">
          <div>
            <h3>How to host a website that isn't publicly reachable</h3>
          </div>

          <span>Thursday, September 3rd 2026</span>
        </a>

        <a href="/posts/tutorials/ai-log-analysis-agent-in-an-upsun-task-container">
          <div>
            <h3>Run an AI Log-Analysis Agent in an Upsun Task Container</h3>
          </div>

          <span>Tuesday, September 1st 2026</span>
        </a>

        <a href="/posts/how-it-works/why-lets-encrypt-certificate-renewals-fail">
          <div>
            <h3>Why Let's Encrypt certificate renewals fail</h3>
          </div>

          <span>Tuesday, August 25th 2026</span>
        </a>

        <a href="/posts/tutorials/offload-heavy-jobs-to-upsun-task-containers-with-cron">
          <div>
            <h3>Offload Heavy Jobs to Upsun Task Containers, Triggered by Cron</h3>
          </div>

          <span>Thursday, August 20th 2026</span>
        </a>

        <a href="/posts/how-it-works/how-ssh-authentication-works-on-upsun">
          <div>
            <h3>How SSH authentication works on Upsun Cloud</h3>
          </div>

          <span>Tuesday, August 18th 2026</span>
        </a>

        <a href="/posts/ai/how-to-choose-a-code-index-for-your-coding-agent">
          <div>
            <h3>How to choose a code index for your coding agent</h3>
          </div>

          <span>Tuesday, August 4th 2026</span>
        </a>

        <a href="/posts/insights/which-stack-would-you-pick-for-an-interactive-ai-app-today">
          <div>
            <h3>Which stack would you pick for an interactive AI app today?</h3>
          </div>

          <span>Friday, July 31st 2026</span>
        </a>

        <a href="/posts/how-it-works/backup-consistency-why-it-matters-and-how-upsun-handles-it">
          <div>
            <h3>Backup consistency: why it matters and how Upsun handles it</h3>
          </div>

          <span>Tuesday, July 21st 2026</span>
        </a>

        <a href="/posts/how-it-works/can-you-trust-the-x-client-ip-header">
          <div>
            <h3>Can you trust the X-Client-IP header?</h3>
          </div>

          <span>Tuesday, July 14th 2026</span>
        </a>

        <a href="/posts/how-it-works/write-a-git-server-with-per-branch-permissions-in-five-minutes">
          <div>
            <h3>Write a Git server with per-branch permissions in five minutes</h3>
          </div>

          <span>Tuesday, July 7th 2026</span>
        </a>

        <a href="/posts/insights/why-emacs-is-still-my-interface-to-my-computer">
          <div>
            <h3>Why Emacs is still my interface to my computer</h3>
          </div>

          <span>Tuesday, June 30th 2026</span>
        </a>

        <a href="/posts/hands-on/civicrm-with-wordpress-bedrock-on-upsun">
          <div>
            <h3>CiviCRM with WordPress Bedrock on Upsun</h3>
          </div>

          <span>Tuesday, June 30th 2026</span>
        </a>

        <a href="/posts/how-it-works/cloning-a-terabyte-in-a-minute-and-the-limit-hiding-behind-it">
          <div>
            <h3>Cloning a terabyte in a minute, and the limit hiding behind it</h3>
          </div>

          <span>Tuesday, June 23rd 2026</span>
        </a>

        <a href="/posts/how-it-works/how-redundancy-and-failover-work-on-upsun">
          <div>
            <h3>How redundancy and failover work on Upsun</h3>
          </div>

          <span>Tuesday, June 16th 2026</span>
        </a>

        <a href="/posts/insights/code-matters-less-than-ever-and-more-than-ever">
          <div>
            <h3>Code matters less than ever, and more than ever</h3>
          </div>

          <span>Tuesday, June 9th 2026</span>
        </a>

        <a href="/posts/how-it-works/upsun-deployment-hooks-and-commands-which-one-to-use-and-when">
          <div>
            <h3>Upsun deployment hooks and commands: which one to use, and when</h3>
          </div>

          <span>Thursday, June 4th 2026</span>
        </a>

        <a href="/posts/ai/opencode-token-optimization">
          <div>
            <h3>How to slash OpenCode Token costs by 90% on Upsun</h3>
          </div>

          <span>Tuesday, June 2nd 2026</span>
        </a>

        <a href="/posts/tutorials/deploying-laravel-reverb-on-upsun">
          <div>
            <h3>Deploying Laravel Reverb on Upsun</h3>
          </div>

          <span>Thursday, May 21st 2026</span>
        </a>

        <a href="/posts/insights/ddev-is-in-good-hands">
          <div>
            <h3>DDEV is in good hands</h3>
          </div>

          <span>Thursday, May 21st 2026</span>
        </a>

        <a href="/posts/ai/opencode-on-upsun">
          <div>
            <h3>How to Host OpenCode on Upsun</h3>
          </div>

          <span>Tuesday, May 19th 2026</span>
        </a>

        <a href="/posts/insights/rate-limiting-rails-apps-when-you-cant-put-varnish-in-front">
          <div>
            <h3>Rate limiting Rails apps when you can't put Varnish in front</h3>
          </div>

          <span>Tuesday, May 12th 2026</span>
        </a>

        <a href="/posts/insights/the-not-so-hidden-cost-of-ai-scrapers">
          <div>
            <h3>The (not so) hidden cost of AI scrapers</h3>
          </div>

          <span>Tuesday, May 5th 2026</span>
        </a>

        <a href="/posts/how-tos/supply-chain-attacks-in-the-ai-era-and-what-to-do-about-them">
          <div>
            <h3>Supply chain attacks in the AI era, and what to do about them</h3>
          </div>

          <span>Thursday, April 30th 2026</span>
        </a>

        <a href="/posts/use-cases/n8n-upgrade-with-postgresql-and-redis">
          <div>
            <h3>Scale n8n with PostgreSQL and Redis on Upsun</h3>
          </div>

          <span>Wednesday, April 29th 2026</span>
        </a>

        <a href="/posts/ai/aiweekly-2026-04-27">
          <div>
            <h3>AI Weekly Review - Apr. 27th 2026</h3>
          </div>

          <span>Monday, April 27th 2026</span>
        </a>

        <a href="/posts/how-it-works/building-observability-from-scratch-three-times-over">
          <div>
            <h3>Building observability from scratch, three times over</h3>
          </div>

          <span>Tuesday, April 21st 2026</span>
        </a>

        <a href="/posts/how-it-works/how-we-caught-a-silent-io-storm-before-it-hit-production">
          <div>
            <h3>How we caught a silent IO storm before it hit production</h3>
          </div>

          <span>Tuesday, April 14th 2026</span>
        </a>

        <a href="/posts/ai/aiweekly-2026-04-13">
          <div>
            <h3>AI Weekly Review - Apr. 13th 2026</h3>
          </div>

          <span>Monday, April 13th 2026</span>
        </a>

        <a href="/posts/how-it-works/how-upsun-provisions-tls-certificates-at-scale">
          <div>
            <h3>How Upsun provisions TLS certificates at scale</h3>
          </div>

          <span>Thursday, April 9th 2026</span>
        </a>

        <a href="/posts/tutorials/sandboxing-ai-agents-on-upsun">
          <div>
            <h3>Sandboxing AI agents on Upsun</h3>
          </div>

          <span>Wednesday, April 8th 2026</span>
        </a>

        <a href="/posts/core-concepts/meta-upsun-validation-schema-dx-improvement">
          <div>
            <h3>How Meta-Upsun improved Validation Schema and Developer eXperience</h3>
          </div>

          <span>Tuesday, April 7th 2026</span>
        </a>

        <a href="/posts/ai/aiweekly-2026-04-07">
          <div>
            <h3>AI Weekly Review - Apr. 7th 2026</h3>
          </div>

          <span>Tuesday, April 7th 2026</span>
        </a>

        <a href="/posts/how-it-works/why-upsun-moved-from-lvm-to-ceph">
          <div>
            <h3>Why we moved from LVM to Ceph for container storage</h3>
          </div>

          <span>Thursday, April 2nd 2026</span>
        </a>

        <a href="/posts/how-tos/meta-version-updater-introduction">
          <div>
            <h3>Automating Runtime and Service Tracking with Meta Version Updater</h3>
          </div>

          <span>Wednesday, April 1st 2026</span>
        </a>

        <a href="/posts/discussions/why-ai-agents-need-cloud-sandboxes">
          <div>
            <h3>Why AI agents need cloud sandboxes</h3>
          </div>

          <span>Tuesday, March 31st 2026</span>
        </a>

        <a href="/posts/ai/aiweekly-2026-03-30">
          <div>
            <h3>AI Weekly Review - Mar. 30th 2026</h3>
          </div>

          <span>Monday, March 30th 2026</span>
        </a>

        <a href="/posts/ai/stuck-on-localhost">
          <div>
            <h3>Your agents are stuck on localhost. Upsun isn't.</h3>
          </div>

          <span>Thursday, March 26th 2026</span>
        </a>

        <a href="/posts/how-it-works/meta-reference-source-introduction">
          <div>
            <h3>Centralising Upsun Technical References with Meta-Upsun</h3>
          </div>

          <span>Wednesday, March 25th 2026</span>
        </a>

        <a href="/posts/discussions/governance-is-a-contract-chain-and-youre-in-it">
          <div>
            <h3>Governance is a contract chain, and you're in it</h3>
          </div>

          <span>Tuesday, March 24th 2026</span>
        </a>

        <a href="/posts/ai/aiweekly-2026-03-23">
          <div>
            <h3>AI Weekly Review - Mar. 23rd 2026</h3>
          </div>

          <span>Monday, March 23rd 2026</span>
        </a>

        <a href="/posts/how-it-works/rpm-repo-s3">
          <div>
            <h3>How we host an RPM repository on AWS S3</h3>
          </div>

          <span>Tuesday, March 17th 2026</span>
        </a>

        <a href="/posts/releases/introducing-developer-upsun-com">
          <div>
            <h3>Introducing developer.upsun.com: Upsun docs, rebuilt for developers and AI agents</h3>
          </div>

          <span>Monday, March 16th 2026</span>
        </a>

        <a href="/posts/ai/aiweekly-2026-03-16">
          <div>
            <h3>AI Weekly Review - Mar. 16th 2026</h3>
          </div>

          <span>Monday, March 16th 2026</span>
        </a>

        <a href="/posts/how-it-works/natural-scaling-for-multi-country-ecommerce">
          <div>
            <h3>Natural scaling for multi-country ecommerce</h3>
          </div>

          <span>Thursday, March 12th 2026</span>
        </a>

        <a href="/posts/how-tos/replicate-your-production-outage-on-staging">
          <div>
            <h3>Replicate your production outage on staging</h3>
          </div>

          <span>Tuesday, March 10th 2026</span>
        </a>

        <a href="/posts/ai/aiweekly-2026-03-09">
          <div>
            <h3>AI Weekly Review - Mar. 9th 2026</h3>
          </div>

          <span>Monday, March 9th 2026</span>
        </a>

        <a href="/posts/discussions/how-product-managers-use-preview-environments-and-ai-to-prototype">
          <div>
            <h3>How product managers use preview environments and AI to prototype</h3>
          </div>

          <span>Thursday, March 5th 2026</span>
        </a>

        <a href="/posts/hands-on/that-cron-should-be-a-worker">
          <div>
            <h3>That cron should be a worker</h3>
          </div>

          <span>Wednesday, March 4th 2026</span>
        </a>

        <a href="/posts/how-tos/fastly-cdn-and-waf">
          <div>
            <h3>Speed vs. Security? Why not both: The Fastly CDN and WAF on Upsun</h3>
          </div>

          <span>Tuesday, March 3rd 2026</span>
        </a>

        <a href="/posts/ai/aiweekly-2026-03-02">
          <div>
            <h3>AI Weekly Review - Mar. 2nd 2026</h3>
          </div>

          <span>Monday, March 2nd 2026</span>
        </a>

        <a href="/posts/tutorials/deploy-mattermost-on-upsun">
          <div>
            <h3>Deploy Mattermost Team Edition on Upsun</h3>
          </div>

          <span>Friday, February 27th 2026</span>
        </a>

        <a href="/posts/discussions/cpu-vs-gpu">
          <div>
            <h3>CPU vs GPU for AI: most AI applications don't need GPUs</h3>
          </div>

          <span>Thursday, February 26th 2026</span>
        </a>

        <a href="/posts/releases/upsun-node-sdk-announcement">
          <div>
            <h3>Announcing the Official Upsun Node.js SDK</h3>
          </div>

          <span>Wednesday, February 25th 2026</span>
        </a>

        <a href="/posts/discussions/instant-data-cloning-was-a-bet-ai-agents-are-the-payoff">
          <div>
            <h3>Instant data cloning was a bet. AI agents are the payoff.</h3>
          </div>

          <span>Tuesday, February 24th 2026</span>
        </a>

        <a href="/posts/ai/aiweekly-2026-02-23">
          <div>
            <h3>AI Weekly Review - Feb. 23th 2026</h3>
          </div>

          <span>Monday, February 23rd 2026</span>
        </a>

        <a href="/posts/ai/agents-md-less-is-more">
          <div>
            <h3>The research is in: your AGENTS.md is probably too long</h3>
          </div>

          <span>Monday, February 23rd 2026</span>
        </a>

        <a href="/posts/discussions/building-an-ai-code-review-agent-for-gitlab">
          <div>
            <h3>Building an AI code review agent for our self-hosted GitLab</h3>
          </div>

          <span>Thursday, February 19th 2026</span>
        </a>

        <a href="/posts/how-it-works/your-waf-is-buffering-ours-is-streaming">
          <div>
            <h3>Your WAF is buffering. Ours is streaming.</h3>
          </div>

          <span>Wednesday, February 18th 2026</span>
        </a>

        <a href="/posts/ai/aiweekly-2026-02-17">
          <div>
            <h3>AI Weekly Review - Feb. 17th 2026</h3>
          </div>

          <span>Tuesday, February 17th 2026</span>
        </a>

        <a href="/posts/ai/making-coding-agents-reliable">
          <div>
            <h3>Making coding agents (Claude Code, Codex, etc.) reliable</h3>
          </div>

          <span>Tuesday, February 17th 2026</span>
        </a>

        <a href="/posts/hands-on/the-real-story-of-setting-up-drupal-canvas-with-ai">
          <div>
            <h3>From DrupalCon keynote to live Upsun demo: the real story of setting up Drupal Canvas with AI</h3>
          </div>

          <span>Friday, February 13th 2026</span>
        </a>

        <a href="/posts/ai/git-worktrees-for-parallel-ai-coding-agents">
          <div>
            <h3>Git worktrees for parallel AI coding agents</h3>
          </div>

          <span>Wednesday, February 11th 2026</span>
        </a>

        <a href="/posts/hands-on/scriberr-on-upsun">
          <div>
            <h3>Scriberr on Upsun</h3>
          </div>

          <span>Tuesday, February 10th 2026</span>
        </a>

        <a href="/posts/hands-on/unstable-website-use-queues">
          <div>
            <h3>Unstable website? Use queues.</h3>
          </div>

          <span>Thursday, February 5th 2026</span>
        </a>

        <a href="/posts/core-concepts/eliminating-database-pwd-risk-with-network-isolation">
          <div>
            <h3>Eliminating Database Password Risk with Network Isolation</h3>
          </div>

          <span>Wednesday, February 4th 2026</span>
        </a>

        <a href="/posts/insights/the-only-correct-way-to-git-pull-and-merge">
          <div>
            <h3>The only correct way to git pull and merge</h3>
          </div>

          <span>Tuesday, February 3rd 2026</span>
        </a>

        <a href="/posts/ai/will-ai-make-software-companies-worthless">
          <div>
            <h3>Will AI make software companies worthless?</h3>
          </div>

          <span>Friday, January 30th 2026</span>
        </a>

        <a href="/posts/how-it-works/spf-dkim-dmarc-what-are-those-for-anyway">
          <div>
            <h3>SPF, DKIM, DMARC, what are those for anyway?</h3>
          </div>

          <span>Thursday, January 29th 2026</span>
        </a>

        <a href="/posts/insights/the-third-way-to-scale-that-nobody-talks-about">
          <div>
            <h3>The third way to scale that nobody talks about</h3>
          </div>

          <span>Tuesday, January 20th 2026</span>
        </a>

        <a href="/posts/hands-on/how-to-use-harlequin-sql-ide-with-upsun">
          <div>
            <h3>How to Use Harlequin SQL IDE with Upsun</h3>
          </div>

          <span>Wednesday, January 14th 2026</span>
        </a>

        <a href="/posts/how-it-works/how-weve-been-hardening-containers-since-before-docker-made-it-cool">
          <div>
            <h3>How we've been hardening containers since before Docker made it cool</h3>
          </div>

          <span>Tuesday, January 13th 2026</span>
        </a>

        <a href="/posts/how-tos/automated-encrypt-backups-amazon-s3">
          <div>
            <h3>Automated encrypted backups to Amazon S3 | Upsun</h3>
          </div>

          <span>Monday, January 12th 2026</span>
        </a>

        <a href="/posts/discussions/the-universal-commerce-protocol-and-the-inevitable-rise-of-agentic-commerce">
          <div>
            <h3>The universal commerce protocol and the inevitable rise of agentic commerce</h3>
          </div>

          <span>Monday, January 12th 2026</span>
        </a>

        <a href="/posts/hands-on/stop-testing-jcr-apps-in-production">
          <div>
            <h3>Stop testing JCR apps in production</h3>
          </div>

          <span>Tuesday, January 6th 2026</span>
        </a>

        <a href="/posts/releases/composer-2.9">
          <div>
            <h3>Composer 2.9 lands on Upsun PHP Images: Here’s what you need to know</h3>
          </div>

          <span>Thursday, December 25th 2025</span>
        </a>

        <a href="/posts/hands-on/civicrm-drupal-11-on-upsun">
          <div>
            <h3>Installing CiviCRM with Drupal 11 on Upsun</h3>
          </div>

          <span>Friday, December 19th 2025</span>
        </a>

        <a href="/posts/discussions/whatsun-efficient-code-analysis">
          <div>
            <h3>Efficient code analysis for LLMs</h3>
          </div>

          <span>Thursday, December 18th 2025</span>
        </a>

        <a href="/posts/unknown/how-we-scaled-live-connections-for-1200-developers-at-symfonycon">
          <div>
            <h3>How we scaled live connections for 1200 developers at SymfonyCon</h3>
          </div>

          <span>Wednesday, December 17th 2025</span>
        </a>

        <a href="/posts/hands-on/migration-day-executing-your-upsun-cutover">
          <div>
            <h3>Migration day: executing your Upsun cutover</h3>
          </div>

          <span>Tuesday, December 16th 2025</span>
        </a>

        <a href="/posts/releases/composable-image-embraces-real-world-diversity">
          <div>
            <h3>One project, many needs: How Composable Image embraces real-world diversity</h3>
          </div>

          <span>Thursday, December 11th 2025</span>
        </a>

        <a href="/posts/how-it-works/keeping-the-peace-how-zookeeper-stops-database-nodes-from-fighting">
          <div>
            <h3>Keeping the peace: how ZooKeeper stops database nodes from fighting</h3>
          </div>

          <span>Tuesday, December 9th 2025</span>
        </a>

        <a href="/posts/insights/why-you-cant-just-add-infinite-php-fpm-workers">
          <div>
            <h3>Why you can't just add infinite PHP-FPM workers</h3>
          </div>

          <span>Monday, December 8th 2025</span>
        </a>

        <a href="/posts/discussions/building-ai-feature-necessary-evals">
          <div>
            <h3>Building an AI feature: The necessary evals</h3>
          </div>

          <span>Thursday, December 4th 2025</span>
        </a>

        <a href="/posts/discussions/nextjs-cve-2025-66478">
          <div>
            <h3>Critical Next.js Security Update: CVE-2025-66478 Affects RSC</h3>
          </div>

          <span>Thursday, December 4th 2025</span>
        </a>

        <a href="/posts/hands-on/zero-downtime-deployments-with-upsun">
          <div>
            <h3>Zero-downtime deployments: now in open beta</h3>
          </div>

          <span>Wednesday, December 3rd 2025</span>
        </a>

        <a href="/posts/tutorials/angular-and-upsun">
          <div>
            <h3>Building and Deploying Angular Apps on Upsun</h3>
          </div>

          <span>Wednesday, December 3rd 2025</span>
        </a>

        <a href="/posts/how-tos/planning-your-upsun-migration-the-6-9-week-roadmap">
          <div>
            <h3>Planning your Upsun migration: the 6-9 week roadmap</h3>
          </div>

          <span>Tuesday, December 2nd 2025</span>
        </a>

        <a href="/posts/insights/why-setting-your-php-memory-limit-to-60gb-wont-help">
          <div>
            <h3>Why setting your PHP memory limit to 60GB won't help</h3>
          </div>

          <span>Monday, December 1st 2025</span>
        </a>

        <a href="/posts/hands-on/ai-use-case-generate-load-test-scenarios">
          <div>
            <h3>AI use-case: Generate load test scenarios with MCPs</h3>
          </div>

          <span>Thursday, November 27th 2025</span>
        </a>

        <a href="/posts/insights/my-terminal-setup-mac-linux">
          <div>
            <h3>My terminal setup (Mac & Linux)</h3>
          </div>

          <span>Wednesday, November 26th 2025</span>
        </a>

        <a href="/posts/how-it-works/when-php-fpm-runs-out-of-workers-a-502-error-field-guide">
          <div>
            <h3>When php-fpm runs out of workers: a 502 error field guide</h3>
          </div>

          <span>Monday, November 24th 2025</span>
        </a>

        <a href="/posts/releases/php-85-release">
          <div>
            <h3>PHP 8.5 is here!</h3>
          </div>

          <span>Thursday, November 20th 2025</span>
        </a>

        <a href="/posts/how-it-works/we-switched-from-lvm-to-sparse-files">
          <div>
            <h3>We switched from LVM to... sparse files?!</h3>
          </div>

          <span>Friday, November 14th 2025</span>
        </a>

        <a href="/posts/how-tos/creating-custom-reports-using-cli">
          <div>
            <h3>Creating Custom Reports using the Upsun Cloud CLI</h3>
          </div>

          <span>Wednesday, November 12th 2025</span>
        </a>

        <a href="/posts/insights/the-mystery-of-the-shrinking-database-dump">
          <div>
            <h3>The mystery of the shrinking database dump</h3>
          </div>

          <span>Monday, November 10th 2025</span>
        </a>

        <a href="/posts/hands-on/varnish-104-advanced-traffic-filtering-with-classification-headers-on-upsun">
          <div>
            <h3>Varnish 104: Advanced Traffic Filtering with Classification Headers on Upsun</h3>
          </div>

          <span>Friday, November 7th 2025</span>
        </a>

        <a href="/posts/releases/upsun-php-sdk-announcement">
          <div>
            <h3>Introducing the Upsun PHP SDK</h3>
          </div>

          <span>Tuesday, November 4th 2025</span>
        </a>

        <a href="/posts/how-it-works/we-made-our-infrastructure-read-only-and-never-looked-back">
          <div>
            <h3>We made our infrastructure read-only and never looked back</h3>
          </div>

          <span>Monday, November 3rd 2025</span>
        </a>

        <a href="/posts/hands-on/varnish-103-cache-optimization-with-url-normalization-on-upsun">
          <div>
            <h3>Varnish 103: Cache Optimization with URL Normalization on Upsun</h3>
          </div>

          <span>Friday, October 31st 2025</span>
        </a>

        <a href="/posts/hands-on/varnish-102-protecting-your-application-with-rate-limiting-on-upsun">
          <div>
            <h3>Varnish 102: Protecting Your Application with Rate Limiting on Upsun</h3>
          </div>

          <span>Friday, October 24th 2025</span>
        </a>

        <a href="/posts/how-it-works/event-loop-monitoring-in-nextjs-performance-guide">
          <div>
            <h3>Event Loop Monitoring in Next.js: Performance Guide</h3>
          </div>

          <span>Friday, October 24th 2025</span>
        </a>

        <a href="/posts/how-it-works/autoscaling-deep-dive">
          <div>
            <h3>Auto-scaling on Upsun Flex. A deep dive.</h3>
          </div>

          <span>Monday, October 20th 2025</span>
        </a>

        <a href="/posts/hands-on/varnish-101-protecting-paths-with-http-basic-authentication-on-upsun">
          <div>
            <h3>Varnish 101: Protecting Paths with HTTP Basic Authentication on Upsun</h3>
          </div>

          <span>Friday, October 17th 2025</span>
        </a>

        <a href="/posts/how-it-works/fake-ip-till-you-make-ip">
          <div>
            <h3>Fake IP till you make IP</h3>
          </div>

          <span>Tuesday, October 14th 2025</span>
        </a>

        <a href="/posts/how-tos/fastlycdn-pluginapp-activation">
          <div>
            <h3>Streamline Your CDN Management with Fastly CDN Plugin App \[BETA]</h3>
          </div>

          <span>Tuesday, October 7th 2025</span>
        </a>

        <a href="/posts/tutorials/deploying-open-source-on-upsun">
          <div>
            <h3>Deploying open-source projects on Upsun: Snipe-IT as an example</h3>
          </div>

          <span>Tuesday, October 7th 2025</span>
        </a>

        <a href="/posts/insights/build-time-environment-variables-considered-harmful">
          <div>
            <h3>Build-time environment variables considered harmful</h3>
          </div>

          <span>Monday, October 6th 2025</span>
        </a>

        <a href="/posts/how-it-works/explore-plan-execute-methodology">
          <div>
            <h3>Mastering the Explore, Plan, Execute methodology for AI-assisted development</h3>
          </div>

          <span>Friday, October 3rd 2025</span>
        </a>

        <a href="/posts/tutorials/building-async-processing-pipelines-with-fastapi-and-celery-on-upsun">
          <div>
            <h3>Building async processing pipelines with FastAPI and Celery on Upsun</h3>
          </div>

          <span>Friday, October 3rd 2025</span>
        </a>

        <a href="/posts/hands-on/building-internal-ai-agents-for-our-teams-on-upsun">
          <div>
            <h3>Building internal AI agents for our teams on Upsun</h3>
          </div>

          <span>Tuesday, September 30th 2025</span>
        </a>

        <a href="/posts/ai/upsun-mcp-announcement">
          <div>
            <h3>Introducing the Upsun MCP server: bring Upsun into your LLMs</h3>
          </div>

          <span>Monday, September 22nd 2025</span>
        </a>

        <a href="/posts/insights/why-you-should-replace-postgresql-with-git-for-your-next-project">
          <div>
            <h3>Why you should replace PostgreSQL with Git for your next project</h3>
          </div>

          <span>Friday, September 19th 2025</span>
        </a>

        <a href="/posts/hands-on/run-tailscale-on-upsun-secure-vpn-connections">
          <div>
            <h3>Run Tailscale on Upsun: Create secure VPN connections for your applications</h3>
          </div>

          <span>Tuesday, September 16th 2025</span>
        </a>

        <a href="/posts/how-tos/composer1-rip">
          <div>
            <h3>Composer 1 is dead – Upgrade to Composer 2 now</h3>
          </div>

          <span>Tuesday, September 9th 2025</span>
        </a>

        <a href="/posts/how-it-works/cut-aws-bandwidth-costs-95-with-dm-cache">
          <div>
            <h3>How we cut AWS bandwidth costs 95% with dm-cache: fast local SSD caching for network storage</h3>
          </div>

          <span>Tuesday, September 9th 2025</span>
        </a>

        <a href="/posts/hands-on/store-embeddings-in-chroma-with-persistent-storage-nodejs-and-python-examples">
          <div>
            <h3>Store embeddings in chroma with persistent storage (nodejs and python examples)</h3>
          </div>

          <span>Wednesday, September 3rd 2025</span>
        </a>

        <a href="/posts/hands-on/fastly-maintenance">
          <div>
            <h3>How to enable custom maintenance page in Fastly</h3>
          </div>

          <span>Monday, August 25th 2025</span>
        </a>

        <a href="/posts/how-it-works/how-do-we-do-incremental-but-really-full-backups-on-top-of-ceph">
          <div>
            <h3>High-performance backups: How Ceph snapshots enable incremental full backups</h3>
          </div>

          <span>Monday, August 25th 2025</span>
        </a>

        <a href="/posts/hands-on/connect-multiple-projects-applications-or-services-together">
          <div>
            <h3>Connect multiple projects applications or services together</h3>
          </div>

          <span>Friday, August 15th 2025</span>
        </a>

        <a href="/posts/insights/why-your-readme-matters-more-than-ai-configuration-files">
          <div>
            <h3>AGENTS.md: Why your README matters more than AI configuration files</h3>
          </div>

          <span>Tuesday, August 12th 2025</span>
        </a>

        <a href="/posts/insights/why-python-developers-should-switch-to-uv">
          <div>
            <h3>Why Python developers should switch to uv</h3>
          </div>

          <span>Thursday, August 7th 2025</span>
        </a>

        <a href="/posts/how-it-works/how-upsun-built-stateless-mesh-networking-for-high-density-containers">
          <div>
            <h3>How Upsun built stateless mesh networking for high-density containers</h3>
          </div>

          <span>Wednesday, August 6th 2025</span>
        </a>

        <a href="/posts/unknown/platformsh-un-global-compact-sdgs-2025">
          <div>
            <h3>Platform.sh reaffirms commitment to the UN Global Compact and the SDGs</h3>
          </div>

          <span>Wednesday, July 30th 2025</span>
        </a>

        <a href="/posts/hands-on/gitlab-push-solution">
          <div>
            <h3>Synchronize your air-gapped GitLab with Upsun</h3>
          </div>

          <span>Monday, July 21st 2025</span>
        </a>

        <a href="/posts/unknown/new-improvement-global-settings-in-console">
          <div>
            <h3>New improvement: global settings in console</h3>
          </div>

          <span>Wednesday, July 9th 2025</span>
        </a>

        <a href="/posts/use-cases/n8n-saved-my-life">
          <div>
            <h3>How n8n saved our Advocacy impact on Social Media!</h3>
          </div>

          <span>Thursday, July 3rd 2025</span>
        </a>

        <a href="/posts/insights/why-configuration-as-code-beats-click-and-deploy">
          <div>
            <h3>Git-Driven Infrastructure: Why Configuration as Code Beats Click-and-Deploy</h3>
          </div>

          <span>Thursday, June 12th 2025</span>
        </a>

        <a href="/posts/how-it-works/mcp-interaction-types-article">
          <div>
            <h3>Beyond Tool Calling: Understanding MCP's Three Core Interaction Types</h3>
          </div>

          <span>Saturday, June 7th 2025</span>
        </a>

        <a href="/posts/hands-on/deploy-mcp-servers-on-upsun">
          <div>
            <h3>Build and deploy AI-Native Applications with MCP Servers on Upsun</h3>
          </div>

          <span>Thursday, June 5th 2025</span>
        </a>

        <a href="/posts/releases/redis-release">
          <div>
            <h3>Redis 8.0 is here</h3>
          </div>

          <span>Wednesday, June 4th 2025</span>
        </a>

        <a href="/posts/how-tos/handling-well-known-directory">
          <div>
            <h3>How to manage the `.well-known` directory on Upsun and Platform.sh</h3>
          </div>

          <span>Monday, May 26th 2025</span>
        </a>

        <a href="/posts/hands-on/nocode-n8n">
          <div>
            <h3>NoCode with Upsun: Supercharge Your Automation with Zero Code</h3>
          </div>

          <span>Wednesday, May 14th 2025</span>
        </a>

        <a href="/posts/insights/advanced-prompting-techniques-for-coding">
          <div>
            <h3>Advanced prompting techniques for complex coding tasks</h3>
          </div>

          <span>Thursday, May 8th 2025</span>
        </a>

        <a href="/posts/releases/file_size_limit">
          <div>
            <h3>New file size limits explained</h3>
          </div>

          <span>Wednesday, May 7th 2025</span>
        </a>

        <a href="/posts/releases/vscode-extension">
          <div>
            <h3>Supercharge your workflow with the Upsun VSCode Extension</h3>
          </div>

          <span>Tuesday, May 6th 2025</span>
        </a>

        <a href="/posts/how-tos/validate-yaml-config">
          <div>
            <h3>Making .upsun/config.yaml easier to edit with IDE autocomplete and validation</h3>
          </div>

          <span>Tuesday, May 6th 2025</span>
        </a>

        <a href="/posts/hands-on/pytorch-running-on-upsun">
          <div>
            <h3>How to run PyTorch in an Upsun application?</h3>
          </div>

          <span>Thursday, May 1st 2025</span>
        </a>

        <a href="/posts/how-tos/context7-mcp">
          <div>
            <h3>Upsun documentation is now available via the Context7 MCP</h3>
          </div>

          <span>Thursday, May 1st 2025</span>
        </a>

        <a href="/posts/hands-on/postgres-mcp-on-upsun">
          <div>
            <h3>Using PostgreSQL MCP with Upsun Remote Database</h3>
          </div>

          <span>Wednesday, April 30th 2025</span>
        </a>

        <a href="/posts/hands-on/route-ids-env">
          <div>
            <h3>How to automatically inject multi-app endpoints as environment variables</h3>
          </div>

          <span>Monday, April 28th 2025</span>
        </a>

        <a href="/posts/tutorials/oauth-nextjs-laravel">
          <div>
            <h3>OAuth authentication between Next.js and Laravel Passport</h3>
          </div>

          <span>Monday, April 28th 2025</span>
        </a>

        <a href="/posts/tutorials/deploying-clamav-service">
          <div>
            <h3>Deploy ClamAV on Upsun, on service mode.</h3>
          </div>

          <span>Thursday, April 24th 2025</span>
        </a>

        <a href="/posts/releases/valkey-release">
          <div>
            <h3>Valkey is now available</h3>
          </div>

          <span>Wednesday, April 16th 2025</span>
        </a>

        <a href="/posts/hands-on/install-gh-asset-on-upsun">
          <div>
            <h3>Up(sun) and ready with GitHub release assets installation</h3>
          </div>

          <span>Thursday, April 10th 2025</span>
        </a>

        <a href="/posts/unknown/nextjs-cve-2025-2997">
          <div>
            <h3>Next.js Security Vulnerability (CVE-2025-29927): What Upsun Users Need to Know</h3>
          </div>

          <span>Tuesday, March 25th 2025</span>
        </a>

        <a href="/posts/tutorials/sfcon2024-decouple-frontend">
          <div>
            <h3>Decouple your Symfony frontend using Next.js</h3>
          </div>

          <span>Monday, March 24th 2025</span>
        </a>

        <a href="/posts/tutorials/deploying-with-lisp">
          <div>
            <h3>Up(sun) and running with Lisp</h3>
          </div>

          <span>Monday, March 17th 2025</span>
        </a>

        <a href="/posts/tutorials/deploying-twill-on-upsun">
          <div>
            <h3>Up(sun) and Running with Twill</h3>
          </div>

          <span>Wednesday, March 12th 2025</span>
        </a>

        <a href="/posts/releases/elixir-118-release-available">
          <div>
            <h3>Apologies to the Elixir community: 1.18 release now available</h3>
          </div>

          <span>Wednesday, February 26th 2025</span>
        </a>

        <a href="/posts/tutorials/deploying-clamav-onetime">
          <div>
            <h3>Deploy ClamAV on Upsun, on one-time scan</h3>
          </div>

          <span>Friday, February 14th 2025</span>
        </a>

        <a href="/posts/releases/llms-introduction">
          <div>
            <h3>Upsun and Platform.sh Docs are now llms.txt compatible!</h3>
          </div>

          <span>Friday, February 14th 2025</span>
        </a>

        <a href="/posts/how-tos/install-pandoc-on-upsun">
          <div>
            <h3>Up(sun) and ready with Pandoc</h3>
          </div>

          <span>Wednesday, February 12th 2025</span>
        </a>

        <a href="/posts/unknown/magento-performance-optimization">
          <div>
            <h3>Magento performance optimization–Actionable tips and strategies</h3>
          </div>

          <span>Tuesday, February 4th 2025</span>
        </a>

        <a href="/posts/how-it-works/debian-repo-s3">
          <div>
            <h3>How we host a Debian repository on AWS S3</h3>
          </div>

          <span>Wednesday, January 29th 2025</span>
        </a>

        <a href="/posts/tutorials/upsun-and-running-forem">
          <div>
            <h3>Up(sun) and Running with Forem</h3>
          </div>

          <span>Friday, January 24th 2025</span>
        </a>

        <a href="/posts/tutorials/drupal-and-upsun">
          <div>
            <h3>Drupal and Upsun</h3>
          </div>

          <span>Thursday, January 16th 2025</span>
        </a>

        <a href="/posts/hands-on/deploying-chainlit-with-rag">
          <div>
            <h3>Experiment with Chainlit AI interface with RAG on Upsun</h3>
          </div>

          <span>Tuesday, January 14th 2025</span>
        </a>

        <a href="/posts/how-tos/no-downtime-postgres-updates">
          <div>
            <h3>How to update your PostgreSQL database without downtime</h3>
          </div>

          <span>Thursday, January 9th 2025</span>
        </a>

        <a href="/posts/discussions/triage-bot">
          <div>
            <h3>How did we migrate issues from GitLab to Linear?</h3>
          </div>

          <span>Wednesday, December 18th 2024</span>
        </a>

        <a href="/posts/discussions/go-124">
          <div>
            <h3>Golang 1.24 is looking seriously awesome</h3>
          </div>

          <span>Sunday, December 15th 2024</span>
        </a>

        <a href="/posts/discussions/cve-2024-45337">
          <div>
            <h3>CVE-2024-45337</h3>
          </div>

          <span>Friday, December 13th 2024</span>
        </a>

        <a href="/posts/unknown/uncovered-and-patched-golang-vunerability">
          <div>
            <h3>Security vulnerability uncovered and patched in the golang.org/x/crypto /ssh package</h3>
          </div>

          <span>Friday, December 13th 2024</span>
        </a>

        <a href="/posts/releases/php-84-release">
          <div>
            <h3>PHP 8.4 is here!</h3>
          </div>

          <span>Tuesday, November 26th 2024</span>
        </a>

        <a href="/posts/tutorials/laravel-rest-api-on-upsun">
          <div>
            <h3>Creating and deploying a Laravel REST API on Upsun in 10 minutes</h3>
          </div>

          <span>Friday, November 15th 2024</span>
        </a>

        <a href="/posts/how-tos/blackfire-google-alert-markers-interfaces">
          <div>
            <h3>Import multiple RSS Feeds on your Blackfire timeline + extra interfaces</h3>
          </div>

          <span>Tuesday, November 5th 2024</span>
        </a>

        <a href="/posts/unknown/human-impact-of-adopting-platformsh">
          <div>
            <h3>A tale of people: the human impact of adopting Platform.sh</h3>
          </div>

          <span>Tuesday, October 29th 2024</span>
        </a>

        <a href="/posts/how-tos/schedule-resource-availability">
          <div>
            <h3>Scheduling resources</h3>
          </div>

          <span>Thursday, October 24th 2024</span>
        </a>

        <a href="/posts/releases/continuous-profiling-comparisons">
          <div>
            <h3>Continuous profiling comparisons</h3>
          </div>

          <span>Wednesday, October 23rd 2024</span>
        </a>

        <a href="/posts/tutorials/rails8-upsun-tutorial">
          <div>
            <h3>Deploy your first Rails 8 application on Upsun</h3>
          </div>

          <span>Wednesday, October 23rd 2024</span>
        </a>

        <a href="/posts/how-tos/configuring-an-autoscaler">
          <div>
            <h3>Adding an autoscaler to Upsun projects</h3>
          </div>

          <span>Saturday, October 19th 2024</span>
        </a>

        <a href="/posts/how-tos/blackfire-google-alert-markers">
          <div>
            <h3>Add context on your Blackfire timeline from a Google Alerts RSS Feed</h3>
          </div>

          <span>Monday, October 7th 2024</span>
        </a>

        <a href="/posts/releases/context-driven-navigation">
          <div>
            <h3>Context driven navigation</h3>
          </div>

          <span>Thursday, October 3rd 2024</span>
        </a>

        <a href="/posts/discussions/understanding-cors">
          <div>
            <h3>Understanding Cross-Origin Resource Sharing (CORS)</h3>
          </div>

          <span>Monday, September 30th 2024</span>
        </a>

        <a href="/posts/unknown/evolve-partner-summit-awards">
          <div>
            <h3>It's almost time…Platform.sh’s Evolve Partner Summit Awards</h3>
          </div>

          <span>Monday, September 23rd 2024</span>
        </a>

        <a href="/posts/how-tos/automate-with-gatling-1">
          <div>
            <h3>How to automate load tests with Gatling</h3>
          </div>

          <span>Friday, September 20th 2024</span>
        </a>

        <a href="/posts/how-it-works/using-the-upsun-api">
          <div>
            <h3>Using the Upsun API</h3>
          </div>

          <span>Thursday, September 19th 2024</span>
        </a>

        <a href="/posts/discussions/preview-environments-a-developers-secret-weapon">
          <div>
            <h3>Preview Environments</h3>
          </div>

          <span>Thursday, September 19th 2024</span>
        </a>

        <a href="/posts/releases/introducing-dev-center">
          <div>
            <h3>Introducing the Upsun Developer Center</h3>
          </div>

          <span>Wednesday, September 18th 2024</span>
        </a>

        <a href="/posts/tutorials/how-to-host-multiple-applications">
          <div>
            <h3>How to host a multiple-application project on Platform.sh</h3>
          </div>

          <span>Friday, August 16th 2024</span>
        </a>

        <a href="/posts/hands-on/harnessing-power-embeddings">
          <div>
            <h3>Harnessing the power of Embeddings: a real-world example of a watch recommendation app using a vector database.</h3>
          </div>

          <span>Monday, May 20th 2024</span>
        </a>

        <a href="/posts/use-cases/wordpress-performance-optimization-with-blackfire">
          <div>
            <h3>Meeting Jonny Harris: WordPress performance optimization with Blackfire</h3>
          </div>

          <span>Tuesday, April 16th 2024</span>
        </a>

        <a href="/posts/hands-on/guide-to-limit-deployments-to-platformsh-only-with-tags-part-three">
          <div>
            <h3>Limit deployments to Platform.sh only with tags: part three</h3>
          </div>

          <span>Friday, April 12th 2024</span>
        </a>

        <a href="/posts/unknown/drupal-camp-florida-2024">
          <div>
            <h3>DrupalCamp Florida 2024: sharing takeaways from the experts</h3>
          </div>

          <span>Monday, March 25th 2024</span>
        </a>

        <a href="/posts/hands-on/guide-to-limit-deployments-to-platformsh-only-with-tags-part-one">
          <div>
            <h3>Limit deployments to Platform.sh only with tags: part one</h3>
          </div>

          <span>Thursday, March 14th 2024</span>
        </a>

        <a href="/posts/hands-on/guide-to-limit-deployments-to-platformsh-only-with-tags-part-two">
          <div>
            <h3>Limit deployments to Platform.sh only when Git tagged: part two</h3>
          </div>

          <span>Thursday, March 14th 2024</span>
        </a>

        <a href="/posts/tutorials/deploying-remixjs-app-on-upsun">
          <div>
            <h3>Deploying a Remix JS app on Upsun in 5 minutes</h3>
          </div>

          <span>Friday, March 1st 2024</span>
        </a>

        <a href="/posts/tutorials/deploying-laravel-with-horizon-on-upsun">
          <div>
            <h3>Deploying Laravel with Horizon on Upsun</h3>
          </div>

          <span>Wednesday, February 28th 2024</span>
        </a>

        <a href="/posts/unknown/whats-the-deal-with-eu-headquartered-iaas-providers">
          <div>
            <h3>International data protection with EU-entities of US-headquartered IaaS providers</h3>
          </div>

          <span>Monday, November 13th 2023</span>
        </a>

        <a href="/posts/unknown/building-a-trust-centric-culture-for-success">
          <div>
            <h3>Building a trust-centric culture for success</h3>
          </div>

          <span>Wednesday, November 8th 2023</span>
        </a>

        <a href="/posts/how-it-works/how-platformsh-stays-ahead-of-emerging-cybersecurity-threats">
          <div>
            <h3>Semper vigilans: how Platform.sh stays ahead of emerging cybersecurity threats (so you don’t have to)</h3>
          </div>

          <span>Friday, October 13th 2023</span>
        </a>

        <a href="/posts/releases/bun-support-is-here">
          <div>
            <h3>It's out of the Oven: Bun 1.0 support on Platform.sh</h3>
          </div>

          <span>Friday, September 8th 2023</span>
        </a>

        <a href="/posts/how-tos/help-reduce-resource-consumption-put-your-preview-environments-on-pause">
          <div>
            <h3>Help reduce resource consumption: Put your preview environments on pause</h3>
          </div>

          <span>Friday, August 18th 2023</span>
        </a>

        <a href="/posts/unknown/an-update-to-our-events-privacy-policy">
          <div>
            <h3>An update to our events privacy policy</h3>
          </div>

          <span>Wednesday, May 31st 2023</span>
        </a>

        <a href="/posts/unknown/greater-organization-insights-through-weekly-activity-reports-emails">
          <div>
            <h3>Greater organization insights through weekly activity reports emails</h3>
          </div>

          <span>Monday, April 10th 2023</span>
        </a>

        <a href="/posts/unknown/infrastructure-metrics-expanded-to-longer-time-frames">
          <div>
            <h3>Infrastructure Monitoring Metrics with Longer Time Frames</h3>
          </div>

          <span>Wednesday, February 1st 2023</span>
        </a>

        <a href="/posts/unknown/its-time-for-version--all-new-upgrades-for-our-api-server">
          <div>
            <h3>Introducing version 19: New upgrades for our API server</h3>
          </div>

          <span>Thursday, January 26th 2023</span>
        </a>

        <a href="/posts/releases/platformsh-is-always-one-step-ahead-announcing-postgresql--python--and-ruby--for-our-users">
          <div>
            <h3>Platform.sh is always one step ahead: Announcing PostgreSQL 15, Python 3.11, and Ruby 3.2 for our users</h3>
          </div>

          <span>Monday, January 16th 2023</span>
        </a>

        <a href="/posts/hands-on/powerup-your-local-development-with-ddev">
          <div>
            <h3>Power-up Your Local Development with DDEV</h3>
          </div>

          <span>Thursday, January 5th 2023</span>
        </a>

        <a href="/posts/unknown/introducing-our-new-api-and-metrics-servers-upgrades">
          <div>
            <h3>Introducing our new API and Metrics servers upgrades</h3>
          </div>

          <span>Thursday, December 15th 2022</span>
        </a>

        <a href="/posts/unknown/dont-be-held-to-ransom-security-awareness-with-platformsh">
          <div>
            <h3>Don’t be held to ransom: Security awareness with Platform.sh</h3>
          </div>

          <span>Friday, December 2nd 2022</span>
        </a>

        <a href="/posts/unknown/are-your-websites-ready-to-handle-traffic-peaks-this-holiday-season">
          <div>
            <h3>Are your websites ready to handle traffic peaks this holiday season?</h3>
          </div>

          <span>Monday, November 28th 2022</span>
        </a>

        <a href="/posts/unknown/the-platformsh-cli-is-ready-to-golang">
          <div>
            <h3>The Platform.sh CLI is ready to Go(lang)</h3>
          </div>

          <span>Thursday, November 17th 2022</span>
        </a>

        <a href="/posts/releases/introducing-a-more-complete-logs-forwarding-experience">
          <div>
            <h3>Introducing a more complete logs forwarding experience</h3>
          </div>

          <span>Friday, November 4th 2022</span>
        </a>

        <a href="/posts/unknown/platformsh-partners-with-mongodb-to-help-customers-build-modern-applications-faster">
          <div>
            <h3>Platform.sh partners with MongoDB to help customers build modern applications faster</h3>
          </div>

          <span>Thursday, October 6th 2022</span>
        </a>

        <a href="/posts/unknown/mohammed-ajmal-siddiqui">
          <div>
            <h3>Platform.sh | Journeys Mohammed Ajmal Siddiqui</h3>
          </div>

          <span>Friday, September 16th 2022</span>
        </a>

        <a href="/posts/unknown/weve-made-changes-to-our-dpa-to-clarify-platformsh-role-under-the-gdpr">
          <div>
            <h3>We’ve made changes to our DPA to clarify Platform.sh role under the GDPR</h3>
          </div>

          <span>Thursday, September 1st 2022</span>
        </a>

        <a href="/posts/unknown/were-updating-our-privacy-policy-to-include-event-accommodations">
          <div>
            <h3>We’re updating our privacy policy to include event accommodations</h3>
          </div>

          <span>Friday, August 19th 2022</span>
        </a>

        <a href="/posts/unknown/pandemic-caused-spike-in-cybercrime">
          <div>
            <h3>The pandemic has indeed caused a massive spike in cybercrime</h3>
          </div>

          <span>Thursday, May 26th 2022</span>
        </a>

        <a href="/posts/unknown/infrastructure-metrics-for-all-professional-projects">
          <div>
            <h3>Infrastructure Metrics available for all Professional projects</h3>
          </div>

          <span>Tuesday, May 3rd 2022</span>
        </a>

        <a href="/posts/unknown/greener-hosting-starts-with-transparency">
          <div>
            <h3>Greener hosting starts with transparency</h3>
          </div>

          <span>Friday, April 22nd 2022</span>
        </a>

        <a href="/posts/unknown/automated-code-updates">
          <div>
            <h3>Automated code updates</h3>
          </div>

          <span>Friday, April 15th 2022</span>
        </a>

        <a href="/posts/unknown/split-projects-and-users-across-organizations">
          <div>
            <h3>Split projects and users across multiple organizations</h3>
          </div>

          <span>Friday, April 15th 2022</span>
        </a>

        <a href="/posts/unknown/go-1-18-released-on-platformsh">
          <div>
            <h3>Go 1.18 released on Platform.sh</h3>
          </div>

          <span>Wednesday, March 16th 2022</span>
        </a>

        <a href="/posts/unknown/privacy-policy-updates">
          <div>
            <h3>Privacy Policy updates and subprocessors list change</h3>
          </div>

          <span>Wednesday, February 16th 2022</span>
        </a>

        <a href="/posts/unknown/platformsh-announces-microsoft-azure-support-australian-market">
          <div>
            <h3>Announcing Microsoft Azure Support for Australia</h3>
          </div>

          <span>Friday, January 28th 2022</span>
        </a>

        <a href="/posts/unknown/managing-multiple-website">
          <div>
            <h3>The secret to managing multiple websites</h3>
          </div>

          <span>Thursday, January 27th 2022</span>
        </a>

        <a href="/posts/how-tos/measuring-the-success-of-a-deployment-with-githubactions">
          <div>
            <h3>Measuring Deployment Success with GitHub Actions</h3>
          </div>

          <span>Thursday, December 23rd 2021</span>
        </a>

        <a href="/posts/unknown/share-your-activities-with-robots-surfacing-activities-with-github-actions">
          <div>
            <h3>Surfacing activities with GitHub actions</h3>
          </div>

          <span>Wednesday, December 22nd 2021</span>
        </a>

        <a href="/posts/unknown/share-your-failures-fix-them-faster">
          <div>
            <h3>Share and fix failures faster with shareable activities</h3>
          </div>

          <span>Wednesday, December 8th 2021</span>
        </a>

        <a href="/posts/unknown/overview-video">
          <div>
            <h3>New Platform.sh overview video: a proven, 5-step approach helps explain a complex concept</h3>
          </div>

          <span>Monday, November 15th 2021</span>
        </a>

        <a href="/posts/unknown/creating-problem-solving-partnerships-through-open-innovation">
          <div>
            <h3>Creating problem-solving partnerships with open innovation</h3>
          </div>

          <span>Wednesday, September 8th 2021</span>
        </a>

        <a href="/posts/unknown/keeping-afloat-during-flood-of-worker-turnover">
          <div>
            <h3>Keeping afloat during the flood of worker turnover</h3>
          </div>

          <span>Thursday, August 19th 2021</span>
        </a>

        <a href="/posts/unknown/beginners-guide-to-platformsh">
          <div>
            <h3>A beginner’s guide to Platform.sh</h3>
          </div>

          <span>Tuesday, August 17th 2021</span>
        </a>

        <a href="/posts/how-tos/get-more-control-over-your-environments-with-build-variables">
          <div>
            <h3>Get more control over your environments with build variables</h3>
          </div>

          <span>Tuesday, August 10th 2021</span>
        </a>

        <a href="/posts/unknown/building-better-mousetrap-barebones-budget">
          <div>
            <h3>Building a better mousetrap on a barebones budget</h3>
          </div>

          <span>Thursday, July 1st 2021</span>
        </a>

        <a href="/posts/unknown/best-practices-for-engaging-digital-agency">
          <div>
            <h3>Best practices for engaging a digital agency</h3>
          </div>

          <span>Monday, April 26th 2021</span>
        </a>

        <a href="/posts/unknown/four-reasons-to-build-ecommerce-site-with-modern-paas">
          <div>
            <h3>Four reasons to build your ecommerce site with a modern PaaS</h3>
          </div>

          <span>Thursday, April 22nd 2021</span>
        </a>

        <a href="/posts/unknown/plan-monitor-operate-more-knowledgeably-with-metrics">
          <div>
            <h3>Plan, monitor, and operate more knowledgeably with metrics</h3>
          </div>

          <span>Wednesday, March 17th 2021</span>
        </a>

        <a href="/posts/unknown/time-to-breakup-three-reasons-to-decouple-your-application">
          <div>
            <h3>Time to breakup? Three reasons to decouple your application</h3>
          </div>

          <span>Wednesday, February 10th 2021</span>
        </a>

        <a href="/posts/core-concepts/https-and-tls-certificates-always-served-fresh">
          <div>
            <h3>HTTPS and TLS certificates: Always served fresh</h3>
          </div>

          <span>Tuesday, February 9th 2021</span>
        </a>

        <a href="/posts/unknown/how-digital-agency-adapt-innovates-without-heavy-lifting">
          <div>
            <h3>How digital agency Adapt innovates—without heavy-lifting</h3>
          </div>

          <span>Wednesday, February 3rd 2021</span>
        </a>

        <a href="/posts/unknown/lazard-names-platformsh-to-their-t100-index">
          <div>
            <h3>Lazard names Platform.sh to their T100 Index</h3>
          </div>

          <span>Monday, February 1st 2021</span>
        </a>

        <a href="/posts/unknown/renaming-your-projects-default-branch">
          <div>
            <h3>Renaming your project’s default branch</h3>
          </div>

          <span>Wednesday, January 20th 2021</span>
        </a>

        <a href="/posts/unknown/frederic-potvin-and-yann-deshayes">
          <div>
            <h3>Platform.sh | Journeys Frederic Potvin and Yann Deshayes</h3>
          </div>

          <span>Tuesday, January 19th 2021</span>
        </a>

        <a href="/posts/unknown/free-your-developers-the-simple-way-to-rebalance-your-devops-resources">
          <div>
            <h3>Free your developers! The simple way to rebalance your DevOps resources</h3>
          </div>

          <span>Thursday, January 14th 2021</span>
        </a>

        <a href="/posts/unknown/what-the-heck-is-a-decoupled-website">
          <div>
            <h3>CMS architecture: What the heck is . . . a decoupled website?</h3>
          </div>

          <span>Monday, January 11th 2021</span>
        </a>

        <a href="/posts/unknown/platformsh-joins-gaia-x">
          <div>
            <h3>Platform.sh joins the Gaia-X data infrastructure initiative</h3>
          </div>

          <span>Monday, December 7th 2020</span>
        </a>

        <a href="/posts/unknown/record-breaking-2020-black-friday-cyber-monday-volumes">
          <div>
            <h3>Record-breaking 2020 Black Friday volumes</h3>
          </div>

          <span>Monday, December 7th 2020</span>
        </a>

        <a href="/posts/unknown/what-the-heck-is-a-cdn">
          <div>
            <h3>What the heck is . . . a CDN?</h3>
          </div>

          <span>Friday, November 27th 2020</span>
        </a>

        <a href="/posts/unknown/php-80-brings-it-all-together-on-platformsh">
          <div>
            <h3>PHP 8.0 brings it all together on Platform.sh</h3>
          </div>

          <span>Thursday, November 26th 2020</span>
        </a>

        <a href="/posts/core-concepts/getting-gitops-right">
          <div>
            <h3>Getting GitOps right</h3>
          </div>

          <span>Tuesday, November 10th 2020</span>
        </a>

        <a href="/posts/releases/php-80-feature-focus-constructor-property-promotion">
          <div>
            <h3>PHP 8.0 feature focus: Class constructor property promotion</h3>
          </div>

          <span>Thursday, November 5th 2020</span>
        </a>

        <a href="/posts/unknown/php-80-feature-focus-language-tightening">
          <div>
            <h3>PHP 8.0 feature focus: Language tightenings</h3>
          </div>

          <span>Thursday, October 22nd 2020</span>
        </a>

        <a href="/posts/how-it-works/how-do-you-manage-ssh-keys-in-your-organization">
          <div>
            <h3>SSH certificates with Platform.sh</h3>
          </div>

          <span>Wednesday, October 21st 2020</span>
        </a>

        <a href="/posts/unknown/ks-chan">
          <div>
            <h3>Platform.sh | Journeys KS Chan</h3>
          </div>

          <span>Wednesday, October 21st 2020</span>
        </a>

        <a href="/posts/unknown/php-80-feature-focus-quality-of-life-improvements">
          <div>
            <h3>PHP 8.0 feature focus: quality of life improvements</h3>
          </div>

          <span>Wednesday, October 14th 2020</span>
        </a>

        <a href="/posts/unknown/what-the-heck-is-a-container">
          <div>
            <h3>CMS architecture: What the heck is . . . containerization?</h3>
          </div>

          <span>Monday, October 5th 2020</span>
        </a>

        <a href="/posts/releases/php-80-feature-focus-weak-maps">
          <div>
            <h3>PHP 8.0 feature focus: Weak maps</h3>
          </div>

          <span>Thursday, October 1st 2020</span>
        </a>

        <a href="/posts/unknown/mahdi-mokhtariirani">
          <div>
            <h3>Platform.sh | Journeys Mahdi Mokhtariirani</h3>
          </div>

          <span>Wednesday, September 16th 2020</span>
        </a>

        <a href="/posts/unknown/microsoft-azure-west-datacenter">
          <div>
            <h3>Expansion of Microsoft Azure Data Center services</h3>
          </div>

          <span>Tuesday, September 8th 2020</span>
        </a>

        <a href="/posts/unknown/pre-release-php-8-0-images-now-available">
          <div>
            <h3>Pre-release PHP 8.0 images now available</h3>
          </div>

          <span>Thursday, September 3rd 2020</span>
        </a>

        <a href="/posts/how-it-works/installers-that-dont-suck">
          <div>
            <h3>Installers that don't suck</h3>
          </div>

          <span>Wednesday, August 5th 2020</span>
        </a>

        <a href="/posts/engineering/save-your-drupal-team-hours-and-effort-with-source-operations-and-activity-scripts">
          <div>
            <h3>Source Operations and Activity Scripts for Drupal teams</h3>
          </div>

          <span>Tuesday, July 28th 2020</span>
        </a>

        <a href="/posts/unknown/headless-but-this-time-live-decoupled-drupal-with-gatsby">
          <div>
            <h3>Headless, but this time live! Decoupled Drupal with Gatsby</h3>
          </div>

          <span>Tuesday, July 28th 2020</span>
        </a>

        <a href="/posts/unknown/connecting-with-the-community-at-drupalcon-global">
          <div>
            <h3>Connecting with the community at DrupalCon Global</h3>
          </div>

          <span>Friday, July 24th 2020</span>
        </a>

        <a href="/posts/unknown/sso-for-platformsh-now-available-for-openid-connect-and-google">
          <div>
            <h3>SSO available for OpenID Connect and Google</h3>
          </div>

          <span>Thursday, June 25th 2020</span>
        </a>

        <a href="/posts/unknown/platformsh-partner-eZ-Systems-announces-name-change-to-ibexa">
          <div>
            <h3>Platform.sh partner eZ Systems announces name change to Ibexa</h3>
          </div>

          <span>Tuesday, June 23rd 2020</span>
        </a>

        <a href="/posts/unknown/integrations-management-through-platform-sh-console">
          <div>
            <h3>View your external integrations through the console</h3>
          </div>

          <span>Thursday, June 18th 2020</span>
        </a>

        <a href="/posts/unknown/headless-strapi-and-wordpress-content-with-gatsby-builds">
          <div>
            <h3>Going headless during your Gatsby builds</h3>
          </div>

          <span>Wednesday, May 13th 2020</span>
        </a>

        <a href="/posts/unknown/improve-visibility-over-your-external-integrations">
          <div>
            <h3>Improve visibility over your external integrations</h3>
          </div>

          <span>Tuesday, May 12th 2020</span>
        </a>

        <a href="/posts/unknown/improving-access-and-security-for-your-projects">
          <div>
            <h3>Improving access and security for your projects</h3>
          </div>

          <span>Monday, April 20th 2020</span>
        </a>

        <a href="/posts/unknown/supporting-drupal-covid-19">
          <div>
            <h3>Supporting the Drupal Association through COVID-19</h3>
          </div>

          <span>Friday, April 17th 2020</span>
        </a>

        <a href="/posts/unknown/taking-your-application-to-saas-a-business-decision">
          <div>
            <h3>High-performance for cloud application development</h3>
          </div>

          <span>Friday, April 17th 2020</span>
        </a>

        <a href="/posts/unknown/new-enterprise-pricing-tiers-fleetops">
          <div>
            <h3>New pricing tiers make FleetOps accessible</h3>
          </div>

          <span>Wednesday, April 15th 2020</span>
        </a>

        <a href="/posts/unknown/the-monolith-myth-why-tech-suites-are-not-solution">
          <div>
            <h3>A monolith myth: All-in-one tech suites aren't the solution</h3>
          </div>

          <span>Monday, April 13th 2020</span>
        </a>

        <a href="/posts/unknown/a-10x-increase-in-enterprise-valuation-over-two-years-a-saas-case-study">
          <div>
            <h3>SaaS case study: 10x increase in enterprise valuation</h3>
          </div>

          <span>Tuesday, April 7th 2020</span>
        </a>

        <a href="/posts/unknown/the-suddenly-online-conference">
          <div>
            <h3>The suddenly online conference: an Indy Cloud Conf case study</h3>
          </div>

          <span>Thursday, April 2nd 2020</span>
        </a>

        <a href="/posts/unknown/platformsh-covid-19-response">
          <div>
            <h3>A note to Platform.sh customers about COVID-19 preparedness</h3>
          </div>

          <span>Tuesday, March 17th 2020</span>
        </a>

        <a href="/posts/unknown/survival-guide-for-efficient-remote-work">
          <div>
            <h3>Voilà! You’re now a distributed workforce</h3>
          </div>

          <span>Friday, March 13th 2020</span>
        </a>

        <a href="/posts/releases/deploy-strapi-on-platformsh">
          <div>
            <h3>Platform.sh–deploying the future of content with one click</h3>
          </div>

          <span>Tuesday, March 3rd 2020</span>
        </a>

        <a href="/posts/unknown/out-of-the-lab-Node.js-12-features-graduate-from-experimental-status">
          <div>
            <h3>Node.js 12 features graduate from experimental status</h3>
          </div>

          <span>Tuesday, January 14th 2020</span>
        </a>

        <a href="/posts/unknown/what-is-new-with-jakarta-nosql-part-II">
          <div>
            <h3>What’s new with Jakarta NoSQL? (Part II)</h3>
          </div>

          <span>Wednesday, January 8th 2020</span>
        </a>

        <a href="/posts/unknown/sharpen-your-tusks-it-is-time-for-python-3.8">
          <div>
            <h3>Sharpen your tusks: it's time for Python 3.8</h3>
          </div>

          <span>Wednesday, December 18th 2019</span>
        </a>

        <a href="/posts/unknown/php-7.4-is-just-a-git-push-away">
          <div>
            <h3>PHP 7.4 is just a git push away</h3>
          </div>

          <span>Thursday, November 28th 2019</span>
        </a>

        <a href="/posts/unknown/new-services-page">
          <div>
            <h3>New Services Page: more shininess, as promised</h3>
          </div>

          <span>Tuesday, October 15th 2019</span>
        </a>

        <a href="/posts/business/website-fleet">
          <div>
            <h3>Website fleet management: challenges and opportunities</h3>
          </div>

          <span>Friday, October 11th 2019</span>
        </a>

        <a href="/posts/engineering/three-ways-to-manage-a-fleet">
          <div>
            <h3>Three ways to manage a website fleet</h3>
          </div>

          <span>Friday, October 11th 2019</span>
        </a>

        <a href="/posts/unknown/strong-customer-authentication">
          <div>
            <h3>Strong Customer Authentication will be required for European credit and bank card payments</h3>
          </div>

          <span>Thursday, September 26th 2019</span>
        </a>

        <a href="/posts/unknown/security-updates-for-php-rolling-out-now">
          <div>
            <h3>Security updates for PHP: rolling out now</h3>
          </div>

          <span>Wednesday, September 11th 2019</span>
        </a>

        <a href="/posts/unknown/go-release-1.13-on-Platform.sh">
          <div>
            <h3>New: Go release 1.13 on Platform.sh</h3>
          </div>

          <span>Wednesday, September 4th 2019</span>
        </a>

        <a href="/posts/unknown/try-out-the-future-of-php-on-platform.sh-today">
          <div>
            <h3>PHP 7.4 is here: Try out the future of PHP on Platform.sh today!</h3>
          </div>

          <span>Tuesday, August 27th 2019</span>
        </a>

        <a href="/posts/unknown/microservices-in-the-cloud-part-two">
          <div>
            <h3>Microservices in the cloud, part two</h3>
          </div>

          <span>Friday, August 23rd 2019</span>
        </a>

        <a href="/posts/unknown/microservices-in-the-cloud-part-one">
          <div>
            <h3>Microservices in the cloud, part one</h3>
          </div>

          <span>Tuesday, August 13th 2019</span>
        </a>

        <a href="/posts/unknown/lisp">
          <div>
            <h3>We are happy, relieved and somewhat amused to announce the availability of Common Lisp on Platform.sh</h3>
          </div>

          <span>Thursday, August 8th 2019</span>
        </a>

        <a href="/posts/unknown/platform.sh-documentation-new-guides-new-look">
          <div>
            <h3>Platform.sh documentation: new guides, new look</h3>
          </div>

          <span>Thursday, August 1st 2019</span>
        </a>

        <a href="/posts/unknown/jakarta-ee-generation-iv-a-new-hope">
          <div>
            <h3>Jakarta EE: Generation IV - a new hope</h3>
          </div>

          <span>Tuesday, July 30th 2019</span>
        </a>

        <a href="/posts/unknown/version-will-be-required-in-type-what-it-means-for-your-projects">
          <div>
            <h3>Version will be required in type: what it means for your projects</h3>
          </div>

          <span>Monday, July 22nd 2019</span>
        </a>

        <a href="/posts/unknown/eclipse-microprofiles-gain-agility-release-faster">
          <div>
            <h3>Eclipse MicroProfiles: gain agility, release faster</h3>
          </div>

          <span>Monday, July 15th 2019</span>
        </a>

        <a href="/posts/unknown/web-dev-plus-IT-unique-roles-equal-partners-in-application-success">
          <div>
            <h3>Web dev + IT: unique roles, equal partners in app success</h3>
          </div>

          <span>Monday, June 24th 2019</span>
        </a>

        <a href="/posts/unknown/Spring-MVC-and-MongoDB-a-match-made-in-Platform.sh-heaven">
          <div>
            <h3>Spring MVC and MongoDB: a match made in Platform.sh heaven</h3>
          </div>

          <span>Wednesday, June 19th 2019</span>
        </a>

        <a href="/posts/unknown/off-with-its-head-headless-Chrome-as-a-service">
          <div>
            <h3>Off with its Head! Headless Chrome as a Service decoded</h3>
          </div>

          <span>Wednesday, June 12th 2019</span>
        </a>

        <a href="/posts/unknown/java-hello-world-at-platform.sh">
          <div>
            <h3>Java: Hello, World! at Platform.sh</h3>
          </div>

          <span>Thursday, June 6th 2019</span>
        </a>

        <a href="/posts/unknown/apache-kafka-support">
          <div>
            <h3>Apache Kafka now available</h3>
          </div>

          <span>Wednesday, June 5th 2019</span>
        </a>

        <a href="/posts/unknown/new-german-region">
          <div>
            <h3>New Germany region: more speed, more capability, lower cost</h3>
          </div>

          <span>Wednesday, May 22nd 2019</span>
        </a>

        <a href="/posts/unknown/it-worked-in-staging">
          <div>
            <h3>Learning to trust the machines and the process in DevOps</h3>
          </div>

          <span>Thursday, April 25th 2019</span>
        </a>

        <a href="/posts/unknown/shiny-new-platformsh-web-management-console">
          <div>
            <h3>Shiny, new Platform.sh management console</h3>
          </div>

          <span>Thursday, April 11th 2019</span>
        </a>

        <a href="/posts/unknown/adobe-summit-2019">
          <div>
            <h3>Adobe Summit 2019: take-aways</h3>
          </div>

          <span>Monday, April 1st 2019</span>
        </a>

        <a href="/posts/unknown/four-days-four-languages-four-frameworks-day-3-gatsbyjs-the-reactbased-static-site-generator">
          <div>
            <h3>4 days, 4 languages, 4 frameworks, Day 3: GatsbyJS</h3>
          </div>

          <span>Thursday, February 28th 2019</span>
        </a>

        <a href="/posts/unknown/four-days-four-languages-four-frameworks-day-2-running-hugo">
          <div>
            <h3>4 days, 4 languages, 4 frameworks, Day 2: Running Hugo</h3>
          </div>

          <span>Wednesday, February 27th 2019</span>
        </a>

        <a href="/posts/unknown/four-days-four-languages-four-frameworks-on-platformsh">
          <div>
            <h3>Four days, four languages, four frameworks on Platform.sh</h3>
          </div>

          <span>Tuesday, February 26th 2019</span>
        </a>

        <a href="/posts/unknown/platformsh-full-speed-ahead-into-2019">
          <div>
            <h3>Platform.sh full speed ahead into 2019</h3>
          </div>

          <span>Tuesday, January 29th 2019</span>
        </a>

        <a href="/posts/unknown/open-source-software-roi-for-your-organization">
          <div>
            <h3>Open source software ROI for your organization</h3>
          </div>

          <span>Wednesday, January 2nd 2019</span>
        </a>

        <a href="/posts/unknown/give-the-gift-of-ruby-this-season">
          <div>
            <h3>Give the gift of Ruby this season</h3>
          </div>

          <span>Tuesday, December 18th 2018</span>
        </a>

        <a href="/posts/releases/deploy-with-php-73-this-friday-er-thursday">
          <div>
            <h3>Deploy with PHP 7.3 this Friday, er, Thursday</h3>
          </div>

          <span>Thursday, December 6th 2018</span>
        </a>

        <a href="/posts/unknown/update-to-our-privacy-policy">
          <div>
            <h3>Update to our Privacy Policy</h3>
          </div>

          <span>Monday, November 19th 2018</span>
        </a>

        <a href="/posts/unknown/our-black-friday-gift-10000-cpus-overnight-without-downtime">
          <div>
            <h3>Our Black Friday gift: 10,000 CPUs without downtime</h3>
          </div>

          <span>Friday, November 16th 2018</span>
        </a>

        <a href="/posts/unknown/good-morning-australia-were-back-in-business">
          <div>
            <h3>Good morning, Australia: we’re back in business</h3>
          </div>

          <span>Thursday, November 15th 2018</span>
        </a>

        <a href="/posts/unknown/why-you-should-care-about-wechat-before-its-too-late">
          <div>
            <h3>Why you should care about WeChat before it's too late!</h3>
          </div>

          <span>Wednesday, October 31st 2018</span>
        </a>

        <a href="/posts/releases/golang-forth-and-deploy">
          <div>
            <h3>Go\[lang] forth and deploy</h3>
          </div>

          <span>Monday, October 29th 2018</span>
        </a>

        <a href="/posts/unknown/were-improving-our-communications-tools-at-platformsh">
          <div>
            <h3>We're improving our communications tools at Platform.sh</h3>
          </div>

          <span>Friday, October 26th 2018</span>
        </a>

        <a href="/posts/releases/deploy-your-python-37-code-to-the-moon">
          <div>
            <h3>Deploy your Python 3.7 code to the Moon</h3>
          </div>

          <span>Wednesday, September 5th 2018</span>
        </a>

        <a href="/posts/unknown/platformsh-wins-2018-stratus-award-for-cloud-computing">
          <div>
            <h3>Platform.sh Wins 2018 Stratus Award for Cloud Computing</h3>
          </div>

          <span>Thursday, August 30th 2018</span>
        </a>

        <a href="/posts/unknown/of-cicadas-and-cron-jobs">
          <div>
            <h3>Of Cicadas and cron jobs</h3>
          </div>

          <span>Tuesday, August 21st 2018</span>
        </a>

        <a href="/posts/unknown/its-july-2018-do-you-know-what-your-php-is">
          <div>
            <h3>It's July 2018, do you know what your PHP is?</h3>
          </div>

          <span>Tuesday, July 3rd 2018</span>
        </a>

        <a href="/posts/unknown/some-gifts-for-the-json-fans">
          <div>
            <h3>Some gifts for the JSON fans</h3>
          </div>

          <span>Thursday, June 28th 2018</span>
        </a>

        <a href="/posts/unknown/your-guide-to-gdpr-compliance-training-your-employees">
          <div>
            <h3>Your Guide to GDPR Compliance: Training your employees</h3>
          </div>

          <span>Friday, June 8th 2018</span>
        </a>

        <a href="/posts/unknown/the-github-acquisition-its-all-about-cloud-for-microsoft">
          <div>
            <h3>The Github acquisition: it's all about cloud for Microsoft</h3>
          </div>

          <span>Tuesday, June 5th 2018</span>
        </a>

        <a href="/posts/unknown/your-guide-to-gdpr-compliance-transfers-of-personal-data-to-third-countries">
          <div>
            <h3>Your Guide to GDPR Compliance: Transfers of personal data to third countries</h3>
          </div>

          <span>Wednesday, May 30th 2018</span>
        </a>

        <a href="/posts/unknown/your-guide-to-gdpr-compliance-data-protection-impact-assessment-and-security-measures-for-processing-data">
          <div>
            <h3>Your Guide to GDPR Compliance: Data protection impact assessment and security measures for processing data</h3>
          </div>

          <span>Friday, May 25th 2018</span>
        </a>

        <a href="/posts/unknown/platformsh-raises-34m-to-bring-speed-and-confidence-to-enterprise-cloud-deployments">
          <div>
            <h3>Platform.sh raises \$34M in series C funding</h3>
          </div>

          <span>Wednesday, May 23rd 2018</span>
        </a>

        <a href="/posts/unknown/your-guide-to-gdpr-compliance-data-subject-rights">
          <div>
            <h3>Your Guide to GDPR Compliance: Data subject rights</h3>
          </div>

          <span>Wednesday, May 23rd 2018</span>
        </a>

        <a href="/posts/unknown/data-protection-by-design-and-default">
          <div>
            <h3>Data protection by design and by default</h3>
          </div>

          <span>Monday, May 7th 2018</span>
        </a>

        <a href="/posts/unknown/platformsh-confirms-that-it-is-ready-for-the-gdpr">
          <div>
            <h3>Platform.sh confirms that it is ready for the GDPR</h3>
          </div>

          <span>Wednesday, May 2nd 2018</span>
        </a>

        <a href="/posts/unknown/your-guide-to-gdpr-compliance-the-six-principles-of-processing-personal-data">
          <div>
            <h3>Your Guide to GDPR Compliance: The Six Principles of Processing Personal Data</h3>
          </div>

          <span>Friday, April 20th 2018</span>
        </a>

        <a href="/posts/insights/what-will-you-do-after-you-deploy">
          <div>
            <h3>What will you do after you deploy?</h3>
          </div>

          <span>Tuesday, April 17th 2018</span>
        </a>

        <a href="/posts/unknown/your-guide-to-gdpr-compliance-roles-and-responsibilities">
          <div>
            <h3>Your Guide to GDPR Compliance: Roles and Responsibilities</h3>
          </div>

          <span>Monday, April 9th 2018</span>
        </a>

        <a href="/posts/unknown/your-guide-to-gdpr-compliance-introduction">
          <div>
            <h3>Your Guide to GDPR Compliance (Introduction)</h3>
          </div>

          <span>Wednesday, April 4th 2018</span>
        </a>

        <a href="/posts/unknown/drupal-critical-core-vulnerability-announced">
          <div>
            <h3>Drupal critical core vulnerability announced</h3>
          </div>

          <span>Wednesday, March 28th 2018</span>
        </a>

        <a href="/posts/unknown/using-platformsh-with-scrum">
          <div>
            <h3>Using Platform.sh with Scrum</h3>
          </div>

          <span>Tuesday, February 13th 2018</span>
        </a>

        <a href="/posts/releases/hhvm-deploys-off-into-the-sunset">
          <div>
            <h3>HHVM deploys off into the sunset</h3>
          </div>

          <span>Tuesday, January 30th 2018</span>
        </a>

        <a href="/posts/unknown/platformsh-is-ready-to-make-an-impact-in-china">
          <div>
            <h3>Platform.sh is ready to make an Impact in China</h3>
          </div>

          <span>Wednesday, January 24th 2018</span>
        </a>

        <a href="/posts/unknown/spectremeltdown-security-update-notice">
          <div>
            <h3>Spectre/Meltdown Security Update Notice</h3>
          </div>

          <span>Friday, January 5th 2018</span>
        </a>

        <a href="/posts/unknown/backup-and-forget">
          <div>
            <h3>Backup and Forget</h3>
          </div>

          <span>Wednesday, January 3rd 2018</span>
        </a>

        <a href="/posts/unknown/a-look-back-on-2017">
          <div>
            <h3>A look back on 2017</h3>
          </div>

          <span>Friday, December 29th 2017</span>
        </a>

        <a href="/posts/unknown/tighten-up-your-tls">
          <div>
            <h3>Tighten up your TLS</h3>
          </div>

          <span>Thursday, December 28th 2017</span>
        </a>

        <a href="/posts/unknown/route-all-the-things">
          <div>
            <h3>Route all the things</h3>
          </div>

          <span>Wednesday, December 20th 2017</span>
        </a>

        <a href="/posts/unknown/gitlab-integration-is-here">
          <div>
            <h3>GitLab Integration is here!</h3>
          </div>

          <span>Tuesday, December 12th 2017</span>
        </a>

        <a href="/posts/unknown/living-on-the-edge-with-ruby-25-preview">
          <div>
            <h3>Living on the edge with Ruby 2.5 (preview)</h3>
          </div>

          <span>Tuesday, December 12th 2017</span>
        </a>

        <a href="/posts/unknown/platformsh-joins-the-prestigious-french-tech-tour-china-2017">
          <div>
            <h3>Platform.sh joins the prestigious French Tech Tour China 2017</h3>
          </div>

          <span>Sunday, December 3rd 2017</span>
        </a>

        <a href="/posts/unknown/welcome-to-the-world-php-72">
          <div>
            <h3>Welcome to the world, PHP 7.2!</h3>
          </div>

          <span>Thursday, November 30th 2017</span>
        </a>

        <a href="/posts/unknown/deploy-api-platform-on-platformsh">
          <div>
            <h3>Simplifying API Platform Deployment on Platform.sh</h3>
          </div>

          <span>Wednesday, November 29th 2017</span>
        </a>

        <a href="/posts/unknown/wordpress-security-updates-the-quick-way">
          <div>
            <h3>WordPress security updates, the quick way</h3>
          </div>

          <span>Wednesday, November 1st 2017</span>
        </a>

        <a href="/posts/unknown/going-local-with-lando">
          <div>
            <h3>Going Local with Lando</h3>
          </div>

          <span>Wednesday, October 18th 2017</span>
        </a>

        <a href="/posts/unknown/wildcard-support-for-cookies-in-the-http-cache">
          <div>
            <h3>Wildcard support for cookies in the HTTP cache</h3>
          </div>

          <span>Tuesday, October 17th 2017</span>
        </a>

        <a href="/posts/how-it-works/the-platformsh-build-and-deploy-pipeline">
          <div>
            <h3>The Platform.sh build-and-deploy pipeline</h3>
          </div>

          <span>Tuesday, October 3rd 2017</span>
        </a>

        <a href="/posts/unknown/taking-care-of-your-health">
          <div>
            <h3>Taking care of your health</h3>
          </div>

          <span>Monday, October 2nd 2017</span>
        </a>

        <a href="/posts/unknown/platformsh-joins-orange-cloud-for-business-at-huawei-connect-2017-shanghai">
          <div>
            <h3>Platform.sh & Orange Cloud at Huawei Connect 2017, Shanghai</h3>
          </div>

          <span>Monday, September 4th 2017</span>
        </a>

        <a href="/posts/unknown/6-things-to-do-to-make-your-application-cloud-friendly">
          <div>
            <h3>7 things to do to make your application cloud-friendly</h3>
          </div>

          <span>Monday, August 7th 2017</span>
        </a>

        <a href="/posts/unknown/deploy-down-under-platformsh-is-now-available-in-australia">
          <div>
            <h3>Deploy Down Under: Platform.sh is now available in Australia</h3>
          </div>

          <span>Monday, July 3rd 2017</span>
        </a>

        <a href="/posts/unknown/containers-old-containers-new-memcached-support-and-php-72">
          <div>
            <h3>Containers, memcached support, and PHP 7.2</h3>
          </div>

          <span>Monday, June 26th 2017</span>
        </a>

        <a href="/posts/unknown/now-available-sovereign-hosting-solution-in-microsoft-cloud-germany">
          <div>
            <h3>Sovereign Hosting Solution in Microsoft Cloud Germany</h3>
          </div>

          <span>Thursday, June 22nd 2017</span>
        </a>

        <a href="/posts/unknown/getting-to-5050-women-men-participation-polyconf-a-very-diverse-conference">
          <div>
            <h3>Getting to 50/50: Polyconf, a very diverse conference</h3>
          </div>

          <span>Thursday, June 8th 2017</span>
        </a>

        <a href="/posts/unknown/the-ultimate-third-party-resources-list-on-using-platformsh">
          <div>
            <h3>The Ultimate Third Party Resources List on Using Platform.sh</h3>
          </div>

          <span>Tuesday, May 16th 2017</span>
        </a>

        <a href="/posts/unknown/devops-gives-you-wings">
          <div>
            <h3>DevOps gives you wings</h3>
          </div>

          <span>Tuesday, May 9th 2017</span>
        </a>

        <a href="/posts/unknown/screencast-composer-and-continuous-integration">
          <div>
            <h3>Screencast - Composer and Continuous Integration</h3>
          </div>

          <span>Tuesday, May 9th 2017</span>
        </a>

        <a href="/posts/unknown/sponsoring-predotscale-and-election-drinks">
          <div>
            <h3>Sponsoring pre-dotScale and election drinks !</h3>
          </div>

          <span>Friday, April 21st 2017</span>
        </a>

        <a href="/posts/unknown/free-ssl-certificates-for-every-project-every-environment">
          <div>
            <h3>Free SSL certificates for every project & every environment</h3>
          </div>

          <span>Thursday, April 20th 2017</span>
        </a>

        <a href="/posts/unknown/imagine-2017-the-new-magento-ecosystem">
          <div>
            <h3>Imagine 2017: The New Magento Ecosystem</h3>
          </div>

          <span>Thursday, April 13th 2017</span>
        </a>

        <a href="/posts/unknown/global-app-cache-our-managed-tiered-cdn-feature-for-global-page-and-asset-cache-coverage">
          <div>
            <h3>Global App Cache: Managed CDNs for optimal performance</h3>
          </div>

          <span>Wednesday, April 5th 2017</span>
        </a>

        <a href="/posts/unknown/influxdb">
          <div>
            <h3>Now you can save time in a database</h3>
          </div>

          <span>Monday, March 27th 2017</span>
        </a>

        <a href="/posts/unknown/oliver-sweeney-website-revamp-with-magento-cloud-powered-by-platformsh-oozes-sophistication-and-luxury">
          <div>
            <h3>Oliver Sweeney website revamp with Magento Cloud</h3>
          </div>

          <span>Friday, March 17th 2017</span>
        </a>

        <a href="/posts/unknown/expands-usa-operations-meet-growing-demand-north-america">
          <div>
            <h3>Platform.sh expands its US operations</h3>
          </div>

          <span>Tuesday, February 14th 2017</span>
        </a>

        <a href="/posts/unknown/multi-mysql">
          <div>
            <h3>Multiple MySQLs Make Platform.sh a Multisite Machine</h3>
          </div>

          <span>Friday, February 10th 2017</span>
        </a>

        <a href="/posts/unknown/platformsh-at-the-oop-conference">
          <div>
            <h3>Platform.sh is down wit' OOP</h3>
          </div>

          <span>Thursday, January 26th 2017</span>
        </a>

        <a href="/posts/unknown/persistent-redis">
          <div>
            <h3>Redis, now for long-term keys and values</h3>
          </div>

          <span>Wednesday, January 25th 2017</span>
        </a>

        <a href="/posts/unknown/solr-63">
          <div>
            <h3>New year, new Solr, new features</h3>
          </div>

          <span>Tuesday, January 17th 2017</span>
        </a>

        <a href="/posts/unknown/mongodb_apocalypse">
          <div>
            <h3>Your instances safe from MongoDB Apocalypse on the Platform.sh PaaS</h3>
          </div>

          <span>Tuesday, January 10th 2017</span>
        </a>

        <a href="/posts/unknown/the-year-we-won-php">
          <div>
            <h3>2016, The Year We Won PHP</h3>
          </div>

          <span>Monday, January 9th 2017</span>
        </a>

        <a href="/posts/unknown/http2">
          <div>
            <h3>Announcing HTTP/2 support!</h3>
          </div>

          <span>Sunday, January 8th 2017</span>
        </a>

        <a href="/posts/unknown/php-71">
          <div>
            <h3>Next Wave PHP now supported</h3>
          </div>

          <span>Thursday, December 29th 2016</span>
        </a>

        <a href="/posts/unknown/what-is-your-timezone">
          <div>
            <h3>What's your timezone?</h3>
          </div>

          <span>Tuesday, December 27th 2016</span>
        </a>

        <a href="/posts/unknown/production-artifact">
          <div>
            <h3>Production is an artifact of development</h3>
          </div>

          <span>Friday, December 23rd 2016</span>
        </a>

        <a href="/posts/unknown/project-variables">
          <div>
            <h3>This week in new features - Build-time variables</h3>
          </div>

          <span>Tuesday, December 20th 2016</span>
        </a>

        <a href="/posts/unknown/screencast-yaml">
          <div>
            <h3>Screencast - Configuring your Platform.sh Project</h3>
          </div>

          <span>Monday, December 19th 2016</span>
        </a>

        <a href="/posts/unknown/leader-php-hosting-multiple-partnerships">
          <div>
            <h3>Platform.sh at the forefront of PHP hosting in 2016</h3>
          </div>

          <span>Thursday, December 15th 2016</span>
        </a>

        <a href="/posts/how-it-works/repeatable-deployments">
          <div>
            <h3>How repeatable deployments work</h3>
          </div>

          <span>Tuesday, December 13th 2016</span>
        </a>

        <a href="/posts/unknown/app-updates-php">
          <div>
            <h3>Application updates for PHP containers</h3>
          </div>

          <span>Friday, December 9th 2016</span>
        </a>

        <a href="/posts/unknown/screencast-basic-platformsh-workflow">
          <div>
            <h3>Screencast - Basic Platform.sh Workflow</h3>
          </div>

          <span>Monday, December 5th 2016</span>
        </a>

        <a href="/posts/unknown/a-cloud-for-symfony">
          <div>
            <h3>A Cloud for Symfony</h3>
          </div>

          <span>Friday, December 2nd 2016</span>
        </a>

        <a href="/posts/unknown/typo3-8-starting-platformsh-cloud">
          <div>
            <h3>TYPO3 CMS 8 starting today with Platform.sh in the cloud</h3>
          </div>

          <span>Thursday, October 27th 2016</span>
        </a>

        <a href="/posts/unknown/do-more-with-less">
          <div>
            <h3>Cut your digital budget by 30% by doing less work</h3>
          </div>

          <span>Monday, October 17th 2016</span>
        </a>

        <a href="/posts/unknown/typo3-platformsh-cloud-integration">
          <div>
            <h3>TYPO3 and Platform.sh announce cloud readiness and tech preview of strategic integration</h3>
          </div>

          <span>Thursday, October 13th 2016</span>
        </a>

        <a href="/posts/unknown/vc-ready-funding-survey">
          <div>
            <h3>Three trends that make successful tech startups attractive to VCs</h3>
          </div>

          <span>Tuesday, October 4th 2016</span>
        </a>

        <a href="/posts/releases/python-ruby-support">
          <div>
            <h3>Continuous Deployment - Now with Python and Ruby support!</h3>
          </div>

          <span>Friday, September 23rd 2016</span>
        </a>

        <a href="/posts/unknown/documentation-tng">
          <div>
            <h3>Platform.sh Documentation - The Next Generation</h3>
          </div>

          <span>Wednesday, September 21st 2016</span>
        </a>

        <a href="/posts/unknown/ez-systems-partnership">
          <div>
            <h3>We partnered with eZ Systems to accelerate development</h3>
          </div>

          <span>Monday, September 19th 2016</span>
        </a>

        <a href="/posts/releases/github-blackfire-platformsh">
          <div>
            <h3>Develop on GitHub, Deploy on Platform.sh, Test on Blackfire.io</h3>
          </div>

          <span>Tuesday, August 30th 2016</span>
        </a>

        <a href="/posts/unknown/gitflow-is-now-supported">
          <div>
            <h3>GitFlow is now supported on Platform.sh!</h3>
          </div>

          <span>Wednesday, August 24th 2016</span>
        </a>

        <a href="/posts/unknown/release-ui-2-13">
          <div>
            <h3>UI version 2.13 released</h3>
          </div>

          <span>Tuesday, August 23rd 2016</span>
        </a>

        <a href="/posts/unknown/httpoxy">
          <div>
            <h3>Httpoxy or how Platform.sh keeps your applications safe</h3>
          </div>

          <span>Wednesday, July 20th 2016</span>
        </a>

        <a href="/posts/unknown/release-ui-2-12">
          <div>
            <h3>UI version 2.12 released</h3>
          </div>

          <span>Monday, July 18th 2016</span>
        </a>

        <a href="/posts/unknown/release-ui-2-11">
          <div>
            <h3>UI version 2.11 released</h3>
          </div>

          <span>Tuesday, July 5th 2016</span>
        </a>

        <a href="/posts/unknown/new-features-june">
          <div>
            <h3>June Features Update</h3>
          </div>

          <span>Thursday, June 30th 2016</span>
        </a>

        <a href="/posts/unknown/is-thecloud-really-someone-elses-computer">
          <div>
            <h3>Is the Cloud really someone else's computer?</h3>
          </div>

          <span>Monday, June 27th 2016</span>
        </a>

        <a href="/posts/unknown/cloud-adoption-europe-data-privacy">
          <div>
            <h3>Cloud adoption in Europe: Addressing data privacy concerns</h3>
          </div>

          <span>Tuesday, June 21st 2016</span>
        </a>

        <a href="/posts/unknown/marketing-manager-paris">
          <div>
            <h3>Looking for our new marketing manager! Are you the one?</h3>
          </div>

          <span>Friday, June 10th 2016</span>
        </a>

        <a href="/posts/unknown/drupal-8-starter-kit-now-with-php-7-and-composer">
          <div>
            <h3>Drupal 8 starter kit now with PHP 7 and Composer!</h3>
          </div>

          <span>Tuesday, June 7th 2016</span>
        </a>

        <a href="/posts/unknown/release-ui-2-10">
          <div>
            <h3>UI version 2.10 released</h3>
          </div>

          <span>Tuesday, June 7th 2016</span>
        </a>

        <a href="/posts/unknown/microsoft-joint-paas-offering">
          <div>
            <h3>Microsoft and Platform.sh announce joint PaaS offering for High Availability (HA) hosting</h3>
          </div>

          <span>Thursday, June 2nd 2016</span>
        </a>

        <a href="/posts/unknown/isv-saas-iaas-providers">
          <div>
            <h3>Software vendor, SaaS or IaaS - doesn’t matter which. Platform.sh really is the killer app for you!</h3>
          </div>

          <span>Wednesday, May 25th 2016</span>
        </a>

        <a href="/posts/unknown/drupalcon-nola-survival-guide">
          <div>
            <h3>DrupalCon New Orleans Survival Guide</h3>
          </div>

          <span>Thursday, May 5th 2016</span>
        </a>

        <a href="/posts/unknown/larry-garfield-joins-platformsh">
          <div>
            <h3>The one and only Director of Runtimes and Integrations</h3>
          </div>

          <span>Monday, May 2nd 2016</span>
        </a>

        <a href="/posts/unknown/magento-enterprise-cloud-edition-powered-by-platform-sh">
          <div>
            <h3>Platform.sh Provides PaaS Technology to Magento Commerce</h3>
          </div>

          <span>Tuesday, April 12th 2016</span>
        </a>

        <a href="/posts/unknown/deploy-to-the-moon">
          <div>
            <h3>Platform.sh announces world’s first LDN for web applications</h3>
          </div>

          <span>Friday, April 1st 2016</span>
        </a>

        <a href="/posts/unknown/release-cli-3-0">
          <div>
            <h3>CLI version 3.0 released</h3>
          </div>

          <span>Tuesday, March 22nd 2016</span>
        </a>

        <a href="/posts/unknown/platform.sh-independent-company">
          <div>
            <h3>Platform.sh becomes an independent company</h3>
          </div>

          <span>Tuesday, February 9th 2016</span>
        </a>

        <a href="/posts/unknown/php-session-bug">
          <div>
            <h3>All Platform.sh clients kept automatically safe from serious PHP bug</h3>
          </div>

          <span>Thursday, December 17th 2015</span>
        </a>

        <a href="/posts/unknown/drupal-8-release-party">
          <div>
            <h3>Drupal 8.0 has been released... Party time!</h3>
          </div>

          <span>Thursday, November 19th 2015</span>
        </a>

        <a href="/posts/unknown/safe-harbour-safe">
          <div>
            <h3>Concerned about the recent European Court ruling on Safe Harbor?</h3>
          </div>

          <span>Tuesday, November 3rd 2015</span>
        </a>

        <a href="/posts/unknown/badcamp">
          <div>
            <h3>Platform.sh to exhibit at BADCamp 2015</h3>
          </div>

          <span>Tuesday, October 20th 2015</span>
        </a>

        <a href="/posts/unknown/best-horizontal-cloud-solution-for-2015-in-europe">
          <div>
            <h3>Platform.sh Best Horizontal Cloud Solution for 2015 in Europe</h3>
          </div>

          <span>Friday, October 9th 2015</span>
        </a>

        <a href="/posts/unknown/release-hhvm">
          <div>
            <h3>HHVM versions 3.9 and 3.12 supported</h3>
          </div>

          <span>Wednesday, September 23rd 2015</span>
        </a>

        <a href="/posts/unknown/symfony-documentation-pull-requests">
          <div>
            <h3>Platform.sh hosts Symfony documentation GitHub pull requests</h3>
          </div>

          <span>Thursday, September 10th 2015</span>
        </a>

        <a href="/posts/unknown/featured-on-bitbucket">
          <div>
            <h3>Platform.sh / Bitbucket Integration, featured on the Bitbucket Blog</h3>
          </div>

          <span>Monday, August 17th 2015</span>
        </a>

        <a href="/posts/unknown/platform-sh-hiring-interns">
          <div>
            <h3>Hiring interns</h3>
          </div>

          <span>Monday, August 10th 2015</span>
        </a>

        <a href="/posts/unknown/work-with-distribution">
          <div>
            <h3>The correct way to work with Drupal distributions</h3>
          </div>

          <span>Tuesday, July 28th 2015</span>
        </a>

        <a href="/posts/unknown/release-docs-3-0">
          <div>
            <h3>Documentation version 3.0 released</h3>
          </div>

          <span>Saturday, July 25th 2015</span>
        </a>

        <a href="/posts/unknown/five-platform-sh-the-paas-for-drupal-8">
          <div>
            <h3>Five reasons why Platform.sh is the PaaS you need for Drupal 8</h3>
          </div>

          <span>Thursday, July 16th 2015</span>
        </a>

        <a href="/posts/unknown/best-horizontal-cloud-platform-eurocloud">
          <div>
            <h3>Platform.sh elected Best Horizontal Cloud Platform of the year</h3>
          </div>

          <span>Friday, July 10th 2015</span>
        </a>

        <a href="/posts/unknown/ceo-interviewed-on-bfm-business">
          <div>
            <h3>CEO of Commerce Guys is interviewed by the main French Business TV Channel about Platform.sh</h3>
          </div>

          <span>Wednesday, July 8th 2015</span>
        </a>

        <a href="/posts/unknown/european-horizon-2020-grant">
          <div>
            <h3>Platform.sh awarded a €1.95M grant</h3>
          </div>

          <span>Thursday, June 25th 2015</span>
        </a>

        <a href="/posts/unknown/2015-06-european-cloud-leadership-born-in-france">
          <div>
            <h3>European cloud leadership is being born before our very own eyes in France</h3>
          </div>

          <span>Tuesday, June 23rd 2015</span>
        </a>

        <a href="/posts/unknown/release-ui-2-0">
          <div>
            <h3>UI version 2.0 released</h3>
          </div>

          <span>Wednesday, May 27th 2015</span>
        </a>

        <a href="/posts/unknown/groundbreaking-drupal-8-news-portal-goes-live-platformsh">
          <div>
            <h3>Groundbreaking Drupal 8 news portal goes live on Platform.sh</h3>
          </div>

          <span>Wednesday, May 13th 2015</span>
        </a>

        <a href="/posts/unknown/platformsh-cli-developments-1-10">
          <div>
            <h3>Platform.sh CLI developments</h3>
          </div>

          <span>Monday, March 16th 2015</span>
        </a>

        <a href="/posts/how-it-works/how-platform-paas-works">
          <div>
            <h3>How the Platform.sh PaaS works</h3>
          </div>

          <span>Tuesday, March 3rd 2015</span>
        </a>

        <a href="/posts/discussions/containers-are-the-new-static-binaries">
          <div>
            <h3>Containers are the new static binaries</h3>
          </div>

          <span>Thursday, February 26th 2015</span>
        </a>

        <a href="/posts/unknown/blackfire-integration">
          <div>
            <h3>Support for Blackfire Profiler</h3>
          </div>

          <span>Monday, February 2nd 2015</span>
        </a>

        <a href="/posts/unknown/release-ui-1-10">
          <div>
            <h3>UI version 1.10 released</h3>
          </div>

          <span>Monday, January 26th 2015</span>
        </a>

        <a href="/posts/unknown/release-cli-1-7">
          <div>
            <h3>CLI version 1.7 released</h3>
          </div>

          <span>Tuesday, January 20th 2015</span>
        </a>

        <a href="/posts/unknown/git-clients-vulnerable">
          <div>
            <h3>Git clients vulnerable</h3>
          </div>

          <span>Friday, December 19th 2014</span>
        </a>

        <a href="/posts/unknown/release-ui-1-9">
          <div>
            <h3>UI version 1.9 released</h3>
          </div>

          <span>Wednesday, December 3rd 2014</span>
        </a>

        <a href="/posts/unknown/us-platform-adoption">
          <div>
            <h3>Leading digital agencies adopt Platform.sh to support Continuous Delivery</h3>
          </div>

          <span>Wednesday, November 5th 2014</span>
        </a>

        <a href="/posts/unknown/release-cli-1-2">
          <div>
            <h3>CLI version 1.2 released</h3>
          </div>

          <span>Wednesday, October 29th 2014</span>
        </a>

        <a href="/posts/unknown/1000-tickets-strong">
          <div>
            <h3>1000 tickets strong</h3>
          </div>

          <span>Wednesday, October 22nd 2014</span>
        </a>

        <a href="/posts/unknown/protecting-your-apps">
          <div>
            <h3>Protecting your apps</h3>
          </div>

          <span>Tuesday, October 21st 2014</span>
        </a>

        <a href="/posts/unknown/sa-core-2014-005">
          <div>
            <h3>Platform.sh and Drupal 7.32 Core SQL Injection</h3>
          </div>

          <span>Wednesday, October 15th 2014</span>
        </a>

        <a href="/posts/unknown/wunderkraut-chooses-platform">
          <div>
            <h3>Wunderkraut adopts Platform.sh for all of its 14 international offices</h3>
          </div>

          <span>Tuesday, September 30th 2014</span>
        </a>

        <a href="/posts/unknown/platform-removes-developer-overhead-6">
          <div>
            <h3>FlixBus launches new eCommerce Service on Platform.sh Enterprise</h3>
          </div>

          <span>Tuesday, September 23rd 2014</span>
        </a>

        <a href="/posts/unknown/release-cli-1-1">
          <div>
            <h3>CLI version 1.1 released</h3>
          </div>

          <span>Tuesday, September 9th 2014</span>
        </a>

        <a href="/posts/unknown/platform-removes-developer-overhead">
          <div>
            <h3>How the Platform.sh PaaS removes developer overhead</h3>
          </div>

          <span>Thursday, July 31st 2014</span>
        </a>

        <a href="/posts/unknown/commerce-guys-launches-platform">
          <div>
            <h3>Commerce Guys Launches Platform.sh, Continuous Delivery Cloud on Amazon Web Services</h3>
          </div>

          <span>Tuesday, May 13th 2014</span>
        </a>
      </ShowMore>

      <ShowMore>
        <a href="/posts/insights/session-storage-gets-complicated-faster-than-you-think">
          <div>
            <div>
              <span>Wednesday, September 30th 2026</span>
            </div>

            <h3>Session storage gets complicated faster than you think</h3>
            <p>Explore session storage tradeoffs across files, PostgreSQL, Redis, and Valkey, from expiration and cleanup to memory limits. Test your options on Upsun Cloud.</p>
          </div>
        </a>

        <a href="/posts/how-it-works/airflow-on-a-locked-down-platform">
          <div>
            <div>
              <span>Tuesday, September 22nd 2026</span>
            </div>

            <h3>Airflow on a locked-down platform</h3>
            <p>Running Apache Airflow on Upsun's hardened containers takes 30 lines of C and a decision about how much task isolation you actually want back.</p>
          </div>
        </a>

        <a href="/posts/ai/prompts-are-the-new-legacy-code">
          <div>
            <div>
              <span>Thursday, September 10th 2026</span>
            </div>

            <h3>Prompts are the new legacy code</h3>
            <p>Dispatch's code review agent lost 80% of its prompt and four sub-agents. Same model, same quality, cost more than halved, 25% faster. Here's the method.</p>
          </div>
        </a>

        <a href="/posts/discussions/give-your-ai-agent-a-system-that-is-safe-to-break">
          <div>
            <div>
              <span>Tuesday, September 8th 2026</span>
            </div>

            <h3>Give your AI agent a system that is safe to break</h3>
            <p>Handing an agent credentials narrows what it can do, not where its mistakes land. Run it inside a branched environment instead, and the worst outcome is a broken copy of your stack.</p>
          </div>
        </a>

        <a href="/posts/how-it-works/how-to-host-a-website-that-isnt-publicly-reachable">
          <div>
            <div>
              <span>Thursday, September 3rd 2026</span>
            </div>

            <h3>How to host a website that isn't publicly reachable</h3>
            <p>Some applications should never answer a request from the open internet. Here are the ways to make one unreachable on Upsun, and how to pick between them.</p>
          </div>
        </a>

        <a href="/posts/tutorials/ai-log-analysis-agent-in-an-upsun-task-container">
          <div>
            <div>
              <span>Tuesday, September 1st 2026</span>
            </div>

            <h3>Run an AI Log-Analysis Agent in an Upsun Task Container</h3>
            <p>Reuse the cron-triggers-a-task pattern to run an OpenCode AI agent inside an Upsun task container. The agent reads your cron and application logs, analyzes them, and writes a Markdown health report to the task logs and a temporary file.</p>
          </div>
        </a>

        <a href="/posts/how-it-works/why-lets-encrypt-certificate-renewals-fail">
          <div>
            <div>
              <span>Tuesday, August 25th 2026</span>
            </div>

            <h3>Why Let's Encrypt certificate renewals fail</h3>
            <p>Certificate renewals fail for a handful of recurring reasons. Here's how the HTTP-01 challenge works and what breaks it, from IPv6 records to CDN rules.</p>
          </div>
        </a>

        <a href="/posts/tutorials/offload-heavy-jobs-to-upsun-task-containers-with-cron">
          <div>
            <div>
              <span>Thursday, August 20th 2026</span>
            </div>

            <h3>Offload Heavy Jobs to Upsun Task Containers, Triggered by Cron</h3>
            <p>Move long, resource-hungry jobs out of your crons and into on-demand Upsun task containers. Learn how to define a task, authorize your app to trigger it, and fire it from a lightweight cron for database imports or search reindexing.</p>
          </div>
        </a>

        <a href="/posts/how-it-works/how-ssh-authentication-works-on-upsun">
          <div>
            <div>
              <span>Tuesday, August 18th 2026</span>
            </div>

            <h3>How SSH authentication works on Upsun Cloud</h3>
            <p>Decode the SSH certificate the Upsun CLI provisions for you, then follow it through the SSH proxy: CA trust, revocation, access documents, and MFA.</p>
          </div>
        </a>

        <a href="/posts/ai/how-to-choose-a-code-index-for-your-coding-agent">
          <div>
            <div>
              <span>Tuesday, August 4th 2026</span>
            </div>

            <h3>How to choose a code index for your coding agent</h3>
            <p>Compare Graft and roam-code on a real Go, TypeScript, Swift, and SQL codebase to evaluate context coverage, retrieval quality, and change analysis in practice.</p>
          </div>
        </a>

        <a href="/posts/insights/which-stack-would-you-pick-for-an-interactive-ai-app-today">
          <div>
            <div>
              <span>Friday, July 31st 2026</span>
            </div>

            <h3>Which stack would you pick for an interactive AI app today?</h3>
            <p>Coding agents changed how new teams pick a tech stack. A tour of 8 ecosystems for interactive AI apps, and why "can we run it" beats "can we write it".</p>
          </div>
        </a>

        <a href="/posts/how-it-works/backup-consistency-why-it-matters-and-how-upsun-handles-it">
          <div>
            <div>
              <span>Tuesday, July 21st 2026</span>
            </div>

            <h3>Backup consistency: why it matters and how Upsun handles it</h3>
            <p>Learn what backup consistency means at the filesystem and service levels, and how Upsun balances consistent backups with zero-disruption live backups.</p>
          </div>
        </a>

        <a href="/posts/how-it-works/can-you-trust-the-x-client-ip-header">
          <div>
            <div>
              <span>Tuesday, July 14th 2026</span>
            </div>

            <h3>Can you trust the X-Client-IP header?</h3>
            <p>Why the X-Client-IP header on Upsun holds the real visitor IP behind Fastly, Cloudflare, and CloudFront, and how to log real client IPs behind any other CDN.</p>
          </div>
        </a>

        <a href="/posts/how-it-works/write-a-git-server-with-per-branch-permissions-in-five-minutes">
          <div>
            <div>
              <span>Tuesday, July 7th 2026</span>
            </div>

            <h3>Write a Git server with per-branch permissions in five minutes</h3>
            <p>Upsun's most basic API is a Git server. Build one in Python with Dulwich and Paramiko, and add per-branch read permissions in a single method.</p>
          </div>
        </a>

        <a href="/posts/insights/why-emacs-is-still-my-interface-to-my-computer">
          <div>
            <div>
              <span>Tuesday, June 30th 2026</span>
            </div>

            <h3>Why Emacs is still my interface to my computer</h3>
            <p>Why I still use Emacs every day: one consistent interface for editing, Git with Magit, terminals, a Claude Code agent per project, and the rest of my computer.</p>
          </div>
        </a>

        <a href="/posts/hands-on/civicrm-with-wordpress-bedrock-on-upsun">
          <div>
            <div>
              <span>Tuesday, June 30th 2026</span>
            </div>

            <h3>CiviCRM with WordPress Bedrock on Upsun</h3>
            <p>A guide to deploying CiviCRM on top of a Bedrock-based WordPress installation on Upsun, utilizing an optimized Composer template and MariaDB schemas.</p>
          </div>
        </a>

        <a href="/posts/how-it-works/cloning-a-terabyte-in-a-minute-and-the-limit-hiding-behind-it">
          <div>
            <div>
              <span>Tuesday, June 23rd 2026</span>
            </div>

            <h3>Cloning a terabyte in a minute, and the limit hiding behind it</h3>
            <p>Upsun clones a terabyte production environment in under a minute using Ceph copy-on-write. Here is the 16-level clone-depth limit behind it, why flattening is the price you pay, and what it says about engineering trade-offs.</p>
          </div>
        </a>

        <a href="/posts/how-it-works/how-redundancy-and-failover-work-on-upsun">
          <div>
            <div>
              <span>Tuesday, June 16th 2026</span>
            </div>

            <h3>How redundancy and failover work on Upsun</h3>
            <p>Upsun handles redundancy and failover inside your region, at the compute, storage, and network layers. Here's where it happens, how fast it is, and the trade-offs behind it.</p>
          </div>
        </a>

        <a href="/posts/insights/code-matters-less-than-ever-and-more-than-ever">
          <div>
            <div>
              <span>Tuesday, June 9th 2026</span>
            </div>

            <h3>Code matters less than ever, and more than ever</h3>
            <p>AI made code cheap to write and cheap to throw away, so it matters less than ever. It also matters more, because debugging, reviews, and velocity all depend on it.</p>
          </div>
        </a>

        <a href="/posts/how-it-works/upsun-deployment-hooks-and-commands-which-one-to-use-and-when">
          <div>
            <div>
              <span>Thursday, June 4th 2026</span>
            </div>

            <h3>Upsun deployment hooks and commands: which one to use, and when</h3>
            <p>Build hooks, deploy hooks, pre\_start, start, and post\_start all shape how Upsun deploys your app. Learn what each one does and when to reach for it.</p>
          </div>
        </a>

        <a href="/posts/ai/opencode-token-optimization">
          <div>
            <div>
              <span>Tuesday, June 2nd 2026</span>
            </div>

            <h3>How to slash OpenCode Token costs by 90% on Upsun</h3>
            <p>Cut your OpenCode token usage by up to 90% on Upsun with three community plugins: OpenSlimedit, opencode-dcp, and opencode-snip. Step-by-step guide to install and configure them on your existing deployment, with benchmarks, troubleshooting, and best practices.</p>
          </div>
        </a>

        <a href="/posts/tutorials/deploying-laravel-reverb-on-upsun">
          <div>
            <div>
              <span>Thursday, May 21st 2026</span>
            </div>

            <h3>Deploying Laravel Reverb on Upsun</h3>
            <p>Build a real-time voting app with Laravel and Reverb, deploy it to Upsun, then scale the WebSocket layer horizontally with Redis pub/sub.</p>
          </div>
        </a>

        <a href="/posts/insights/ddev-is-in-good-hands">
          <div>
            <div>
              <span>Thursday, May 21st 2026</span>
            </div>

            <h3>DDEV is in good hands</h3>
            <p>DDEV is alive, actively maintained, and back with its foundation. A look at our chapter in the project, why we got involved, and why we are happy to step out of the way.</p>
          </div>
        </a>

        <a href="/posts/ai/opencode-on-upsun">
          <div>
            <div>
              <span>Tuesday, May 19th 2026</span>
            </div>

            <h3>How to Host OpenCode on Upsun</h3>
            <p>Deploy an OpenCode AI coding agent on Upsun with a single git push. This tutorial covers configuration, persistent storage, LLM API keys, and remote MCP server integration.</p>
          </div>
        </a>

        <a href="/posts/insights/rate-limiting-rails-apps-when-you-cant-put-varnish-in-front">
          <div>
            <div>
              <span>Tuesday, May 12th 2026</span>
            </div>

            <h3>Rate limiting Rails apps when you can't put Varnish in front</h3>
            <p>When the edge isn't yours, rate limit from inside the application. How rack-attack works, why limits are about quality of service, and what Rails 8 changed.</p>
          </div>
        </a>

        <a href="/posts/insights/the-not-so-hidden-cost-of-ai-scrapers">
          <div>
            <div>
              <span>Tuesday, May 5th 2026</span>
            </div>

            <h3>The (not so) hidden cost of AI scrapers</h3>
            <p>AI scrapers drive up your hosting cost while real users wait. Use robots.txt, cache normalization, and sane application limits to take the pressure off.</p>
          </div>
        </a>

        <a href="/posts/how-tos/supply-chain-attacks-in-the-ai-era-and-what-to-do-about-them">
          <div>
            <div>
              <span>Thursday, April 30th 2026</span>
            </div>

            <h3>Supply chain attacks in the AI era, and what to do about them</h3>
            <p>AI agents are reading code at scale, including your dependencies. Why supply chain risk just changed, plus a build-time fix to add on Upsun.</p>
          </div>
        </a>

        <a href="/posts/use-cases/n8n-upgrade-with-postgresql-and-redis">
          <div>
            <div>
              <span>Wednesday, April 29th 2026</span>
            </div>

            <h3>Scale n8n with PostgreSQL and Redis on Upsun</h3>
            <p>Upgrade your n8n instance from SQLite to PostgreSQL and add Redis caching for better performance, scalability, and reliability. Step-by-step guide for Upsun.</p>
          </div>
        </a>

        <a href="/posts/ai/aiweekly-2026-04-27">
          <div>
            <div>
              <span>Monday, April 27th 2026</span>
            </div>

            <h3>AI Weekly Review - Apr. 27th 2026</h3>
            <p>A press, Youtube and Github review of everything AI</p>
          </div>
        </a>

        <a href="/posts/how-it-works/building-observability-from-scratch-three-times-over">
          <div>
            <div>
              <span>Tuesday, April 21st 2026</span>
            </div>

            <h3>Building observability from scratch, three times over</h3>
            <p>A look back at how Platform.sh / Upsun's observability evolved from Nagios on a single box to a unified stack across thousands of VMs, and the migration patterns that made each transition smooth.</p>
          </div>
        </a>

        <a href="/posts/how-it-works/how-we-caught-a-silent-io-storm-before-it-hit-production">
          <div>
            <div>
              <span>Tuesday, April 14th 2026</span>
            </div>

            <h3>How we caught a silent IO storm before it hit production</h3>
            <p>A sysctl setting that worked fine for years caused over 500 MB/s of disk writes after migrating to Debian 12. MariaDB stalled on pending IO, Redis complained about slow fsync, and RBD-backed storage ground to a halt. The culprit: cgroup v2 changes how the kernel divides dirty page budgets across containers.</p>
          </div>
        </a>

        <a href="/posts/ai/aiweekly-2026-04-13">
          <div>
            <div>
              <span>Monday, April 13th 2026</span>
            </div>

            <h3>AI Weekly Review - Apr. 13th 2026</h3>
            <p>A press, Youtube and Github review of everything AI</p>
          </div>
        </a>

        <a href="/posts/how-it-works/how-upsun-provisions-tls-certificates-at-scale">
          <div>
            <div>
              <span>Thursday, April 9th 2026</span>
            </div>

            <h3>How Upsun provisions TLS certificates at scale</h3>
            <p>Every Upsun environment gets HTTPS automatically. Here's how the certificate system works, from wildcards to Let's Encrypt automation.</p>
          </div>
        </a>

        <a href="/posts/tutorials/sandboxing-ai-agents-on-upsun">
          <div>
            <div>
              <span>Wednesday, April 8th 2026</span>
            </div>

            <h3>Sandboxing AI agents on Upsun</h3>
            <p>Sandbox AI agents in Upsun containers to protect secrets from prompt injection. Covers Linux primitives, Claude Code, and Codex.</p>
          </div>
        </a>

        <a href="/posts/core-concepts/meta-upsun-validation-schema-dx-improvement">
          <div>
            <div>
              <span>Tuesday, April 7th 2026</span>
            </div>

            <h3>How Meta-Upsun improved Validation Schema and Developer eXperience</h3>
            <p>The introduction of Meta-Upsun enabled dynamic validation schemas and version enumeration for Upsun services and runtimes, significantly improving developer experience.</p>
          </div>
        </a>

        <a href="/posts/ai/aiweekly-2026-04-07">
          <div>
            <div>
              <span>Tuesday, April 7th 2026</span>
            </div>

            <h3>AI Weekly Review - Apr. 7th 2026</h3>
            <p>A press, Youtube and Github review of everything AI</p>
          </div>
        </a>

        <a href="/posts/how-it-works/why-upsun-moved-from-lvm-to-ceph">
          <div>
            <div>
              <span>Thursday, April 2nd 2026</span>
            </div>

            <h3>Why we moved from LVM to Ceph for container storage</h3>
            <p>Upsun migrated from LVM to Ceph for container storage to separate compute from storage, enable instant volume migration, and make VMs disposable again.</p>
          </div>
        </a>

        <a href="/posts/how-tos/meta-version-updater-introduction">
          <div>
            <div>
              <span>Wednesday, April 1st 2026</span>
            </div>

            <h3>Automating Runtime and Service Tracking with Meta Version Updater</h3>
            <p>Meta is Upsun’s shared reference layer for runtimes, services, regions, and extensions. Learn why we built it, how it works, and how it powers the next generation of Upsun documentation and tooling.</p>
          </div>
        </a>

        <a href="/posts/discussions/why-ai-agents-need-cloud-sandboxes">
          <div>
            <div>
              <span>Tuesday, March 31st 2026</span>
            </div>

            <h3>Why AI agents need cloud sandboxes</h3>
            <p>AI agents run real commands on real systems. Learn why cloud sandboxes with production data beat local isolation for safe AI agent workflows.</p>
          </div>
        </a>

        <a href="/posts/ai/aiweekly-2026-03-30">
          <div>
            <div>
              <span>Monday, March 30th 2026</span>
            </div>

            <h3>AI Weekly Review - Mar. 30th 2026</h3>
            <p>A press, Youtube and Github review of everything AI</p>
          </div>
        </a>

        <a href="/posts/ai/stuck-on-localhost">
          <div>
            <div>
              <span>Thursday, March 26th 2026</span>
            </div>

            <h3>Your agents are stuck on localhost. Upsun isn't.</h3>
            <p>Coding agents made engineers faster, but cycle time hasn't budged. Background agents running on GitHub, GitLab, and Claude Code can break the bottleneck by producing PRs that Upsun deploys and validates automatically. A practical guide to setting it up with real YAML configs, infrastructure-as-code workflows, and preview environments.</p>
          </div>
        </a>

        <a href="/posts/how-it-works/meta-reference-source-introduction">
          <div>
            <div>
              <span>Wednesday, March 25th 2026</span>
            </div>

            <h3>Centralising Upsun Technical References with Meta-Upsun</h3>
            <p>How Upsun centralised runtime, service, region, and PHP reference data into a single public API to improve consistency, automation, and documentation accuracy.</p>
          </div>
        </a>

        <a href="/posts/discussions/governance-is-a-contract-chain-and-youre-in-it">
          <div>
            <div>
              <span>Tuesday, March 24th 2026</span>
            </div>

            <h3>Governance is a contract chain, and you're in it</h3>
            <p>Governance is a chain of contracts from certification bodies to you. AI didn't change the chain, but it produces code faster than humans can review it.</p>
          </div>
        </a>

        <a href="/posts/ai/aiweekly-2026-03-23">
          <div>
            <div>
              <span>Monday, March 23rd 2026</span>
            </div>

            <h3>AI Weekly Review - Mar. 23rd 2026</h3>
            <p>A press, Youtube and Github review of everything AI</p>
          </div>
        </a>

        <a href="/posts/how-it-works/rpm-repo-s3">
          <div>
            <div>
              <span>Tuesday, March 17th 2026</span>
            </div>

            <h3>How we host an RPM repository on AWS S3</h3>
            <p>Learn how to host an RPM repository entirely on AWS S3 with no active components, minimal cost, and authenticated access using IAM.</p>
          </div>
        </a>

        <a href="/posts/releases/introducing-developer-upsun-com">
          <div>
            <div>
              <span>Monday, March 16th 2026</span>
            </div>

            <h3>Introducing developer.upsun.com: Upsun docs, rebuilt for developers and AI agents</h3>
            <p>The Upsun documentation has moved to developer.upsun.com with a complete infrastructure rebuild focused on agent-readiness. 244+ pages of structured, machine-readable content with llms.txt support and built-in AI assistance.</p>
          </div>
        </a>

        <a href="/posts/ai/aiweekly-2026-03-16">
          <div>
            <div>
              <span>Monday, March 16th 2026</span>
            </div>

            <h3>AI Weekly Review - Mar. 16th 2026</h3>
            <p>A press, Youtube and Github review of everything AI</p>
          </div>
        </a>

        <a href="/posts/how-it-works/natural-scaling-for-multi-country-ecommerce">
          <div>
            <div>
              <span>Thursday, March 12th 2026</span>
            </div>

            <h3>Natural scaling for multi-country ecommerce</h3>
            <p>Multi-country ecommerce is a textbook case for natural scaling. Instead of cramming every country into one store, give each its own. Here's why.</p>
          </div>
        </a>

        <a href="/posts/how-tos/replicate-your-production-outage-on-staging">
          <div>
            <div>
              <span>Tuesday, March 10th 2026</span>
            </div>

            <h3>Replicate your production outage on staging</h3>
            <p>After fixing a production outage, you need to prove the fix works under the same traffic. Here's how to replicate real production traffic on an Upsun staging environment using the observability API and k6.</p>
          </div>
        </a>

        <a href="/posts/ai/aiweekly-2026-03-09">
          <div>
            <div>
              <span>Monday, March 9th 2026</span>
            </div>

            <h3>AI Weekly Review - Mar. 9th 2026</h3>
            <p>A press, Youtube and Github review of everything AI</p>
          </div>
        </a>

        <a href="/posts/discussions/how-product-managers-use-preview-environments-and-ai-to-prototype">
          <div>
            <div>
              <span>Thursday, March 5th 2026</span>
            </div>

            <h3>How product managers use preview environments and AI to prototype</h3>
            <p>Learn how product managers at Upsun use AI coding assistants and preview environments to prototype feature ideas, validate concepts with real data, and share interactive demos with stakeholders.</p>
          </div>
        </a>

        <a href="/posts/hands-on/that-cron-should-be-a-worker">
          <div>
            <div>
              <span>Wednesday, March 4th 2026</span>
            </div>

            <h3>That cron should be a worker</h3>
            <p>Long-running crons block your deployments, steal resources from your app container, and create support tickets. Here's when to use workers instead.</p>
          </div>
        </a>

        <a href="/posts/how-tos/fastly-cdn-and-waf">
          <div>
            <div>
              <span>Tuesday, March 3rd 2026</span>
            </div>

            <h3>Speed vs. Security? Why not both: The Fastly CDN and WAF on Upsun</h3>
            <p>Learn how to pair Fastly’s CDN for speed with its Next-Gen WAF for security on Upsun. Optimize global performance while protecting your infrastructure from threats.</p>
          </div>
        </a>

        <a href="/posts/ai/aiweekly-2026-03-02">
          <div>
            <div>
              <span>Monday, March 2nd 2026</span>
            </div>

            <h3>AI Weekly Review - Mar. 2nd 2026</h3>
            <p>A press, Youtube and Github review of everything AI</p>
          </div>
        </a>

        <a href="/posts/tutorials/deploy-mattermost-on-upsun">
          <div>
            <div>
              <span>Friday, February 27th 2026</span>
            </div>

            <h3>Deploy Mattermost Team Edition on Upsun</h3>
            <p>Learn how to deploy a self-hosted Mattermost Team Edition server on Upsun, with PostgreSQL 16 and OpenSearch 2 configured automatically through a single infrastructure-as-code file.</p>
          </div>
        </a>

        <a href="/posts/discussions/cpu-vs-gpu">
          <div>
            <div>
              <span>Thursday, February 26th 2026</span>
            </div>

            <h3>CPU vs GPU for AI: most AI applications don't need GPUs</h3>
            <p>How to build and deploy an Angular application on Upsun.</p>
          </div>
        </a>

        <a href="/posts/releases/upsun-node-sdk-announcement">
          <div>
            <div>
              <span>Wednesday, February 25th 2026</span>
            </div>

            <h3>Announcing the Official Upsun Node.js SDK</h3>
            <p>Discover how the Upsun Node SDK simplifies API access and speeds up integrations, with clear documentation and modern tooling.</p>
          </div>
        </a>

        <a href="/posts/discussions/instant-data-cloning-was-a-bet-ai-agents-are-the-payoff">
          <div>
            <div>
              <span>Tuesday, February 24th 2026</span>
            </div>

            <h3>Instant data cloning was a bet. AI agents are the payoff.</h3>
            <p>How Upsun's data-first architecture, built a decade ago for CMS and e-commerce needs, turns out to be the exact infrastructure AI agents need: instant, isolated, production-identical environments with real data.</p>
          </div>
        </a>

        <a href="/posts/ai/aiweekly-2026-02-23">
          <div>
            <div>
              <span>Monday, February 23rd 2026</span>
            </div>

            <h3>AI Weekly Review - Feb. 23th 2026</h3>
            <p>A press, Youtube and Github review of everything AI</p>
          </div>
        </a>

        <a href="/posts/ai/agents-md-less-is-more">
          <div>
            <div>
              <span>Monday, February 23rd 2026</span>
            </div>

            <h3>The research is in: your AGENTS.md is probably too long</h3>
            <p>Research shows comprehensive AGENTS.md files actually hurt coding agent performance. Learn why less is more and how to build context files that work.</p>
          </div>
        </a>

        <a href="/posts/discussions/building-an-ai-code-review-agent-for-gitlab">
          <div>
            <div>
              <span>Thursday, February 19th 2026</span>
            </div>

            <h3>Building an AI code review agent for our self-hosted GitLab</h3>
            <p>I vibe-coded a GitLab code review agent last month - 40K lines of Python written by Claude - and it has reviewed 1000 merge requests.</p>
          </div>
        </a>

        <a href="/posts/how-it-works/your-waf-is-buffering-ours-is-streaming">
          <div>
            <div>
              <span>Wednesday, February 18th 2026</span>
            </div>

            <h3>Your WAF is buffering. Ours is streaming.</h3>
            <p>Most WAFs buffer your entire request before validating it. That's slow. Upsun's technical WAF validates requests while streaming them to your backend, so you don't pay a latency tax for security.</p>
          </div>
        </a>

        <a href="/posts/ai/aiweekly-2026-02-17">
          <div>
            <div>
              <span>Tuesday, February 17th 2026</span>
            </div>

            <h3>AI Weekly Review - Feb. 17th 2026</h3>
            <p>A press, Youtube and Github review of everything AI</p>
          </div>
        </a>

        <a href="/posts/ai/making-coding-agents-reliable">
          <div>
            <div>
              <span>Tuesday, February 17th 2026</span>
            </div>

            <h3>Making coding agents (Claude Code, Codex, etc.) reliable</h3>
            <p>The bottleneck for AI coding agents isn't model capability. It's your verification infrastructure. Here's how to fix that.</p>
          </div>
        </a>

        <a href="/posts/hands-on/the-real-story-of-setting-up-drupal-canvas-with-ai">
          <div>
            <div>
              <span>Friday, February 13th 2026</span>
            </div>

            <h3>From DrupalCon keynote to live Upsun demo: the real story of setting up Drupal Canvas with AI</h3>
            <p>Discover how the Lemberg Solutions team set up Drupal Canvas with an AI assistant: how long it took, the challenges we faced and lessons we learned.</p>
          </div>
        </a>

        <a href="/posts/ai/git-worktrees-for-parallel-ai-coding-agents">
          <div>
            <div>
              <span>Wednesday, February 11th 2026</span>
            </div>

            <h3>Git worktrees for parallel AI coding agents</h3>
            <p>Learn how git worktrees enable parallel AI agent workflows, their limitations, and what an ideal orchestration tool needs.</p>
          </div>
        </a>

        <a href="/posts/hands-on/scriberr-on-upsun">
          <div>
            <div>
              <span>Tuesday, February 10th 2026</span>
            </div>

            <h3>Scriberr on Upsun</h3>
            <p>Learn how to deploy Scriberr, an AI-powered transcription tool, on Upsun for self-hosted audio and video transcription.</p>
          </div>
        </a>

        <a href="/posts/hands-on/unstable-website-use-queues">
          <div>
            <div>
              <span>Thursday, February 5th 2026</span>
            </div>

            <h3>Unstable website? Use queues.</h3>
            <p>Your site throws 502 errors when external APIs are slow. The fix isn't more resources. It's offloading that work to background jobs so your responses stay fast.</p>
          </div>
        </a>

        <a href="/posts/core-concepts/eliminating-database-pwd-risk-with-network-isolation">
          <div>
            <div>
              <span>Wednesday, February 4th 2026</span>
            </div>

            <h3>Eliminating Database Password Risk with Network Isolation</h3>
            <p>By removing default database passwords, Upsun reduces common credential risks (leaks, reuse, hardcoding) and relies on stronger security controls like SSH keys and private networking.</p>
          </div>
        </a>

        <a href="/posts/insights/the-only-correct-way-to-git-pull-and-merge">
          <div>
            <div>
              <span>Tuesday, February 3rd 2026</span>
            </div>

            <h3>The only correct way to git pull and merge</h3>
            <p>A strongly opinionated guide to git pull and merge strategies that will make your commit history actually useful. Learn when to rebase, when to merge, and why the defaults are lying to you.</p>
          </div>
        </a>

        <a href="/posts/ai/will-ai-make-software-companies-worthless">
          <div>
            <div>
              <span>Friday, January 30th 2026</span>
            </div>

            <h3>Will AI make software companies worthless?</h3>
            <p>If anyone can build software with AI, do software companies still matter? The answer is more nuanced than you might think.</p>
          </div>
        </a>

        <a href="/posts/how-it-works/spf-dkim-dmarc-what-are-those-for-anyway">
          <div>
            <div>
              <span>Thursday, January 29th 2026</span>
            </div>

            <h3>SPF, DKIM, DMARC, what are those for anyway?</h3>
            <p>Finally understand what SPF, DKIM, and DMARC actually do, why email needs them, and how to set them up without wanting to flip a table.</p>
          </div>
        </a>

        <a href="/posts/insights/the-third-way-to-scale-that-nobody-talks-about">
          <div>
            <div>
              <span>Tuesday, January 20th 2026</span>
            </div>

            <h3>The third way to scale that nobody talks about</h3>
            <p>Beyond vertical and horizontal scaling lies a third approach that most scaling discussions ignore. Learn about natural scaling, where you sidestep the problem entirely.</p>
          </div>
        </a>

        <a href="/posts/hands-on/how-to-use-harlequin-sql-ide-with-upsun">
          <div>
            <div>
              <span>Wednesday, January 14th 2026</span>
            </div>

            <h3>How to Use Harlequin SQL IDE with Upsun</h3>
            <p>Learn two ways to connect Harlequin SQL IDE to your Upsun PostgreSQL database: using local SSH tunnels or deploying Harlequin directly on the platform.</p>
          </div>
        </a>

        <a href="/posts/how-it-works/how-weve-been-hardening-containers-since-before-docker-made-it-cool">
          <div>
            <div>
              <span>Tuesday, January 13th 2026</span>
            </div>

            <h3>How we've been hardening containers since before Docker made it cool</h3>
            <p>Docker's hardened images are great, but we've been doing this for years. Here's the automated pipeline that's been securing hundreds of container images behind the scenes at Upsun.</p>
          </div>
        </a>

        <a href="/posts/how-tos/automated-encrypt-backups-amazon-s3">
          <div>
            <div>
              <span>Monday, January 12th 2026</span>
            </div>

            <h3>Automated encrypted backups to Amazon S3 | Upsun</h3>
            <p>Learn how to configure Duplicity, GPG keys, and cron on Upsun to send incremental, encrypted backups of your application to AWS S3 for reliable restores</p>
          </div>
        </a>

        <a href="/posts/discussions/the-universal-commerce-protocol-and-the-inevitable-rise-of-agentic-commerce">
          <div>
            <div>
              <span>Monday, January 12th 2026</span>
            </div>

            <h3>The universal commerce protocol and the inevitable rise of agentic commerce</h3>
            <p>Fifteen years ago, I believed the trajectory of digital commerce was destined for a singular, consolidated fate. To me, the technological landscape was fracturing rapidly; the desktop monopoly had shattered, giving way to the mobile web, native applications, and the nascent experiments of Google Glass and early IoT devices. In my view, for independent brands and retailers, this multiplication of channels represented a terrifying escalation in technical complexity. To sell effectively, I thought a merchant needed not just a website, but a mobile-responsive design, an iOS app, an Android app, and integrations with a growing roster of marketplaces.</p>
          </div>
        </a>

        <a href="/posts/hands-on/stop-testing-jcr-apps-in-production">
          <div>
            <div>
              <span>Tuesday, January 6th 2026</span>
            </div>

            <h3>Stop testing JCR apps in production</h3>
            <p>Learn why JCR-based applications benefit from fast, production-grade environment cloning. Discover how Upsun removes one of JCR's biggest operational challenges through instant repository duplication.</p>
          </div>
        </a>

        <a href="/posts/releases/composer-2.9">
          <div>
            <div>
              <span>Thursday, December 25th 2025</span>
            </div>

            <h3>Composer 2.9 lands on Upsun PHP Images: Here’s what you need to know</h3>
            <p>Remote code execution vulnerability in Next.js 15.x and 16.x App Router requires immediate patching. Learn how to secure your applications.</p>
          </div>
        </a>

        <a href="/posts/hands-on/civicrm-drupal-11-on-upsun">
          <div>
            <div>
              <span>Friday, December 19th 2025</span>
            </div>

            <h3>Installing CiviCRM with Drupal 11 on Upsun</h3>
            <p>Learn how to install CiviCRM with Drupal 11 on Upsun, from config.yml and databases to cron, caching, extensions and Skvare’s best-practice template.</p>
          </div>
        </a>

        <a href="/posts/discussions/whatsun-efficient-code-analysis">
          <div>
            <div>
              <span>Thursday, December 18th 2025</span>
            </div>

            <h3>Efficient code analysis for LLMs</h3>
            <p>Learn how Whatsun generates concise codebase summaries to improve the performance and accuracy of AI features.</p>
          </div>
        </a>

        <a href="/posts/unknown/how-we-scaled-live-connections-for-1200-developers-at-symfonycon">
          <div>
            <div>
              <span>Wednesday, December 17th 2025</span>
            </div>

            <h3>How we scaled live connections for 1200 developers at SymfonyCon</h3>
            <p>A Symfony core contributor's journey from FrankenPHP 502 errors to a stable multi-app architecture that handled hundreds of live connections at SymfonyCon 2025.</p>
          </div>
        </a>

        <a href="/posts/hands-on/migration-day-executing-your-upsun-cutover">
          <div>
            <div>
              <span>Tuesday, December 16th 2025</span>
            </div>

            <h3>Migration day: executing your Upsun cutover</h3>
            <p>A step-by-step guide to migration day: maintenance windows, cutover sequences, verification, and post-migration monitoring strategies.</p>
          </div>
        </a>

        <a href="/posts/releases/composable-image-embraces-real-world-diversity">
          <div>
            <div>
              <span>Thursday, December 11th 2025</span>
            </div>

            <h3>One project, many needs: How Composable Image embraces real-world diversity</h3>
            <p>Applications rarely fit inside a single tidy runtime box. They evolve through experiments, architectural shifts, quick MVP spikes that outlast their intended lifespan, and the continuous layering of new business needs.</p>
          </div>
        </a>

        <a href="/posts/how-it-works/keeping-the-peace-how-zookeeper-stops-database-nodes-from-fighting">
          <div>
            <div>
              <span>Tuesday, December 9th 2025</span>
            </div>

            <h3>Keeping the peace: how ZooKeeper stops database nodes from fighting</h3>
            <p>Learn how Upsun uses Zookeeper's sequences, watchers, and ephemeral nodes to coordinate MariaDB clusters and workers across distributed systems without breaking your application.</p>
          </div>
        </a>

        <a href="/posts/insights/why-you-cant-just-add-infinite-php-fpm-workers">
          <div>
            <div>
              <span>Monday, December 8th 2025</span>
            </div>

            <h3>Why you can't just add infinite PHP-FPM workers</h3>
            <p>Workers need memory. Learn how PHP-FPM sizing hints work, why you can't just add infinite workers, and how to tune your worker count based on actual memory usage.</p>
          </div>
        </a>

        <a href="/posts/discussions/building-ai-feature-necessary-evals">
          <div>
            <div>
              <span>Thursday, December 4th 2025</span>
            </div>

            <h3>Building an AI feature: The necessary evals</h3>
            <p>What we learned building an AI feature: evaluations take most of the time, and your existing tools are enough.</p>
          </div>
        </a>

        <a href="/posts/discussions/nextjs-cve-2025-66478">
          <div>
            <div>
              <span>Thursday, December 4th 2025</span>
            </div>

            <h3>Critical Next.js Security Update: CVE-2025-66478 Affects RSC</h3>
            <p>Remote code execution vulnerability in Next.js 15.x and 16.x App Router requires immediate patching. Learn how to secure your applications.</p>
          </div>
        </a>

        <a href="/posts/hands-on/zero-downtime-deployments-with-upsun">
          <div>
            <div>
              <span>Wednesday, December 3rd 2025</span>
            </div>

            <h3>Zero-downtime deployments: now in open beta</h3>
            <p>We've launched zero-downtime deployments in open beta. Deploy your applications without service interruption.</p>
          </div>
        </a>

        <a href="/posts/tutorials/angular-and-upsun">
          <div>
            <div>
              <span>Wednesday, December 3rd 2025</span>
            </div>

            <h3>Building and Deploying Angular Apps on Upsun</h3>
            <p>How to build and deploy an Angular application on Upsun.</p>
          </div>
        </a>

        <a href="/posts/how-tos/planning-your-upsun-migration-the-6-9-week-roadmap">
          <div>
            <div>
              <span>Tuesday, December 2nd 2025</span>
            </div>

            <h3>Planning your Upsun migration: the 6-9 week roadmap</h3>
            <p>Learn why 6-9 weeks is the ideal timeline for Upsun migrations, with expert insights on planning, testing, and avoiding common pitfalls.</p>
          </div>
        </a>

        <a href="/posts/insights/why-setting-your-php-memory-limit-to-60gb-wont-help">
          <div>
            <div>
              <span>Monday, December 1st 2025</span>
            </div>

            <h3>Why setting your PHP memory limit to 60GB won't help</h3>
            <p>When you see a PHP memory limit error, your instinct shouldn't be to just increase the limit. Learn what PHP memory\_limit actually does and why blindly increasing it can hurt your site's uptime.</p>
          </div>
        </a>

        <a href="/posts/hands-on/ai-use-case-generate-load-test-scenarios">
          <div>
            <div>
              <span>Thursday, November 27th 2025</span>
            </div>

            <h3>AI use-case: Generate load test scenarios with MCPs</h3>
            <p>Automate Locust load testing by combining Chrome MCP and Context7 to generate realistic user behavior patterns with Claude Code.</p>
          </div>
        </a>

        <a href="/posts/insights/my-terminal-setup-mac-linux">
          <div>
            <div>
              <span>Wednesday, November 26th 2025</span>
            </div>

            <h3>My terminal setup (Mac & Linux)</h3>
            <p>A no-nonsense guide to transforming your terminal from painful to powerful with GhostTTY, NeoVim, and Claude Code</p>
          </div>
        </a>

        <a href="/posts/how-it-works/when-php-fpm-runs-out-of-workers-a-502-error-field-guide">
          <div>
            <div>
              <span>Monday, November 24th 2025</span>
            </div>

            <h3>When php-fpm runs out of workers: a 502 error field guide</h3>
            <p>Your PHP site keeps throwing 502 errors. Your CDN shows 503s. Learn why PHP-FPM workers get exhausted and how to diagnose and fix the real problems.</p>
          </div>
        </a>

        <a href="/posts/releases/php-85-release">
          <div>
            <div>
              <span>Thursday, November 20th 2025</span>
            </div>

            <h3>PHP 8.5 is here!</h3>
            <p>What if the next PHP revolution made no noise but completely transformed your developer daily life?</p>
          </div>
        </a>

        <a href="/posts/how-it-works/we-switched-from-lvm-to-sparse-files">
          <div>
            <div>
              <span>Friday, November 14th 2025</span>
            </div>

            <h3>We switched from LVM to... sparse files?!</h3>
            <p>How we eliminated 90% of VM evacuation time by replacing LVM with sparse files for temporary storage. A tale of inertia, performance bottlenecks, and surprisingly effective solutions.</p>
          </div>
        </a>

        <a href="/posts/how-tos/creating-custom-reports-using-cli">
          <div>
            <div>
              <span>Wednesday, November 12th 2025</span>
            </div>

            <h3>Creating Custom Reports using the Upsun Cloud CLI</h3>
            <p>Someone recently asked me</p>
          </div>
        </a>

        <a href="/posts/insights/the-mystery-of-the-shrinking-database-dump">
          <div>
            <div>
              <span>Monday, November 10th 2025</span>
            </div>

            <h3>The mystery of the shrinking database dump</h3>
            <p>Your database uses 10GB but dumps to 100MB. Discover why database dumps shrink, how InnoDB fragmentation works, and how to reclaim that missing storage space.</p>
          </div>
        </a>

        <a href="/posts/hands-on/varnish-104-advanced-traffic-filtering-with-classification-headers-on-upsun">
          <div>
            <div>
              <span>Friday, November 7th 2025</span>
            </div>

            <h3>Varnish 104: Advanced Traffic Filtering with Classification Headers on Upsun</h3>
            <p>Learn how to implement advanced security controls in Varnish on Upsun using classification headers to block malicious traffic, restrict geographic access, filter by ASN, and protect sensitive paths with HTTP Basic Auth.</p>
          </div>
        </a>

        <a href="/posts/releases/upsun-php-sdk-announcement">
          <div>
            <div>
              <span>Tuesday, November 4th 2025</span>
            </div>

            <h3>Introducing the Upsun PHP SDK</h3>
            <p>Discover how the Upsun PHP SDK simplifies API access and speeds up integrations, with clear documentation and modern tooling.</p>
          </div>
        </a>

        <a href="/posts/how-it-works/we-made-our-infrastructure-read-only-and-never-looked-back">
          <div>
            <div>
              <span>Monday, November 3rd 2025</span>
            </div>

            <h3>We made our infrastructure read-only and never looked back</h3>
            <p>Learn why read-only infrastructure eliminates entire classes of security attacks, improves reproducibility, and simplifies compliance while enabling predictable deployments.</p>
          </div>
        </a>

        <a href="/posts/hands-on/varnish-103-cache-optimization-with-url-normalization-on-upsun">
          <div>
            <div>
              <span>Friday, October 31st 2025</span>
            </div>

            <h3>Varnish 103: Cache Optimization with URL Normalization on Upsun</h3>
            <p>Learn how to maximize Varnish cache efficiency through URL normalization, query string sorting, and tracking parameter removal to dramatically improve cache hit ratios and reduce backend load.</p>
          </div>
        </a>

        <a href="/posts/hands-on/varnish-102-protecting-your-application-with-rate-limiting-on-upsun">
          <div>
            <div>
              <span>Friday, October 24th 2025</span>
            </div>

            <h3>Varnish 102: Protecting Your Application with Rate Limiting on Upsun</h3>
            <p>Learn how to implement effective rate limiting in Varnish using the vsthrottle VMOD to protect your application from abuse, prevent DDoS attacks, and ensure fair resource allocation.</p>
          </div>
        </a>

        <a href="/posts/how-it-works/event-loop-monitoring-in-nextjs-performance-guide">
          <div>
            <div>
              <span>Friday, October 24th 2025</span>
            </div>

            <h3>Event Loop Monitoring in Next.js: Performance Guide</h3>
            <p>Learn to implement event loop monitoring in Next.js applications to identify blocking operations, optimize performance, and scale confidently with production-ready code.</p>
          </div>
        </a>

        <a href="/posts/how-it-works/autoscaling-deep-dive">
          <div>
            <div>
              <span>Monday, October 20th 2025</span>
            </div>

            <h3>Auto-scaling on Upsun Flex. A deep dive.</h3>
            <p>Learn how Upsun's autoscaling dynamically adjusts application instances based on CPU usage, ensuring performance during traffic spikes while optimizing costs.</p>
          </div>
        </a>

        <a href="/posts/hands-on/varnish-101-protecting-paths-with-http-basic-authentication-on-upsun">
          <div>
            <div>
              <span>Friday, October 17th 2025</span>
            </div>

            <h3>Varnish 101: Protecting Paths with HTTP Basic Authentication on Upsun</h3>
            <p>Learn how to implement HTTP Basic Authentication directly in Varnish VCL on Upsun to protect specific paths like admin areas, staging environments, and work-in-progress content without touching your backend.</p>
          </div>
        </a>

        <a href="/posts/how-it-works/fake-ip-till-you-make-ip">
          <div>
            <div>
              <span>Tuesday, October 14th 2025</span>
            </div>

            <h3>Fake IP till you make IP</h3>
            <p>How Upsun uses virtual IPs and NAT to keep your database connections stable even when containers move between VMs. A look at the networking tricks behind relationship stability.</p>
          </div>
        </a>

        <a href="/posts/how-tos/fastlycdn-pluginapp-activation">
          <div>
            <div>
              <span>Tuesday, October 7th 2025</span>
            </div>

            <h3>Streamline Your CDN Management with Fastly CDN Plugin App \[BETA]</h3>
            <p>Managing Content Delivery Network (CDN) configurations alongside your application deployments can be a complex task, often requiring developers to switch between multiple interfaces and tools. The Fastly CDN plugin app bridges this gap by bringing Fastly CDN management directly into your Upsun console, creating a seamless workflow for developers who want to manage their CDN configurations without leaving their primary development environment.</p>
          </div>
        </a>

        <a href="/posts/tutorials/deploying-open-source-on-upsun">
          <div>
            <div>
              <span>Tuesday, October 7th 2025</span>
            </div>

            <h3>Deploying open-source projects on Upsun: Snipe-IT as an example</h3>
            <p>Learn how to deploy any GitHub-hosted open-source project on Upsun by forking repositories, configuring for deployment, and keeping your fork synchronized with upstream updates.</p>
          </div>
        </a>

        <a href="/posts/insights/build-time-environment-variables-considered-harmful">
          <div>
            <div>
              <span>Monday, October 6th 2025</span>
            </div>

            <h3>Build-time environment variables considered harmful</h3>
            <p>Build-time environment variables break deployment caching, compromise security, and force unnecessary rebuilds. Learn why runtime configuration is the better alternative.</p>
          </div>
        </a>

        <a href="/posts/how-it-works/explore-plan-execute-methodology">
          <div>
            <div>
              <span>Friday, October 3rd 2025</span>
            </div>

            <h3>Mastering the Explore, Plan, Execute methodology for AI-assisted development</h3>
            <p>Learn how to transform AI coding assistants from eager juniors into rockstar developers using proven context strategies, quality assurance, and the three-phase workflow</p>
          </div>
        </a>

        <a href="/posts/tutorials/building-async-processing-pipelines-with-fastapi-and-celery-on-upsun">
          <div>
            <div>
              <span>Friday, October 3rd 2025</span>
            </div>

            <h3>Building async processing pipelines with FastAPI and Celery on Upsun</h3>
            <p>Learn how to build production-ready async processing pipelines using FastAPI and Celery on Upsun. From architecture design to deployment, discover how to handle long-running tasks without blocking your API responses.</p>
          </div>
        </a>

        <a href="/posts/hands-on/building-internal-ai-agents-for-our-teams-on-upsun">
          <div>
            <div>
              <span>Tuesday, September 30th 2025</span>
            </div>

            <h3>Building internal AI agents for our teams on Upsun</h3>
            <p>Learn how to build and deploy production-ready AI agents on Upsun using Google's ADK, ChromaDB vector database, and Retrieval-Augmented Generation (RAG) to create context-aware, domain-specific agents for your team.</p>
          </div>
        </a>

        <a href="/posts/ai/upsun-mcp-announcement">
          <div>
            <div>
              <span>Monday, September 22nd 2025</span>
            </div>

            <h3>Introducing the Upsun MCP server: bring Upsun into your LLMs</h3>
            <p>Manage your Upsun infrastructure directly through AI assistants with our new Model Context Protocol server - now in beta at mcp.upsun.com</p>
          </div>
        </a>

        <a href="/posts/insights/why-you-should-replace-postgresql-with-git-for-your-next-project">
          <div>
            <div>
              <span>Friday, September 19th 2025</span>
            </div>

            <h3>Why you should replace PostgreSQL with Git for your next project</h3>
            <p>Explore how Git's internal architecture makes it a surprisingly capable database alternative. Learn Git's data structures through a practical todo app implementation that might make you reconsider your database choices.</p>
          </div>
        </a>

        <a href="/posts/hands-on/run-tailscale-on-upsun-secure-vpn-connections">
          <div>
            <div>
              <span>Tuesday, September 16th 2025</span>
            </div>

            <h3>Run Tailscale on Upsun: Create secure VPN connections for your applications</h3>
            <p>Learn how to integrate Tailscale VPN with your Upsun applications to create secure, private network connections between your containers and infrastructure.</p>
          </div>
        </a>

        <a href="/posts/how-tos/composer1-rip">
          <div>
            <div>
              <span>Tuesday, September 9th 2025</span>
            </div>

            <h3>Composer 1 is dead – Upgrade to Composer 2 now</h3>
            <p>Composer 1 has reached end of life and is no longer available on Upsun and Platform.sh. Learn why it’s no longer possible to rely on Composer 1, what errors you’ll see, and how to safely upgrade your project to Composer 2.</p>
          </div>
        </a>

        <a href="/posts/how-it-works/cut-aws-bandwidth-costs-95-with-dm-cache">
          <div>
            <div>
              <span>Tuesday, September 9th 2025</span>
            </div>

            <h3>How we cut AWS bandwidth costs 95% with dm-cache: fast local SSD caching for network storage</h3>
            <p>Learn how Upsun solved costly inter-AZ bandwidth billing by implementing dm-cache with local SSDs, achieving 95% read traffic reduction and 30x performance improvement.</p>
          </div>
        </a>

        <a href="/posts/hands-on/store-embeddings-in-chroma-with-persistent-storage-nodejs-and-python-examples">
          <div>
            <div>
              <span>Wednesday, September 3rd 2025</span>
            </div>

            <h3>Store embeddings in chroma with persistent storage (nodejs and python examples)</h3>
            <p>Learn how to implement Chroma with persistent storage on Upsun using both Node.js and Python, including document ingestion and embedding storage.</p>
          </div>
        </a>

        <a href="/posts/hands-on/fastly-maintenance">
          <div>
            <div>
              <span>Monday, August 25th 2025</span>
            </div>

            <h3>How to enable custom maintenance page in Fastly</h3>
            <p>Configure GitLab CI/CD to deploy to Upsun from private air-gapped GitLab instances using push-based workflows and API automation.</p>
          </div>
        </a>

        <a href="/posts/how-it-works/how-do-we-do-incremental-but-really-full-backups-on-top-of-ceph">
          <div>
            <div>
              <span>Monday, August 25th 2025</span>
            </div>

            <h3>High-performance backups: How Ceph snapshots enable incremental full backups</h3>
            <p>Learn how Upsun leverages Ceph's RBD export-diff feature to implement high-performance incremental backups that maintain full restore capabilities for large-scale container storage.</p>
          </div>
        </a>

        <a href="/posts/hands-on/connect-multiple-projects-applications-or-services-together">
          <div>
            <div>
              <span>Friday, August 15th 2025</span>
            </div>

            <h3>Connect multiple projects applications or services together</h3>
            <p>Learn how to use Chisel to securely connect applications and services across different Upsun projects, with a practical MariaDB replication example.</p>
          </div>
        </a>

        <a href="/posts/insights/why-your-readme-matters-more-than-ai-configuration-files">
          <div>
            <div>
              <span>Tuesday, August 12th 2025</span>
            </div>

            <h3>AGENTS.md: Why your README matters more than AI configuration files</h3>
            <p>AGENTS.md promises to standardize AI coding assistant configuration, but the real solution is writing better READMEs that serve both humans and AI agents</p>
          </div>
        </a>

        <a href="/posts/insights/why-python-developers-should-switch-to-uv">
          <div>
            <div>
              <span>Thursday, August 7th 2025</span>
            </div>

            <h3>Why Python developers should switch to uv</h3>
            <p>Learn how uv, the revolutionary Python package manager, delivers 100x faster installations and streamlines project management with automatic virtual environments and dependency tracking.</p>
          </div>
        </a>

        <a href="/posts/how-it-works/how-upsun-built-stateless-mesh-networking-for-high-density-containers">
          <div>
            <div>
              <span>Wednesday, August 6th 2025</span>
            </div>

            <h3>How Upsun built stateless mesh networking for high-density containers</h3>
            <p>Discover how Upsun's innovative stateless mesh networking architecture handles thousands of containers without databases or bottlenecks.</p>
          </div>
        </a>

        <a href="/posts/unknown/platformsh-un-global-compact-sdgs-2025">
          <div>
            <div>
              <span>Wednesday, July 30th 2025</span>
            </div>

            <h3>Platform.sh reaffirms commitment to the UN Global Compact and the SDGs</h3>
            <p>We’re pleased to confirm that Platform.</p>
          </div>
        </a>

        <a href="/posts/hands-on/gitlab-push-solution">
          <div>
            <div>
              <span>Monday, July 21st 2025</span>
            </div>

            <h3>Synchronize your air-gapped GitLab with Upsun</h3>
            <p>Configure GitLab CI/CD to deploy to Upsun from private air-gapped GitLab instances using push-based workflows and API automation</p>
          </div>
        </a>

        <a href="/posts/unknown/new-improvement-global-settings-in-console">
          <div>
            <div>
              <span>Wednesday, July 9th 2025</span>
            </div>

            <h3>New improvement: global settings in console</h3>
            <p>Discover the new global settings page in the Console. Easily configure project and environment settings in one location for a smoother experience.</p>
          </div>
        </a>

        <a href="/posts/use-cases/n8n-saved-my-life">
          <div>
            <div>
              <span>Thursday, July 3rd 2025</span>
            </div>

            <h3>How n8n saved our Advocacy impact on Social Media!</h3>
            <p>Learn how n8n workflows improve internal communication and amplify our Advocacy social media impact.</p>
          </div>
        </a>

        <a href="/posts/insights/why-configuration-as-code-beats-click-and-deploy">
          <div>
            <div>
              <span>Thursday, June 12th 2025</span>
            </div>

            <h3>Git-Driven Infrastructure: Why Configuration as Code Beats Click-and-Deploy</h3>
            <p>Discover why YAML-driven infrastructure outperforms point-and-click deployment for scalable, maintainable applications. Learn best practices for configuration as code.</p>
          </div>
        </a>

        <a href="/posts/how-it-works/mcp-interaction-types-article">
          <div>
            <div>
              <span>Saturday, June 7th 2025</span>
            </div>

            <h3>Beyond Tool Calling: Understanding MCP's Three Core Interaction Types</h3>
            <p>Discover how prompts, resources, and tools work together in the Model Context Protocol to create richer AI application experiences beyond simple tool calling.</p>
          </div>
        </a>

        <a href="/posts/hands-on/deploy-mcp-servers-on-upsun">
          <div>
            <div>
              <span>Thursday, June 5th 2025</span>
            </div>

            <h3>Build and deploy AI-Native Applications with MCP Servers on Upsun</h3>
            <p>Learn how Model Context Protocol servers work with different transports and deploy them to Upsun for scalable AI-powered applications</p>
          </div>
        </a>

        <a href="/posts/releases/redis-release">
          <div>
            <div>
              <span>Wednesday, June 4th 2025</span>
            </div>

            <h3>Redis 8.0 is here</h3>
            <p>We are excited to announce that **Redis 8.0** is now available for all customers.</p>
          </div>
        </a>

        <a href="/posts/how-tos/handling-well-known-directory">
          <div>
            <div>
              <span>Monday, May 26th 2025</span>
            </div>

            <h3>How to manage the `.well-known` directory on Upsun and Platform.sh</h3>
            <p>If you have ever tried to enable</p>
          </div>
        </a>

        <a href="/posts/hands-on/nocode-n8n">
          <div>
            <div>
              <span>Wednesday, May 14th 2025</span>
            </div>

            <h3>NoCode with Upsun: Supercharge Your Automation with Zero Code</h3>
            <p>Learn how to leverage Upsun to deploy powerful NoCode tools like n8n for workflow automation. Fast setup, secure hosting, and real-world use cases — all without writing code.</p>
          </div>
        </a>

        <a href="/posts/insights/advanced-prompting-techniques-for-coding">
          <div>
            <div>
              <span>Thursday, May 8th 2025</span>
            </div>

            <h3>Advanced prompting techniques for complex coding tasks</h3>
            <p>This articles will give you an overview of prompting strategies that help coding assistants reason through difficult problems and produce higher-quality solutions.</p>
          </div>
        </a>

        <a href="/posts/releases/file_size_limit">
          <div>
            <div>
              <span>Wednesday, May 7th 2025</span>
            </div>

            <h3>New file size limits explained</h3>
            <p>To ensure the optimal performance, stability, and reliability of our Git infrastructure, we are introducing a limit on the size of individual files that can be pushed to your project repositories.</p>
          </div>
        </a>

        <a href="/posts/releases/vscode-extension">
          <div>
            <div>
              <span>Tuesday, May 6th 2025</span>
            </div>

            <h3>Supercharge your workflow with the Upsun VSCode Extension</h3>
            <p>If you're working on Upsun projects with VSCode, the **Upsun VSCode extension** is an essential tool to enhance your development experience. Learn more...</p>
          </div>
        </a>

        <a href="/posts/how-tos/validate-yaml-config">
          <div>
            <div>
              <span>Tuesday, May 6th 2025</span>
            </div>

            <h3>Making .upsun/config.yaml easier to edit with IDE autocomplete and validation</h3>
            <p>Boost your productivity and eliminate configuration errors with real-time autocompletion and validation for your .upsun/config.yaml — discover how to enhance your IDE experience in just a few simple steps!</p>
          </div>
        </a>

        <a href="/posts/hands-on/pytorch-running-on-upsun">
          <div>
            <div>
              <span>Thursday, May 1st 2025</span>
            </div>

            <h3>How to run PyTorch in an Upsun application?</h3>
            <p>Learn how to deploy a sentiment analysis application powered by PyTorch and FastAPI on the Upsun cloud platform</p>
          </div>
        </a>

        <a href="/posts/how-tos/context7-mcp">
          <div>
            <div>
              <span>Thursday, May 1st 2025</span>
            </div>

            <h3>Upsun documentation is now available via the Context7 MCP</h3>
            <p>Access Upsun documentation directly from your AI workflows using Context7's Model Context Protocol integration</p>
          </div>
        </a>

        <a href="/posts/hands-on/postgres-mcp-on-upsun">
          <div>
            <div>
              <span>Wednesday, April 30th 2025</span>
            </div>

            <h3>Using PostgreSQL MCP with Upsun Remote Database</h3>
            <p>Learn how to set up an MCP server to connect your Upsun PostgreSQL database to language models like Claude or IDE like VSCode GitHub Copilot and Cursor, enabling natural language data queries without writing SQL.</p>
          </div>
        </a>

        <a href="/posts/hands-on/route-ids-env">
          <div>
            <div>
              <span>Monday, April 28th 2025</span>
            </div>

            <h3>How to automatically inject multi-app endpoints as environment variables</h3>
            <p>Learn how to use Upsun route identifiers and the PLATFORM\_ROUTES variable to easily get and use the hostnames of dynamically deployed applications in your project.</p>
          </div>
        </a>

        <a href="/posts/tutorials/oauth-nextjs-laravel">
          <div>
            <div>
              <span>Monday, April 28th 2025</span>
            </div>

            <h3>OAuth authentication between Next.js and Laravel Passport</h3>
            <p>Learn how to implement secure OAuth authentication between a Next.js frontend and Laravel backend using Passport with the Authorization Code Flow and PKCE.</p>
          </div>
        </a>

        <a href="/posts/tutorials/deploying-clamav-service">
          <div>
            <div>
              <span>Thursday, April 24th 2025</span>
            </div>

            <h3>Deploy ClamAV on Upsun, on service mode.</h3>
            <p>Learn how to deploy ClamAV service on Upsun. This tutorial covers ClamAV integration on service scan mode.</p>
          </div>
        </a>

        <a href="/posts/releases/valkey-release">
          <div>
            <div>
              <span>Wednesday, April 16th 2025</span>
            </div>

            <h3>Valkey is now available</h3>
            <p>We're excited to announce the availability of [Valkey](https://valkey.io/), a high-performance, open-source key/value database, now offered as a managed service on Upsun. Valkey serves as a drop-in alternative to Redis, particularly relevant following recent licensing changes to the Redis project.</p>
          </div>
        </a>

        <a href="/posts/hands-on/install-gh-asset-on-upsun">
          <div>
            <div>
              <span>Thursday, April 10th 2025</span>
            </div>

            <h3>Up(sun) and ready with GitHub release assets installation</h3>
            <p>Discover how to install any GitHub release asset you want in your Upsun project.</p>
          </div>
        </a>

        <a href="/posts/unknown/nextjs-cve-2025-2997">
          <div>
            <div>
              <span>Tuesday, March 25th 2025</span>
            </div>

            <h3>Next.js Security Vulnerability (CVE-2025-29927): What Upsun Users Need to Know</h3>
            <p>A comprehensive guide to understanding and addressing the recent Next.js security vulnerability CVE-2025-29927 for applications deployed on Upsun.</p>
          </div>
        </a>

        <a href="/posts/tutorials/sfcon2024-decouple-frontend">
          <div>
            <div>
              <span>Monday, March 24th 2025</span>
            </div>

            <h3>Decouple your Symfony frontend using Next.js</h3>
            <p>How to decouple your frontend from your backend, using a Symfony project as backend and adding a Next.js application for frontend.</p>
          </div>
        </a>

        <a href="/posts/tutorials/deploying-with-lisp">
          <div>
            <div>
              <span>Monday, March 17th 2025</span>
            </div>

            <h3>Up(sun) and running with Lisp</h3>
            <p>Lisp support was discontinued in March 2025. If you really want to power a Lisp project, feel free to reach out on the [Upsun Community Forum](https://community.upsun.com/).</p>
          </div>
        </a>

        <a href="/posts/tutorials/deploying-twill-on-upsun">
          <div>
            <div>
              <span>Wednesday, March 12th 2025</span>
            </div>

            <h3>Up(sun) and Running with Twill</h3>
            <p>This guide provides instructions for deploying and working with [Twill](https://twillcms.com/), an "open-source</p>
          </div>
        </a>

        <a href="/posts/releases/elixir-118-release-available">
          <div>
            <div>
              <span>Wednesday, February 26th 2025</span>
            </div>

            <h3>Apologies to the Elixir community: 1.18 release now available</h3>
            <p>Elixir 1.18 is now available on Upsun and Platform.sh with type checking, LSP improvements, and built-in JSON support.</p>
          </div>
        </a>

        <a href="/posts/tutorials/deploying-clamav-onetime">
          <div>
            <div>
              <span>Friday, February 14th 2025</span>
            </div>

            <h3>Deploy ClamAV on Upsun, on one-time scan</h3>
            <p>Learn how to deploy ClamAV service on Upsun. This tutorial covers ClamAV integration on one-time scan mode.</p>
          </div>
        </a>

        <a href="/posts/releases/llms-introduction">
          <div>
            <div>
              <span>Friday, February 14th 2025</span>
            </div>

            <h3>Upsun and Platform.sh Docs are now llms.txt compatible!</h3>
            <p>We’re thrilled to announce that both [Upsun Documentation](https://docs.upsun.com) and [Platform.sh Documentation](https://docs.platform.sh) are now fully compatible with [llms.txt proposed standard](https://llmstxt.org/)!</p>
          </div>
        </a>

        <a href="/posts/how-tos/install-pandoc-on-upsun">
          <div>
            <div>
              <span>Wednesday, February 12th 2025</span>
            </div>

            <h3>Up(sun) and ready with Pandoc</h3>
            <p>With the recent growth in enthusiasm for AI assistants, you may be looking for how these assistants can provide technical information about your product.</p>
          </div>
        </a>

        <a href="/posts/unknown/magento-performance-optimization">
          <div>
            <div>
              <span>Tuesday, February 4th 2025</span>
            </div>

            <h3>Magento performance optimization–Actionable tips and strategies</h3>
            <p>Is your ecommerce store traffic resulting in enough conversions.</p>
          </div>
        </a>

        <a href="/posts/how-it-works/debian-repo-s3">
          <div>
            <div>
              <span>Wednesday, January 29th 2025</span>
            </div>

            <h3>How we host a Debian repository on AWS S3</h3>
            <p>Pretty cool fact about our internal Debian repositories: they’re hosted entirely on AWS S3. Why is that cool? For 2</p>
          </div>
        </a>

        <a href="/posts/tutorials/upsun-and-running-forem">
          <div>
            <div>
              <span>Friday, January 24th 2025</span>
            </div>

            <h3>Up(sun) and Running with Forem</h3>
            <p>This guide provides instructions for deploying and working with [Forem](https://www.forem.com/), an "open-source</p>
          </div>
        </a>

        <a href="/posts/tutorials/drupal-and-upsun">
          <div>
            <div>
              <span>Thursday, January 16th 2025</span>
            </div>

            <h3>Drupal and Upsun</h3>
            <p>[Drupal CMS](https://www.drupal.org/project/cms), born of [DrupalCon 2024 initiative](https://www.drupal.org/about/in-the-news/blog/drupal-cms-groundbreaking-new-version-of-drupal-detailed-at-drupalcon-singapore-2024) "Starshot", has been [released today](https://www.drupal.org/blog/drupal-cms-1-0).</p>
          </div>
        </a>

        <a href="/posts/hands-on/deploying-chainlit-with-rag">
          <div>
            <div>
              <span>Tuesday, January 14th 2025</span>
            </div>

            <h3>Experiment with Chainlit AI interface with RAG on Upsun</h3>
            <p>Learn to deploy production-ready RAG applications with Chainlit and Python on Upsun. Tutorial covers OpenAI Assistants integration, llama\_index implementation, and secure authentication.</p>
          </div>
        </a>

        <a href="/posts/how-tos/no-downtime-postgres-updates">
          <div>
            <div>
              <span>Thursday, January 9th 2025</span>
            </div>

            <h3>How to update your PostgreSQL database without downtime</h3>
            <p>On paper, releasing a new version of your application that requires upgrading the schema of the database is straightforward. But, changes of code and schema can not be updated in an atomic way, you only need to take care that old code is not performing a query against new schema, and reciprocally.</p>
          </div>
        </a>

        <a href="/posts/discussions/triage-bot">
          <div>
            <div>
              <span>Wednesday, December 18th 2024</span>
            </div>

            <h3>How did we migrate issues from GitLab to Linear?</h3>
            <p>We migrated our issues from GitLab to Linear due to GitLab's limited issue-tracking features. To handle thousands of issues and tight timelines, we developed a migration tool using GitLab Triage Bot and Linear's GraphQL API. The tool mapped issue states, assignees, labels, and comments, and transformed GitLab epics into Linear issues with sub-issues. It was successful overall and enabled team-by-team migration for flexibility. Now, [we’re open-sourcing the migrator](https://github.com/upsun/gitlab-triage-linear-migrator) to help others facing similar challenges.</p>
          </div>
        </a>

        <a href="/posts/discussions/go-124">
          <div>
            <div>
              <span>Sunday, December 15th 2024</span>
            </div>

            <h3>Golang 1.24 is looking seriously awesome</h3>
            <p>The Golang team just released the [first release candidate of Golang 1.24](https://tip.golang.org/doc/go1.24). At Upsun, we use Golang extensively for everything in our hot path, especially for the routing of HTTP requests throughout our infrastructure. Here is what we are looking forward to the most.</p>
          </div>
        </a>

        <a href="/posts/discussions/cve-2024-45337">
          <div>
            <div>
              <span>Friday, December 13th 2024</span>
            </div>

            <h3>CVE-2024-45337</h3>
            <p>This article was originally published on the [Platform.sh blog](https://platform.sh/blog/uncovered-and-patched-golang-vunerability/).</p>
          </div>
        </a>

        <a href="/posts/unknown/uncovered-and-patched-golang-vunerability">
          <div>
            <div>
              <span>Friday, December 13th 2024</span>
            </div>

            <h3>Security vulnerability uncovered and patched in the golang.org/x/crypto /ssh package</h3>
            <p>Misimplementation of PublicKeyCallback leads to authorization bypass in Go's x/crypto/sshPlatform.</p>
          </div>
        </a>

        <a href="/posts/releases/php-84-release">
          <div>
            <div>
              <span>Tuesday, November 26th 2024</span>
            </div>

            <h3>PHP 8.4 is here!</h3>
            <p>PHP 8.4 was [officially released](https://www.php.net/archive/2024.php#2024-11-21-4) on November 21st, and with it comes a number of improvements and new features that you can - as of today - begin working with on your Upsun and Platform.sh projects.</p>
          </div>
        </a>

        <a href="/posts/tutorials/laravel-rest-api-on-upsun">
          <div>
            <div>
              <span>Friday, November 15th 2024</span>
            </div>

            <h3>Creating and deploying a Laravel REST API on Upsun in 10 minutes</h3>
            <p>Follow this comprehensive guide to build and deploy a modern Laravel REST API on Upsun's cloud platform. We'll walk through setting up your local development environment, creating API endpoints, and deploying to production with a custom domain. This tutorial is perfect for developers looking to quickly ship production-ready Laravel applications without dealing with complex infrastructure management.</p>
          </div>
        </a>

        <a href="/posts/how-tos/blackfire-google-alert-markers-interfaces">
          <div>
            <div>
              <span>Tuesday, November 5th 2024</span>
            </div>

            <h3>Import multiple RSS Feeds on your Blackfire timeline + extra interfaces</h3>
            <p>We saw in the [previous episode](/posts/how-tos/blackfire-google-alert-markers) how to automatically add context on your Blackfire timeline from an RSS Feed (Google Alert),</p>
          </div>
        </a>

        <a href="/posts/unknown/human-impact-of-adopting-platformsh">
          <div>
            <div>
              <span>Tuesday, October 29th 2024</span>
            </div>

            <h3>A tale of people: the human impact of adopting Platform.sh</h3>
            <p>I have a complicated relationship with people.</p>
          </div>
        </a>

        <a href="/posts/how-tos/schedule-resource-availability">
          <div>
            <div>
              <span>Thursday, October 24th 2024</span>
            </div>

            <h3>Scheduling resources</h3>
            <p>As Upsun does purely usage-driven billing,</p>
          </div>
        </a>

        <a href="/posts/releases/continuous-profiling-comparisons">
          <div>
            <div>
              <span>Wednesday, October 23rd 2024</span>
            </div>

            <h3>Continuous profiling comparisons</h3>
            <p>Upsun’s new continuous profiling comparisons feature provides deeper insights into application performance, enabling you to easily contrast performance metrics over time or between code versions.</p>
          </div>
        </a>

        <a href="/posts/tutorials/rails8-upsun-tutorial">
          <div>
            <div>
              <span>Wednesday, October 23rd 2024</span>
            </div>

            <h3>Deploy your first Rails 8 application on Upsun</h3>
            <p>Learn how to build and deploy a modern Rails 8 blog application on Upsun's cloud platform. This hands-on tutorial walks you through local development setup, creating a feature-rich blog application, and deploying it to production with proper monitoring and scaling. Discover why Platform-as-a-Service remains relevant even with Rails 8's new deployment features, and learn best practices for cloud deployment. Perfect for developers wanting to quickly ship production-ready Rails applications without managing complex infrastructure.</p>
          </div>
        </a>

        <a href="/posts/how-tos/configuring-an-autoscaler">
          <div>
            <div>
              <span>Saturday, October 19th 2024</span>
            </div>

            <h3>Adding an autoscaler to Upsun projects</h3>
            <p>In this post we will describe a small configuration that will</p>
          </div>
        </a>

        <a href="/posts/how-tos/blackfire-google-alert-markers">
          <div>
            <div>
              <span>Monday, October 7th 2024</span>
            </div>

            <h3>Add context on your Blackfire timeline from a Google Alerts RSS Feed</h3>
            <p>Observing your application is essential to be able to find what needs (and what does not need) to be optimized.</p>
          </div>
        </a>

        <a href="/posts/releases/context-driven-navigation">
          <div>
            <div>
              <span>Thursday, October 3rd 2024</span>
            </div>

            <h3>Context driven navigation</h3>
            <p>You may have noticed some changes to navigation and user settings on your Platform.sh dashboard.</p>
          </div>
        </a>

        <a href="/posts/discussions/understanding-cors">
          <div>
            <div>
              <span>Monday, September 30th 2024</span>
            </div>

            <h3>Understanding Cross-Origin Resource Sharing (CORS)</h3>
            <p>Learn about Cross-Origin Resource Sharing (CORS), a crucial web security mechanism. Understand its importance, key concepts, and implementation in Symfony, Next.js, and Laravel. Includes practical examples and tips for testing with curl and Postman, plus Platform.sh configuration guidance.</p>
          </div>
        </a>

        <a href="/posts/unknown/evolve-partner-summit-awards">
          <div>
            <div>
              <span>Monday, September 23rd 2024</span>
            </div>

            <h3>It's almost time…Platform.sh’s Evolve Partner Summit Awards</h3>
            <p>We’d love for you to join us in Paris to celebrate the incredible work you’ve done.</p>
          </div>
        </a>

        <a href="/posts/how-tos/automate-with-gatling-1">
          <div>
            <div>
              <span>Friday, September 20th 2024</span>
            </div>

            <h3>How to automate load tests with Gatling</h3>
            <p>When I was on your side of the keyboard, developing cool and funny applications (more or less :D), load tests were (most of the time) executed a few days before going live.</p>
          </div>
        </a>

        <a href="/posts/how-it-works/using-the-upsun-api">
          <div>
            <div>
              <span>Thursday, September 19th 2024</span>
            </div>

            <h3>Using the Upsun API</h3>
            <p>> Anything you can do, API can do better!</p>
          </div>
        </a>

        <a href="/posts/discussions/preview-environments-a-developers-secret-weapon">
          <div>
            <div>
              <span>Thursday, September 19th 2024</span>
            </div>

            <h3>Preview Environments</h3>
            <p>Discover how preview environments transform software deployment, reducing stress and improving code quality. Learn about the six essential components for implementing preview environments, including Git, infrastructure as code, and automated DNS management. Find out why preview environments are crucial for catching bugs, testing performance, and enhancing collaboration between technical and non-technical team members. Explore how Upsun's platform leverages preview environments to streamline the development process and deliver higher-quality software products.</p>
          </div>
        </a>

        <a href="/posts/releases/introducing-dev-center">
          <div>
            <div>
              <span>Wednesday, September 18th 2024</span>
            </div>

            <h3>Introducing the Upsun Developer Center</h3>
            <p>This month our Developer Relations and Advocacy teams are excited to share with you our latest resource: the Upsun Developer Center.</p>
          </div>
        </a>

        <a href="/posts/tutorials/how-to-host-multiple-applications">
          <div>
            <div>
              <span>Friday, August 16th 2024</span>
            </div>

            <h3>How to host a multiple-application project on Platform.sh</h3>
            <p>Learn how to host and configure multiple-application projects on Platform.sh with this step-by-step guide.</p>
          </div>
        </a>

        <a href="/posts/hands-on/harnessing-power-embeddings">
          <div>
            <div>
              <span>Monday, May 20th 2024</span>
            </div>

            <h3>Harnessing the power of Embeddings: a real-world example of a watch recommendation app using a vector database.</h3>
            <p>Learn how to build a real-world watch recommendation application using embeddings and a vector database. This tutorial covers using Postgres with pgvector, Laravel, React, OpenAI, and Groq, deployed on Upsun.</p>
          </div>
        </a>

        <a href="/posts/use-cases/wordpress-performance-optimization-with-blackfire">
          <div>
            <div>
              <span>Tuesday, April 16th 2024</span>
            </div>

            <h3>Meeting Jonny Harris: WordPress performance optimization with Blackfire</h3>
            <p>Jonny Harris is a WordPress core contributor and committer based in the UK and a member of the WordPress Performance</p>
          </div>
        </a>

        <a href="/posts/hands-on/guide-to-limit-deployments-to-platformsh-only-with-tags-part-three">
          <div>
            <div>
              <span>Friday, April 12th 2024</span>
            </div>

            <h3>Limit deployments to Platform.sh only with tags: part three</h3>
            <p>In parts [one](/posts/hands-on/guide-to-limit-deployments-to-platformsh-only-with-tags-part-one) and</p>
          </div>
        </a>

        <a href="/posts/unknown/drupal-camp-florida-2024">
          <div>
            <div>
              <span>Monday, March 25th 2024</span>
            </div>

            <h3>DrupalCamp Florida 2024: sharing takeaways from the experts</h3>
            <p>I had the pleasure of returning to DrupalCamp FL (DCFL) again this year and even now in its sixteenth year, DCFL 2024 was as lively and energetic as ever.</p>
          </div>
        </a>

        <a href="/posts/hands-on/guide-to-limit-deployments-to-platformsh-only-with-tags-part-one">
          <div>
            <div>
              <span>Thursday, March 14th 2024</span>
            </div>

            <h3>Limit deployments to Platform.sh only with tags: part one</h3>
            <p>Throughout the years, many users have asked us if it’s possible to only deploy to Platform.sh when a tag is pushed using</p>
          </div>
        </a>

        <a href="/posts/hands-on/guide-to-limit-deployments-to-platformsh-only-with-tags-part-two">
          <div>
            <div>
              <span>Thursday, March 14th 2024</span>
            </div>

            <h3>Limit deployments to Platform.sh only when Git tagged: part two</h3>
            <p>In [part one of this series](https://platform.sh/blog/guide-to-limit-deployments-to-platformsh-only-with-tags-part-one/),</p>
          </div>
        </a>

        <a href="/posts/tutorials/deploying-remixjs-app-on-upsun">
          <div>
            <div>
              <span>Friday, March 1st 2024</span>
            </div>

            <h3>Deploying a Remix JS app on Upsun in 5 minutes</h3>
            <p>Learn how to deploy a Remix JS application on Upsun in just 5 minutes. This tutorial covers creating a project, setting up the Node.js server, and deploying your app.</p>
          </div>
        </a>

        <a href="/posts/tutorials/deploying-laravel-with-horizon-on-upsun">
          <div>
            <div>
              <span>Wednesday, February 28th 2024</span>
            </div>

            <h3>Deploying Laravel with Horizon on Upsun</h3>
            <p>Learn how to deploy a Laravel application with Redis queues and Horizon on Upsun, including PostgreSQL database setup, environment configuration, and domain management.</p>
          </div>
        </a>

        <a href="/posts/unknown/whats-the-deal-with-eu-headquartered-iaas-providers">
          <div>
            <div>
              <span>Monday, November 13th 2023</span>
            </div>

            <h3>International data protection with EU-entities of US-headquartered IaaS providers</h3>
            <p>Learn why we use EU-headquartered IaaS providers for maximum data protection and the additional measures we have in place with our providers for GDPR.</p>
          </div>
        </a>

        <a href="/posts/unknown/building-a-trust-centric-culture-for-success">
          <div>
            <div>
              <span>Wednesday, November 8th 2023</span>
            </div>

            <h3>Building a trust-centric culture for success</h3>
            <p>Trust is more than compliance. It drives employee and customer retention, positive word of mouth, and builds your brand reputation. Find out how to build it.</p>
          </div>
        </a>

        <a href="/posts/how-it-works/how-platformsh-stays-ahead-of-emerging-cybersecurity-threats">
          <div>
            <div>
              <span>Friday, October 13th 2023</span>
            </div>

            <h3>Semper vigilans: how Platform.sh stays ahead of emerging cybersecurity threats (so you don’t have to)</h3>
            <p>Always vigilant is more than a motto. Find out how the Platform.sh Security team monitors vulnerabilities 24x7 to protect customers from cybersecurity threats.</p>
          </div>
        </a>

        <a href="/posts/releases/bun-support-is-here">
          <div>
            <div>
              <span>Friday, September 8th 2023</span>
            </div>

            <h3>It's out of the Oven: Bun 1.0 support on Platform.sh</h3>
            <p>Bun 1.0 support is now available on Platform.sh. Discover our comparison results against Yarn and how to test Bun 1.0 out for yourself in this article.</p>
          </div>
        </a>

        <a href="/posts/how-tos/help-reduce-resource-consumption-put-your-preview-environments-on-pause">
          <div>
            <div>
              <span>Friday, August 18th 2023</span>
            </div>

            <h3>Help reduce resource consumption: Put your preview environments on pause</h3>
            <p>You can now manually pause your idle preview environments or have them automatically paused after 14 days of being idle to minimize your resource usage.</p>
          </div>
        </a>

        <a href="/posts/unknown/an-update-to-our-events-privacy-policy">
          <div>
            <div>
              <span>Wednesday, May 31st 2023</span>
            </div>

            <h3>An update to our events privacy policy</h3>
            <p>To ensure the best experience at Platform.sh conferences and events, we've updated our privacy policy detailing how we'll use and care for your personal data.</p>
          </div>
        </a>

        <a href="/posts/unknown/greater-organization-insights-through-weekly-activity-reports-emails">
          <div>
            <div>
              <span>Monday, April 10th 2023</span>
            </div>

            <h3>Greater organization insights through weekly activity reports emails</h3>
            <p>For our Elite/Enterprise customers, we now will be sending weekly activity reports to provide visibility on the key stats and metrics on all projects.</p>
          </div>
        </a>

        <a href="/posts/unknown/infrastructure-metrics-expanded-to-longer-time-frames">
          <div>
            <div>
              <span>Wednesday, February 1st 2023</span>
            </div>

            <h3>Infrastructure Monitoring Metrics with Longer Time Frames</h3>
            <p>Unlock valuable insights with longer time frames in infrastructure metrics on Platform.sh. Make informed decisions for better capacity planning.</p>
          </div>
        </a>

        <a href="/posts/unknown/its-time-for-version--all-new-upgrades-for-our-api-server">
          <div>
            <div>
              <span>Thursday, January 26th 2023</span>
            </div>

            <h3>Introducing version 19: New upgrades for our API server</h3>
            <p>Unlock the power of Version 19 upgrades, boosting API server performance. Upgrade with Platform.sh for a seamless experience and enhanced capabilities.</p>
          </div>
        </a>

        <a href="/posts/releases/platformsh-is-always-one-step-ahead-announcing-postgresql--python--and-ruby--for-our-users">
          <div>
            <div>
              <span>Monday, January 16th 2023</span>
            </div>

            <h3>Platform.sh is always one step ahead: Announcing PostgreSQL 15, Python 3.11, and Ruby 3.2 for our users</h3>
            <p>Explore the new features and performance improvements in Python 3.11, PostgreSQL 15, and Ruby 3.2. Stay up-to-date with the latest programming languages.</p>
          </div>
        </a>

        <a href="/posts/hands-on/powerup-your-local-development-with-ddev">
          <div>
            <div>
              <span>Thursday, January 5th 2023</span>
            </div>

            <h3>Power-up Your Local Development with DDEV</h3>
            <p>Get the best local development experience with the DDEV-Platform.sh add-on. Follow our guide, share your feedback, and optimize your workflow</p>
          </div>
        </a>

        <a href="/posts/unknown/introducing-our-new-api-and-metrics-servers-upgrades">
          <div>
            <div>
              <span>Thursday, December 15th 2022</span>
            </div>

            <h3>Introducing our new API and Metrics servers upgrades</h3>
            <p>Updates: Jenkins 'H' pattern for cron jobs, result filters for activity scripts, cancellable build and source operations, and the clear build cache activity.</p>
          </div>
        </a>

        <a href="/posts/unknown/dont-be-held-to-ransom-security-awareness-with-platformsh">
          <div>
            <div>
              <span>Friday, December 2nd 2022</span>
            </div>

            <h3>Don’t be held to ransom: Security awareness with Platform.sh</h3>
            <p>Learn how to safeguard your organization against ransomware attacks. Explore security measures and proactive steps to protect your company's data.</p>
          </div>
        </a>

        <a href="/posts/unknown/are-your-websites-ready-to-handle-traffic-peaks-this-holiday-season">
          <div>
            <div>
              <span>Monday, November 28th 2022</span>
            </div>

            <h3>Are your websites ready to handle traffic peaks this holiday season?</h3>
            <p>Discover how to optimize your website for increased holiday traffic. Learn best practices for performance and customer experience during the busy sales season.</p>
          </div>
        </a>

        <a href="/posts/unknown/the-platformsh-cli-is-ready-to-golang">
          <div>
            <div>
              <span>Thursday, November 17th 2022</span>
            </div>

            <h3>The Platform.sh CLI is ready to Go(lang)</h3>
            <p>New Universal Platform.sh CLI, designed to help developers manage projects efficiently, supporting multiple languages and eliminating PHP dependency.</p>
          </div>
        </a>

        <a href="/posts/releases/introducing-a-more-complete-logs-forwarding-experience">
          <div>
            <div>
              <span>Friday, November 4th 2022</span>
            </div>

            <h3>Introducing a more complete logs forwarding experience</h3>
            <p>Streamline monitoring with centralized log forwarding. Platform.sh now supports log forwarding to Sumologic, New Relic Logs, Splunk, and more. Discover how!</p>
          </div>
        </a>

        <a href="/posts/unknown/platformsh-partners-with-mongodb-to-help-customers-build-modern-applications-faster">
          <div>
            <div>
              <span>Thursday, October 6th 2022</span>
            </div>

            <h3>Platform.sh partners with MongoDB to help customers build modern applications faster</h3>
            <p>Announcing MongoDB 5.0 for Enterprise and Elite customers. Enjoy improved security, support, and features. Upgrade now for seamless MongoDB integration.</p>
          </div>
        </a>

        <a href="/posts/unknown/mohammed-ajmal-siddiqui">
          <div>
            <div>
              <span>Friday, September 16th 2022</span>
            </div>

            <h3>Platform.sh | Journeys Mohammed Ajmal Siddiqui</h3>
            <p>Follow Ajmal's journey from India to Paris as he navigates programming, internships, and lockdowns. Join Platform.sh's success story today!</p>
          </div>
        </a>

        <a href="/posts/unknown/weve-made-changes-to-our-dpa-to-clarify-platformsh-role-under-the-gdpr">
          <div>
            <div>
              <span>Thursday, September 1st 2022</span>
            </div>

            <h3>We’ve made changes to our DPA to clarify Platform.sh role under the GDPR</h3>
            <p>Discover how Platform.sh complies with GDPR, acting as both a data controller and data processor under the European Union's General Data Protection Regulation.</p>
          </div>
        </a>

        <a href="/posts/unknown/were-updating-our-privacy-policy-to-include-event-accommodations">
          <div>
            <div>
              <span>Friday, August 19th 2022</span>
            </div>

            <h3>We’re updating our privacy policy to include event accommodations</h3>
            <p>Learn about our privacy policy update regarding dietary restrictions and disability accommodations at Platform.sh events.</p>
          </div>
        </a>

        <a href="/posts/unknown/pandemic-caused-spike-in-cybercrime">
          <div>
            <div>
              <span>Thursday, May 26th 2022</span>
            </div>

            <h3>The pandemic has indeed caused a massive spike in cybercrime</h3>
            <p>Insights from Joey Stanford, VP of Privacy & Security at Platform.sh, on cybersecurity trends, challenges, and the future of security for modern businesses.</p>
          </div>
        </a>

        <a href="/posts/unknown/infrastructure-metrics-for-all-professional-projects">
          <div>
            <div>
              <span>Tuesday, May 3rd 2022</span>
            </div>

            <h3>Infrastructure Metrics available for all Professional projects</h3>
            <p>Gain insight into your application's behavior with observability and metrics on Platform.sh. Monitor CPU, RAM, disk space, and more for informed decisions.</p>
          </div>
        </a>

        <a href="/posts/unknown/greener-hosting-starts-with-transparency">
          <div>
            <div>
              <span>Friday, April 22nd 2022</span>
            </div>

            <h3>Greener hosting starts with transparency</h3>
            <p>Platform.sh enhances transparency about its carbon footprint. Make informed choices on where to deploy your projects with data on environmental impact.</p>
          </div>
        </a>

        <a href="/posts/unknown/automated-code-updates">
          <div>
            <div>
              <span>Friday, April 15th 2022</span>
            </div>

            <h3>Automated code updates</h3>
            <p>Simplify updates and security for critical apps. Platform.sh offers automated source operations to keep your apps up to date.</p>
          </div>
        </a>

        <a href="/posts/unknown/split-projects-and-users-across-organizations">
          <div>
            <div>
              <span>Friday, April 15th 2022</span>
            </div>

            <h3>Split projects and users across multiple organizations</h3>
            <p>Platform.sh now allows creating multiple organizations to suit your project, billing, and contributor management needs.</p>
          </div>
        </a>

        <a href="/posts/unknown/go-1-18-released-on-platformsh">
          <div>
            <div>
              <span>Wednesday, March 16th 2022</span>
            </div>

            <h3>Go 1.18 released on Platform.sh</h3>
            <p>Discover the new features in Go 1.18, including support for generics, and learn how to upgrade your Go projects on Platform.sh for enhanced functionality.</p>
          </div>
        </a>

        <a href="/posts/unknown/privacy-policy-updates">
          <div>
            <div>
              <span>Wednesday, February 16th 2022</span>
            </div>

            <h3>Privacy Policy updates and subprocessors list change</h3>
            <p>Discover the latest changes in Privacy Policy version 6.0, including UTMs and Law Enforcement Requests guidelines. Learn more at Platform.sh.</p>
          </div>
        </a>

        <a href="/posts/unknown/platformsh-announces-microsoft-azure-support-australian-market">
          <div>
            <div>
              <span>Friday, January 28th 2022</span>
            </div>

            <h3>Announcing Microsoft Azure Support for Australia</h3>
            <p>Extending services to the Australian market, offering more choice and local support for web platform development on Microsoft Azure and other cloud providers.</p>
          </div>
        </a>

        <a href="/posts/unknown/managing-multiple-website">
          <div>
            <div>
              <span>Thursday, January 27th 2022</span>
            </div>

            <h3>The secret to managing multiple websites</h3>
            <p>Learn how a unified DevOps strategy can help manage a diverse website portfolio at scale while controlling costs and driving predictability with Platform.sh.</p>
          </div>
        </a>

        <a href="/posts/how-tos/measuring-the-success-of-a-deployment-with-githubactions">
          <div>
            <div>
              <span>Thursday, December 23rd 2021</span>
            </div>

            <h3>Measuring Deployment Success with GitHub Actions</h3>
            <p>Learn how GitHub actions can streamline your Platform.sh deployments for faster and more efficient development workflows</p>
          </div>
        </a>

        <a href="/posts/unknown/share-your-activities-with-robots-surfacing-activities-with-github-actions">
          <div>
            <div>
              <span>Wednesday, December 22nd 2021</span>
            </div>

            <h3>Surfacing activities with GitHub actions</h3>
            <p>Learn how to leverage the predictable link in your workflow by integrating Platform.sh with GitHub Actions. Streamline your deployments and error handling.</p>
          </div>
        </a>

        <a href="/posts/unknown/share-your-failures-fix-them-faster">
          <div>
            <div>
              <span>Wednesday, December 8th 2021</span>
            </div>

            <h3>Share and fix failures faster with shareable activities</h3>
            <p>Troubleshoot failures efficiently with shareable activity logs. Collaborate with your team and Platform.sh support to streamline Continuous Delivery workflow.</p>
          </div>
        </a>

        <a href="/posts/unknown/overview-video">
          <div>
            <div>
              <span>Monday, November 15th 2021</span>
            </div>

            <h3>New Platform.sh overview video: a proven, 5-step approach helps explain a complex concept</h3>
            <p>Discover what Platform.sh does in this 5-step overview video. Clear explanations, no technical jargon. Learn how it can benefit your business. Watch now!</p>
          </div>
        </a>

        <a href="/posts/unknown/creating-problem-solving-partnerships-through-open-innovation">
          <div>
            <div>
              <span>Wednesday, September 8th 2021</span>
            </div>

            <h3>Creating problem-solving partnerships with open innovation</h3>
            <p>Learn about open innovation, its challenges, and benefits. Discover how companies collaborate for creative problem-solving and innovation.</p>
          </div>
        </a>

        <a href="/posts/unknown/keeping-afloat-during-flood-of-worker-turnover">
          <div>
            <div>
              <span>Thursday, August 19th 2021</span>
            </div>

            <h3>Keeping afloat during the flood of worker turnover</h3>
            <p>Discover insights on the talent turnover tsunami, burnout, and remote work strategies. Learn how to win the talent war in today's job market.</p>
          </div>
        </a>

        <a href="/posts/unknown/beginners-guide-to-platformsh">
          <div>
            <div>
              <span>Tuesday, August 17th 2021</span>
            </div>

            <h3>A beginner’s guide to Platform.sh</h3>
            <p>Beginner's guide to Platform.sh: a complete end-to-end cloud Platform-as-a-Service for development teams. Discover the features and developer experience.</p>
          </div>
        </a>

        <a href="/posts/how-tos/get-more-control-over-your-environments-with-build-variables">
          <div>
            <div>
              <span>Tuesday, August 10th 2021</span>
            </div>

            <h3>Get more control over your environments with build variables</h3>
            <p>Discover the visible-build flag on Platform.sh, enabling environment-specific build variables for more control over your development process.</p>
          </div>
        </a>

        <a href="/posts/unknown/building-better-mousetrap-barebones-budget">
          <div>
            <div>
              <span>Thursday, July 1st 2021</span>
            </div>

            <h3>Building a better mousetrap on a barebones budget</h3>
            <p>Learn from Dan Kildahl's insights on innovating wisely with limited resources in the latest Fleet Club session. Join the conversation at Fleet Club.</p>
          </div>
        </a>

        <a href="/posts/unknown/best-practices-for-engaging-digital-agency">
          <div>
            <div>
              <span>Monday, April 26th 2021</span>
            </div>

            <h3>Best practices for engaging a digital agency</h3>
            <p>Build a strong digital agency partnership with open communication and trust. Learn top tips from Carl Smith, Bureau of Digital principal.</p>
          </div>
        </a>

        <a href="/posts/unknown/four-reasons-to-build-ecommerce-site-with-modern-paas">
          <div>
            <div>
              <span>Thursday, April 22nd 2021</span>
            </div>

            <h3>Four reasons to build your ecommerce site with a modern PaaS</h3>
            <p>Discover why SportRx and FREITAG chose Platform.sh for their ecommerce businesses. Higher performance, scalability, stability, and redundancy.</p>
          </div>
        </a>

        <a href="/posts/unknown/plan-monitor-operate-more-knowledgeably-with-metrics">
          <div>
            <div>
              <span>Wednesday, March 17th 2021</span>
            </div>

            <h3>Plan, monitor, and operate more knowledgeably with metrics</h3>
            <p>Introducing metrics and observability on Dedicated infrastructure projects, allowing you to easily monitor CPU, RAM, and disk usage across your hosts.</p>
          </div>
        </a>

        <a href="/posts/unknown/time-to-breakup-three-reasons-to-decouple-your-application">
          <div>
            <div>
              <span>Wednesday, February 10th 2021</span>
            </div>

            <h3>Time to breakup? Three reasons to decouple your application</h3>
            <p>Reasons to consider decoupling your website on Platform.sh. Specialized frameworks, focused teams, and create once, publish everywhere benefits.</p>
          </div>
        </a>

        <a href="/posts/core-concepts/https-and-tls-certificates-always-served-fresh">
          <div>
            <div>
              <span>Tuesday, February 9th 2021</span>
            </div>

            <h3>HTTPS and TLS certificates: Always served fresh</h3>
            <p>Goodbye to expired certificates! We now auto-renew TLS certificates for your websites, ensuring end-to-end encryption without interruptions.</p>
          </div>
        </a>

        <a href="/posts/unknown/how-digital-agency-adapt-innovates-without-heavy-lifting">
          <div>
            <div>
              <span>Wednesday, February 3rd 2021</span>
            </div>

            <h3>How digital agency Adapt innovates—without heavy-lifting</h3>
            <p>Discover how to optimize websites using Statamic on Laravel with Platform.sh. Flexible, secure, and editor-friendly solutions for developers and editors.</p>
          </div>
        </a>

        <a href="/posts/unknown/lazard-names-platformsh-to-their-t100-index">
          <div>
            <div>
              <span>Monday, February 1st 2021</span>
            </div>

            <h3>Lazard names Platform.sh to their T100 Index</h3>
            <p>Lazard recognizes Platform.sh as a top European company with disruptive potential. Learn how we enable innovation and flexibility for businesses.</p>
          </div>
        </a>

        <a href="/posts/unknown/renaming-your-projects-default-branch">
          <div>
            <div>
              <span>Wednesday, January 20th 2021</span>
            </div>

            <h3>Renaming your project’s default branch</h3>
            <p>Update your Project's default branch in Git repositories. Rename your master branch to support a more inclusive default naming convention.</p>
          </div>
        </a>

        <a href="/posts/unknown/frederic-potvin-and-yann-deshayes">
          <div>
            <div>
              <span>Tuesday, January 19th 2021</span>
            </div>

            <h3>Platform.sh | Journeys Frederic Potvin and Yann Deshayes</h3>
            <p>Stories of two Platform.sh engineers who left and returned, highlighting the company's flexibility, employee support, and commitment to a healthy work culture</p>
          </div>
        </a>

        <a href="/posts/unknown/free-your-developers-the-simple-way-to-rebalance-your-devops-resources">
          <div>
            <div>
              <span>Thursday, January 14th 2021</span>
            </div>

            <h3>Free your developers! The simple way to rebalance your DevOps resources</h3>
            <p>Discover how Platform-as-a-Service (PaaS) can shift the balance of power from Ops to Dev, giving organizations more time, money, and tools for development.</p>
          </div>
        </a>

        <a href="/posts/unknown/what-the-heck-is-a-decoupled-website">
          <div>
            <div>
              <span>Monday, January 11th 2021</span>
            </div>

            <h3>CMS architecture: What the heck is . . . a decoupled website?</h3>
            <p>A decoupled CMS architecture splits website tasks into smaller apps while maintaining specific functions. Learn how Platform.sh improves the process.</p>
          </div>
        </a>

        <a href="/posts/unknown/platformsh-joins-gaia-x">
          <div>
            <div>
              <span>Monday, December 7th 2020</span>
            </div>

            <h3>Platform.sh joins the Gaia-X data infrastructure initiative</h3>
            <p>Platform.sh partners with Gaia-X, boosting EU data security and processing. Trusted by leading European institutions, we're committed to a secure data future.</p>
          </div>
        </a>

        <a href="/posts/unknown/record-breaking-2020-black-friday-cyber-monday-volumes">
          <div>
            <div>
              <span>Monday, December 7th 2020</span>
            </div>

            <h3>Record-breaking 2020 Black Friday volumes</h3>
            <p>Platform.sh helped retailers thrive during the 2020 holiday season with record traffic and order volumes. Learn more about our high-performance architecture.</p>
          </div>
        </a>

        <a href="/posts/unknown/what-the-heck-is-a-cdn">
          <div>
            <div>
              <span>Friday, November 27th 2020</span>
            </div>

            <h3>What the heck is . . . a CDN?</h3>
            <p>Ask a non-technical professional what the most challenging part of their job is and you’ll often hear, “Understanding what the heck our developers are talking about.</p>
          </div>
        </a>

        <a href="/posts/unknown/php-80-brings-it-all-together-on-platformsh">
          <div>
            <div>
              <span>Thursday, November 26th 2020</span>
            </div>

            <h3>PHP 8.0 brings it all together on Platform.sh</h3>
            <p>Discover the new features in PHP 8.0 and learn how to upgrade your Platform.sh projects. Constructor Property Promotion, Attributes, Named Arguments, and more!</p>
          </div>
        </a>

        <a href="/posts/core-concepts/getting-gitops-right">
          <div>
            <div>
              <span>Tuesday, November 10th 2020</span>
            </div>

            <h3>Getting GitOps right</h3>
            <p>Source code management has never been simpler with GitOps from Platform.sh. We'll help you get started with automating your deployments.</p>
          </div>
        </a>

        <a href="/posts/releases/php-80-feature-focus-constructor-property-promotion">
          <div>
            <div>
              <span>Thursday, November 5th 2020</span>
            </div>

            <h3>PHP 8.0 feature focus: Class constructor property promotion</h3>
            <p>Discover how PHP 8.0's Constructor Property Promotion feature can streamline your code, reduce verbosity, and make coding faster. Try it on Platform.sh today!</p>
          </div>
        </a>

        <a href="/posts/unknown/php-80-feature-focus-language-tightening">
          <div>
            <div>
              <span>Thursday, October 22nd 2020</span>
            </div>

            <h3>PHP 8.0 feature focus: Language tightenings</h3>
            <p>Explore PHP 8.0's language changes for safer code. Discover stable sorting, numeric string handling, stricter magic methods, and more on Platform.sh!</p>
          </div>
        </a>

        <a href="/posts/how-it-works/how-do-you-manage-ssh-keys-in-your-organization">
          <div>
            <div>
              <span>Wednesday, October 21st 2020</span>
            </div>

            <h3>SSH certificates with Platform.sh</h3>
            <p>Learn how Platform.sh simplifies provisioning SSH certificates for secure and keyless SSH authentication, enhancing security and making compliance easier.</p>
          </div>
        </a>

        <a href="/posts/unknown/ks-chan">
          <div>
            <div>
              <span>Wednesday, October 21st 2020</span>
            </div>

            <h3>Platform.sh | Journeys KS Chan</h3>
            <p>Discover how a Platform.sh engineer found work-life balance while shaping the company's largest department, all while spending time with his family.</p>
          </div>
        </a>

        <a href="/posts/unknown/php-80-feature-focus-quality-of-life-improvements">
          <div>
            <div>
              <span>Wednesday, October 14th 2020</span>
            </div>

            <h3>PHP 8.0 feature focus: quality of life improvements</h3>
            <p>Explore PHP 8.0's new string functions, throw expression, and other improvements. Try PHP 8.0 on Platform.sh today!</p>
          </div>
        </a>

        <a href="/posts/unknown/what-the-heck-is-a-container">
          <div>
            <div>
              <span>Monday, October 5th 2020</span>
            </div>

            <h3>CMS architecture: What the heck is . . . containerization?</h3>
            <p>Want to better understand containerization? Let Platform.sh walk you through it. Our no-hassle container platform will keep your applications running smoothly.</p>
          </div>
        </a>

        <a href="/posts/releases/php-80-feature-focus-weak-maps">
          <div>
            <div>
              <span>Thursday, October 1st 2020</span>
            </div>

            <h3>PHP 8.0 feature focus: Weak maps</h3>
            <p>Learn how PHP 8.0's Weak Maps simplify memory management by efficiently handling cached objects. Try PHP 8.0 on Platform.sh today!</p>
          </div>
        </a>

        <a href="/posts/unknown/mahdi-mokhtariirani">
          <div>
            <div>
              <span>Wednesday, September 16th 2020</span>
            </div>

            <h3>Platform.sh | Journeys Mahdi Mokhtariirani</h3>
            <p>Follow Mahdi's journey from Iran to Europe, his experiences at Platform.sh, and how he continues to learn and grow in unfamiliar surroundings.</p>
          </div>
        </a>

        <a href="/posts/unknown/microsoft-azure-west-datacenter">
          <div>
            <div>
              <span>Tuesday, September 8th 2020</span>
            </div>

            <h3>Expansion of Microsoft Azure Data Center services</h3>
            <p>Platform.sh expands to Microsoft Azure West US 2, offering agile teams in the West faster access. Learn more about our end-to-end web platform.</p>
          </div>
        </a>

        <a href="/posts/unknown/pre-release-php-8-0-images-now-available">
          <div>
            <div>
              <span>Thursday, September 3rd 2020</span>
            </div>

            <h3>Pre-release PHP 8.0 images now available</h3>
            <p>Explore PHP 8.0's new features and performance improvements. Try it out early on Platform.sh with a simple configuration change.</p>
          </div>
        </a>

        <a href="/posts/how-it-works/installers-that-dont-suck">
          <div>
            <div>
              <span>Wednesday, August 5th 2020</span>
            </div>

            <h3>Installers that don't suck</h3>
            <p>Learn how to create cloud-friendly web application installers that account for cloud-based environments and optimize the user experience.</p>
          </div>
        </a>

        <a href="/posts/engineering/save-your-drupal-team-hours-and-effort-with-source-operations-and-activity-scripts">
          <div>
            <div>
              <span>Tuesday, July 28th 2020</span>
            </div>

            <h3>Source Operations and Activity Scripts for Drupal teams</h3>
            <p>Learn how to automate Drupal updates on Platform.sh using Source Operations and Activity Scripts, saving your development team time and effort.</p>
          </div>
        </a>

        <a href="/posts/unknown/headless-but-this-time-live-decoupled-drupal-with-gatsby">
          <div>
            <div>
              <span>Tuesday, July 28th 2020</span>
            </div>

            <h3>Headless, but this time live! Decoupled Drupal with Gatsby</h3>
            <p>Learn to decouple Drupal and Gatsby on Platform.sh for parallel work and efficient content management. Follow our tutorial and deploy your project today!</p>
          </div>
        </a>

        <a href="/posts/unknown/connecting-with-the-community-at-drupalcon-global">
          <div>
            <div>
              <span>Friday, July 24th 2020</span>
            </div>

            <h3>Connecting with the community at DrupalCon Global</h3>
            <p>Discover our highlights from DrupalCon Global, including our partnership with Lando and booth demos. Stay updated on our Drupal community involvement.</p>
          </div>
        </a>

        <a href="/posts/unknown/sso-for-platformsh-now-available-for-openid-connect-and-google">
          <div>
            <div>
              <span>Thursday, June 25th 2020</span>
            </div>

            <h3>SSO available for OpenID Connect and Google</h3>
            <p>Enhance security with Single Sign-On for OpenID Connect and Google. Protect your projects with two-factor authentication and password rotation.</p>
          </div>
        </a>

        <a href="/posts/unknown/platformsh-partner-eZ-Systems-announces-name-change-to-ibexa">
          <div>
            <div>
              <span>Tuesday, June 23rd 2020</span>
            </div>

            <h3>Platform.sh partner eZ Systems announces name change to Ibexa</h3>
            <p>After twenty years as a successful Web Content Management vendor, eZ Systems last month announced the launch of its new corporate brand identity and name: Ibexa</p>
          </div>
        </a>

        <a href="/posts/unknown/integrations-management-through-platform-sh-console">
          <div>
            <div>
              <span>Thursday, June 18th 2020</span>
            </div>

            <h3>View your external integrations through the console</h3>
            <p>View, create, update, and debug your Platform.sh project's external integrations directly from the console for increased control.</p>
          </div>
        </a>

        <a href="/posts/unknown/headless-strapi-and-wordpress-content-with-gatsby-builds">
          <div>
            <div>
              <span>Wednesday, May 13th 2020</span>
            </div>

            <h3>Going headless during your Gatsby builds</h3>
            <p>Recently, Platform.</p>
          </div>
        </a>

        <a href="/posts/unknown/improve-visibility-over-your-external-integrations">
          <div>
            <div>
              <span>Tuesday, May 12th 2020</span>
            </div>

            <h3>Improve visibility over your external integrations</h3>
            <p>Stay updated with activities from your integrations in the API or CLI. Easily validate, test, and troubleshoot external integrations with Platform.sh.</p>
          </div>
        </a>

        <a href="/posts/unknown/improving-access-and-security-for-your-projects">
          <div>
            <div>
              <span>Monday, April 20th 2020</span>
            </div>

            <h3>Improving access and security for your projects</h3>
            <p>Improved user security measures, including strong password policies and Single Sign-On (SSO) capabilities for enhanced authentication and mitigation control.</p>
          </div>
        </a>

        <a href="/posts/unknown/supporting-drupal-covid-19">
          <div>
            <div>
              <span>Friday, April 17th 2020</span>
            </div>

            <h3>Supporting the Drupal Association through COVID-19</h3>
            <p>Platform.sh remains committed to DrupalCon, Drupal Association, and COVID-19 response initiatives during these challenging times.</p>
          </div>
        </a>

        <a href="/posts/unknown/taking-your-application-to-saas-a-business-decision">
          <div>
            <div>
              <span>Friday, April 17th 2020</span>
            </div>

            <h3>High-performance for cloud application development</h3>
            <p>Learn why some applications make it to a \$2 billion SaaS acquisition while others don't. Explore the path to SaaS success with Platform.sh.</p>
          </div>
        </a>

        <a href="/posts/unknown/new-enterprise-pricing-tiers-fleetops">
          <div>
            <div>
              <span>Wednesday, April 15th 2020</span>
            </div>

            <h3>New pricing tiers make FleetOps accessible</h3>
            <p>New product tiers offering features for managing multiple websites. Explore Platform.sh's Elite tier with Technical Account Management, higher SLAs, and more.</p>
          </div>
        </a>

        <a href="/posts/unknown/the-monolith-myth-why-tech-suites-are-not-solution">
          <div>
            <div>
              <span>Monday, April 13th 2020</span>
            </div>

            <h3>A monolith myth: All-in-one tech suites aren't the solution</h3>
            <p>Explore the reality behind all-in-one tech suites and why they often fail to meet the diverse needs of businesses</p>
          </div>
        </a>

        <a href="/posts/unknown/a-10x-increase-in-enterprise-valuation-over-two-years-a-saas-case-study">
          <div>
            <div>
              <span>Tuesday, April 7th 2020</span>
            </div>

            <h3>SaaS case study: 10x increase in enterprise valuation</h3>
            <p>Learn how an ecommerce company increased valuation via a Platform.sh cloud transition. Explore SaaS benefits, business value, and insights for your model.</p>
          </div>
        </a>

        <a href="/posts/unknown/the-suddenly-online-conference">
          <div>
            <div>
              <span>Thursday, April 2nd 2020</span>
            </div>

            <h3>The suddenly online conference: an Indy Cloud Conf case study</h3>
            <p>Explore the challenges and successes of transitioning from in-person conferences to remote events during the COVID-19 pandemic.</p>
          </div>
        </a>

        <a href="/posts/unknown/platformsh-covid-19-response">
          <div>
            <div>
              <span>Tuesday, March 17th 2020</span>
            </div>

            <h3>A note to Platform.sh customers about COVID-19 preparedness</h3>
            <p>Platform.sh remains fully operational during the COVID-19 pandemic. Learn about our measures to ensure business continuity and employee safety.</p>
          </div>
        </a>

        <a href="/posts/unknown/survival-guide-for-efficient-remote-work">
          <div>
            <div>
              <span>Friday, March 13th 2020</span>
            </div>

            <h3>Voilà! You’re now a distributed workforce</h3>
            <p>A Survival Guide for managers who need to drive a company that became remote overnight due to COVID-19</p>
          </div>
        </a>

        <a href="/posts/releases/deploy-strapi-on-platformsh">
          <div>
            <div>
              <span>Tuesday, March 3rd 2020</span>
            </div>

            <h3>Platform.sh–deploying the future of content with one click</h3>
            <p>Platform.sh and Strapi empower developers with a headless CMS solution for streamlined digital experiences. Deploy Strapi instantly. Learn more</p>
          </div>
        </a>

        <a href="/posts/unknown/out-of-the-lab-Node.js-12-features-graduate-from-experimental-status">
          <div>
            <div>
              <span>Tuesday, January 14th 2020</span>
            </div>

            <h3>Node.js 12 features graduate from experimental status</h3>
            <p>Discover the latest Node.js 12 LTS release with performance optimizations and new features. Upgrade your applications seamlessly with Platform.sh. Learn more!</p>
          </div>
        </a>

        <a href="/posts/unknown/what-is-new-with-jakarta-nosql-part-II">
          <div>
            <div>
              <span>Wednesday, January 8th 2020</span>
            </div>

            <h3>What’s new with Jakarta NoSQL? (Part II)</h3>
            <p>Discover cloud-native with Jakarta EE, best practices, and deploying applications with Jakarta EE NoSQL. Move to the cloud with Platform.sh.</p>
          </div>
        </a>

        <a href="/posts/unknown/sharpen-your-tusks-it-is-time-for-python-3.8">
          <div>
            <div>
              <span>Wednesday, December 18th 2019</span>
            </div>

            <h3>Sharpen your tusks: it's time for Python 3.8</h3>
            <p>Discover the latest features in Python 3.8, including the walrus operator, self-documenting f-strings, and more. Upgrade your Python applications</p>
          </div>
        </a>

        <a href="/posts/unknown/php-7.4-is-just-a-git-push-away">
          <div>
            <div>
              <span>Thursday, November 28th 2019</span>
            </div>

            <h3>PHP 7.4 is just a git push away</h3>
            <p>The latest features in PHP 7.4. Learn about typed properties, short-lambda syntax, null coalesce assignment, and opcache preloading.</p>
          </div>
        </a>

        <a href="/posts/unknown/new-services-page">
          <div>
            <div>
              <span>Tuesday, October 15th 2019</span>
            </div>

            <h3>New Services Page: more shininess, as promised</h3>
            <p>Discover the brand new Services page in our management console. Get detailed insights into your services, routes, and applications right from the console.</p>
          </div>
        </a>

        <a href="/posts/business/website-fleet">
          <div>
            <div>
              <span>Friday, October 11th 2019</span>
            </div>

            <h3>Website fleet management: challenges and opportunities</h3>
            <p>A solution to manage website fleets, automate code updates, and streamline operations for organizations with numerous websites and applications.</p>
          </div>
        </a>

        <a href="/posts/engineering/three-ways-to-manage-a-fleet">
          <div>
            <div>
              <span>Friday, October 11th 2019</span>
            </div>

            <h3>Three ways to manage a website fleet</h3>
            <p>Efficient multi-website management using Source Operations on Platform.sh. Automate updates, builds, and deployments for a large number of websites with ease.</p>
          </div>
        </a>

        <a href="/posts/unknown/strong-customer-authentication">
          <div>
            <div>
              <span>Thursday, September 26th 2019</span>
            </div>

            <h3>Strong Customer Authentication will be required for European credit and bank card payments</h3>
            <p>Get ready for Strong Customer Authentication (SCA) in Europe. Ensure your Platform.sh account complies with new credit card payment security regulations.</p>
          </div>
        </a>

        <a href="/posts/unknown/security-updates-for-php-rolling-out-now">
          <div>
            <div>
              <span>Wednesday, September 11th 2019</span>
            </div>

            <h3>Security updates for PHP: rolling out now</h3>
            <p>Stay secure with the latest PHP updates. Learn how Platform.sh ensures your protection with automatic upgrades. No action needed on your part.</p>
          </div>
        </a>

        <a href="/posts/unknown/go-release-1.13-on-Platform.sh">
          <div>
            <div>
              <span>Wednesday, September 4th 2019</span>
            </div>

            <h3>New: Go release 1.13 on Platform.sh</h3>
            <p>Upgrade your Go projects on Platform.sh to version 1.13, featuring improvements like Go Modules, enhanced number literal support, and more. Try it now!</p>
          </div>
        </a>

        <a href="/posts/unknown/try-out-the-future-of-php-on-platform.sh-today">
          <div>
            <div>
              <span>Tuesday, August 27th 2019</span>
            </div>

            <h3>PHP 7.4 is here: Try out the future of PHP on Platform.sh today!</h3>
            <p>Explore the new features in PHP 7.4 and learn how to deploy pre-release versions on Platform.sh to test and prepare your project for the official release.</p>
          </div>
        </a>

        <a href="/posts/unknown/microservices-in-the-cloud-part-two">
          <div>
            <div>
              <span>Friday, August 23rd 2019</span>
            </div>

            <h3>Microservices in the cloud, part two</h3>
            <p>Discover microservices, clean code, SOLID principles, and more. Explore Speaker, Session, Conference services with Eclipse MicroProfile.</p>
          </div>
        </a>

        <a href="/posts/unknown/microservices-in-the-cloud-part-one">
          <div>
            <div>
              <span>Tuesday, August 13th 2019</span>
            </div>

            <h3>Microservices in the cloud, part one</h3>
            <p>Microservices are a software architecture, where the systems are a collection of several independent services. Each service has a specific b</p>
          </div>
        </a>

        <a href="/posts/unknown/lisp">
          <div>
            <div>
              <span>Thursday, August 8th 2019</span>
            </div>

            <h3>We are happy, relieved and somewhat amused to announce the availability of Common Lisp on Platform.sh</h3>
            <p>Discover the history and uniqueness of Lisp, a programming language often called 'the path not taken,' and learn how to deploy a Lisp web applications.</p>
          </div>
        </a>

        <a href="/posts/unknown/platform.sh-documentation-new-guides-new-look">
          <div>
            <div>
              <span>Thursday, August 1st 2019</span>
            </div>

            <h3>Platform.sh documentation: new guides, new look</h3>
            <p>Explore the comprehensive Platform.sh documentation. Find step-by-step guides, tutorials, and resources to simplify web app development with Platform.sh.</p>
          </div>
        </a>

        <a href="/posts/unknown/jakarta-ee-generation-iv-a-new-hope">
          <div>
            <div>
              <span>Tuesday, July 30th 2019</span>
            </div>

            <h3>Jakarta EE: Generation IV - a new hope</h3>
            <p>Explore Jakarta EE & MongoDB on Platform.sh. Build enterprise apps with Java & NoSQL. Easy deployment with our tutorial.</p>
          </div>
        </a>

        <a href="/posts/unknown/version-will-be-required-in-type-what-it-means-for-your-projects">
          <div>
            <div>
              <span>Monday, July 22nd 2019</span>
            </div>

            <h3>Version will be required in type: what it means for your projects</h3>
            <p>Important changes to Platform.sh configuration requirements. Learn how including versions in your configurations impacts your projects.</p>
          </div>
        </a>

        <a href="/posts/unknown/eclipse-microprofiles-gain-agility-release-faster">
          <div>
            <div>
              <span>Monday, July 15th 2019</span>
            </div>

            <h3>Eclipse MicroProfiles: gain agility, release faster</h3>
            <p>Explore how Eclipse MicroProfile optimizes Enterprise Java for microservices architecture. Learn about Java frameworks and Platform.sh for cloud deployment.</p>
          </div>
        </a>

        <a href="/posts/unknown/web-dev-plus-IT-unique-roles-equal-partners-in-application-success">
          <div>
            <div>
              <span>Monday, June 24th 2019</span>
            </div>

            <h3>Web dev + IT: unique roles, equal partners in app success</h3>
            <p>Platform.sh enables web development teams to work autonomously without the need for IT assistance, with a focus on governance, security, and compliance.</p>
          </div>
        </a>

        <a href="/posts/unknown/Spring-MVC-and-MongoDB-a-match-made-in-Platform.sh-heaven">
          <div>
            <div>
              <span>Wednesday, June 19th 2019</span>
            </div>

            <h3>Spring MVC and MongoDB: a match made in Platform.sh heaven</h3>
            <p>Learn how to effortlessly integrate Spring MVC with MongoDB on Platform.sh. Create stand-alone, production-grade applications with ease.</p>
          </div>
        </a>

        <a href="/posts/unknown/off-with-its-head-headless-Chrome-as-a-service">
          <div>
            <div>
              <span>Wednesday, June 12th 2019</span>
            </div>

            <h3>Off with its Head! Headless Chrome as a Service decoded</h3>
            <p>Headless Chrome is a headless browser configurable on Platform.sh. Compare screenshots and generate PDFs hassle-free today</p>
          </div>
        </a>

        <a href="/posts/unknown/java-hello-world-at-platform.sh">
          <div>
            <div>
              <span>Thursday, June 6th 2019</span>
            </div>

            <h3>Java: Hello, World! at Platform.sh</h3>
            <p>Discover how to deploy Java applications on Platform.sh. Learn about Spring Boot, MySQL integration, and continuous deployment for Java apps.</p>
          </div>
        </a>

        <a href="/posts/unknown/apache-kafka-support">
          <div>
            <div>
              <span>Wednesday, June 5th 2019</span>
            </div>

            <h3>Apache Kafka now available</h3>
            <p>Discover the power of Apache Kafka for real-time streaming applications and data pipelines. Get started with Kafka on Platform.sh. No servers to configure.</p>
          </div>
        </a>

        <a href="/posts/unknown/new-german-region">
          <div>
            <div>
              <span>Wednesday, May 22nd 2019</span>
            </div>

            <h3>New Germany region: more speed, more capability, lower cost</h3>
            <p>Discover Platform.sh Enterprise in Germany. Get more speed, capability, and compliance for your applications with strict data control.</p>
          </div>
        </a>

        <a href="/posts/unknown/it-worked-in-staging">
          <div>
            <div>
              <span>Thursday, April 25th 2019</span>
            </div>

            <h3>Learning to trust the machines and the process in DevOps</h3>
            <p>Platform.sh enables seamless collaboration between development and operations teams, leading to predictable and reliable deployments for your applications.</p>
          </div>
        </a>

        <a href="/posts/unknown/shiny-new-platformsh-web-management-console">
          <div>
            <div>
              <span>Thursday, April 11th 2019</span>
            </div>

            <h3>Shiny, new Platform.sh management console</h3>
            <p>Explore the new and improved Platform.sh management console, built for better usability and visualization. Try it now and share your feedback!</p>
          </div>
        </a>

        <a href="/posts/unknown/adobe-summit-2019">
          <div>
            <div>
              <span>Monday, April 1st 2019</span>
            </div>

            <h3>Adobe Summit 2019: take-aways</h3>
            <p>Discover key announcements from the Adobe Summit 2019, including Magento integration and Adobe Experience Cloud.</p>
          </div>
        </a>

        <a href="/posts/unknown/four-days-four-languages-four-frameworks-day-3-gatsbyjs-the-reactbased-static-site-generator">
          <div>
            <div>
              <span>Thursday, February 28th 2019</span>
            </div>

            <h3>4 days, 4 languages, 4 frameworks, Day 3: GatsbyJS</h3>
            <p>Explore how to run GatsbyJS, a Progressive Web App (PWA), on Platform.sh. Learn about JAMstack architecture and deploy your Gatsby site easily.</p>
          </div>
        </a>

        <a href="/posts/unknown/four-days-four-languages-four-frameworks-day-2-running-hugo">
          <div>
            <div>
              <span>Wednesday, February 27th 2019</span>
            </div>

            <h3>4 days, 4 languages, 4 frameworks, Day 2: Running Hugo</h3>
            <p>Learn how to build a static site with Hugo on Platform.sh. Hugo is a fast and light static site generator that's easy to use with Platform.sh.</p>
          </div>
        </a>

        <a href="/posts/unknown/four-days-four-languages-four-frameworks-on-platformsh">
          <div>
            <div>
              <span>Tuesday, February 26th 2019</span>
            </div>

            <h3>Four days, four languages, four frameworks on Platform.sh</h3>
            <p>Learn how to run Brightspot CMS, a Java-based content management system, on Platform.sh with Apache Tomcat, MySQL, and Solr. Deploy with ease</p>
          </div>
        </a>

        <a href="/posts/unknown/platformsh-full-speed-ahead-into-2019">
          <div>
            <div>
              <span>Tuesday, January 29th 2019</span>
            </div>

            <h3>Platform.sh full speed ahead into 2019</h3>
            <p>Discover Platform.sh's achievements in 2018 and its goals for 2019. From customer success to robust products, see what's in store for the future.</p>
          </div>
        </a>

        <a href="/posts/unknown/open-source-software-roi-for-your-organization">
          <div>
            <div>
              <span>Wednesday, January 2nd 2019</span>
            </div>

            <h3>Open source software ROI for your organization</h3>
            <p>The benefits of contributing to open-source software and how it can enhance your organization, attract top developers, and improve your software quality.</p>
          </div>
        </a>

        <a href="/posts/unknown/give-the-gift-of-ruby-this-season">
          <div>
            <div>
              <span>Tuesday, December 18th 2018</span>
            </div>

            <h3>Give the gift of Ruby this season</h3>
            <p>Discover the new features in Ruby 2.5 and how to easily upgrade your Ruby apps to the latest version with Platform.sh. Enjoy improved performance and syntax.</p>
          </div>
        </a>

        <a href="/posts/releases/deploy-with-php-73-this-friday-er-thursday">
          <div>
            <div>
              <span>Thursday, December 6th 2018</span>
            </div>

            <h3>Deploy with PHP 7.3 this Friday, er, Thursday</h3>
            <p>Platform.sh welcomes PHP 7.3! Explore the latest features and performance improvements. Upgrade your application with a simple YAML tweak.</p>
          </div>
        </a>

        <a href="/posts/unknown/update-to-our-privacy-policy">
          <div>
            <div>
              <span>Monday, November 19th 2018</span>
            </div>

            <h3>Update to our Privacy Policy</h3>
            <p>The latest updates to our Privacy Policy, version 2.1, including grammar fixes, GDPR compliance, and a toll-free contact number for California citizens.</p>
          </div>
        </a>

        <a href="/posts/unknown/our-black-friday-gift-10000-cpus-overnight-without-downtime">
          <div>
            <div>
              <span>Friday, November 16th 2018</span>
            </div>

            <h3>Our Black Friday gift: 10,000 CPUs without downtime</h3>
            <p>Prepare your ecommerce site for Black Friday seamlessly with Platform.sh. Add capacity, handle high traffic, and ensure performance without downtime.</p>
          </div>
        </a>

        <a href="/posts/unknown/good-morning-australia-were-back-in-business">
          <div>
            <div>
              <span>Thursday, November 15th 2018</span>
            </div>

            <h3>Good morning, Australia: we’re back in business</h3>
            <p>Reflecting on Platform.sh's first year in Australia. Improved uptime, support, pricing, and plans for a better experience. Learn how we can help you.</p>
          </div>
        </a>

        <a href="/posts/unknown/why-you-should-care-about-wechat-before-its-too-late">
          <div>
            <div>
              <span>Wednesday, October 31st 2018</span>
            </div>

            <h3>Why you should care about WeChat before it's too late!</h3>
            <p>Learn about WeChat, China's super-app, and discover strategies for reaching its vast user base. WeChat's influence on mobile commerce and marketing.</p>
          </div>
        </a>

        <a href="/posts/releases/golang-forth-and-deploy">
          <div>
            <div>
              <span>Monday, October 29th 2018</span>
            </div>

            <h3>Go\[lang] forth and deploy</h3>
            <p>Discover the full support for Go 1.11 on Platform.sh. No more GOPATH required. Easy setup and deployment for Go applications with Go modules and Platform.sh.</p>
          </div>
        </a>

        <a href="/posts/unknown/were-improving-our-communications-tools-at-platformsh">
          <div>
            <div>
              <span>Friday, October 26th 2018</span>
            </div>

            <h3>We're improving our communications tools at Platform.sh</h3>
            <p>We value your privacy. Learn about our email management system, Marketo, and how to change your opt-in status.</p>
          </div>
        </a>

        <a href="/posts/releases/deploy-your-python-37-code-to-the-moon">
          <div>
            <div>
              <span>Wednesday, September 5th 2018</span>
            </div>

            <h3>Deploy your Python 3.7 code to the Moon</h3>
            <p>Platform.sh now supports Python 3.7. Explore the latest features and enhancements. Update your .platform.app.yaml file and enjoy Python 3.7!</p>
          </div>
        </a>

        <a href="/posts/unknown/platformsh-wins-2018-stratus-award-for-cloud-computing">
          <div>
            <div>
              <span>Thursday, August 30th 2018</span>
            </div>

            <h3>Platform.sh Wins 2018 Stratus Award for Cloud Computing</h3>
            <p>Platform.sh wins 2018 Stratus Award for Cloud Computing in the Platform-as-a-Service category by Business Intelligence Group.</p>
          </div>
        </a>

        <a href="/posts/unknown/of-cicadas-and-cron-jobs">
          <div>
            <div>
              <span>Tuesday, August 21st 2018</span>
            </div>

            <h3>Of Cicadas and cron jobs</h3>
            <p>Discover how cicadas and prime numbers can teach us about optimizing web development tasks and avoiding conflicts in cron jobs for smoother website performance.</p>
          </div>
        </a>

        <a href="/posts/unknown/its-july-2018-do-you-know-what-your-php-is">
          <div>
            <div>
              <span>Tuesday, July 3rd 2018</span>
            </div>

            <h3>It's July 2018, do you know what your PHP is?</h3>
            <p>Discover the benefits of upgrading to PHP 7, including better performance, enhanced security, and new functionality.</p>
          </div>
        </a>

        <a href="/posts/unknown/some-gifts-for-the-json-fans">
          <div>
            <div>
              <span>Thursday, June 28th 2018</span>
            </div>

            <h3>Some gifts for the JSON fans</h3>
            <p>Platform.sh now supports the latest MongoDB versions and Node.js version 10. Upgrade seamlessly to enjoy new features and stability for your applications.</p>
          </div>
        </a>

        <a href="/posts/unknown/your-guide-to-gdpr-compliance-training-your-employees">
          <div>
            <div>
              <span>Friday, June 8th 2018</span>
            </div>

            <h3>Your Guide to GDPR Compliance: Training your employees</h3>
            <p>Discover the importance of GDPR staff training for data protection and how it can safeguard your organization. Ensure GDPR compliance with informed employees.</p>
          </div>
        </a>

        <a href="/posts/unknown/the-github-acquisition-its-all-about-cloud-for-microsoft">
          <div>
            <div>
              <span>Tuesday, June 5th 2018</span>
            </div>

            <h3>The Github acquisition: it's all about cloud for Microsoft</h3>
            <p>Explore how Microsoft's acquisition of GitHub aligns with its cloud strategy and the emerging paradigm of GitOps for application deployment to the cloud.</p>
          </div>
        </a>

        <a href="/posts/unknown/your-guide-to-gdpr-compliance-transfers-of-personal-data-to-third-countries">
          <div>
            <div>
              <span>Wednesday, May 30th 2018</span>
            </div>

            <h3>Your Guide to GDPR Compliance: Transfers of personal data to third countries</h3>
            <p>International personal data transfers under GDPR and the conditions for such transfers. Ensure your organization complies with data protection rules.</p>
          </div>
        </a>

        <a href="/posts/unknown/your-guide-to-gdpr-compliance-data-protection-impact-assessment-and-security-measures-for-processing-data">
          <div>
            <div>
              <span>Friday, May 25th 2018</span>
            </div>

            <h3>Your Guide to GDPR Compliance: Data protection impact assessment and security measures for processing data</h3>
            <p>Discover how the GDPR's Data Protection Impact Assessment (DPIA) can help you identify and minimize privacy risks, build trust, and achieve compliance.</p>
          </div>
        </a>

        <a href="/posts/unknown/platformsh-raises-34m-to-bring-speed-and-confidence-to-enterprise-cloud-deployments">
          <div>
            <div>
              <span>Wednesday, May 23rd 2018</span>
            </div>

            <h3>Platform.sh raises \$34M in series C funding</h3>
            <p>Platform.sh secures \$34M in Series C funding to accelerate growth and support customers in North America. Simplify cloud infrastructures with Platform.sh.</p>
          </div>
        </a>

        <a href="/posts/unknown/your-guide-to-gdpr-compliance-data-subject-rights">
          <div>
            <div>
              <span>Wednesday, May 23rd 2018</span>
            </div>

            <h3>Your Guide to GDPR Compliance: Data subject rights</h3>
            <p>Explore GDPR data rights: be informed, access, rectify, erase, restrict processing, data portability, object, and automated decision-making.</p>
          </div>
        </a>

        <a href="/posts/unknown/data-protection-by-design-and-default">
          <div>
            <div>
              <span>Monday, May 7th 2018</span>
            </div>

            <h3>Data protection by design and by default</h3>
            <p>Explore protection by design in our GDPR blog series. Platform.sh ensures data security through privacy by design principles in this insightful article</p>
          </div>
        </a>

        <a href="/posts/unknown/platformsh-confirms-that-it-is-ready-for-the-gdpr">
          <div>
            <div>
              <span>Wednesday, May 2nd 2018</span>
            </div>

            <h3>Platform.sh confirms that it is ready for the GDPR</h3>
            <p>Discover what GDPR (General Data Protection Regulation) is and how it impacts your organization's data privacy. Learn about our GDPR measures and guidelines.</p>
          </div>
        </a>

        <a href="/posts/unknown/your-guide-to-gdpr-compliance-the-six-principles-of-processing-personal-data">
          <div>
            <div>
              <span>Friday, April 20th 2018</span>
            </div>

            <h3>Your Guide to GDPR Compliance: The Six Principles of Processing Personal Data</h3>
            <p>Discover the six key data protection principles of GDPR and why they are vital for compliance. Learn how to prioritize your GDPR efforts.</p>
          </div>
        </a>

        <a href="/posts/insights/what-will-you-do-after-you-deploy">
          <div>
            <div>
              <span>Tuesday, April 17th 2018</span>
            </div>

            <h3>What will you do after you deploy?</h3>
            <p>Learn how Platform.sh's post\_deploy hook can keep your site responsive during deploy tasks, making your deploys faster and more efficient.</p>
          </div>
        </a>

        <a href="/posts/unknown/your-guide-to-gdpr-compliance-roles-and-responsibilities">
          <div>
            <div>
              <span>Monday, April 9th 2018</span>
            </div>

            <h3>Your Guide to GDPR Compliance: Roles and Responsibilities</h3>
            <p>Learn the roles and responsibilities under GDPR - data subject, data controller, data processor. Get ready for GDPR compliance today!</p>
          </div>
        </a>

        <a href="/posts/unknown/your-guide-to-gdpr-compliance-introduction">
          <div>
            <div>
              <span>Wednesday, April 4th 2018</span>
            </div>

            <h3>Your Guide to GDPR Compliance (Introduction)</h3>
            <p>Get ready for GDPR with our comprehensive guide. Understand its impact, your responsibilities, and how to protect personal data and privacy.</p>
          </div>
        </a>

        <a href="/posts/unknown/drupal-critical-core-vulnerability-announced">
          <div>
            <div>
              <span>Wednesday, March 28th 2018</span>
            </div>

            <h3>Drupal critical core vulnerability announced</h3>
            <p>Urgent security update for Drupal users. Update to 8.5.1 / 8.4.9 / 8.3.8 / 7.58 immediately. Platform.sh is working on a platform-level fix.</p>
          </div>
        </a>

        <a href="/posts/unknown/using-platformsh-with-scrum">
          <div>
            <div>
              <span>Tuesday, February 13th 2018</span>
            </div>

            <h3>Using Platform.sh with Scrum</h3>
            <p>Learn how Platform.sh's Git-based environment workflow unblocks Scrum projects, allowing for efficient testing, parallel development, and feature isolation.</p>
          </div>
        </a>

        <a href="/posts/releases/hhvm-deploys-off-into-the-sunset">
          <div>
            <div>
              <span>Tuesday, January 30th 2018</span>
            </div>

            <h3>HHVM deploys off into the sunset</h3>
            <p>Platform.sh will no longer support HHVM runtime after 1 March 2018. Learn about this change and the evolution of PHP alternatives.</p>
          </div>
        </a>

        <a href="/posts/unknown/platformsh-is-ready-to-make-an-impact-in-china">
          <div>
            <div>
              <span>Wednesday, January 24th 2018</span>
            </div>

            <h3>Platform.sh is ready to make an Impact in China</h3>
            <p>Platform.sh is partnering with Impact China 2018 to help China ready startups expand their operations in China and offer cloud hosting services in the region.</p>
          </div>
        </a>

        <a href="/posts/unknown/spectremeltdown-security-update-notice">
          <div>
            <div>
              <span>Friday, January 5th 2018</span>
            </div>

            <h3>Spectre/Meltdown Security Update Notice</h3>
            <p>Platform.sh addresses the Spectre and Meltdown vulnerabilities with scheduled maintenance. Learn more about the updates and potential downtime.</p>
          </div>
        </a>

        <a href="/posts/unknown/backup-and-forget">
          <div>
            <div>
              <span>Wednesday, January 3rd 2018</span>
            </div>

            <h3>Backup and Forget</h3>
            <p>Learn how to automate disaster recovery backups using Platform.sh. A simple 3-step process for routine snapshots of your production environment.</p>
          </div>
        </a>

        <a href="/posts/unknown/a-look-back-on-2017">
          <div>
            <div>
              <span>Friday, December 29th 2017</span>
            </div>

            <h3>A look back on 2017</h3>
            <p>Explore a year of enhancements at Platform.sh, from HTTP/2 support to expanded services. Preview what's coming in 2018 for our PaaS.</p>
          </div>
        </a>

        <a href="/posts/unknown/tighten-up-your-tls">
          <div>
            <div>
              <span>Thursday, December 28th 2017</span>
            </div>

            <h3>Tighten up your TLS</h3>
            <p>Discover new TLS-related features for increased website security on Platform.sh. Restrict TLS versions, enable HSTS, and implement client-authenticated TLS.</p>
          </div>
        </a>

        <a href="/posts/unknown/route-all-the-things">
          <div>
            <div>
              <span>Wednesday, December 20th 2017</span>
            </div>

            <h3>Route all the things</h3>
            <p>Learn how the routing system works on Platform.sh, including its flexibility, multi-domain support, and routing configurations.</p>
          </div>
        </a>

        <a href="/posts/unknown/gitlab-integration-is-here">
          <div>
            <div>
              <span>Tuesday, December 12th 2017</span>
            </div>

            <h3>GitLab Integration is here!</h3>
            <p>Easily integrate GitLab with Platform.sh for streamlined code management, deployment, and collaboration. Create environments for every branch and pull request.</p>
          </div>
        </a>

        <a href="/posts/unknown/living-on-the-edge-with-ruby-25-preview">
          <div>
            <div>
              <span>Tuesday, December 12th 2017</span>
            </div>

            <h3>Living on the edge with Ruby 2.5 (preview)</h3>
            <p>Discover how to effortlessly migrate your Ruby and Rails applications to Ruby 2.5 on Platform.sh, with enhanced performance and new features.</p>
          </div>
        </a>

        <a href="/posts/unknown/platformsh-joins-the-prestigious-french-tech-tour-china-2017">
          <div>
            <div>
              <span>Sunday, December 3rd 2017</span>
            </div>

            <h3>Platform.sh joins the prestigious French Tech Tour China 2017</h3>
            <p>Join our CEO and team in Singapore, Hong Kong, Shenzhen, Shanghai, and Beijing for the French Tech Tour China 2017. Learn more about Platform.sh's journey.</p>
          </div>
        </a>

        <a href="/posts/unknown/welcome-to-the-world-php-72">
          <div>
            <div>
              <span>Thursday, November 30th 2017</span>
            </div>

            <h3>Welcome to the world, PHP 7.2!</h3>
            <p>Learn about the new features and improvements in PHP 7.2.0, including better performance and security enhancements. Try PHP 7.2.0 on Platform.sh with ease.</p>
          </div>
        </a>

        <a href="/posts/unknown/deploy-api-platform-on-platformsh">
          <div>
            <div>
              <span>Wednesday, November 29th 2017</span>
            </div>

            <h3>Simplifying API Platform Deployment on Platform.sh</h3>
            <p>Optimize API development with Platform.sh. Deploy API Platform effortlessly and unlock robust backend capabilities for your APIs</p>
          </div>
        </a>

        <a href="/posts/unknown/wordpress-security-updates-the-quick-way">
          <div>
            <div>
              <span>Wednesday, November 1st 2017</span>
            </div>

            <h3>WordPress security updates, the quick way</h3>
            <p>Learn how to update your WordPress version to 4.8.3 to fix a security vulnerability.</p>
          </div>
        </a>

        <a href="/posts/unknown/going-local-with-lando">
          <div>
            <div>
              <span>Wednesday, October 18th 2017</span>
            </div>

            <h3>Going Local with Lando</h3>
            <p>Lando, a Docker-based local development tool recommended by Platform.sh. Easily set up your local environment and sync data from for seamless web development.</p>
          </div>
        </a>

        <a href="/posts/unknown/wildcard-support-for-cookies-in-the-http-cache">
          <div>
            <div>
              <span>Tuesday, October 17th 2017</span>
            </div>

            <h3>Wildcard support for cookies in the HTTP cache</h3>
            <p>Learn how to use regular expressions for wildcard cookie matching at the cache layer on Platform.sh, improving caching rules and caching performance.</p>
          </div>
        </a>

        <a href="/posts/how-it-works/the-platformsh-build-and-deploy-pipeline">
          <div>
            <div>
              <span>Tuesday, October 3rd 2017</span>
            </div>

            <h3>The Platform.sh build-and-deploy pipeline</h3>
            <p>Learn how Platform.sh simplifies the build and deploy pipeline for web applications, ensuring consistency and repeatability with Git-based semantics.</p>
          </div>
        </a>

        <a href="/posts/unknown/taking-care-of-your-health">
          <div>
            <div>
              <span>Monday, October 2nd 2017</span>
            </div>

            <h3>Taking care of your health</h3>
            <p>Easily monitor your project's health with built-in notification checks for disk space, sent via email, Slack, or Pager Duty on Platform Professional projects.</p>
          </div>
        </a>

        <a href="/posts/unknown/platformsh-joins-orange-cloud-for-business-at-huawei-connect-2017-shanghai">
          <div>
            <div>
              <span>Monday, September 4th 2017</span>
            </div>

            <h3>Platform.sh & Orange Cloud at Huawei Connect 2017, Shanghai</h3>
            <p>Join Platform.sh and Orange Cloud for Business at Huawei Connect in Shanghai. Discover Continuous Deployment cloud hosting for agile development.</p>
          </div>
        </a>

        <a href="/posts/unknown/6-things-to-do-to-make-your-application-cloud-friendly">
          <div>
            <div>
              <span>Monday, August 7th 2017</span>
            </div>

            <h3>7 things to do to make your application cloud-friendly</h3>
            <p>Make your app cloud-friendly with 7 steps. Test it on Platform.sh for free to ensure compatibility in a real-world environment.</p>
          </div>
        </a>

        <a href="/posts/unknown/deploy-down-under-platformsh-is-now-available-in-australia">
          <div>
            <div>
              <span>Monday, July 3rd 2017</span>
            </div>

            <h3>Deploy Down Under: Platform.sh is now available in Australia</h3>
            <p>Experience unmatched Australian cloud hosting. Deploy PHP, NodeJS, Ruby & Python projects with Platform.sh's Continuous Deployment. Try it now!</p>
          </div>
        </a>

        <a href="/posts/unknown/containers-old-containers-new-memcached-support-and-php-72">
          <div>
            <div>
              <span>Monday, June 26th 2017</span>
            </div>

            <h3>Containers, memcached support, and PHP 7.2</h3>
            <p>Stay updated with Platform.sh's latest features, including MariaDB and Memcached support. Try PHP 7.2-alpha and explore new languages</p>
          </div>
        </a>

        <a href="/posts/unknown/now-available-sovereign-hosting-solution-in-microsoft-cloud-germany">
          <div>
            <div>
              <span>Thursday, June 22nd 2017</span>
            </div>

            <h3>Sovereign Hosting Solution in Microsoft Cloud Germany</h3>
            <p>A sovereign, end-to-end development and production hosting solution in Microsoft Cloud Germany. Ensure compliance, data security, and efficiency gains.</p>
          </div>
        </a>

        <a href="/posts/unknown/getting-to-5050-women-men-participation-polyconf-a-very-diverse-conference">
          <div>
            <div>
              <span>Thursday, June 8th 2017</span>
            </div>

            <h3>Getting to 50/50: Polyconf, a very diverse conference</h3>
            <p>Learn about PolyConf 2023, a conference promoting diversity in tech. Discover how Platform.sh supports gender diversity and inclusion in the tech community.</p>
          </div>
        </a>

        <a href="/posts/unknown/the-ultimate-third-party-resources-list-on-using-platformsh">
          <div>
            <div>
              <span>Tuesday, May 16th 2017</span>
            </div>

            <h3>The Ultimate Third Party Resources List on Using Platform.sh</h3>
            <p>Resources and guides from the Platform.sh community. Get tips on migrations, debugging, workflows, and more for your projects. Contribute to this growing list.</p>
          </div>
        </a>

        <a href="/posts/unknown/devops-gives-you-wings">
          <div>
            <div>
              <span>Tuesday, May 9th 2017</span>
            </div>

            <h3>DevOps gives you wings</h3>
            <p>Discover the importance of DevOps and automation for your organization. Learn how Platform.sh can help you achieve better DevOps for competitive success.</p>
          </div>
        </a>

        <a href="/posts/unknown/screencast-composer-and-continuous-integration">
          <div>
            <div>
              <span>Tuesday, May 9th 2017</span>
            </div>

            <h3>Screencast - Composer and Continuous Integration</h3>
            <p>Discover how Platform.sh simplifies Composer usage and streamlines continuous integration. Learn about managing PHP applications effectively.</p>
          </div>
        </a>

        <a href="/posts/unknown/sponsoring-predotscale-and-election-drinks">
          <div>
            <div>
              <span>Friday, April 21st 2017</span>
            </div>

            <h3>Sponsoring pre-dotScale and election drinks !</h3>
            <p>Platform.sh invites you to enjoy free drinks at Café Delaville in Paris before the dotSecurity and dotScale conferences. A perfect opportunity to mingle!</p>
          </div>
        </a>

        <a href="/posts/unknown/free-ssl-certificates-for-every-project-every-environment">
          <div>
            <div>
              <span>Thursday, April 20th 2017</span>
            </div>

            <h3>Free SSL certificates for every project & every environment</h3>
            <p>We now offer free automatic Let's Encrypt SSL certificates, making your site secure, fast, and feature-rich. Say hello to secure, fast, and easy web hosting!</p>
          </div>
        </a>

        <a href="/posts/unknown/imagine-2017-the-new-magento-ecosystem">
          <div>
            <div>
              <span>Thursday, April 13th 2017</span>
            </div>

            <h3>Imagine 2017: The New Magento Ecosystem</h3>
            <p>Dive into the excitement of Magento Imagine 2017. Discover how Magento's revitalized spirit and innovative approach are shaping the future of e-commerce.</p>
          </div>
        </a>

        <a href="/posts/unknown/global-app-cache-our-managed-tiered-cdn-feature-for-global-page-and-asset-cache-coverage">
          <div>
            <div>
              <span>Wednesday, April 5th 2017</span>
            </div>

            <h3>Global App Cache: Managed CDNs for optimal performance</h3>
            <p>CDN caching boosts website speed and reliability. Learn how our Global App Cache combines multiple CDNs for optimal delivery and 99.99% uptime.</p>
          </div>
        </a>

        <a href="/posts/unknown/influxdb">
          <div>
            <div>
              <span>Monday, March 27th 2017</span>
            </div>

            <h3>Now you can save time in a database</h3>
            <p>Introducing Influx DB 1.2, perfect for high-volume logging, data collection, and metrics. Easily add it to your services.yaml file for improved data handling.</p>
          </div>
        </a>

        <a href="/posts/unknown/oliver-sweeney-website-revamp-with-magento-cloud-powered-by-platformsh-oozes-sophistication-and-luxury">
          <div>
            <div>
              <span>Friday, March 17th 2017</span>
            </div>

            <h3>Oliver Sweeney website revamp with Magento Cloud</h3>
            <p>When your company sells luxury items, you want your website to offer that same exclusive, stunning digital experience for your customers too.</p>
          </div>
        </a>

        <a href="/posts/unknown/expands-usa-operations-meet-growing-demand-north-america">
          <div>
            <div>
              <span>Tuesday, February 14th 2017</span>
            </div>

            <h3>Platform.sh expands its US operations</h3>
            <p>Platform.sh opens its US headquarters in San Francisco, forms a US Advisory board, and launches strong North America recruitment to meet growing demand.</p>
          </div>
        </a>

        <a href="/posts/unknown/multi-mysql">
          <div>
            <div>
              <span>Friday, February 10th 2017</span>
            </div>

            <h3>Multiple MySQLs Make Platform.sh a Multisite Machine</h3>
            <p>Learn how Platform.sh now supports multiple databases in MySQL and restricted user access. Optimize your projects with flexible database configurations.</p>
          </div>
        </a>

        <a href="/posts/unknown/platformsh-at-the-oop-conference">
          <div>
            <div>
              <span>Thursday, January 26th 2017</span>
            </div>

            <h3>Platform.sh is down wit' OOP</h3>
            <p>Join us at OOP Conference 2017 in Munich from Jan 30 to Feb 3. Live demos, answers to your PaaS questions, and more at booth 3.14. Don't miss it!</p>
          </div>
        </a>

        <a href="/posts/unknown/persistent-redis">
          <div>
            <div>
              <span>Wednesday, January 25th 2017</span>
            </div>

            <h3>Redis, now for long-term keys and values</h3>
            <p>Discover Platform.sh's Redis Persistent Service, a super-fast key-value database that allows you to store data permanently. Learn how to configure and use it.</p>
          </div>
        </a>

        <a href="/posts/unknown/solr-63">
          <div>
            <div>
              <span>Tuesday, January 17th 2017</span>
            </div>

            <h3>New year, new Solr, new features</h3>
            <p>Platform.sh launches the new Apache Solr version 6.3 with multi-core support, providing better search capabilities for your applications.</p>
          </div>
        </a>

        <a href="/posts/unknown/mongodb_apocalypse">
          <div>
            <div>
              <span>Tuesday, January 10th 2017</span>
            </div>

            <h3>Your instances safe from MongoDB Apocalypse on the Platform.sh PaaS</h3>
            <p>Discover why your MongoDB instances are safe on Platform.sh. Our secure architecture keeps your data protected. Join us for peace of mind!</p>
          </div>
        </a>

        <a href="/posts/unknown/the-year-we-won-php">
          <div>
            <div>
              <span>Monday, January 9th 2017</span>
            </div>

            <h3>2016, The Year We Won PHP</h3>
            <p>Why Platform.sh is the preferred choice for hosting PHP applications. From Drupal and Symfony to Magento and more, we're here to make it run seamlessly.</p>
          </div>
        </a>

        <a href="/posts/unknown/http2">
          <div>
            <div>
              <span>Sunday, January 8th 2017</span>
            </div>

            <h3>Announcing HTTP/2 support!</h3>
            <p>Experience blazing-fast website loading times in 2017 with HTTP/2 support on all Platform.sh regions. No setup required; it's already active!</p>
          </div>
        </a>

        <a href="/posts/unknown/php-71">
          <div>
            <div>
              <span>Thursday, December 29th 2016</span>
            </div>

            <h3>Next Wave PHP now supported</h3>
            <p>Discover the latest PHP 7.1 features, async support, and PThreads support on Platform.sh. Upgrade your PHP version for improved speed and new features.</p>
          </div>
        </a>

        <a href="/posts/unknown/what-is-your-timezone">
          <div>
            <div>
              <span>Tuesday, December 27th 2016</span>
            </div>

            <h3>What's your timezone?</h3>
            <p>Discover how Platform.sh, a fully distributed company, manages its global team and communication using Node.js and self-hosted timezone.io.</p>
          </div>
        </a>

        <a href="/posts/unknown/production-artifact">
          <div>
            <div>
              <span>Friday, December 23rd 2016</span>
            </div>

            <h3>Production is an artifact of development</h3>
            <p>Explore the concept that production is an artifact of development and how Platform.sh revolutionizes web hosting for modern web applications.</p>
          </div>
        </a>

        <a href="/posts/unknown/project-variables">
          <div>
            <div>
              <span>Tuesday, December 20th 2016</span>
            </div>

            <h3>This week in new features - Build-time variables</h3>
            <p>Discover the benefits of project-level variables available at build time on Platform.sh and explore their use cases, including private composer repositories.</p>
          </div>
        </a>

        <a href="/posts/unknown/screencast-yaml">
          <div>
            <div>
              <span>Monday, December 19th 2016</span>
            </div>

            <h3>Screencast - Configuring your Platform.sh Project</h3>
            <p>Learn to set up your project on Platform.sh, manage dependencies with infrastructure as code, and gain independence in this quick technical screencast.</p>
          </div>
        </a>

        <a href="/posts/unknown/leader-php-hosting-multiple-partnerships">
          <div>
            <div>
              <span>Thursday, December 15th 2016</span>
            </div>

            <h3>Platform.sh at the forefront of PHP hosting in 2016</h3>
            <p>Platform.sh is the go-to PaaS for major PHP vendors like Magento, eZ Systems, TYPO3, and Sensio Labs. Get maximum scalability, stability, and performance.</p>
          </div>
        </a>

        <a href="/posts/how-it-works/repeatable-deployments">
          <div>
            <div>
              <span>Tuesday, December 13th 2016</span>
            </div>

            <h3>How repeatable deployments work</h3>
            <p>Platform.sh ensures predictable, repeatable deployments by controlling the key inputs to your application and guaranteeing code consistency.</p>
          </div>
        </a>

        <a href="/posts/unknown/app-updates-php">
          <div>
            <div>
              <span>Friday, December 9th 2016</span>
            </div>

            <h3>Application updates for PHP containers</h3>
            <p>Discover the latest improvements for PHP containers on Platform.sh. Learn about environment configuration, starting processes, and log file changes.</p>
          </div>
        </a>

        <a href="/posts/unknown/screencast-basic-platformsh-workflow">
          <div>
            <div>
              <span>Monday, December 5th 2016</span>
            </div>

            <h3>Screencast - Basic Platform.sh Workflow</h3>
            <p>Discover how Platform.sh makes Git branching and merging easier. Streamline your development process in this Platform.sh from Scratch series.</p>
          </div>
        </a>

        <a href="/posts/unknown/a-cloud-for-symfony">
          <div>
            <div>
              <span>Friday, December 2nd 2016</span>
            </div>

            <h3>A Cloud for Symfony</h3>
            <p>Discover SensioCloud, the new comprehensive cloud offering for Symfony applications. Managed services, optimized runtimes, and scalability.</p>
          </div>
        </a>

        <a href="/posts/unknown/typo3-8-starting-platformsh-cloud">
          <div>
            <div>
              <span>Thursday, October 27th 2016</span>
            </div>

            <h3>TYPO3 CMS 8 starting today with Platform.sh in the cloud</h3>
            <p>Try TYPO3 CMS 8 on Platform.sh with Microsoft Azure in Germany. Scale your projects, enjoy developer-friendly features, and ensure data protection.</p>
          </div>
        </a>

        <a href="/posts/unknown/do-more-with-less">
          <div>
            <div>
              <span>Monday, October 17th 2016</span>
            </div>

            <h3>Cut your digital budget by 30% by doing less work</h3>
            <p>Discover how Platform.sh can help you simplify digital, reduce costs, and increase efficiency with faster development and deployment processes.</p>
          </div>
        </a>

        <a href="/posts/unknown/typo3-platformsh-cloud-integration">
          <div>
            <div>
              <span>Thursday, October 13th 2016</span>
            </div>

            <h3>TYPO3 and Platform.sh announce cloud readiness and tech preview of strategic integration</h3>
            <p>Test TYPO3 on Platform.sh cloud hosting. Discover the benefits of this partnership with continuous delivery hosting. Ideal for Composer-based applications.</p>
          </div>
        </a>

        <a href="/posts/unknown/vc-ready-funding-survey">
          <div>
            <div>
              <span>Tuesday, October 4th 2016</span>
            </div>

            <h3>Three trends that make successful tech startups attractive to VCs</h3>
            <p>Explore best practices for software development and team management in today's startup landscape. Learn how to build attractive software for VC funding.</p>
          </div>
        </a>

        <a href="/posts/releases/python-ruby-support">
          <div>
            <div>
              <span>Friday, September 23rd 2016</span>
            </div>

            <h3>Continuous Deployment - Now with Python and Ruby support!</h3>
            <p>Platform.sh now offers continuous deployment for Ruby and Python developers. Explore the benefits of continuous deployment for your projects in these languages.</p>
          </div>
        </a>

        <a href="/posts/unknown/documentation-tng">
          <div>
            <div>
              <span>Wednesday, September 21st 2016</span>
            </div>

            <h3>Platform.sh Documentation - The Next Generation</h3>
            <p>Explore our redesigned documentation to discover the full potential of Platform.sh for your development needs.</p>
          </div>
        </a>

        <a href="/posts/unknown/ez-systems-partnership">
          <div>
            <div>
              <span>Monday, September 19th 2016</span>
            </div>

            <h3>We partnered with eZ Systems to accelerate development</h3>
            <p>eZ Systems and Platform.sh partner to accelerate development with eZ Platform, offering an accelerated path to build content-rich websites and applications.</p>
          </div>
        </a>

        <a href="/posts/releases/github-blackfire-platformsh">
          <div>
            <div>
              <span>Tuesday, August 30th 2016</span>
            </div>

            <h3>Develop on GitHub, Deploy on Platform.sh, Test on Blackfire.io</h3>
            <p>Learn how to easily integrate GitHub, Blackfire, and Platform.sh for streamlined code management, deployment, and performance testing.</p>
          </div>
        </a>

        <a href="/posts/unknown/gitflow-is-now-supported">
          <div>
            <div>
              <span>Wednesday, August 24th 2016</span>
            </div>

            <h3>GitFlow is now supported on Platform.sh!</h3>
            <p>Learn about our recent infrastructure update with bug fixes and GitFlow branch name support. Enjoy the new features on Platform.sh!</p>
          </div>
        </a>

        <a href="/posts/unknown/release-ui-2-13">
          <div>
            <div>
              <span>Tuesday, August 23rd 2016</span>
            </div>

            <h3>UI version 2.13 released</h3>
            <p>Announcing Platform.sh UI version 2.13 with new enhancements, error notifications, SSH key alerts, and better environment handling. Stay informed and organized. Try it now!</p>
          </div>
        </a>

        <a href="/posts/unknown/httpoxy">
          <div>
            <div>
              <span>Wednesday, July 20th 2016</span>
            </div>

            <h3>Httpoxy or how Platform.sh keeps your applications safe</h3>
            <p>Ensure your applications' security! We've fixed the Httpoxy vulnerability in every Platform.sh region, so you're safe without any redeployments.</p>
          </div>
        </a>

        <a href="/posts/unknown/release-ui-2-12">
          <div>
            <div>
              <span>Monday, July 18th 2016</span>
            </div>

            <h3>UI version 2.12 released</h3>
            <p>Announcing Platform.sh UI version 2.12 with enhancements for easier setup, domain validation, SSH keys, environment management, and user administration. Explore now!</p>
          </div>
        </a>

        <a href="/posts/unknown/release-ui-2-11">
          <div>
            <div>
              <span>Tuesday, July 5th 2016</span>
            </div>

            <h3>UI version 2.11 released</h3>
            <p>Announcing Platform.sh UI version 2.11 with new warning notifications, environment grouping, autofocus on text inputs, and improved display of environment variables.</p>
          </div>
        </a>

        <a href="/posts/unknown/new-features-june">
          <div>
            <div>
              <span>Thursday, June 30th 2016</span>
            </div>

            <h3>June Features Update</h3>
            <p>The latest updates and improvements from Platform.sh. From web interface enhancements to CLI improvements and Drupal 8 with Composer updates.</p>
          </div>
        </a>

        <a href="/posts/unknown/is-thecloud-really-someone-elses-computer">
          <div>
            <div>
              <span>Monday, June 27th 2016</span>
            </div>

            <h3>Is the Cloud really someone else's computer?</h3>
            <p>Difference between "the Cloud" and cloud computing. The benefits and drawbacks of both concepts, and how Platform.sh offers a unique approach to hosting.</p>
          </div>
        </a>

        <a href="/posts/unknown/cloud-adoption-europe-data-privacy">
          <div>
            <div>
              <span>Tuesday, June 21st 2016</span>
            </div>

            <h3>Cloud adoption in Europe: Addressing data privacy concerns</h3>
            <p>Discover the advantages of cloud services and data privacy considerations for European enterprises, including Platform.sh's partnership with Microsoft Azure.</p>
          </div>
        </a>

        <a href="/posts/unknown/marketing-manager-paris">
          <div>
            <div>
              <span>Friday, June 10th 2016</span>
            </div>

            <h3>Looking for our new marketing manager! Are you the one?</h3>
            <p>Exciting opportunity to join the award-winning Platform.sh marketing team. Grow your career with a groundbreaking hosting and development tool.</p>
          </div>
        </a>

        <a href="/posts/unknown/drupal-8-starter-kit-now-with-php-7-and-composer">
          <div>
            <div>
              <span>Tuesday, June 7th 2016</span>
            </div>

            <h3>Drupal 8 starter kit now with PHP 7 and Composer!</h3>
            <p>Discover how Drupal 8.1 embraces Composer and PHP 7 on Platform.sh. Learn what changes and how it benefits your Drupal projects.</p>
          </div>
        </a>

        <a href="/posts/unknown/release-ui-2-10">
          <div>
            <div>
              <span>Tuesday, June 7th 2016</span>
            </div>

            <h3>UI version 2.10 released</h3>
            <p>Announcing Platform.sh UI version 2.10 with accessibility improvements, better messages, and enhanced log display in the activity stream.</p>
          </div>
        </a>

        <a href="/posts/unknown/microsoft-joint-paas-offering">
          <div>
            <div>
              <span>Thursday, June 2nd 2016</span>
            </div>

            <h3>Microsoft and Platform.sh announce joint PaaS offering for High Availability (HA) hosting</h3>
            <p>Platform.sh announces plans for scalable web apps in German datacenters, offering 99.99% uptime, and Azure integration. Learn more today!</p>
          </div>
        </a>

        <a href="/posts/unknown/isv-saas-iaas-providers">
          <div>
            <div>
              <span>Wednesday, May 25th 2016</span>
            </div>

            <h3>Software vendor, SaaS or IaaS - doesn’t matter which. Platform.sh really is the killer app for you!</h3>
            <p>Discover how Platform.sh is revolutionizing SaaS, software vendors, and hosting providers by offering innovative solutions in the cloud computing space.</p>
          </div>
        </a>

        <a href="/posts/unknown/drupalcon-nola-survival-guide">
          <div>
            <div>
              <span>Thursday, May 5th 2016</span>
            </div>

            <h3>DrupalCon New Orleans Survival Guide</h3>
            <p>Attending DrupalCon New Orleans? Learn tips for making the most of your experience, from networking to sessions and sprints, with Platform.sh.</p>
          </div>
        </a>

        <a href="/posts/unknown/larry-garfield-joins-platformsh">
          <div>
            <div>
              <span>Monday, May 2nd 2016</span>
            </div>

            <h3>The one and only Director of Runtimes and Integrations</h3>
            <p>Meet Larry Garfield, our new Director of Runtimes, Integrations, and Services. Discover why he's a perfect fit for Platform.sh and connect with him on Twitter.</p>
          </div>
        </a>

        <a href="/posts/unknown/magento-enterprise-cloud-edition-powered-by-platform-sh">
          <div>
            <div>
              <span>Tuesday, April 12th 2016</span>
            </div>

            <h3>Platform.sh Provides PaaS Technology to Magento Commerce</h3>
            <p>Discover how Magento Commerce benefits from Platform.sh's second-generation PaaS for its Enterprise Cloud Edition, enhancing development and release management.</p>
          </div>
        </a>

        <a href="/posts/unknown/deploy-to-the-moon">
          <div>
            <div>
              <span>Friday, April 1st 2016</span>
            </div>

            <h3>Platform.sh announces world’s first LDN for web applications</h3>
            <p>Platform.sh achieves the extraordinary by deploying PHP apps on the lunar surface. Experience the world's first Lunar Delivery Network (LDN).</p>
          </div>
        </a>

        <a href="/posts/unknown/release-cli-3-0">
          <div>
            <div>
              <span>Tuesday, March 22nd 2016</span>
            </div>

            <h3>CLI version 3.0 released</h3>
            <p>Announcing Platform.sh CLI version 3.0 with major changes: new file structure, web root location, and PHP requirement. Upgrade now!</p>
          </div>
        </a>

        <a href="/posts/unknown/platform.sh-independent-company">
          <div>
            <div>
              <span>Tuesday, February 9th 2016</span>
            </div>

            <h3>Platform.sh becomes an independent company</h3>
            <p>Exciting news from Platform.sh! We're now an independent company, with a renewed focus on our cloud hosting solution. Read about our journey and plans.</p>
          </div>
        </a>

        <a href="/posts/unknown/php-session-bug">
          <div>
            <div>
              <span>Thursday, December 17th 2015</span>
            </div>

            <h3>All Platform.sh clients kept automatically safe from serious PHP bug</h3>
            <p>PHP session extension bug and how Platform.sh has automatically updated sites to prevent vulnerability. No action required for our customers.</p>
          </div>
        </a>

        <a href="/posts/unknown/drupal-8-release-party">
          <div>
            <div>
              <span>Thursday, November 19th 2015</span>
            </div>

            <h3>Drupal 8.0 has been released... Party time!</h3>
            <p>Join the global Drupal 8 release celebration! Learn more about Drupal 8 parties and deploy it today on Platform.sh for a free trial.</p>
          </div>
        </a>

        <a href="/posts/unknown/safe-harbour-safe">
          <div>
            <div>
              <span>Tuesday, November 3rd 2015</span>
            </div>

            <h3>Concerned about the recent European Court ruling on Safe Harbor?</h3>
            <p>Discover the consequences of the EU-US Safe Harbor agreement invalidation and how Platform.sh offers flexibility to protect your data as needed.</p>
          </div>
        </a>

        <a href="/posts/unknown/badcamp">
          <div>
            <div>
              <span>Tuesday, October 20th 2015</span>
            </div>

            <h3>Platform.sh to exhibit at BADCamp 2015</h3>
            <p>Platform.sh, a Contrib Level sponsor, will be at BADCamp 2015. Visit our booth for demos and learn about web application hosting.</p>
          </div>
        </a>

        <a href="/posts/unknown/best-horizontal-cloud-solution-for-2015-in-europe">
          <div>
            <div>
              <span>Friday, October 9th 2015</span>
            </div>

            <h3>Platform.sh Best Horizontal Cloud Solution for 2015 in Europe</h3>
            <p>Platform.sh awarded Best Horizontal Cloud Solution in Europe by Eurocloud. Find out more.</p>
          </div>
        </a>

        <a href="/posts/unknown/release-hhvm">
          <div>
            <div>
              <span>Wednesday, September 23rd 2015</span>
            </div>

            <h3>HHVM versions 3.9 and 3.12 supported</h3>
            <p>Announcing HHVM support on Platform.sh. HHVM offers improved PHP performance and scalability. Learn how to use and configure it in our documentation.</p>
          </div>
        </a>

        <a href="/posts/unknown/symfony-documentation-pull-requests">
          <div>
            <div>
              <span>Thursday, September 10th 2015</span>
            </div>

            <h3>Platform.sh hosts Symfony documentation GitHub pull requests</h3>
            <p>Symfony's documentation now uses Platform.sh for automatic code deployment into isolated environments, simplifying review and testing.</p>
          </div>
        </a>

        <a href="/posts/unknown/featured-on-bitbucket">
          <div>
            <div>
              <span>Monday, August 17th 2015</span>
            </div>

            <h3>Platform.sh / Bitbucket Integration, featured on the Bitbucket Blog</h3>
            <p>Discover the Bitbucket integration with Platform.sh. Learn how it works in this short screencast. Get the details on the Bitbucket Blog.</p>
          </div>
        </a>

        <a href="/posts/unknown/platform-sh-hiring-interns">
          <div>
            <div>
              <span>Monday, August 10th 2015</span>
            </div>

            <h3>Hiring interns</h3>
            <p>Explore cloud engineering internships at Platform.sh. Gain hands-on experience with high availability cloud infrastructure and cutting-edge technologies.</p>
          </div>
        </a>

        <a href="/posts/unknown/work-with-distribution">
          <div>
            <div>
              <span>Tuesday, July 28th 2015</span>
            </div>

            <h3>The correct way to work with Drupal distributions</h3>
            <p>Learn how to easily build and maintain your Drupal site on top of distributions using Platform.sh's support for Drush Make files.</p>
          </div>
        </a>

        <a href="/posts/unknown/release-docs-3-0">
          <div>
            <div>
              <span>Saturday, July 25th 2015</span>
            </div>

            <h3>Documentation version 3.0 released</h3>
            <p>Announcing Platform.sh documentation version 3.0 with improved guides and easier contributions. Explore the new documentation now!</p>
          </div>
        </a>

        <a href="/posts/unknown/five-platform-sh-the-paas-for-drupal-8">
          <div>
            <div>
              <span>Thursday, July 16th 2015</span>
            </div>

            <h3>Five reasons why Platform.sh is the PaaS you need for Drupal 8</h3>
            <p>Discover why Drupal 8 on Platform.sh is making waves. From Swiss publishers to usability testing, explore the Drupal 8 hype. Get ready for the future!</p>
          </div>
        </a>

        <a href="/posts/unknown/best-horizontal-cloud-platform-eurocloud">
          <div>
            <div>
              <span>Friday, July 10th 2015</span>
            </div>

            <h3>Platform.sh elected Best Horizontal Cloud Platform of the year</h3>
            <p>Platform.sh wins Best Cloud Services for horizontal markets at CLOUD WEEK Paris. Discover how Platform.sh empowers marketing teams for agile web development.</p>
          </div>
        </a>

        <a href="/posts/unknown/ceo-interviewed-on-bfm-business">
          <div>
            <div>
              <span>Wednesday, July 8th 2015</span>
            </div>

            <h3>CEO of Commerce Guys is interviewed by the main French Business TV Channel about Platform.sh</h3>
            <p>Fred Plais, Platform.sh CEO, discusses Platform.sh's innovation and European Grant on French business TV channel interview.</p>
          </div>
        </a>

        <a href="/posts/unknown/european-horizon-2020-grant">
          <div>
            <div>
              <span>Thursday, June 25th 2015</span>
            </div>

            <h3>Platform.sh awarded a €1.95M grant</h3>
            <p>PaaS leader Platform.sh receives EU innovation grant. Explore their ambitious roadmap for multi-cloud, distributed storage, and more.</p>
          </div>
        </a>

        <a href="/posts/unknown/2015-06-european-cloud-leadership-born-in-france">
          <div>
            <div>
              <span>Tuesday, June 23rd 2015</span>
            </div>

            <h3>European cloud leadership is being born before our very own eyes in France</h3>
            <p>Discover how Platform.sh achieved success following Commerce Guys with 250+ customers worldwide.</p>
          </div>
        </a>

        <a href="/posts/unknown/release-ui-2-0">
          <div>
            <div>
              <span>Wednesday, May 27th 2015</span>
            </div>

            <h3>UI version 2.0 released</h3>
            <p>Announcing Platform.sh UI version 2.0 with new features: environment status, access control, SSH key upload, SSL certificate management, and more.</p>
          </div>
        </a>

        <a href="/posts/unknown/groundbreaking-drupal-8-news-portal-goes-live-platformsh">
          <div>
            <div>
              <span>Wednesday, May 13th 2015</span>
            </div>

            <h3>Groundbreaking Drupal 8 news portal goes live on Platform.sh</h3>
            <p>Platform.sh, PaaS leader, is hosting one of the first Enterprise production sites on Drupal 8. Platform.sh enhances development workflows.</p>
          </div>
        </a>

        <a href="/posts/unknown/platformsh-cli-developments-1-10">
          <div>
            <div>
              <span>Monday, March 16th 2015</span>
            </div>

            <h3>Platform.sh CLI developments</h3>
            <p>Explore the latest updates and features in the Platform.sh CLI, the powerful tool for web developers. Manage your projects with ease. Install or upgrade now!</p>
          </div>
        </a>

        <a href="/posts/how-it-works/how-platform-paas-works">
          <div>
            <div>
              <span>Tuesday, March 3rd 2015</span>
            </div>

            <h3>How the Platform.sh PaaS works</h3>
            <p>Discover how Platform.sh simplifies PaaS. Focus on your code; we manage the rest. Explore our second-generation PaaS for seamless application development.</p>
          </div>
        </a>

        <a href="/posts/discussions/containers-are-the-new-static-binaries">
          <div>
            <div>
              <span>Thursday, February 26th 2015</span>
            </div>

            <h3>Containers are the new static binaries</h3>
            <p>Platform.sh updates: new languages, MariaDB, and PHP 7.2-alpha support. Stay informed and enjoy your containers.</p>
          </div>
        </a>

        <a href="/posts/unknown/blackfire-integration">
          <div>
            <div>
              <span>Monday, February 2nd 2015</span>
            </div>

            <h3>Support for Blackfire Profiler</h3>
            <p>Optimize performance with Blackfire Profiler on Platform.sh. Monitor server resources, identify bottlenecks, and compare codebases for better performance.</p>
          </div>
        </a>

        <a href="/posts/unknown/release-ui-1-10">
          <div>
            <div>
              <span>Monday, January 26th 2015</span>
            </div>

            <h3>UI version 1.10 released</h3>
            <p>Announcing Platform.sh UI version 1.10 with easy SSH key upload and snapshot restoration. Enhance your Platform.sh experience. Explore the new features now!</p>
          </div>
        </a>

        <a href="/posts/unknown/release-cli-1-7">
          <div>
            <div>
              <span>Tuesday, January 20th 2015</span>
            </div>

            <h3>CLI version 1.7 released</h3>
            <p>Announcing Platform.sh CLI version 1.7.1 with new features, improved commands, and enhanced HTTP access control. Install or upgrade using Composer!</p>
          </div>
        </a>

        <a href="/posts/unknown/git-clients-vulnerable">
          <div>
            <div>
              <span>Friday, December 19th 2014</span>
            </div>

            <h3>Git clients vulnerable</h3>
            <p>Learn about the Git vulnerability affecting Mac OS X and Windows users. Find out how Platform.sh customers can protect their Git clients.</p>
          </div>
        </a>

        <a href="/posts/unknown/release-ui-1-9">
          <div>
            <div>
              <span>Wednesday, December 3rd 2014</span>
            </div>

            <h3>UI version 1.9 released</h3>
            <p>Announcing Platform.sh UI version 1.9 with quick environment access, easy Git and SSH command copying, and unified configuration screens.</p>
          </div>
        </a>

        <a href="/posts/unknown/us-platform-adoption">
          <div>
            <div>
              <span>Wednesday, November 5th 2014</span>
            </div>

            <h3>Leading digital agencies adopt Platform.sh to support Continuous Delivery</h3>
            <p>Discover the benefits of Platform.sh for hosting Drupal and Symfony web applications. Streamline development, reduce costs, and improve deployment.</p>
          </div>
        </a>

        <a href="/posts/unknown/release-cli-1-2">
          <div>
            <div>
              <span>Wednesday, October 29th 2014</span>
            </div>

            <h3>CLI version 1.2 released</h3>
            <p>Announcing Platform.sh CLI version 1.2.2 with new features, colorful interface, safer commands, and more. Install or upgrade using Composer now!</p>
          </div>
        </a>

        <a href="/posts/unknown/1000-tickets-strong">
          <div>
            <div>
              <span>Wednesday, October 22nd 2014</span>
            </div>

            <h3>1000 tickets strong</h3>
            <p>Join us in recognizing the milestone of 1,000 support tickets, showcasing rapid responses, high satisfaction, and efficient issue resolution.</p>
          </div>
        </a>

        <a href="/posts/unknown/protecting-your-apps">
          <div>
            <div>
              <span>Tuesday, October 21st 2014</span>
            </div>

            <h3>Protecting your apps</h3>
            <p>Platform.sh launched automated blocking for critical vulnerabilities (incl. Drupal SQL Injection) and seeks collaborators for an open-source signature database</p>
          </div>
        </a>

        <a href="/posts/unknown/sa-core-2014-005">
          <div>
            <div>
              <span>Wednesday, October 15th 2014</span>
            </div>

            <h3>Platform.sh and Drupal 7.32 Core SQL Injection</h3>
            <p>Learn about the Drupal 7.32 security update and the steps taken by Platform.sh to protect your Drupal website from a severe SQL injection vulnerability.</p>
          </div>
        </a>

        <a href="/posts/unknown/wunderkraut-chooses-platform">
          <div>
            <div>
              <span>Tuesday, September 30th 2014</span>
            </div>

            <h3>Wunderkraut adopts Platform.sh for all of its 14 international offices</h3>
            <p>Wunderkraut announces their partnership for adopting Platform.sh in all 14 international offices, enhancing cloud hosting and development.</p>
          </div>
        </a>

        <a href="/posts/unknown/platform-removes-developer-overhead-6">
          <div>
            <div>
              <span>Tuesday, September 23rd 2014</span>
            </div>

            <h3>FlixBus launches new eCommerce Service on Platform.sh Enterprise</h3>
            <p>sh is a one-stop solution offering a new paradigm in collaborative web development and live hosting London, U.</p>
          </div>
        </a>

        <a href="/posts/unknown/release-cli-1-1">
          <div>
            <div>
              <span>Tuesday, September 9th 2014</span>
            </div>

            <h3>CLI version 1.1 released</h3>
            <p>Platform.sh CLI version 1.1.0 is out with new features and commands. Upgrade now! Learn more on GitHub.</p>
          </div>
        </a>

        <a href="/posts/unknown/platform-removes-developer-overhead">
          <div>
            <div>
              <span>Thursday, July 31st 2014</span>
            </div>

            <h3>How the Platform.sh PaaS removes developer overhead</h3>
            <p>Platform.sh is a PaaS designed to bring continuous delivery to Drupal. Explore its features and CLI for agile Drupal development.</p>
          </div>
        </a>

        <a href="/posts/unknown/commerce-guys-launches-platform">
          <div>
            <div>
              <span>Tuesday, May 13th 2014</span>
            </div>

            <h3>Commerce Guys Launches Platform.sh, Continuous Delivery Cloud on Amazon Web Services</h3>
            <p>Discover Platform.sh, a revolutionary cloud hosting solution for Drupal, Symfony, and PHP-based applications. Achieve up to 25% savings on developer effort.</p>
          </div>
        </a>
      </ShowMore>
    </div>
  </div>
</div>


# Advanced prompting techniques for complex coding tasks
Source: https://developer.upsun.com/posts/insights/advanced-prompting-techniques-for-coding

This articles will give you an overview of prompting strategies that help coding assistants reason through difficult problems and produce higher-quality solutions.


<PostMeta />

When you're tackling sophisticated development challenges or refactoring a large codebase, basic prompting approaches may fall short. Complex coding tasks such as implementing algorithms, designing architectures, or building systems with multiple integrated components require more advanced prompting techniques.

This articles will give you an overview of prompting strategies that help coding assistants reason through difficult problems and produce higher-quality solutions.

Most of the strategies are inspired from general white-paper about **Prompt Engineering** by *Lee Boonstra* and adapted to the Coding context.

## Chain of Thought prompting for algorithm development

Chain of Thought (CoT) prompting guides the coding assistant to break down complex reasoning into explicit steps. This is particularly valuable for algorithm development, where logic needs to be constructed. This is what we see appearing right now with reasoning models.

The technique works by instructing the assistant to solve the problem step by step, thinking through each part of the solution before writing any code:

```
Implement a TypeScript function to find the longest increasing subsequence in an array.

Think through this problem step by step:
1. First, define what we're looking for precisely
2. Consider the naive approach and its limitations
3. Develop a dynamic programming solution
4. Analyze the time and space complexity
5. Implement the optimized solution with appropriate comments

Then write the final solution with full TypeScript typing.
```

By explicitly requesting this step-by-step reasoning, you:

1. Force the assistant to consider the problem more thoroughly
2. Reduce the likelihood of errors in complex logic
3. Get insight into the assistant's reasoning, making it easier to spot mistakes
4. End up with better-documented code that explains its own approach

This technique is especially powerful for:

* Graph algorithms
* Dynamic programming problems
* Complex data transformations
* Optimization challenges
* Recursive algorithms

## Step-back prompting for architectural decisions

Step-back prompting is a technique where you ask the assistant to consider a higher-level view before diving into implementation details. This is invaluable for architectural decisions where the broader context matters significantly.

Here's how to apply this technique:

```
I need to implement a caching layer for our API service that handles user authentication.

Before writing any code, let's step back and consider:
1. What are the key requirements for a caching system in an authentication context?
2. What are the security implications we need to address?
3. What caching strategies would be appropriate for different types of authentication data?
4. How should we handle cache invalidation when credentials change?
5. What are the performance vs. consistency tradeoffs of different approaches?

After analyzing these aspects, recommend an architectural approach and then implement 
a TypeScript class that provides this caching functionality.
```

This approach is particularly useful when:

* Designing system architecture
* Making significant refactoring decisions
* Building reusable libraries or frameworks
* Implementing security-critical components
* Creating systems that must scale

## Using JSON schemas to define expected code structures

For complex code structures, providing a JSON schema can dramatically improve the quality of generated code. This works especially well for defining expected interfaces, API responses, or configuration objects:

```text theme={null}
Create a Python FastAPI application for a book management system.

The API should conform to this JSON schema for book objects:

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "Unique identifier for the book"
    },
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "author": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "biography": { "type": "string", "nullable": true }
      },
      "required": ["name"]
    },
    "publication_year": {
      "type": "integer",
      "minimum": 1000,
      "maximum": 2100
    },
    "genres": {
      "type": "array",
      "items": { "type": "string" },
      "minItems": 1
    },
    "available_copies": {
      "type": "integer",
      "minimum": 0
    }
  },
  "required": ["title", "author", "publication_year", "genres"]
}

Implement the complete API with endpoints for CRUD operations, proper validation, error handling, and data persistence using SQLAlchemy.
```

The schema provides clear constraints and expectations that help the coding assistant generate appropriate models, validation logic, and API endpoints that align with your data requirements.

<Note>
  If you are using a strongly typed language like TypeScript, adding the types to the prompt instead of a JSON schema is also possible.
</Note>

## Self-consistency through multiple solutions

For particularly complex problems, you can leverage the technique of generating multiple approaches and comparing them:

```
Implement an efficient Python function to detect cycles in a directed graph.

Generate three different approaches to solving this problem:
1. A solution using depth-first search
2. A solution using Tarjan's algorithm
3. A solution using topological sorting

For each approach, explain its:
- Time and space complexity
- Key advantages
- Potential limitations

Then, recommend which approach is best for a graph with approximately 10,000 nodes and 50,000 edges, and implement that solution with full type annotations and documentation.
```

This technique helps in several ways:

* It explores multiple valid solutions to complex problems
* It makes trade-offs explicit
* It provides you with alternatives if one approach doesn't work in your specific context
* It gives you deeper insight into the problem space

## Progressive disclosure of requirements

For very complex features, the progressive disclosure technique breaks down implementation into stages, allowing you to review and refine at each step:

```
We need to build a TypeScript library for handling complex form validation with 
nested fields, async validation rules, and dependency tracking between fields.

Let's approach this in stages:

Stage 1: First, design the core interfaces for the validation library without 
implementation. Focus on how developers would use this API and what types they 
would interact with.

[After reviewing the interfaces]

Stage 2: Implement the core validation engine that can process validation rules 
and track field validity state.

[After reviewing the core implementation]

Stage 3: Add support for field dependencies where validating one field requires 
values from other fields.

[After reviewing dependencies implementation]

Stage 4: Implement asynchronous validation support with proper loading states 
and error handling.
```

This approach:

* Makes complex implementations more manageable
* Gives you control points to provide feedback
* Ensures the foundation is solid before building advanced features
* Reduces the chance of fundamental design issues

## Combining structured and natural language requirements

For the most sophisticated coding tasks, combine structured requirements with natural language explanations:

```
Create a Python data pipeline for processing time series sensor data with anomaly detection.

Technical Requirements:
- Input: CSV files with timestamp, sensor_id, and multiple reading columns
- Output: Processed data in Parquet format with anomalies flagged
- Performance: Must process 50GB of data in under 30 minutes on standard hardware
- Deployment: Must work within an Apache Airflow environment

Functional Description:
The system monitors industrial equipment through multiple sensors. Each sensor 
generates readings every 5 seconds. We need to identify anomalies that might indicate equipment failure, specifically looking for:

1. Sudden spikes or drops in readings
2. Gradual drift beyond acceptable thresholds
3. Unusual patterns compared to historical data for similar time periods
4. Correlation anomalies between related sensors

Implementation Guidance:
- Use pandas for initial data loading but switch to Dask for processing at scale
- Implement statistical anomaly detection using robust algorithms suitable for time series
- Include proper logging and error handling
- Design the pipeline to be fault-tolerant and resumable
- Structure the code to make adding new anomaly detection algorithms easy in the future

Start by defining the core data structures and pipeline architecture, then implement the main processing components.
```

This comprehensive approach provides both specific technical constraints and broader context about the problem domain, helping the coding assistant understand not just what to build but why certain approaches might be more appropriate than others.

## Directed improvement through iterative prompting

For extremely sophisticated development tasks, use iterative prompting to refine solutions:

```
Let's build a TypeScript state management library similar to Redux but with improved TypeScript type safety and less boilerplate.

First iteration: Design the core types and basic store implementation with actions and reducers.

[Review the first output and then continue]

Great, now let's address these issues:
1. The type inference could be improved for action creators
2. We need better handling of async actions
3. Add support for middleware with proper typing

[Review the second iteration and continue]

Now let's enhance it with:
1. Add selector functions with memoization
2. Implement proper devtools integration
3. Create a React hook API for consuming the store

[Final review]

Finally, create a complete example using this library to manage a simple application state,
demonstrating all the features we've implemented.
```

This approach allows you to:

* Focus on one aspect of a complex system at a time
* Build incrementally with course corrections
* Address specific weaknesses in each iteration
* End up with a more polished final product

## Wrap-up

By employing these advanced prompting techniques for complex coding tasks, you can help coding assistants tackle problems that would be beyond their capabilities with simpler prompting approaches.

These methods essentially augment the reasoning capabilities of the underlying models, allowing them to work through difficulty by breaking it down into manageable pieces.

While we see a rise in the use of reasoning models, these will still need guidelines to output what you actually need.


# Build-time environment variables considered harmful
Source: https://developer.upsun.com/posts/insights/build-time-environment-variables-considered-harmful

Build-time environment variables break deployment caching, compromise security, and force unnecessary rebuilds. Learn why runtime configuration is the better alternative.

<PostMeta />

Build-time environment variables seem convenient, but they come with hidden costs that can undermine your deployment pipeline's reliability and performance.

## How deployment pipelines actually work

When you push code to [Upsun](https://www.upsun.com), the [build process](https://docs.upsun.com/learn/overview/build-deploy.html) compiles your binaries, runs `npm install` if necessary, and generates a folder of built artifacts. We make a [squashfs archive](https://docs.kernel.org/filesystems/squashfs.html) of that folder. Then that archive gets deployed in a fully read-only manner to a runtime environment behind a live URL.

The build container is isolated from the environments resources. No database access, no external APIs, no live traffic. This isolation prevents you from accidentally messing with your production or preview environments during the build phase.

## The well-intentioned mistake

We implemented [build-time environment variables](https://docs.upsun.com/development/variables/set-variables.html#variable-options) to address a common need: frontend applications required different settings between staging and production. Different API URLs, different feature flags, that sort of thing.

We used to recommend runtime configuration fetching (generate a JSON file in a mount during the deploy hook, expose it at `/config/conf.json`, let your frontend grab it during bootstrap). But JavaScript frameworks didn't support this pattern well at the time. Build-time environment variables filled that gap.

## Why this is a problem

Build-time environment variables create differences between environments, which undermines reliable deployments.

At Upsun, we reuse build outputs whenever possible. When you merge staging to production, you get the exact same code. Not "equivalent" code. The same bytes. This approach gives you three things:

* **Confidence**: What worked in staging will work in production
* **Speed**: No waiting for redundant rebuilds
* **Security**: You're not re-downloading packages that might have changed (and the npm ecosystem has shown us repeatedly why this matters)

Build-time environment variables break this model. We use environment variables as part of the cache key that determines whether a rebuild is necessary. Push the same commit to two environments with different build-time variables, and you'll trigger a rebuild every time.

## Modern frameworks caught up

JavaScript frameworks now support runtime configuration properly. Nuxt supports [server routes for runtime config](https://nuxt.com/docs/4.x/guide/going-further/runtime-config#server-routes). [Next.js](https://nextjs.org/docs/pages/building-your-application/data-fetching/get-server-side-props) has similar patterns. Most modern frameworks do.

You can now configure your applications at runtime without baking values into your build artifacts. Your staging and production builds can be identical, with only the runtime configuration differing.

## What to do instead

Use runtime configuration. Generate your config files during deployment, not during build. Fetch configuration from your server, don't bake it in during the build process.

Your deployment pipeline will thank you. Your staging-to-production promotions will be faster and safer. And you won't force rebuilds every time someone changes an environment variable.

Build-time environment variables made sense when frameworks didn't support better alternatives. They don't anymore; time to move on.


# Code matters less than ever, and more than ever
Source: https://developer.upsun.com/posts/insights/code-matters-less-than-ever-and-more-than-ever

AI made code cheap to write and cheap to throw away, so it matters less than ever. It also matters more, because debugging, reviews, and velocity all depend on it.


<PostMeta />

You can generate a million lines of code in an afternoon. You can also delete all of it before dinner and start fresh. When code is that cheap to make and that cheap to throw away, any single line of it is worth less than it used to be.

Code matters less than ever now. It also matters more than ever. I've been trying to work out why both feel true.

## The naive version

The easy conclusion is that code no longer matters at all. AI writes it, AI rewrites it, you ship it. Why read it? Why care how it's structured? This is the vibe coding pitch, and I understand the appeal. For a weekend project or a throwaway prototype, it's often the right call.

But "the code doesn't matter" falls apart the moment you have to live with what you built.

## What I stopped caring about

AI did change how I work, though not in that direction. It let me step back from the code and look at how my application behaves.

That shift only works if you can see the behavior, which is where observability earns its keep. Good metrics, traces, and logs let me watch what the application does in production without reading a line of it. The less I lean on the code, the more I lean on that.

I care that my application filters rows in the SQL query, not in memory after fetching everything. I care that it uses the thread pool instead of spawning a thread per request. I care that it reaches for the standard library instead of shelling out to run something a built-in function already does. I care that it isn't calling an external server in the middle of a request. Or reading every file on disk when it needs one. Or skipping a cache that should be there.

None of this is premature optimization. It's about not being wasteful for no reason. And it's about keeping things simple enough that I can still reason about them. A thousand threads, each running its own slightly different logic, is a system nobody can hold in their head. I don't want to work on that, and I don't want to build it.

## Why I still care about the code

The naive version misses something, though. I may not care about the code for its own sake, but I care a lot about what good code gives me.

I care about debugging. When something breaks at 2am, I need to understand what the application is doing. If it does everything in a convoluted way I've never looked at, that night gets very long.

I care about reviewing. I work in regulated environments, with governance controls that don't let me push unreviewed changes. Reviewing changes is good practice regardless. And you cannot review a 10,000-line diff. It isn't humanly possible, barring the rare exception.

I care about velocity. When modules are tightly coupled and the logic is scattered, every change risks breaking three things you didn't touch. That's the opposite of fast.

If you skip the code entirely, you don't escape the work. You move it. The bill arrives later, when you're debugging something you don't understand and can't safely change.

## Software, not code

Tell me the code isn't the prettiest, but it's straightforward to debug, quick to review, and safe to change, and I'll take it. In practice you rarely get those three without readable code, but readability was never the goal. It was a proxy.

That's the shift AI pushed me toward, and I think it's a healthy one. We've spent a long time attached to code, defending it, treating it as the goal. It was always a means to an end.

We maintain software, not code.


# DDEV is in good hands
Source: https://developer.upsun.com/posts/insights/ddev-is-in-good-hands

DDEV is alive, actively maintained, and back with its foundation. A look at our chapter in the project, why we got involved, and why we are happy to step out of the way.


<PostMeta />

[DDEV](https://ddev.com/) is alive and actively maintained. The foundation that has run the project for years now holds the trademark, the domain, and the rest of the assets. We are glad about that.

For a few years, those assets were with us. We took them on when DDEV needed a stable home, sponsored Randy Fay as an employee, and helped keep the project moving. They are now back with the people closest to DDEV, where they belong.

## Why we got involved

We rely on open source. Our platform is built on it. Our customers' applications are built on it. Our CPTO, Fabien Potencier, is the creator and lead developer of [Symfony](https://symfony.com/). The question of how open source projects stay funded and supported is not an abstract one at our company.

DDEV came up at a time when its prior home was stepping away. The risk was real enough, and the project mattered enough, that helping made sense. There was also a strategic side. We were interested in local development as a space, and getting closer to DDEV fit that interest. Both reasons were real, and we have never pretended otherwise.

## Why we let go

Our focus shifted over time. Local development became a smaller part of where we were putting our attention, in part because of how AI is changing developer workflows. The reasons that made the arrangement useful on our side were no longer there in the same way. Randy stopped being an employee, and we kept sponsoring his work.

For us, handing the trademark back was the obvious move. A trademark like DDEV's has real commercial value, and we knew that when we let it go.

The foundation has been running the project for a few years now. The trademark, the domain, and the rest of the assets belong with it, not with us. The DDEV team has [confirmed the transfer is now complete](https://ddev.com/blog/upsun-trademark-transfer-complete/).

## What we take from this

DDEV has not missed a step. Randy is still doing the work. The community is still active. That is the outcome we wanted, and we are proud of the part we played in getting there.

Open source funding gets talked about a lot. Most of that talk focuses on the start of these stories: who wrote the check, who took on the project, who stepped in. The endings get less attention. They probably deserve more.

DDEV deserves a long, healthy future, and the project is set up to have one.


# My terminal setup (Mac & Linux)
Source: https://developer.upsun.com/posts/insights/my-terminal-setup-mac-linux

A no-nonsense guide to transforming your terminal from painful to powerful with GhostTTY, NeoVim, and Claude Code

<PostMeta />

## Introduction

Let's be honest: the default terminal experience on macOS and Linux is... rough. Like, really rough. You open Terminal.app on a Mac and you're greeted with this bland, uninspiring blank rectangle that feels like it was designed in 2003 (spoiler: it basically was). The default shell prompt tells you almost nothing useful, the colors make reading logs an eye-straining nightmare, and don't even get me started on trying to split panes or manage multiple sessions.

<img alt="Ugly terminal" />

And sure, you *could* live with it. Plenty of people do. But why would you want to when you spend half your day in that thing?

I've been down the terminal customization rabbit hole more times than I'd like to admit. I've tried iTerm2, Alacritty, Kitty, Warp, and probably a dozen others I've forgotten about. I've cycled through Zsh frameworks, tried Nushell for a hot minute, and even flirted with exotic shells that promised to revolutionize my workflow.

But I think I've finally landed on a setup that actually *works*. It's fast, it looks good, it's packed with genuinely useful features, and most importantly, it gets out of my way when I need to get stuff done.

<img alt="Intro" />

So here's the deal: I'm going to walk you through my current terminal setup that works beautifully on both macOS and Linux. We'll start with GhostTTY (the new kid on the block that's actually worth the hype), configure a shell environment that doesn't suck, set up NeoVim with LazyVim for those times when you need a proper editor, and top it all off with Claude Code integration because, let's face it, AI assistance in your terminal is pretty sweet.

Ready? Let's turn that sad default terminal into something you'll actually enjoy using.

## My palette of choice

<img alt="Catppuccin" />

Before we dive into specific tools, let's talk about something that ties everything together: color schemes. I've tried dozens over the years: Dracula, Nord, Gruvbox, Solarized, One Dark. And while they're all decent, I kept coming back to one: [Catppuccin](https://catppuccin.com/). The [Mocha](https://catppuccin.com/palette/) variant to be exact.

Catppuccin is a community-driven pastel theme that describes itself as "for the high-spirited," and honestly? That's pretty accurate. The colors are soft without being washed out, vibrant without being eye-searing. It's the kind of palette you can stare at for 10 hours straight and not feel like your retinas are being assaulted.

What really sold me on Catppuccin is the consistency. This thing has [ports for *everything*](https://catppuccin.com/ports/). Your terminal? Covered. NeoVim? Of course. VS Code, JetBrains IDEs, Slack, Discord, Firefox, Chrome, Obsidian, Spotify, even your system themes. There's probably a Catppuccin port for it. That means my entire desktop environment has the same cohesive look, which sounds superficial until you realize how jarring it is to jump between apps that all look completely different.

<img alt="Catppuccin" />

I run [Mocha](https://catppuccin.com/palette/) everywhere. It has deep, rich backgrounds with colors that pop just enough to differentiate syntax elements without turning your code into a rainbow explosion. You'll see it referenced throughout this setup guide because, like I said, consistency is king.

## My preferred font: Fira Code

Talking about consistency, I love having matching fonts in all my daily tools. A good monospace font might seem like a minor detail, but when you're staring at code for hours, it makes a real difference.

[Fira Code](https://github.com/tonsky/FiraCode/) has been my go-to for years. It's a free, open-source monospaced font designed specifically for developers, and its killer feature is **ligatures**. You know how operators like `->`, `<=`, `!=`, or `===` are technically multiple characters but represent single logical concepts? Fira Code renders them as unified glyphs. It sounds gimmicky until you try it. Suddenly your code just *looks* cleaner and is easier to scan.

But here's the thing: if you want fancy icons in your terminal prompt (git branch symbols, folder icons, language logos), you need more than just Fira Code. You need the **Nerd Font** version.

[Nerd Fonts](https://github.com/ryanoasis/nerd-fonts) is a project that patches popular programming fonts with thousands of additional glyphs from icon sets like Font Awesome, Devicons, Octicons, and Powerline symbols. The [Fira Code Nerd Font](https://github.com/ryanoasis/nerd-fonts/tree/master/patched-fonts/FiraCode) gives you all the ligature goodness *plus* the icons that make modern shell prompts and file explorers look gorgeous.

Installing is straightforward:

```bash {filename="Terminal"} theme={null}
# Mac
brew install --cask font-fira-code-nerd-font

# Ubuntu/Debian
sudo apt install fonts-firacode
# For the Nerd Font version, download from the releases page
# or use the official install script:
curl -fsSL https://raw.githubusercontent.com/ryanoasis/nerd-fonts/master/install.sh | bash -s -- FiraCode
```

### Other solid options

Fira Code isn't the only game in town. Here are some other excellent monospace fonts worth considering:

* **[JetBrains Mono](https://www.jetbrains.com/lp/mono/)** - Created by JetBrains, excellent ligatures and optimized for reading code. Very popular.
* **[Ubuntu Mono](https://fonts.google.com/specimen/Ubuntu+Mono)** - Clean and highly readable, the default on Ubuntu systems.
* **[Cascadia Code](https://github.com/microsoft/cascadia-code)** - Microsoft's modern font with ligatures, designed for Windows Terminal.
* **[Source Code Pro](https://github.com/adobe-fonts/source-code-pro)** - Adobe's take on a programming font, clean and professional.
* **[Hack](https://sourcefoundry.org/hack/)** - Designed for source code, great readability at small sizes.

All of these have Nerd Font versions available, so pick whatever looks best to you. The important thing is to actually *choose* a font rather than settling for whatever your system defaults to.

## GhostTTY: The Terminal that finally gets it right

[Ghostty](https://ghostty.org/docs) is a fast, feature-rich, and cross-platform terminal emulator that uses platform-native UI and GPU acceleration. It was created by [Mitchell Hashimoto](https://mitchellh.com/) who co-founded Hashicorp and is definitely worth a follow!

```bash {filename="Terminal"} theme={null}
# Mac
brew install --cask ghostty

# Ubuntu using snap
snap install ghostty --classic
```

For more options, head to [the install guide](https://ghostty.org/docs/install/binary). One great thing about Ghostty is the simplicity of the configuration file. Here is mine:

```bash {filename="~/.config/ghostty/config"} theme={null}
theme = catppuccin-mocha.conf
font-size = 19
font-family = FiraCode Nerd Font Mono
mouse-hide-while-typing = true
window-decoration = true
macos-option-as-alt = true

window-padding-x=12
window-padding-y=12
window-padding-balance=true
```

Feel free to tweak it as you need.

The config references the [catppuccin-mocha.conf available in my dotfiles repository](https://github.com/gmoigneu/dotfiles/blob/main/ghostty/themes/catppuccin-mocha.conf) that should be put in `~/.config/ghostty/themes/`.

## `which` shell?

Now that we have a proper terminal emulator, let's make what happens *inside* it actually useful.

### fish

[fish](https://fishshell.com/) (friendly interactive shell) is my shell of choice. It's actively maintained and is a modern alternative to `bash` or `zsh` that prioritizes usability out of the box. It comes with syntax highlighting, intelligent autosuggestions from your command history, and robust tab completions without any configuration.

Installing and switching to fish is straightforward:

```bash {filename="Terminal"} theme={null}
# On macOS
brew install fish

# On Ubuntu/Debian
sudo apt install fish

# Make it your default shell
chsh -s $(which fish)
```

Log out and back in, and you're running fish. Unlike other shells that drop you into an empty config file, fish just *works* immediately. The syntax highlighting and autosuggestions kick in on first launch without any setup.

However, I've seen rare occasions where some features were not working when launched as the default shell. So instead of changing my user shell, I just launch `fish` over `zsh` within Ghostty:

```bash {filename="~/.config/ghostty/config"} theme={null}
command = /opt/homebrew/bin/fish
```

The main trade-off with fish is that it intentionally breaks from POSIX shell syntax. This means scripts and commands copied from most online tutorials won't work directly in fish unless you run them through `bash`. For me, the improved interactive experience is worth it, and I can always run `bash -c "command"` for POSIX-specific scripts when needed.

<Note>
  My whole `config.fish` file: [See on Github](https://github.com/gmoigneu/dotfiles/blob/main/fish/config.fish)
</Note>

#### Zsh: The macOS default

If you prefer to stick with something more traditional, Zsh has been the default shell on macOS since Catalina. You're probably already using it if you're on a Mac.

Zsh offers better tab completion than Bash, more powerful globbing, shared history across sessions, and a massive ecosystem of plugins and themes through frameworks like Oh My Zsh. It's a solid choice if you want something more powerful than Bash while maintaining POSIX compatibility.

On Ubuntu or other Linux distros still running Bash, switching to Zsh is easy:

```bash {filename="Terminal"} theme={null}
# Install Zsh
sudo apt install zsh

# Make it your default shell
chsh -s $(which zsh)
```

<Note>
  My whole `.zshrc` file: [See on Github](https://github.com/gmoigneu/dotfiles/blob/1a9e537ac1337d88ae86916b0ec33ccfeb689941/zsh/.zshrc)
</Note>

### Starship: A prompt that actually helps

Your shell prompt is prime real estate. The default `username@hostname:~$` tells you almost nothing useful. [Starship](https://starship.rs/) fixes that.

Starship is a minimal, blazing-fast prompt written in Rust. It automatically detects what you're working on and shows relevant context: git branch and status, current language versions, cloud provider profiles, Kubernetes context or whatever's relevant to your current directory.

```bash {filename="Terminal"} theme={null}
# Mac
brew install starship

# Linux
curl -sS https://starship.rs/install.sh | sh
```

Then add this to the end of your fish config (`~/.config/fish/config.fish`):

```fish {filename="~/.config/fish/config.fish"} theme={null}
starship init fish | source
```

For Zsh users, add this to `~/.zshrc` instead:

```bash {filename="~/.zshrc"} theme={null}
eval "$(starship init zsh)"
```

Configuration lives in `~/.config/starship.toml`.

<img alt="Starship" />

The above screenshot shows that I am in my `devcenter` project/folder on the `my-terminal` git branch with unstaged changes (`[?]`). It shows my `package.json` version (`1.0.0`) as well as my node.js runtime version. Especially useful if you are switching node versions with `nvm` to get rid of compatibility issues between major releases.

Here's [my whole config](https://github.com/gmoigneu/dotfiles/blob/main/starship/starship.toml):

```toml {filename="~/.config/starship.toml"} theme={null}
# Use Catppuccin Mocha palette
palette = "catppuccin_mocha"

# Don't add a newline at the start of the prompt
add_newline = false

# Minimal left prompt
format = """$directory$character"""

# Everything else goes on the right
right_format = """$git_branch$golang$aws"""

[character]
success_symbol = "[➜](bold green)"
error_symbol = "[✗](bold red)"

[directory]
truncation_length = 3
truncate_to_repo = true

[git_branch]
format = "[$symbol$branch(:$remote_branch)]($style) "

[aws]
format = '[$symbol($profile )(\($region\))]($style) '
symbol = "󰸏 "
style = "bold blue"

# Catppuccin Mocha colors
[palettes.catppuccin_mocha]
rosewater = "#f5e0dc"
flamingo = "#f2cdcd"
pink = "#f5c2e7"
mauve = "#cba6f7"
red = "#f38ba8"
maroon = "#eba0ac"
peach = "#fab387"
yellow = "#f9e2af"
green = "#a6e3a1"
teal = "#94e2d5"
sky = "#89dceb"
sapphire = "#74c7ec"
blue = "#89b4fa"
lavender = "#b4befe"
text = "#cdd6f4"
subtext1 = "#bac2de"
subtext0 = "#a6adc8"
overlay2 = "#9399b2"
overlay1 = "#7f849c"
overlay0 = "#6c7086"
surface2 = "#585b70"
surface1 = "#45475a"
surface0 = "#313244"
base = "#1e1e2e"
mantle = "#181825"
crust = "#11111b"
```

The key here is keeping the left side minimal (just directory and prompt character) while putting contextual info on the right where it doesn't get in the way.

<Note>
  Some modules may take too long to evaluate. If the prompt, feel sluggish, run `env STARSHIP_LOG=trace starship timings` to get a detailed trace of the execution.
</Note>

<img alt="Starship Timings" />

### eza: ls, but actually good

The default `ls` command is... fine. But [eza](https://github.com/eza-community/eza) is better in every way. It's a modern replacement with colors, icons, git status integration, and sensible defaults.

```bash {filename="Terminal"} theme={null}
# Mac
brew install eza

# Ubuntu/Debian
sudo apt install eza
```

I alias `ls` to eza so it's automatic. In fish, add this to your `~/.config/fish/config.fish`:

```fish {filename="~/.config/fish/config.fish"} theme={null}
if command -v eza &> /dev/null
    alias ls='eza -lh --group-directories-first --icons=auto'
    alias lsa='ls -a'
    alias lt='eza --tree --level=2 --long --icons --git'
    alias lta='lt -a'
end
```

For Zsh users (`~/.zshrc`):

```bash {filename="~/.zshrc"} theme={null}
if command -v eza &> /dev/null; then
  alias ls='eza -lh --group-directories-first --icons=auto'
  alias lsa='ls -a'
  alias lt='eza --tree --level=2 --long --icons --git'
  alias lta='lt -a'
fi
```

<img alt="eza" />

Now `ls` gives you a beautiful, informative file listing. `lt` shows a tree view with git status. Once you've used it, going back to plain `ls` feels painful.

### fzf: Fuzzy find everything

[fzf](https://github.com/junegunn/fzf) is a general-purpose fuzzy finder, and once you start using it, you'll wonder how you ever lived without it. It lets you interactively filter any list: files, command history, processes, git branches, you name it.

```bash {filename="Terminal"} theme={null}
# Mac
brew install fzf

# Ubuntu/Debian
sudo apt install fzf
```

Set up the key bindings and shell integration. For fish:

```fish {filename="~/.config/fish/config.fish"} theme={null}
# Set up fzf key bindings
fzf --fish | source
```

For Zsh:

```bash {filename="~/.zshrc"} theme={null}
# Set up fzf key bindings and fuzzy completion
source <(fzf --zsh)
```

Now you get:

* **Ctrl+R** - Fuzzy search through your command history (game changer)
* **Ctrl+T** - Fuzzy find files and insert the path
* **Alt+C** - Fuzzy find directories and cd into them

<img alt="fzf" />

The history search alone is worth the install. Instead of mashing the up arrow trying to find that docker command you ran three days ago, just hit Ctrl+R and type a few characters.

### zoxide: cd that remembers

[zoxide](https://github.com/ajeetdsouza/zoxide) is a smarter `cd` command. It tracks which directories you visit most frequently and lets you jump to them with minimal typing.

```bash {filename="Terminal"} theme={null}
# Mac
brew install zoxide

# Ubuntu/Debian
curl -sSfL https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | sh
```

For fish, add this to your config:

```fish {filename="~/.config/fish/config.fish"} theme={null}
zoxide init fish | source
```

For Zsh:

```bash {filename="~/.zshrc"} theme={null}
eval "$(zoxide init zsh)"
```

Now instead of typing `cd ~/projects/company/frontend/src/components`, you just type `z components` and zoxide figures out which "components" directory you probably mean based on your history. The more you use it, the smarter it gets.

<img alt="zoxide" />

Combine it with fzf for interactive selection: `zi` opens a fuzzy finder with your most-visited directories.

### My aliases

Beyond the tool-specific aliases above, here are some shortcuts I use constantly. In fish:

```fish {filename="~/.config/fish/config.fish"} theme={null}
# Directory navigation
alias ..='cd ..'
alias ...='cd ../..'
alias ....='cd ../../..'

# Tools
alias d='docker'
alias v='nvim'

# Git shortcuts
alias g='git'
alias gcm='git commit -m'
alias gcam='git commit -a -m'
alias gcad='git commit -a --amend'

# Upsun deployment
alias u='upsun'
alias ud='git push upsun && upsun deploy'
```

For Zsh, the syntax is identical, just put these in your `~/.zshrc` instead.

The philosophy here is simple: if you type something more than a few times a day, alias it. Your fingers will thank you.

### Bonus: Nushell

If you're feeling adventurous and want to try something completely different, check out [Nushell](https://www.nushell.sh/). It's a modern shell that treats everything as structured data instead of text strings.

Instead of piping text through `grep` and `awk` and hoping you got the parsing right, Nu pipelines work with actual typed data. You can work with JSON, YAML, SQLite, even Excel files natively. Error messages actually tell you what went wrong and where.

<img alt="nu" />

I'm not using it as my daily driver yet. Too much muscle memory in Zsh and nushell is not POSIX compatible. But it's genuinely impressive and worth experimenting with if you do a lot of data wrangling in the terminal.

```bash {filename="Terminal"} theme={null}
# Mac
brew install nushell

# Ubuntu/Debian
cargo install nu
# or download from GitHub releases
```

## NeoVim + LazyVim: When you need real editing power

<img alt="nvim" />

Let's be real: learning Vim is *hard*. The keybindings are completely alien if you've spent your life in GUI editors, and the learning curve is steep enough to make most people quit within the first hour.

I'm still on that journey myself. I regularly switch between VS Code forks like [Cursor](https://cursor.sh/) and [Anti Gravity](https://antigravity.google/) for my daily work while slowly building up Vim muscle memory. Some days I'm productive in NeoVim; other days I just need to get stuff done and reach for what I know. That's fine. It's a marathon, not a sprint.

That said, if you want to try NeoVim without spending weeks configuring it from scratch, [LazyVim](https://www.lazyvim.org/) is the answer. It's a pre-configured NeoVim setup that gives you a modern IDE experience out of the box: file explorer, fuzzy finding, LSP support, git integration, syntax highlighting. All the things you'd expect, ready to go.

```bash {filename="Terminal"} theme={null}
# Mac
brew install neovim

# Ubuntu/Debian
sudo apt install neovim

# Then install LazyVim (backs up your existing config)
git clone https://github.com/LazyVim/starter ~/.config/nvim
```

Launch `nvim` and let it install all the plugins. First startup takes a minute, but after that it's instant.

The best resource I've found for getting started is this video by Elijah Manor:

<iframe />

It walks you through the LazyVim setup and the essential keybindings you need to be productive. Bookmark it, you'll reference it often in your first few weeks.

A few tips for the learning phase:

* **Start with `:Tutor`** - NeoVim has a built-in tutorial. Run it. Actually do the exercises.
* **Use Vim keybindings in your regular editor first** - Both VS Code and JetBrains IDEs have excellent Vim plugins. Build muscle memory without sacrificing productivity.
* **Don't try to learn everything at once** - Master `hjkl` navigation, then `w/b/e` for word movement, then gradually add more.
* **Keep a cheat sheet handy** - You'll need it for months. That's normal.

The payoff is real, though. Once the keybindings become muscle memory, editing text in NeoVim feels like flying. And since it runs in your terminal, it fits perfectly into this whole setup.

## Claude Code: Your AI Programmer Buddy in the Terminal

<img alt="Claude Code" />

I'm sure you've heard about Claude Code at this point ... This is the AI assistant I have been using for a year now and without going into a lengthy debate on which one is the best, here is a quick run-through:

[Claude Code](https://docs.anthropic.com/en/docs/claude-code) works directly with your codebase: reading files, making edits, running commands, and creating commits. All from your terminal.

```bash {filename="Terminal"} theme={null}
# Mac
brew install claude-code

# Linux (via npm)
npm install -g @anthropic-ai/claude-code
```

Run `claude` in any project directory, authenticate, and you're good to go.

<Note>
  Pro tip: create a `CLAUDE.md` file in your project root describing your codebase and conventions. [Review my other article on the topic](/posts/insights/why-your-readme-matters-more-than-ai-configuration-files) for a detailed walkthrough.
</Note>

### Integrating with NeoVim

[claude-code.nvim](https://github.com/greggh/claude-code.nvim) brings Claude Code directly into NeoVim. Add this to your LazyVim config:

```lua {filename="~/.config/nvim/lua/plugins/claude-code.lua"} theme={null}
return {
  "greggh/claude-code.nvim",
  dependencies = { "nvim-lua/plenary.nvim" },
  keys = {
    { "<leader>ac", "<cmd>ClaudeCode<cr>", desc = "Toggle Claude Code" },
  },
  config = function()
    require("claude-code").setup({
      window = {
        position = "float",
        float = { width = "80%", height = "80%", border = "rounded" },
      },
      refresh = { enable = true, show_notifications = true },
    })
  end,
}
```

Hit `<leader>ac` and Claude Code pops up in a floating window. When it makes changes to files, NeoVim automatically reloads them. The workflow is seamless: edit, toggle Claude, describe what you need, watch it work, and you're back to editing with changes already applied. No context switching.

If you're using a different AI assistant (or want to use multiple), check out [avante.nvim](https://github.com/yetone/avante.nvim). It's a Cursor-like experience for NeoVim that supports Claude, GPT, Gemini, and local models.

## Conclusion

Look, I'm not going to tell you this is the "perfect" setup or the "only" way to configure your terminal. There's no such thing. Your workflow is different from mine, your muscle memory is different, and what drives you crazy might not bother me at all.

But what I *will* tell you is this: investing time in your terminal setup is absolutely worth it. You're going to spend thousands of hours in this environment over your career. Making it fast, pleasant, and actually helpful isn't being picky. It's being smart. And I love the occasional *"Oh wait. How did you do that?"*

<Note>
  You can find all my configurations on my [dotfiles Github repository](https://github.com/gmoigneu/dotfiles/tree/main).
</Note>

Your turn. Take what makes sense, ignore what doesn't, and most importantly: stop settling for that default terminal. You deserve better.

Happy hacking! 🚀


# Rate limiting Rails apps when you can't put Varnish in front
Source: https://developer.upsun.com/posts/insights/rate-limiting-rails-apps-when-you-cant-put-varnish-in-front

When the edge isn't yours, rate limit from inside the application. How rack-attack works, why limits are about quality of service, and what Rails 8 changed.

<PostMeta />

A few years ago, I worked on a Rails app deployed to Heroku. We had public APIs handling device activation pings from Apple and Google. The kind of traffic where every phone in the wild could hit you at any moment, with no authentication, only a key per device.

It worked fine until it didn't. Some endpoints started getting hammered, and we needed a way to stop the abuse before it took everyone down.

The natural answer would have been to drop a reverse proxy in front of Rails and rate limit there. The [previous article in this series](/posts/hands-on/varnish-102-protecting-your-application-with-rate-limiting-on-upsun) shows exactly how to do that with Varnish and `vsthrottle`. But on Heroku, you don't get that layer. You get a router, a dyno, and your app. That's it.

We did the next best thing: we rate limited inside the application.

## Rack middleware: rate limiting before Rails wakes up

The tool we picked was [rack-attack](https://github.com/rack/rack-attack), a Rack middleware that runs ahead of your controllers, your views, and most of the Rails request lifecycle.

Rack middleware sits at the bottom of the stack. A request comes in, hits the middleware chain, and rack-attack decides whether to let it through or return a 429 immediately. The controller never runs. Your business logic stays untouched.

## What rack-attack actually loads

Rack-attack runs early, but it doesn't run in a vacuum. By the time the middleware kicks in, your Rails app is already booted. The database connection pool is alive. Models are loaded. Redis is connected.

When rate limiting blocks a request, you're not saving an entire process boot. You're saving the controller, the queries, the rendering, and whatever else the request would have triggered. On a Ruby app where each worker process serves multiple requests through fibers, that still adds up. CPU stops getting burned on requests you didn't want to serve. Memory pressure stays predictable.

It's not as cheap as filtering at the edge, but it's a lot cheaper than letting the request reach the database.

## Configuration is plain Ruby

Rack-attack configures via Ruby blocks. You give it a name, a key extractor, a limit, and a window. Anything you can read from the request can become the key.

```ruby theme={null}
Rack::Attack.throttle("api/ip", limit: 10, period: 1.second) do |req|
  req.ip if req.path.start_with?("/api/")
end
```

That's the entire pattern. Want to limit by IP? Use `req.ip`. By user? Read the auth header. By a combination? Concatenate and hash. The block has access to the full request object, and the rules can be as expressive as you need.

The trade-off is that any change requires a deploy. There's no live config. For a small set of stable rules, that's fine.

## Where you store the counters

Rack-attack needs somewhere to track how many requests each key has made. The two main options are an in-process memory cache or [Redis](https://docs.upsun.com/add-services/redis). Both are valid. They optimize for different things.

In-memory is the simplest path. No extra service to run, no network hop, counters live next to the code that reads them. It works well when you have a single process, or when each process serves a stable, well-defined slice of traffic. The catch is that each process keeps its own counter. Two dynos means two counters, and your effective limit doubles. Restart a process and the counters reset, which gives a fresh window to anyone patient enough to wait it out.

Redis flips that trade-off. The counters live in one place, shared across every process, and they survive restarts. The price is the dependency: you need Redis reachable, and you pay a small network hop on every request the limiter inspects. We used Redis on the project I described, and never had a performance issue with it.

Pick based on what you're actually defending against. Soft caps for fairness on a single-instance app? In-memory is enough. Hard caps that need to hold across deploys, scale-outs, and restarts? Reach for Redis.

## What we actually capped, and why

The point of capping isn't always to block attackers. Often it's about quality of service.

Your application has finite CPU. Every concurrent request takes a slice of it, and once the slices run out, every request slows down for everyone. Without rate limiting, one greedy client can monopolize that CPU and degrade the experience for the rest of your traffic. With rate limiting, that client gets pushed back to a fair share, and the other users keep getting fast responses.

For us, the CPU pressure came from abusive clients hidden among the legitimate Apple and Google device activation requests. We capped the noisiest endpoints at around 10 requests per second per IP. Higher than what a real device would ever need, low enough that no single client could starve the rest of the stack.

Downtime from these endpoints stopped. The other endpoints kept working through traffic spikes. Latency at the application level held steady. None of it was free, but it was the cheapest thing we could ship without owning the edge.

## What about authenticated traffic?

This is the case where edge rate limiting starts to struggle. Varnish doesn't know who your users are. It can throttle by IP and by URL, but if you want to throttle by authenticated user, you need session data, token lookups, or sometimes a database query. That's the application's job.

GitHub does this. Hit their API unauthenticated and you get 60 requests per hour. Authenticate and you get 5,000. That kind of tiered limit is hard to do at the edge without leaking auth state outside your application.

If you're building anything where the rate limit depends on who the user is, you want this layer.

## Rails 8 ships this out of the box

Rack-attack is still maintained, and it still works. If you're on Rails 8, you don't need it. Rails now ships its own rate limiting primitive in the framework, with the same kind of pluggable storage. Memory cache, Redis cache, whatever your `Rails.cache` is set to.

The API is smaller, and it covers most of what rack-attack does:

```ruby theme={null}
class ApiController < ApplicationController
  rate_limit to: 10, within: 1.second
end
```

Starting fresh on Rails 8? Start there. On an older version? Rack-attack is still the right answer.

## Use the layer that fits the constraint

Edge rate limiting and application rate limiting are not competing. They solve different problems.

Varnish is the right tool when you control the edge and the rules don't need to know anything beyond the request. It's faster, cheaper, and stops abuse before it ever reaches your app. The [previous article in this series](/posts/hands-on/varnish-102-protecting-your-application-with-rate-limiting-on-upsun) goes deep on that.

Rack-attack and Rails 8's built-in rate limiting are the right tools when the edge isn't yours, or when your rules need application context. Authenticated users, account tiers, business rules baked into the rate limiter. That's what they're for.

The good news is that you don't have to pick. On Upsun, you get [Varnish as a managed service](https://docs.upsun.com/add-services/varnish) for the edge, [Redis](https://docs.upsun.com/add-services/redis) for shared counters, and the freedom to layer application-level limits on top. Coarse rules at the edge for the worst offenders, fine-grained rules in Rails for the cases that need user context. If your platform doesn't give you the edge, do it in the application and move on.


# Session storage gets complicated faster than you think
Source: https://developer.upsun.com/posts/insights/session-storage-gets-complicated-faster-than-you-think

Explore session storage tradeoffs across files, PostgreSQL, Redis, and Valkey, from expiration and cleanup to memory limits. Test your options on Upsun Cloud.


<PostMeta />

You're building a PHP application, and you need to remember who's logged in between requests. You enable sessions, store a user ID, and carry on with the next feature. PHP writes the session data to a file in the directory set by [`session.save_path`](https://www.php.net/manual/en/session.configuration.php).

There isn't much to configure. Your application runs on 1 instance. The folder is writable, and the next request can read the session. You might not even have looked at where that folder lives.

A while later, you want to run a second instance of the application. Before adding it, you check what the 2 instances need to share. The database is already external. Uploaded files need some attention. And then there are those session files.

Each instance would have its own directory. A session created on the first wouldn't exist on the second, even though the browser sends the same cookie to both. Sticky sessions would send each user's requests to the same instance. But if that instance goes away, their session goes with it. Shared file storage could work, too, though its performance can be a problem for sessions.

Since both instances already connect to PostgreSQL, putting the sessions there seems reasonable. Your framework has a database session handler. You configure it, create the table, and both instances can now read the same sessions.

## Keeping the session table around

The table doesn't need much: a session ID, some serialized data, and an expiration timestamp. The session ID is the primary key. For each request, the handler reads the row for that session ID and checks the expiration timestamp.

For PostgreSQL, that lookup might look like this:

```sql theme={null}
  SELECT data
  FROM sessions
  WHERE session_id = $1
    AND expires_at > CURRENT_TIMESTAMP;
```

You also need to remove the rows you no longer use. PostgreSQL and MariaDB don't automatically delete rows after a set lifetime, often called a time to live (TTL). Adding an `expires_at` column doesn't change that. Something still needs to delete the expired rows.

A scheduled query takes care of that:

```sql theme={null}
  DELETE FROM sessions
  WHERE expires_at <= CURRENT_TIMESTAMP;
```

An index on `expires_at` helps find expired rows, especially when most of the table hasn't expired yet. You schedule the query every hour and let it run.

That doesn't give your users an extra hour of session lifetime. The handler checks expiration on every read. A session expiring at 14:03 stops working then, even if its row remains until 15:00. You can run cleanup less often, provided keeping those expired rows meets your retention requirements.

This setup may be all you need. It uses a database you already operate, and your framework may handle most of the details. Convenience is a good reason to choose it.

As the application grows, though, that scheduled query has more to do. Finding expired rows is only part of the work. Deleted rows still occupy space until PostgreSQL's [vacuum process](https://www.postgresql.org/docs/current/routine-vacuuming.html) makes it available for reuse. That cleanup, along with session writes and index updates, competes with the rest of your application for database resources.

You can tune the cleanup frequency or delete in batches. If enough data expires together, there's another option worth considering.

## Deleting an hour at a time

With [PostgreSQL range partitioning](https://www.postgresql.org/docs/current/ddl-partitioning.html), you can group sessions by `expires_at` into hourly or daily partitions. Once everything in a partition has expired, you drop the partition. You avoid deleting rows individually and vacuuming afterward. For large batches of expired sessions, that can be much cheaper.

You still check expiration during reads. A daily partition changes when you reclaim storage, not when a session stops being valid.

You do need to create new partitions ahead of time and remove old ones. Dropping a partition also takes locks, which can make other queries wait. Extending a session's expiration may move its row between partitions. Looking up a session by ID alone may require searching several partitions. And if you partition by `expires_at`, the table's primary key must include that column.

That extra work can pay off when you have lots of sessions to remove. At a smaller scale, the original table may be enough.

If you expect to create and expire lots of sessions, planning for partitioning early can save you a migration later. You can migrate without discarding every session, but preserving them takes planning. Asking everyone to log in again might be acceptable for your application. It might also be a rather awkward conversation with the business.

## Letting the store handle expiration

By now, you've spent a fair amount of time thinking about how to remove sessions. A store that already handles expiration starts to look appealing.

The access pattern fits a key-value store well. You have a session ID, some data, and a lifetime. You aren't usually joining sessions against other tables or searching their contents. Redis and Valkey fit this model, and many frameworks already support them as session backends.

With Redis, the handler can set a [TTL on each key](https://redis.io/docs/latest/commands/expire/). If user activity extends the session, it can refresh that TTL. Expired keys become unavailable, and the store handles cleanup. That's one less scheduled job to maintain.

On Upsun Cloud, you can try this by adding a service to a preview environment and changing the session handler there. For sessions that need to survive a service restart, choose [persistent Redis](/docs/add-services/redis#persistent-redis) or [persistent Valkey](/docs/add-services/valkey#persistent-valkey). The ephemeral variants are intended for data you can afford to lose.

But Redis keeps its entire dataset in memory, even with persistence enabled. Persistence adds a disk copy for recovery after a restart. Every session still needs room in RAM while the service runs. The same applies to Valkey.

With long-lived sessions, you can need a lot of memory. You're keeping sessions for users who may not have visited for weeks.

Suppose you create 100,000 new sessions each day and keep them for 30 days. Without early deletion, that's roughly 3 million sessions. If each session contains 2 KB of serialized data, that's about 6 GB before counting keys and Redis's own overhead. You also need spare memory for the service to run and the data to grow.

Most of those users don't need to be on your website today. Their sessions still occupy memory. Keeping sessions longer increases memory use even if the number of users online stays the same.

PostgreSQL and MariaDB also need memory to perform well, but they can store more data than fits in RAM. They keep it on disk and load parts into memory as needed. With Redis, you need RAM for all of it. You may run out of memory long before you would have run out of disk space.

On Upsun Cloud, `maxmemory` sets how much memory Redis can use for its dataset. The platform calculates it from both the memory and disk you allocate, as explained in the [persistent Redis documentation](/docs/add-services/redis#persistent-redis). The container also needs memory for work beyond storing sessions.

## The Redis instance you already have

You might already be running Redis for caching. Using it for sessions would save adding another service, much as using PostgreSQL did earlier.

For cached data, reaching the memory limit can be normal. An eviction policy removes entries, and the application rebuilds them when needed. You still check how well the cache performs, but users may never notice an evicted entry.

A session is harder to rebuild. If its key disappears, the application may have to ask the user to log in again. Any temporary state stored only in that session disappears with it.

An [eviction policy](https://redis.io/docs/latest/develop/reference/eviction/) can remove keys before their TTL expires. Choosing `noeviction` prevents that. But when Redis reaches the limit, writes that need more memory fail instead. Your application then has to handle failures to create or update sessions.

Sharing the service also makes the memory graph harder to read. Session data can gradually occupy more memory while cached data gets evicted to make room. Total memory usage looks similar, but the cache becomes less effective. That graph alone won't tell you how close sessions are to filling the instance. You need to measure session memory separately to know when to add capacity.

A cache can stay within a fixed memory budget by evicting entries, provided the resulting hit rate remains acceptable. Sessions need enough memory for all the data you retain, plus room to grow. As that total grows, you may need to upsize the session store while keeping the cache the same size.

Separate logical databases within the same Redis instance don't give you independent memory limits, eviction policies, or scaling. Separate services do. A dedicated session service lets you monitor its memory use and set alerts before it fills up. You can then add capacity for sessions without resizing the cache.

That's another service to size and monitor. It can still be a good choice, especially if your framework handles renewal and concurrent requests well. You no longer maintain a SQL cleanup job, but you do need to watch memory use.

## Trying it with your application's data

Before changing anything, it's worth trying these options with the amount of session data your application actually keeps. Each comes with trade-offs. Your existing database saves you another service, but session writes and cleanup compete with application queries. Partitioning makes bulk cleanup cheaper, but adds work around partition management and session lookups. Redis or Valkey handles expiration for you, but requires memory for every retained session and monitoring to know when to upsize.

You can explore those options in an [Upsun Cloud preview environment](/docs/environments/actions), with a copy of the parent environment's data where appropriate. Add the service or change the schema there, then test with a realistic number and size of sessions. A handful of test logins won't tell you much about a month's worth of retained sessions.

Run requests across multiple application instances. Check renewal, concurrent updates, expiration, and behavior after a restart. If you're using PostgreSQL, run cleanup while the application handles traffic and measure its impact. With Redis or Valkey, measure memory use and leave room for more sessions.

Once you're happy with the result, merge the code and configuration with a plan for existing sessions. A merge doesn't convert the contents of a PostgreSQL table into Redis keys. You'll need to migrate the existing sessions or accept that users will have to log in again.

The folder may have been enough when you started, and your framework's database handler may be enough for years. The trade-offs change with session volume, lifetime, and the work your team wants to take on. Leave yourself room to try something else when the application needs it.


# The mystery of the shrinking database dump
Source: https://developer.upsun.com/posts/insights/the-mystery-of-the-shrinking-database-dump

Your database uses 10GB but dumps to 100MB. Discover why database dumps shrink, how InnoDB fragmentation works, and how to reclaim that missing storage space.

<PostMeta />

Picture this: You're monitoring your Upsun database container, and you notice you have a 10GB database using nearly all of its allocated storage. Concerned about space, you take a database dump to assess the situation and discover the dump is only 100MB. Where did the other 9.9GB go?

This is a common question we see in support tickets, and it reveals a fascinating quirk about how databases actually work. Let's dive into the mystery of the shrinking database dump.

## The Dump Doesn't Tell the Whole Story

First, let's clarify what a database dump actually is. When you run `mysqldump`, you're not creating a byte-for-byte copy of your database files. Instead, you're generating a set of SQL instructions that tell the database how to recreate your data.

Think of it like the difference between a photograph of a building and the architectural blueprints. The dump is the blueprint: a series of `INSERT` statements, `CREATE TABLE` commands, and index definitions. A single line like `CREATE INDEX idx_user_email ON users(email);` might be tiny in the dump file, but when executed on a large table, it creates an index that consumes substantial disk space.

While dump size generally correlates with actual data volume, they're definitely not the same thing. Understanding why requires a look under the hood at how databases store data on disk.

## How InnoDB Stores Data (And Why It Matters)

On MySQL and MariaDB, the default storage engine is InnoDB, which we commonly use on Upsun. InnoDB uses a file-per-table approach where each table has its own data file (or multiple files, but let's keep it simple).

Here's where things get interesting: When you insert 10,000 records, the table file grows. But when you delete row 5,000, the table file doesn't shrink. InnoDB can't simply shift 5,000 records upward to compress the file as that would be prohibitively expensive. Instead, the deleted row is zeroed out, leaving an empty gap in the file.

If you continue this pattern - inserting records, deleting records, inserting more records - you end up with fragmentation. The table file fills with empty spaces that were once occupied by deleted data, and the file keeps growing even though the actual data volume remains constant or even shrinks.

InnoDB can reclaim some of this space for new records, but only if the new data fits in the gaps left by deletions. If you delete a 100-character row and insert a 101-character row, it won't fit in that space, so it gets appended to the end of the file. Over time, you accumulate a file that's much larger than the actual data it contains.

Sound familiar? If you remember defragmentation tools from the Windows XP days (or FAT32 file systems), this is essentially the same problem, just at the database level instead of the filesystem level.

## The Usual Suspects: Drupal's Watchdog and Key-Value Tables

Certain database usage patterns make this fragmentation problem dramatically worse. In Drupal sites, for example, two tables are notorious offenders: `watchdog` and `key_value_expire`.

The `watchdog` table logs everything your application does. Many sites run cron jobs to clear old log entries to prevent the table from growing indefinitely. The problem? These cleanup scripts typically use `DELETE` statements, not `TRUNCATE`. They delete old records row by row, then new log entries get written. The table grows continuously despite the cleanup efforts.

Similarly, `key_value_expire` stores data that gets created and deleted very often. On high-traffic sites, you get a constant churn of inserts and deletes, leading to severe fragmentation.

These tables often show the largest discrepancy between actual data size and on-disk size.

## Seeing the Fragmentation Yourself

Before we dive into solutions, let's look at how you can diagnose fragmentation in your own database. There's a handy SQL query you can run to see exactly which tables are fragmented and by how much:

```sql theme={null}
SELECT
  table_name,
  round((data_length+index_length)/1048576,2) as size_MB,
  round((data_free)/1048576,2) as Allocated_but_unused
FROM information_schema.tables
WHERE data_free > 1048576*10
ORDER BY data_free DESC;
```

This query shows you the total size of each table alongside the unallocated space (those zeroed-out deleted rows we discussed). Most people know to sum `data_length` and `index_length` to get total table size, but they miss `data_free`, which is the key number that reveals your fragmentation problem.

Run this query, and you'll likely see your `watchdog` and `key_value_expire` tables near the top with significant amounts of allocated-but-unused space. That's your smoking gun.

Here is an example of what you could see:

```
+-------------------------+---------+----------------------+
| table_name              | size_MB | Allocated_but_unused |
+-------------------------+---------+----------------------+
| key_value_expire        |   10.17 |             10728.00 |
| watchdog                |  280.06 |               180.00 |
| file_managed            |   22.78 |                25.00 |
| webform_submission_data |  222.00 |                16.00 |
| webform_submission      |   17.08 |                11.00 |
+-------------------------+---------+----------------------+
```

## DELETE vs TRUNCATE: A Critical Distinction

Speaking of `DELETE` versus `TRUNCATE`, this distinction is crucial. Many developers assume they're functionally equivalent, especially when running `DELETE` without a `WHERE` clause (deleting all rows). But they behave very differently.

`DELETE` removes data row by row. InnoDB iterates through the entire table, zeroing out each row individually. The table file remains the same size, full of empty space. You don't reclaim the disk space.

`TRUNCATE`, on the other hand, drops the entire table file and recreates the table structure from scratch. It's a clean slate. The disk space is immediately reclaimed.

For tables where you don't need to preserve data - like old migration tables or temporary staging tables - `TRUNCATE` is your friend. For log tables like `watchdog`, you might consider truncating them during off-peak hours (though be aware that logs can serve audit purposes, so this isn't always appropriate).

## Defragmenting When You Need Your Data

But what if you actually need to keep your data? You can't just truncate everything. The solution is to copy the data to a new table, drop the old fragmented table, and rename the new one. That's a lot of manual steps, and frankly, nobody wants to do that.

Fortunately, InnoDB provides commands that handle this process automatically through what's called a "table recreate."

### Option 1: OPTIMIZE TABLE

The `OPTIMIZE TABLE` command tells InnoDB to examine a table and recreate it if fragmentation is significant:

```sql theme={null}
OPTIMIZE TABLE watchdog;
```

This works about 75% of the time. Sometimes InnoDB decides the table is "good enough" and doesn't bother optimizing. When that happens, you need to force the issue.

### Option 2: ALTER TABLE ENGINE (The Force Method)

You can trick InnoDB into recreating a table by running:

```sql theme={null}
ALTER TABLE watchdog ENGINE = InnoDB;
```

You're not actually changing anything - the table is already InnoDB. But the engine sees this command and assumes you want a table recreation, so it:

1. Creates a new table structure
2. Copies only the non-deleted rows (actual data) to the new table
3. Drops the old fragmented table
4. Renames the new table to replace the old one

All of this happens internally. The process is relatively quick if your actual data is small, though it locks the table during the operation. If you have millions of rows of real data (not counting deleted rows), this can take a while and block operations on that table.

For that reason, you'll want to run these maintenance operations during low-traffic periods—Sunday mornings are popular.

## The Catch-22: You Need Space to Reclaim Space

Here's the awkward part: This table recreation process requires duplicating your data temporarily. You need free disk space to be able to reclaim disk space.

If you're already at 95% disk usage when you discover the fragmentation problem, you might not have enough room to recreate your largest tables. This is a real catch-22.

The workaround is to start small: Run `ALTER TABLE ENGINE = InnoDB` on your smallest fragmented tables first. Each small table you defragment frees up a bit more space. Work your way up from smallest to largest, and by the time you reach your biggest table, you'll hopefully have freed enough space to handle it.

If you're completely out of space—say, at 100% disk usage—MySQL won't even start. The database becomes unreachable. At this point, you'll need to temporarily increase your container's disk size, start MySQL, run the defragmentation procedures, then shrink the disk back down after you've reclaimed space. This process takes only a few seconds once you're in, but it requires that emergency disk expansion first.

## The Easy Button: Upsun's CLI Tool

Rather than manually running `ALTER TABLE` commands on every fragmented table, Upsun provides a CLI tool that automates this entire workflow:

```bash theme={null}
upsun db:size --cleanup
```

This command examines all tables in your database, calculates the unallocated space (those zeroed-out deleted rows we discussed), and identifies tables with more than 10% unallocated space. You can then choose to defragment all of them automatically, and the tool handles the process for you.

## One More Caveat: The Global InnoDB File

Everything we've discussed so far applies to individual table files, but there's one more piece: InnoDB maintains a global storage file containing metadata about all your tables and their structures. This file grows indefinitely over time as tables are created, altered, and dropped.

Usually, this isn't a problem as most of your storage is in the table files themselves. But on very old databases with extensive schema changes, this global file can balloon.

The only way to shrink it? Dump your entire database, recreate the MySQL server, and re-import the dump. It's not a process you want to undertake lightly, but it's worth knowing about if you encounter an unusually large InnoDB system tablespace.

## What About PostgreSQL?

PostgreSQL faces similar fragmentation issues, but it has a solution: the `VACUUM` command. PostgreSQL's `VACUUM` performs defragmentation similar to MySQL's `OPTIMIZE TABLE`.

Better yet, PostgreSQL enables `autovacuum` by default—a background process that automatically identifies and defragments tables on a regular schedule.

Why doesn't MySQL do this? The challenge is table locking. PostgreSQL's architecture allows `autovacuum` to run with minimal disruption (it only locks DDL commands such as `ALTER TABLE`, but not queries on the table's data), while MySQL's InnoDB engine needs to lock tables during recreation. The length of that lock depends on the size of the actual data, which can range from milliseconds for a small table to minutes for a table with millions of rows. That unpredictability makes it risky to run automatically in production without full knowledge of the application's purpose.

## Wrapping Up the Mystery

So there you have it: Your 100MB dump and your 10GB database can both be accurate representations of the same data. The dump contains only the instructions to recreate the actual rows and indexes, while the database on disk includes all that data plus the invisible ghosts of millions of deleted rows, fragmented across table files.

The next time you see this discrepancy, you'll know exactly what's happening, and more importantly, what to do about it. Start monitoring your table fragmentation, schedule regular maintenance with `OPTIMIZE TABLE` or `upsun db:size-cleanup`, and keep an eye on those high-churn tables.

Your database (and your disk space alerts) will thank you.


# The (not so) hidden cost of AI scrapers
Source: https://developer.upsun.com/posts/insights/the-not-so-hidden-cost-of-ai-scrapers

AI scrapers drive up your hosting cost while real users wait. Use robots.txt, cache normalization, and sane application limits to take the pressure off.


<PostMeta />

Your hosting bill keeps growing. Your servers feel busier than they should. Real users sometimes wait too long for a page. Then you check the access logs and realize the traffic isn't who you thought it was.

Most of it is bots. Specifically, AI scrapers and aggressive crawlers, walking your application end-to-end, generating database queries, blowing through your cache, and quietly inflating your infrastructure cost.

You're not alone. Customers run into this regularly, and the problem is rarely visible until the bill arrives.

## Bots will follow every link, no matter how deep

One pattern keeps showing up: pages with no natural endpoint. A calendar that links back month by month is the textbook example. A bot finds the "previous month" link and follows it. The next page has another "previous month" link, and the bot follows that one too. And on, and on. One customer's calendar generated those links all the way back to the 1700s, and the bots dutifully followed.

The shape is what matters here, not the calendar. Any "previous/next" navigation without a lower bound creates the same trap: archive paginations, year/month/day drill-downs, infinite tag pages.

This isn't malicious. The bot is well-behaved. The site never told it to stop.

## Faceted listings turn into millions of URLs

The other pattern is just as expensive. Picture a product listing with facets: brand, screen size, memory, color, price. Every facet adds a query parameter. A crawler that tries every link on the page eventually tries every permutation of every facet combination.

A dozen facets with a few values each means millions of URLs. All of them hit your application server. All of them render full product listings against your database. None of them get cached, because each URL looks unique.

Each individual request is fine. The aggregate is what hurts your infrastructure budget.

## Where the cost lands

Bot traffic uses the same application servers, the same database, and the same cache as your real users. When that capacity runs hot, you either scale up or your real users start waiting. Either way, you pay for it.

The unpleasant part is that you rarely see the bot tax broken out. Your hosting bill says "compute time" or "database hours". It doesn't say "rendered the same product page 80,000 times for crawlers in a single afternoon". You see the impact as a slowly growing infrastructure spend, the kind of trend that looks like natural growth.

Auto-scaling makes this worse, not better. A platform that quietly adds capacity to absorb crawler traffic will keep you online and keep growing the bill. The site doesn't go down. The graphs look fine. The invoice arrives.

The bots don't notice. Your users do.

## The robots.txt fix

Well-behaved scrapers, which is to say almost all the ones causing this kind of pressure, do read your `robots.txt`. You can tell them which URL patterns to skip. For the faceted-listing case, a single line goes a long way:

```text theme={null}
  User-agent: *
  Disallow: /*?*=*
```

That tells crawlers to ignore any URL with query parameters, anywhere on the site. If only some pages have this problem, scope the rule down:

```text theme={null}
  User-agent: *
  Disallow: /products?
```

There's a trade-off here. The same `Disallow` line that stops AI scrapers from drilling into every facet combination also stops them from indexing those URLs at all. That used to matter mostly for Google search results. Now it also matters for what ChatGPT, Claude, and Perplexity recommend when someone asks. Everyone wants to be what the LLMs recommend.

The fix isn't to give up on `robots.txt`, it's to make sure the products stay reachable through paths the rules don't cover. Link to every product from the main listing page. Add a `sitemap.xml` that points search engines and AI crawlers at the canonical product URLs. Bots that should index your catalog follow those. When the same bots see a `Disallow` line, they politely oblige and skip the URLs you asked them to skip. A `robots.txt` is a polite request, not a wall, and that's exactly enough.

Robots.txt changes don't take effect immediately. Most crawlers re-fetch it every day or two. Expect bot traffic to drop within a few days, not within minutes. Sites that were struggling under crawler load tend to return to normal once the rules propagate.

## Caching, with sorted keys

Even after `robots.txt` is in place, some traffic still comes through, and some of it hits pages with query parameters. Two URLs that differ only in parameter order are functionally identical, but a naive cache treats them as different keys.

The fix is to normalize URLs before they reach the cache, wherever the cache lives: CDN, reverse proxy, or application layer. Sort query parameters alphabetically, and strip the ones you don't care about (tracking IDs, session tokens). Hundreds of variants collapse into a single cache entry.

If you happen to be using Varnish, [Varnish 103: Cache Optimization with URL Normalization on Upsun](/posts/hands-on/varnish-103-cache-optimization-with-url-normalization-on-upsun) walks through the VCL-level details.

## Limits in the application itself

The deepest fix isn't a configuration file. It's the application asking itself: should this link exist?

The 1700s calendar problem isn't really a robots.txt problem. It's a UX problem that happens to also be a crawler problem. Nobody wants to see events from the 18th century. The "previous month" link only needs to keep working as long as you have meaningful events to show. Past that point, return a 404, stop rendering the link, or redirect to the earliest month with content.

The same logic applies to faceted product pages. If a facet combination produces zero results, you don't need a unique URL for it. Render a "no products match" page that doesn't link out to other empty combinations.

These are small changes. They remove the infinite hallway that bots will otherwise wander down.

## A new normal, not a villain story

The bots are doing what their owners asked them to do, on inputs their owners didn't anticipate. The websites were built before AI scrapers existed at scale. Their authors assumed the only mechanical traffic they'd see was the occasional Googlebot pass. Both sides are catching up to a new normal.

The good news: the fixes are mostly cheap and mostly under your control. A `robots.txt` that matches the shape of your site. HTML meta directives like `<meta name="robots" content="noindex">` and `rel="nofollow"` on the links you don't want followed. Application limits where infinite navigation doesn't make sense. A cache that knows the difference between meaningful URL variation and noise. All of these work because the same well-behaved bots that overcrawl your site also read your instructions. Apply the ones that fit your application, and most of the bot pressure goes away on its own.

Your hosting bill should follow.


# The only correct way to git pull and merge
Source: https://developer.upsun.com/posts/insights/the-only-correct-way-to-git-pull-and-merge

A strongly opinionated guide to git pull and merge strategies that will make your commit history actually useful. Learn when to rebase, when to merge, and why the defaults are lying to you.


<PostMeta />

If your git history is full of merge commits that don't seem to mean anything, you're in good company. Git's default behavior is actively working against you. The good news? A couple of configuration changes will fix it.

## The problem with `git pull`

Here's what happens when you run `git pull` with the default settings. You're working on a branch with your teammates. You've got a few commits. Everything's fine. Then you think, "I should grab the latest changes." Reasonable! So you pull.

And git creates a merge commit.

You do this three times during the day because you want to stay up to date. Now you have three merge commits that say absolutely nothing except "I, a developer, updated my local copy of the repository." Thanks for that vital historical information, git.

```text theme={null}
Your branch with default git pull:

main:
A───B───C───D───E───F
     \   \   \       \
      \   \   ├───M2──├───M3
       \   \  │       │
        \  ├──M1      │
         \ │          │
          yours──────yours'

M1 = "Merge branch 'main' into feature" (you pulled at 10am)
M2 = "Merge branch 'main' into feature" (you pulled at 2pm)
M3 = "Merge branch 'main' into feature" (you pulled at 5pm)
```

These commits don't tell you anything about how the code evolved. They don't show meaningful changes. They're noise. Your git history now reads like a diary of your sync habits rather than a story of your codebase.

## What GitLab figured out

Here's the thing: GitLab doesn't even offer you the option to create a merge commit when updating your branch. When your merge request is behind the target branch, you get a "Rebase" button. That's it. No merge commit option.

<img alt="GitLab's Rebase button - no merge commit option in sight" />

GitLab understood that there's no value in a merge commit that only says "I got the latest code." The history should show what actually happened to the code, not your personal workflow habits.

```text theme={null}
Your branch with rebase (what you want):

Before rebase:
main:    A───B───C───D───E───F
              \
               X───Y  (your commits)

After git pull --rebase:
main:    A───B───C───D───E───F
                              \
                               X'──Y'  (your commits, rebased)
```

No merge commits. Your commits sit on top of the latest main. The history tells a clean story.

## When merge commits actually matter

Merge commits aren't evil. They're valuable when you're merging a branch into main. That's the moment when you want to show: "All of these commits were developed together, and they're landing in main as a unit."

The merge commit groups related work. When you're debugging six months from now and you find a problematic line, you can trace it back to its merge commit and see the full context. That refactoring commit? It was part of a larger feature. That feature? Here's every commit that went into it, all grouped together.

```text theme={null}
A meaningful merge commit:

main:    A───B───C───────────────M───
                  \             /
feature:           D───E───F───G
                   │           │
                   └───────────┘
                   "Add user authentication"

M = "Merge 'Add user authentication' into main"

Looking at M, you can see: commits D, E, F, G all belong together.
They implemented one feature. That's useful context.
```

This is useful information. "I pulled at 2:47 PM" is not.

## The fast-forward trap

When you merge without the `--no-ff` flag, git will fast-forward if it can. Your branch commits get added directly on top of main, and it looks like they were developed there all along.

This erases context. You lose the information about which commits belonged together. The history looks linear, but it's a lie. Those commits were developed on a branch, tested together, and merged as a unit. That information matters when you're trying to understand why code exists.

```text theme={null}
Fast-forward merge (git merge feature):

Before:
main:    A───B───C
                  \
feature:           D───E───F

After:
main:    A───B───C───D───E───F
                     │       │
                     └───────┘
                     Where did these come from?
                     Were they developed together?
                     Who knows! The context is gone.
```

```text theme={null}
No-fast-forward merge (git merge --no-ff feature):

Before:
main:    A───B───C
                  \
feature:           D───E───F

After:
main:    A───B───C───────────M
                  \         /
                   D───E───F

M = merge commit that preserves the branch structure.
You can always see: D, E, F were developed together.
```

Use `--no-ff` when merging to main. Always.

## The squash merge problem

Squash merging takes all the commits from your feature branch and combines them into a single commit on main. It sounds tidy. It's actually throwing away information.

```text theme={null}
Squash merge (git merge --squash feature):

Before:
main:    A───B───C
                  \
feature:           D───E───F───G
                   │   │   │   │
                   │   │   │   └── "Fix edge case in auth"
                   │   │   └────── "Add login form"
                   │   └────────── "Set up auth service"
                   └────────────── "Add user model"

After:
main:    A───B───C───S

S = "Add user authentication"

Where did commits D, E, F, G go? Gone.
Why was there an edge case fix? Who knows.
How did this feature evolve? Mystery.
```

When you squash, you lose the story of how the feature was built. That refactoring commit that seemed unrelated? It was preparing for the next step. That bug fix at the end? It reveals an edge case you might hit again. The individual commits show the developer's reasoning, the problems they encountered, the decisions they made.

Six months from now, when you're debugging and you find that the auth service is doing something unexpected, you won't be able to trace back through the thought process. You'll just see one big commit that says "Add user authentication" and wonder why things are the way they are.

## The configuration you actually want

Here's how to fix your git defaults:

```bash theme={null}
git config --global pull.rebase true
```

Now `git pull` rebases by default instead of creating pointless merge commits. Your history stays clean. Your teammates will thank you. Or at least they won't curse your name when reviewing the commit log.

For merges, get in the habit:

```bash theme={null}
git merge --no-ff feature-branch
```

Or configure your merge strategy in your repository settings if your git hosting provider supports it.

## The summary

1. **Configure git to rebase on pull**: `git config --global pull.rebase true`
2. **Use `--no-ff` when merging branches**: Preserve the context of grouped work
3. **Avoid squash merges**: Keep the development history intact

## A note on opinions

This is an opinionated piece, and reasonable people disagree on these things. Some teams love squash merges because they keep the main branch looking clean. Some developers prefer merge commits on pull because they mark a clear point in time. There are arguments for all of these approaches, and your team might have good reasons for doing things differently.

What matters most is that your team agrees on a workflow and sticks to it consistently. A consistent approach beats the "right" approach applied inconsistently.

That said, if you're starting fresh or reconsidering your workflow, the approach outlined here optimizes for one thing: making your git history useful when you need to understand why code exists. Your future self, debugging at 11 PM, will appreciate a history that tells a story rather than a logbook of sync operations or a series of opaque squashed commits.


# The third way to scale that nobody talks about
Source: https://developer.upsun.com/posts/insights/the-third-way-to-scale-that-nobody-talks-about

Beyond vertical and horizontal scaling lies a third approach that most scaling discussions ignore. Learn about natural scaling, where you sidestep the problem entirely.


<PostMeta />

Your application is getting more traffic. Congratulations, you have a good problem. Now you need to scale.

At this point, every blog post, conference talk, and senior engineer in your life will present you with two options. Two respectable, battle-tested approaches. The approved choices.

## The two options you're allowed to pick

**Vertical scaling** is the straightforward one. Your server can't handle the load? Get a bigger server. More CPU, more memory, more everything. It works, and it's satisfying in the same way that buying a larger hard drive is satisfying. The problem is that physics eventually gets in the way. Good luck finding a machine with 400+ CPUs. They exist, but you'll pay for the privilege.

**Horizontal scaling** sounds more sophisticated. Instead of one big server, you run many smaller ones. A load balancer distributes traffic between them. Infinite scalability, right? Well, yes, but there's a catch. Your application needs to support this. If you're storing session data in memory, horizontal scaling will turn your users' experience into a lottery. They'll get different data depending on which server they land on. So you need to externalize state, add a shared cache, and accept the architectural complexity that comes with it. And then there's the database. You can add application servers all day, but they all talk to the same database. At some point, that database becomes the bottleneck, and horizontally scaling databases is a whole different beast. Sharding, replication, consistency trade-offs. It gets complicated fast.

Both approaches have their place. Both require trade-offs. And both are exhaustively documented.

But there's a third option that rarely comes up.

## The scaling approach nobody mentions

I call it "natural scaling" for lack of a better term. The idea is simple: what if you kept each application instance small enough that it never needed to scale?

Instead of one application serving all your users, you run many small applications, each serving a subset. Each instance handles so little traffic that scaling becomes irrelevant.

Consider GitHub, hypothetically. Imagine if each organization got its own dedicated server. Your organization's server handles traffic for your repositories, and that's it. The load is inherently limited because the user base is inherently limited. You don't need to scale that server. You need more servers, but each individual server stays small and manageable.

This isn't hypothetical at Upsun. Every project on our platform gets its own dedicated API server. We don't have one API server that needs to scale to handle all projects. We have thousands of small API servers, each handling exactly one project.

## The catch (because there's always a catch)

Natural scaling trades one problem for another. You don't have to worry about scaling anymore. Instead, you have to worry about operating a fleet.

Deploying three servers is fine. You can do it manually if you have to (though you shouldn't). Deploying 10,000 servers is a different discipline entirely. Your automation has to be flawless. Your deployment pipeline has to be bulletproof. Every update, every security patch, every configuration change has to roll out consistently across the entire fleet.

This may be why natural scaling doesn't get discussed much? The operational overhead is significant. You're trading application complexity for infrastructure complexity. For many teams, that's not a trade they want to make.

## So why consider it?

Because sometimes the trade-off makes sense. If your product naturally segments into isolated units (tenants, organizations, projects), natural scaling aligns with your architecture. You get isolation for free. One customer's traffic spike doesn't affect another customer. One customer's data stays completely separate from another's.

And you never have to have the "we need to rewrite for horizontal scaling" conversation.

Is this the right approach for every application? No. Is it discussed as often as it should be? Probably not. Worth considering the next time someone tells you that you have exactly two options for handling scale.


# What will you do after you deploy?
Source: https://developer.upsun.com/posts/insights/what-will-you-do-after-you-deploy

Learn how Platform.sh's post_deploy hook can keep your site responsive during deploy tasks, making your deploys faster and more efficient.

<PostMeta />

<Tip>
  This post was originally published on the Platform.sh blog and reflects information from the time of publication.
</Tip>

A key part of Platform.sh's benefit comes from its integrated build and deploy hooks. Deploying a new version of your site or application rarely means simply dumping what's in Git onto a server anymore. Platform.sh was built from the ground up to let you execute whatever commands you need to "build" your application — turning what's in Git into what's actually on the server — and then to "deploy" the application — cleanup tasks like database migrations that should be run before the site is opened to visitors again.

There's a caveat there, however. Some deploy tasks need to block the site from new visitors until they complete; think updating the database schema, for instance. Others may not really need exclusive access to the site, but they still get it. That keeps the site unresponsive for critical seconds until those tasks complete.

So, let's fix that. We've now added a third hook, `post_deploy`. It works pretty much as you'd expect. You can do all the same things in it that you can do with a `deploy` hook, but it runs after the site is reopened to the world to accept new requests. Any tasks that don't need exclusive access to the database can be moved there, keeping the site up and responsive as much as possible while allowing for more robust and flexible automated tasks.

For example, the following configuration would run any pending database updates as part of the `deploy` hook but then import new content in the `post_deploy` hook. The new content will become available as soon as possible but the site will still be up and running while it's being updated. Once the import is done we'll also clear the cache a second time to ensure the new content is visible to the next request.

```
hooks:
    deploy: |
        set -e
        update_db.php
        clear_cache.php
    post_deploy: |
        set -e
        migrate_content.php import/
        clear_cache.php
```

What's "safe" to move to the `post_deploy` hook? That's up to you. What does or does not need an exclusive database lock will vary by site. Sometimes a cache clear is safe to do post-open, other times not. You get to make that determination for your application.

See the [hook documentation](https://docs.platform.sh/configuration/app/build.html#hooks) for more information, and enjoy faster deploy tasks.


# Which stack would you pick for an interactive AI app today?
Source: https://developer.upsun.com/posts/insights/which-stack-would-you-pick-for-an-interactive-ai-app-today

Coding agents changed how new teams pick a tech stack. A tour of 8 ecosystems for interactive AI apps, and why "can we run it" beats "can we write it".


<PostMeta />

You're starting a greenfield project. The brief: an interactive web app, background workers, and AI agents calling Anthropic, OpenAI, or Mistral. Which stack do you pick?

For existing teams, this isn't a real question. If you're a Java shop, switching to .NET is pain for no good reason. If you're a Python shop, moving to Node.js changes nothing that matters. You use what you have.

The interesting case is the new team. A handful of people with different backgrounds, each carrying their own ecosystems. I know 5 of them well: Python, PHP, Common Lisp, Node.js, and Go. Most developers I know carry more than one. Put a few of us in a room with a blank repo, and the question becomes very real.

## You still want an ecosystem

An assumption worth stating first: even with coding agents writing much of the code, you should lean on libraries and frameworks as much as possible.

Yes, dependencies mean supply chain management: keeping up with releases, watching advisories, paying the maintenance tax. But you pay that tax anyway. You're not reinventing Linux, or your web server, or your queue. The richer the ecosystem, the less code you own, and code you don't own is code you don't maintain.

For this kind of app, ecosystem maturity comes down to 3 axes: AI and agents, background workers, and interactive UI.

## A quick tour of the ecosystems

| Ecosystem | AI and agents | Workers | Interactive UI |
| - | - | - | - |
| PHP (Symfony) | `symfony/ai` | Messenger | Symfony UX, Live Components, Turbo, Mercure |
| PHP (Laravel) | Prism, Laragent | Horizon | Livewire, Reverb |
| Elixir (Phoenix) | Growing | Oban, the BEAM | LiveView |
| Python (Django) | The AI language | Celery | Channels, less mature |
| .NET | Semantic Kernel, heavy Microsoft investment | Hangfire | Blazor Server |
| Go | Google's ADK | Goroutines, built in | Thin |
| Node.js | Vercel AI SDK | Less mature | Next.js and friends, by far the strongest |
| Java | Strong | Strong | Not there yet |

A few notes from someone who's spent real time in several of these.

`symfony/ai` is younger than the rest of the Symfony ecosystem, but you can say that about the AI layer of every ecosystem here. Laravel has quietly assembled a complete answer: Livewire for live components, Reverb for WebSockets, Horizon for workers, Prism for talking to LLMs, and Laragent for autonomous agents.

Phoenix LiveView is arguably the original interactive web app, and the BEAM was built for exactly this kind of concurrent, connection-heavy workload. Python is the AI language, even if Channels never made Django feel as live as LiveView does. Node.js owns the interactive UI story, with Vercel pushing hard, but its worker story is thinner than elsewhere. Go gives you workers for free with goroutines, and now Google's ADK for agents, but the interactive UI ecosystem isn't there. Java is the one I know least; AI and workers are strong there, with too much corporate weight behind them not to be.

None of these is a wrong answer. That's the problem.

## The criteria changed

Before coding agents, the deciding factor was team expertise. When you're building something new, you go with what you know. That single fact decided most stack choices for the past few decades.

That picture has changed. The coding agent writes most of the code now. You still need enough familiarity to review what it writes, and that might narrow 5 options down to 3. But "how well can we read this language" stopped being the major factor, because you can train yourself into reading a new language much faster than you can train yourself into operating one.

The question that replaced it: how well can we run this application?

Where does it run, Linux or Windows? Which platforms will host it? What does it cost? Can it run on your laptop? If your app needs 64GB of memory to boot, your laptop has opinions. (I'm not saying all Java applications need 64GB. Don't make me say what I'm not saying.) And if you pick Elixir, wonderful ecosystem, but the list of platforms that host it well is short. You're narrowing your options before you've written a line.

## Eliminate, then choose

For this specific app, the operational lens does most of the elimination for me. Go falls off first: the interactive UI ecosystem isn't mature enough. If workers matter a lot, Node.js gets uncomfortable. You can do it, but you'd be swimming against the ecosystem's maturity.

After that, taste still counts. I love Common Lisp for the interactive development environment it gives me, not for its library ecosystem. Developers' preferences don't stop mattering because an agent writes the code.

But the biggest shift is this: switching technologies is easier than it has ever been, which means the ability to switch matters more than it ever has. That's why I care about platforms that don't pick a language for you. AWS qualifies, at a very different altitude. [Upsun](https://upsun.com) sits at the same level as Vercel or Heroku without narrowing what you can run; every stack on this list works there. The limit is your team, not your platform.

Pick the stack your team can run. And keep the door open.


# Git-Driven Infrastructure: Why Configuration as Code Beats Click-and-Deploy
Source: https://developer.upsun.com/posts/insights/why-configuration-as-code-beats-click-and-deploy

Discover why YAML-driven infrastructure outperforms point-and-click deployment for scalable, maintainable applications. Learn best practices for configuration as code.


<PostMeta />

It was 11:47 PM on a Friday when Sarah's phone buzzed. The authentication system was down, and customers couldn't login and use the product. After two hours of frantic debugging, the culprit emerged: someone had "temporarily" changed a security rule in the deployment dashboard three weeks ago and forgotten to document it. The staging environment worked perfectly because it still had the old configuration. Production? Nobody remembered what settings had been changed.

This scenario happens more often than teams want to admit. Click-and-deploy platforms promise simplicity, but they create a dangerous illusion. What starts as a quick deployment becomes a web of undocumented changes, tribal knowledge, and configuration drift that can bring down your application or parts of it when you least expect it.

The truth is that infrastructure, like code, needs version control, peer review, and reproducible builds. For teams serious about reliability and scale, **configuration as code isn't just better, it's essential**.

## The Configuration Drift Problem

### What Happens When Infrastructure Lives in GUIs

Modern deployment platforms make it tempting to treat infrastructure like a point-and-click adventure. Need to add an environment variable? Click here. Want to change the build command? Update this field. Scale up resources? Drag this slider.

Each change feels harmless in isolation. But over time, your infrastructure accumulates invisible complexity. Team members make quick fixes without documentation. Settings drift between environments. Knowledge gets trapped in individual memories rather than shared systems.

Consider a typical scenario: Your team deploys a React application to production using a popular frontend platform. The initial setup takes five minutes. Six months later, you have:

* Environment variables set directly in the dashboard
* Build configurations that differ between staging and production
* Security headers configured through various interface panels
* Resource allocations adjusted by different team members
* Integration settings spread across multiple configuration screens

When something breaks, you face an archaeological expedition through interface panels, trying to reconstruct what actually runs in production.

### Real-World Scenario: The Friday Deployment Disaster

Let's follow a real team through a typical configuration drift disaster. TechFlow, a growing SaaS company, built their customer dashboard using a click-and-deploy platform. The initial deployment was smooth-their frontend deployed automatically from GitHub, and the team loved the simplicity.

As the product evolved, the team made incremental changes:

* Marketing requested A/B testing capabilities, so they added feature flags through the platform's interface
* The security team required custom headers, configured through the dashboard's security panel
* Performance optimization led to CDN settings adjusted across multiple interface screens
* Compliance requirements meant new environment variables for data handling

Three months later, during a critical product launch, the team needed to quickly replicate their production environment for a high-stakes demo. What should have been a simple environment copy became a two-day emergency project.

The staging environment, supposedly identical to production, behaved completely differently. Customer authentication failed, API calls threw errors, and the demo crashed during the presentation. The team spent the weekend manually comparing dozens of configuration screens, trying to identify differences between environments and debug the environment.

The root cause? Eighteen separate configuration changes made through various dashboard interfaces, with no audit trail or documentation. Each change seemed minor at the time, but collectively they created an unreproducible system.

### The Scaling Tipping Point

Every team hits a threshold where click-and-deploy becomes a liability rather than an asset. The tipping point usually occurs when:

**Team Size Exceeds 3-5 Developers**: Multiple people making infrastructure changes without coordination leads to conflicts and confusion. Without version control, you can't track who changed what or why.

**Multiple Environments Become Critical**: Development, staging, production, features and demo environments need to stay synchronized. Manual configuration management across environments becomes error-prone and time-consuming.

**Compliance Requirements Emerge**: SOC2, HIPAA, or GDPR audits require documentation of infrastructure changes. Screenshots of dashboard settings don't meet audit standards.

**Integration Complexity Grows**: Modern applications integrate with databases, APIs, monitoring tools, and external services. Managing these connections through GUI interfaces becomes unwieldy.

**Deployment Frequency Increases**: Teams deploying multiple times per day need predictable, automated infrastructure management. Click-and-deploy workflows become bottlenecks.

## Configuration as Code: The Professional Approach

### Core Principles

Configuration as code treats infrastructure definitions like software-versioned. Reviewed, tested, and deployed through automated processes. This approach follows four fundamental principles:

**Everything in Version Control**: Infrastructure configurations live in Git repositories alongside application code. Every change creates a commit with an author, timestamp, and description. You can track the complete evolution of your infrastructure.

**Reproducible Environments**: Given the same configuration files, you can recreate identical environments. This eliminates the "works on my machine" problem for infrastructure and enables reliable disaster recovery.

**Reviewable Infrastructure Changes**: Infrastructure modifications go through the same peer review process as code changes. Pull requests allow team members to discuss, validate, and approve infrastructure changes before they reach production.

```mermaid theme={null}
graph TD
    subgraph "Git Workflow"
        A(Initial Config) --> B(Security update);
        A --> C("feature-redis-cache<br/>Add Redis service");
        C --> D("Update app config");
        D --> E("Fix cache settings");
        B --> F(Merge feature branch);
        E --> F;
        F --> G(Deploy to production);
        G --> H("hotfix-db-scale<br/>Scale database");
        G --> I(Emergency deploy);
        H --> I;
    end

    subgraph "Legend"
        direction LR
        L1(Main Branch)
        L2(Feature Branch)
        L3(Hotfix Branch)
    end

    style A fill:#D0F302,color:#000
    style B fill:#D0F302,color:#000
    style F fill:#D0F302,color:#000
    style G fill:#D0F302,color:#000
    style I fill:#D0F302,color:#000
    style L1 fill:#D0F302,color:#000

    style C fill:#6046FF,color:#fff
    style D fill:#6046FF,color:#fff
    style E fill:#6046FF,color:#fff
    style L2 fill:#6046FF,color:#fff

    style H fill:#000,color:#fff
    style L3 fill:#000,color:#fff
```

*Git workflow for infrastructure changes: Every modification is versioned, reviewed, and auditable*

**Declarative Configuration**: You describe what you want your infrastructure to look like, not the steps to create it. The platform handles the implementation details, ensuring consistent results.

### Upsun's YAML Approach in Action

Upsun implements configuration as code through YAML files that live in your application repository. Here's how a multi-service application looks in practice:

```yaml {filename=".upsun/config.yaml"} theme={null}
applications:
  frontend:
    source:
      root: "frontend"
    type: "nodejs:18"
    build:
      flavor: none
    hooks:
      build: |
        npm ci
        npm run build
        npm run test:unit
      deploy: |
        npm run migrate:data
    web:
      commands:
        start: "npm start"
      locations:
        "/":
          root: "dist"
          index: ["index.html"]
        "/api":
          passthru: true
    relationships:
      backend: "api:http"
      cache: "redis:redis"
    variables:
      env:
        NODE_ENV: "production"
        API_BASE_URL: $API_BASE_URL

  backend:
    source:
      root: "backend"
    type: "python:3.11"
    hooks:
      build: |
        pip install -r requirements.txt
        python manage.py collectstatic --noinput
      deploy: |
        python manage.py migrate --noinput
    web:
      commands:
        start: "gunicorn myapp.wsgi:application"
    relationships:
      database: "db:postgresql"
      cache: "redis:redis"
    variables:
      env:
        SECRET_KEY: $SECRET_KEY

services:
  db:
    type: postgresql:15
    disk: 2048
    configuration:
      max_connections: 200
      shared_buffers: "256MB"

  redis:
    type: redis:7.0
    configuration:
      maxmemory: "256mb"
      maxmemory-policy: "allkeys-lru"

routes:
  "https://{default}/":
    type: upstream
    upstream: "frontend:http"
    cache:
      enabled: true
      default_ttl: 3600

  "https://{default}/api/":
    type: upstream
    upstream: "backend:http"
    cache:
      enabled: false

  "https://{default}/admin/":
    type: upstream
    upstream: "backend:http"
    cache:
      enabled: false
```

This configuration file tells a complete story about your application architecture. Anyone can read it and understand:

* How services connect to each other
* What databases and caching layers exist
* How traffic routes between components
* What happens during build and deployment
* How different environments should behave

```mermaid theme={null}
graph LR
    U[User] --> LB[Load Balancer]
    
    LB --> |"/ requests"| FE[Frontend<br/>Node.js 18<br/>React App]
    LB --> |"/api requests"| BE[Backend<br/>Python 3.11<br/>Django API]
    LB --> |"/admin requests"| BE
    
    FE --> |API calls| BE
    BE --> |Queries| DB[(PostgreSQL 15<br/>2GB Storage)]
    BE --> |Cache| RD[(Redis 7.0<br/>256MB)]
    FE --> |Session cache| RD
    
    style FE fill:#D0F302,color:#000
    style BE fill:#6046FF,color:#fff
    style DB,RD fill:#000,color:#fff
```

*Multi-service architecture visualization: How the YAML configuration maps to actual infrastructure*

### Benefits of Configuration as Code

This YAML-driven approach delivers immediate practical benefits:

**Clear Dependency Mapping**: The `relationships` section explicitly shows how services connect. You can see at a glance that the frontend talks to the backend, and the backend uses both PostgreSQL and Redis.

**Environment Parity Guaranteed**: The same YAML files deploy to development, staging, and production. Environment-specific differences are handled through variables, not different configurations.

**Infrastructure Changes Reviewed Like Code**: Modifying infrastructure means editing YAML files and creating pull requests. Your team reviews infrastructure changes with the same rigor as application changes.

**Deployment Automation and Rollback**: Deployments become deterministic processes based on Git commits. Rolling back infrastructure changes is as simple as reverting commits.

**Documentation That Stays Current**: The YAML files serve as always-up-to-date documentation of your infrastructure. Unlike wiki pages or README files, this documentation can't drift from reality.

## Comparative Analysis: YAML vs. Click-and-Deploy

### Developer Experience Comparison

The differences between configuration as code and click-and-deploy become apparent in day-to-day development scenarios:

| Aspect | Click-and-Deploy | Configuration as Code |
| - | - | - |
| **Initial Setup** | 5 minutes of clicking through wizards | 30 minutes writing YAML configuration **(only the first time)** |
| **Adding New Service** | 10 clicks across multiple screens, changes undocumented | 5 lines of YAML in pull request with peer review |
| **Environment Replication** | Manual recreation, often with subtle differences | `git clone` followed by automated deployment |
| **Team Onboarding** | Screen sharing session or outdated documentation | Read the configuration files in the repository |
| **Rollback Speed** | Manual reconfiguration through dashboards | `git revert` followed by automated redeployment |
| **Audit Trail** | Platform logs (if comprehensive) | Complete Git history with commit messages |
| **Change Approval** | Tribal knowledge and Slack messages | Formal pull request review process |
| **Configuration Drift** | Inevitable as team makes undocumented changes | Impossible-all changes are versioned |

### Enterprise Scenarios Where Configuration as Code Wins

**Compliance Requirements**: When auditors ask for documentation of infrastructure changes, you need more than screenshots of dashboard settings. Configuration as code provides the audit trail that compliance frameworks require. Every change has an author, reviewer, timestamp, and business justification in the commit message.

**Multi-Region Deployment**: Global applications need consistent configuration across multiple regions. With click-and-deploy platforms, you manually replicate settings across different regional dashboards. Configuration as code lets you deploy identical infrastructure to multiple regions from the same YAML files.

**Disaster Recovery**: When your primary environment goes down, you need to recreate your infrastructure quickly and accurately. Configuration as code enables complete environment recreation from version control-no guesswork, no missing settings, no manual configuration steps.

**Change Management**: Large organizations need approval workflows for infrastructure modifications. Configuration as code integrates with existing code review processes, allowing infrastructure changes to follow the same governance as application changes.

### The Hidden Technical Debt of GUI Configuration

Click-and-deploy platforms create technical debt that compounds over time:

**Knowledge Silos**: Critical infrastructure knowledge gets trapped in individual team members' minds rather than documented in shared systems. When those team members leave, the knowledge leaves with them.

**Integration Challenges**: Modern DevOps requires infrastructure integration with CI/CD pipelines, monitoring systems, and deployment automation. GUI-based configuration creates integration gaps that require manual workarounds.

**Limited Automation**: You can't easily automate changes to GUI-configured infrastructure. This limits your ability to implement advanced deployment strategies, automated scaling, or self-healing systems.

**Testing Difficulties**: Infrastructure changes need testing just like code changes. With GUI configuration, you can't implement infrastructure testing, validate changes in isolated environments, or run automated compliance checks.

## Advanced Upsun Capabilities

### Environment Branching Strategy

Upsun extends Git's branching model to infrastructure, creating powerful workflows for development teams:

```yaml {filename=".upsun/config.yaml"} theme={null}
# Different configurations can be activated based on Git branches
hooks:
  build: |
    if [ "$PLATFORM_BRANCH" = "main" ]; then
      npm run build:production
    else
      npm run build:development
    fi
  deploy: |
    # Run database migrations in production
    if [ "$PLATFORM_BRANCH" = "main" ]; then
      npm run migrate:deploy
    else
      # For development branches, you might seed the database
      npm run db:seed
    fi
```

This branching strategy enables sophisticated development workflows:

* **Feature Branch Environments**: Every feature branch gets its own complete environment with isolated databases and services
* **Database Cloning**: Preview environments include cloned production data with automatic sanitization for privacy compliance
* **Network Isolation**: Each environment runs in isolation, preventing cross-environment interference
* **Automated Cleanup**: Environments automatically clean up when branches are deleted, preventing resource waste

### Integration with Development Workflow

Configuration as code integrates seamlessly with modern development practices:

```yaml {filename=".upsun/config.yaml"} theme={null}
hooks:
  build: |
    set -e
    # Install dependencies
    npm ci
    
    # Run tests
    npm run test:unit
    if [ $? -ne 0 ]; then
      echo "Unit tests failed, aborting build"
      exit 1
    fi
    
    # Build application
    npm run build
    
    # Run integration tests
    npm run test:integration
    if [ $? -ne 0 ]; then
      echo "Integration tests failed, aborting build"
      exit 1
    fi
    
    # Security scanning
    npm audit --audit-level=high
    
  deploy: |
    # Database migrations
    npm run migrate:deploy
    
    # Cache warming
    npm run cache:warm
    
    # Health check
    curl -f http://localhost/health || exit 1
    
    # Notify monitoring systems
    curl -X POST $DEPLOYMENT_WEBHOOK_URL \
      -H "Content-Type: application/json" \
      -d "{\"status\":\"deployed\",\"commit\":\"$PLATFORM_TREE_ID\"}"
```

These hooks ensure that every deployment follows the same quality gates, testing procedures, and notification processes-automatically and consistently.

## Migration Strategy: From Click-and-Deploy to Configuration as Code

### Assessment Phase

Before migrating to configuration as code, inventory your current infrastructure setup:

**Document Existing Configurations**: Export or screenshot current platform settings. Many teams discover they have more configuration complexity than they realized.

**Map Service Dependencies**: Identify how your applications connect to databases, APIs, and external services. This mapping becomes the foundation for your YAML configuration.

**Identify Team Knowledge Gaps**: Determine which infrastructure knowledge exists only in individual team members' minds. This knowledge needs to be captured in configuration files.

**Evaluate Compliance Requirements**: Understand your organization's audit, security, and governance needs. Configuration as code can address many compliance requirements that GUI-based systems cannot.

### Gradual Migration Approach

Teams don't need to migrate everything at once. A phased approach reduces risk and builds confidence:

**Start with New Projects**: Use Upsun for new applications while keeping existing projects on their current platforms. This approach lets teams learn configuration as code without migration pressure.

**Convert Non-Critical Applications First**: Move development tools, internal dashboards, or documentation sites before touching revenue-critical applications.

**Migrate Development Environments Before Production**: Set up development and staging environments on Upsun while keeping production on the existing platform. This approach provides a safety net during the learning process.

**Plan Production Migration During Low-Risk Periods**: Schedule production migrations during maintenance windows or low-traffic periods.

### Measuring Success

Track metrics that demonstrate the value of configuration as code:

**Deployment Frequency and Reliability**: Measure how often you deploy and how often deployments succeed. Configuration as code typically increases deployment frequency while reducing failure rates.

**Time to Environment Creation**: Track how long it takes to create new environments. Configuration as code dramatically reduces environment setup time.

**Mean Time to Recovery**: Measure how quickly you can recover from incidents. Version-controlled infrastructure enables faster rollbacks and more predictable recovery procedures.

**Developer Satisfaction and Velocity**: Survey your team about deployment confidence and development velocity. Configuration as code typically improves both metrics significantly.

## Compliance and Security Benefits

Configuration as code provides security and compliance advantages that GUI-based systems cannot match:

### Audit Trail and Governance

Every infrastructure change creates a permanent audit trail with:

* **Who**: Git commit author and reviewer identities
* **What**: Exact changes made to configuration
* **When**: Precise timestamps for all modifications
* **Why**: Commit messages explaining business justification
* **How**: Pull request discussions showing decision process

This audit trail meets the documentation requirements for SOC2, HIPAA, GDPR, and other compliance frameworks.

### Security Through Review

Infrastructure changes go through the same security review process as code changes:

```yaml {filename=".upsun/config.yaml"} theme={null}
# Security configurations are explicit and reviewable
web:
  headers:
    Strict-Transport-Security: "max-age=31536000; includeSubDomains"
    X-Content-Type-Options: "nosniff"
    X-Frame-Options: "DENY"
    X-XSS-Protection: "1; mode=block"
    Content-Security-Policy: "default-src 'self'; script-src 'self' 'unsafe-inline'"
  
variables:
  env:
    # Secrets management through secure variables
    API_SECRET_KEY: $API_SECRET_KEY
    ENCRYPTION_KEY: $ENCRYPTION_KEY
```

Security misconfigurations become visible in pull requests, allowing team members to catch problems before they reach production.

### Reproducible Security Posture

Configuration as code ensures consistent security settings across all environments. You can't accidentally deploy to production with development-level security settings when your configuration is version-controlled.

## When to Make the Switch

### Signs Your Team Has Outgrown Click-and-Deploy

Several indicators suggest it's time to move beyond GUI-based deployment platforms:

**Configuration Drift Incidents**: If you've experienced production issues caused by undocumented infrastructure changes, you need better configuration management.

**Environment Synchronization Problems**: When staging and production behave differently despite being "identical," you have a configuration management problem.

**Onboarding Difficulties**: If new team members struggle to understand your infrastructure setup, you need better documentation-which configuration as code provides automatically.

**Deployment Anxiety**: Teams shouldn't fear deployments. If your deployments are unpredictable or stressful, configuration as code can provide the reliability you need.

**Scaling Team Size**: Once your team grows beyond 3-5 developers, GUI-based configuration becomes a coordination challenge.

**Compliance Requirements**: If your organization needs to meet formal compliance standards, configuration as code provides the audit trail and documentation you need.

### ROI of Professional Infrastructure Management

The investment in configuration as code pays dividends through:

**Reduced Deployment Time**: Teams typically see 60-80% reductions in deployment time when moving from manual to automated configuration management.

**Lower Error Rates**: Version-controlled infrastructure reduces configuration errors that cause production incidents.

**Faster Environment Creation**: New environments take minutes instead of hours or days to create.

**Improved Developer Productivity**: Developers spend less time on infrastructure tasks and more time building features.

**Better Sleep**: On-call rotations become less stressful when infrastructure is predictable and rollbacks are reliable.

### Getting Started with Upsun

Moving to configuration as code doesn't require a complete infrastructure rewrite. Upsun provides resources to make the transition smooth:

**Documentation and Tutorials**: Comprehensive guides cover everything from basic YAML syntax to advanced deployment strategies.

**Migration Assistance**: Upsun's support team can help plan and execute migrations from existing platforms.

**Community Support**: [Join our community forum](https://community.upsun.com/) to discuss common questions and best practices with experienced users and the team.

**Professional Services**: For complex migrations, Upsun offers professional services to ensure successful transitions.

## Conclusion: Professional Infrastructure for Professional Teams

Configuration as code represents a fundamental shift in how professional teams manage infrastructure. While click-and-deploy platforms offer initial simplicity, they create long-term maintenance burdens that become unsustainable as teams and applications grow.

The choice between GUI configuration and configuration as code mirrors the choice between ad-hoc scripting and professional software development. Both can produce working systems, but only one scales with team size, application complexity, and business requirements.

Teams that embrace configuration as code gain:

* **Reproducible infrastructure** that eliminates environment drift
* **Auditable changes** that meet compliance requirements
* **Collaborative workflows** that scale with team growth
* **Automated deployments** that increase velocity and reliability
* **Predictable rollbacks** that reduce deployment anxiety

The transition requires initial investment in learning YAML syntax and infrastructure concepts. But this investment pays compound returns through improved reliability, faster development cycles, and reduced operational overhead.

If your team is experiencing the scaling limitations of click-and-deploy platforms-configuration drift, environment synchronization issues, deployment anxiety, or compliance challenges-it's time to consider configuration as code.

Professional applications deserve professional infrastructure. Configuration as code provides the foundation for reliable, scalable, and maintainable systems that grow with your business.

***

**Ready to eliminate configuration drift and deployment anxiety? Start building with infrastructure as code-[create your free Upsun account](https://upsun.com) and experience the power of YAML-driven deployment.**

**For enterprise teams planning a migration strategy, [schedule a demo](https://upsun.com/contact-us/) to see how configuration as code can transform your deployment workflow.**


# Why Emacs is still my interface to my computer
Source: https://developer.upsun.com/posts/insights/why-emacs-is-still-my-interface-to-my-computer

Why I still use Emacs every day: one consistent interface for editing, Git with Magit, terminals, a Claude Code agent per project, and the rest of my computer.

<PostMeta />

## Introduction

Tell someone you use [Emacs](https://www.gnu.org/software/emacs/) in 2026 and watch their face. There's usually a smile, sometimes a laugh, occasionally the old line: "Emacs is a great operating system, lacking only a decent editor." The editor wars between vi and Emacs have been running for about 40 years, and somehow we're all still here.

I'm one of the people who never left. I open Emacs every morning and do almost all of my work inside it. It's not nostalgia. It does something for me that no other tool does: it's a single interface to my whole computer.

Here's what that looks like in practice.

## Emacs as an interface, not an editor

The way I think about my machine is split in two. The browser is my interface to the web. Emacs is my interface to everything else on my computer.

I ended up here partly because I write Lisp. The Lisp world leaned on Emacs for decades: the REPL, the packages, and the editing model all fit together, and Emacs became the default home for a lot of us. Once you live in that world, you stop seeing Emacs as a text editor and start seeing it as a place to get things done.

Want to browse a folder? I don't open a file manager. I open [Dired](https://www.gnu.org/software/emacs/manual/html_node/emacs/Dired.html), the directory editor built into Emacs. It lists files, searches them, renames, copies, moves, and lets me work with the filesystem without leaving the window I'm already in.

That's the pattern for everything that follows. The same window and the same keys, handling one more job.

## Magit: the reason some people install Emacs

If I had to name the single package that earns Emacs its keep, it's [Magit](https://magit.vc/). It's a Git client, and I'd argue it's the best one ever made. Plenty of people run Emacs for Magit and nothing else, which tells you something.

Magit is discoverable in a way most tools aren't. Press `?` and it shows you every action available right now. Want to push? A couple of keystrokes. Want to rebase? Also painless, which is rare, because rebasing is where most Git tools fall apart. Magit turns it into something you do without dread.

It quietly makes you a Git power user. You see your staged changes, your branch, your history, and the full state of the repository in one buffer, and you act on all of it with single keys.

## Projectile: everything is a project

[Projectile](https://docs.projectile.mx/projectile/index.html) adds the idea of a "project" to Emacs, and a project is usually a Git repository. With it I can jump between projects, find a file by typing a few letters, search across the whole codebase, or launch Magit for the current project, all from a short shortcut.

My morning tends to start the same way. I use Projectile to jump into a project. I open Magit to see where things stand: which branch, what's modified, what the state of the world is right now. Then I hit a shortcut that opens a [vterm](https://github.com/akermu/emacs-libvterm) buffer (a real terminal inside Emacs) in that project's folder, and it starts `claude`.

## A coding agent per project

Every project I work on has its own Claude Code buffer. 3 repositories open means 3 buffers, each running its own agent.

From there the loop is simple. I tell [Claude Code](https://docs.anthropic.com/en/docs/claude-code) what I want, like everyone else does these days, and then I review the work. I start with Magit, reading the diff and committing the pieces I want. But a diff isn't always the clearest way to judge a change. Sometimes it's easier to open the file and read the whole thing in context than to piece together a handful of changed lines. Emacs is still a text editor underneath all of this, and LSP gives me the autocompletion, go-to-definition, and codebase navigation you'd expect from any IDE. That makes reading a change (an agent's or my own) fast, and writing code by hand is never more than a keystroke away.

Emacs is an IDE, then. But calling it one undersells it: the same window is also my Git client, my file manager... and so much more.

## The throwaway workflow

Not everything is a long-lived project. Sometimes I want to try something for 10 minutes. I go to `/tmp/something`, start Claude Code right there, and work in that folder with no ceremony. When I'm done, it's gone. No project setup, no cleanup.

For shell work I lean on [Eshell](https://www.gnu.org/software/emacs/manual/html_mono/eshell.html), a terminal written in Lisp. It looks like a terminal, but because it's Emacs, the output and the input are plain text in a buffer. I can copy, edit, and move through them like any other text, and I can drop a line of Lisp into the middle of a command when I need to.

## Running commands, however I want

There's no single right way to run a command here, which is the point. Sometimes I type it into Eshell or vterm and watch it scroll by. Sometimes I send it to its own dedicated buffer and tuck that buffer into a corner of the window, glancing at it while I work on something else. Sometimes I run it and forget it, then come back to the output when I care.

Running a command is another part of the OS interface, not a separate app I switch to. The output lands in a buffer like everything else, so I can read it, search it, copy from it, or feed it into the next step without leaving Emacs.

## One window, many jobs

What makes all of this click is that it lives in one interface. Dired, Magit, vterm, Eshell, LSP, and the editor are the same program with the same keys. When I want to build something, I hit a shortcut and Projectile compiles from the repository root. Nothing leaves the window.

Some days that window shows me a lot at once: Git output here, 2 or 3 projects deploying there, an agent working through a task in another buffer. It looks a bit ridiculous, like a movie hacker's screen, and I like it that way.

## And none of this is really about code

What surprises people is that most of what I've described isn't specific to programming. If I wanted to, I could read my email and my RSS feeds without leaving Emacs. It previews Markdown as I write it. I can open a LaTeX file and watch the rendered output update in a window right next to the source. Same keys, same buffers, same muscle memory, pointed at whatever I'm doing that day.

That's the part the "Emacs is an operating system" joke gets right. It's less a text editor than a place to work, and editing code is one of the many things you happen to do there.

## One interface for everything

That's the whole point. It isn't about the specific packages or which editor wins. Emacs is the one place where I edit, commit, browse files, read, ship, and run commands wherever I want them, with the same keys pointed at all of it. The browser is my interface to the web. Emacs is my interface to the rest of my computer.

I'm not trying to talk anyone into it. The jokes are fair and the learning curve is real. But that single, consistent interface is why I open Emacs first thing every morning and stay in it all day.

Happy hacking.


# Why Python developers should switch to uv
Source: https://developer.upsun.com/posts/insights/why-python-developers-should-switch-to-uv

Learn how uv, the revolutionary Python package manager, delivers 100x faster installations and streamlines project management with automatic virtual environments and dependency tracking.

<PostMeta />

## Introduction

Python development has long been plagued by slow package installations and complex dependency management. Enter [uv](https://github.com/astral-sh/uv), a new package manager developed by [Astral](https://astral.sh/) (creators of [Ruff](https://astral.sh/ruff)) that's transforming how Python developers handle projects.

## What is uv?

uv is a super-fast Python package manager and project management tool that serves as a drop-in replacement for pip, but with dramatically enhanced capabilities.

At its core, uv addresses the fundamental pain points that have frustrated Python developers for years: slow installations, manual virtual environment management, and complex project setup processes.

## Key benefits of uv

### Speed and performance

The most striking feature of uv is its incredible speed. Where pip installations can take minutes, uv completes the same tasks in seconds:

* **Up to 100x faster** package installations compared to pip
* Near-instantaneous dependency resolution
* Dramatically reduced wait times for project setup

This speed improvement isn't marginal. Tasks that previously interrupted your development flow now happen so quickly they become seamless.

### Comprehensive project management

uv goes far beyond simple package installation. It provides a complete project management solution:

* **Automatic project initialization** with proper boilerplate structure
* **Built-in virtual environment management** with no manual activation required
* **Intelligent dependency tracking** that separates production and development packages
* **Python version management** without needing separate tools
* **Automatic `.gitignore` generation** with Python-specific excludes

### Simplified dependency management

uv also changes the way you handle dependencies:

* **Clean dependency lists**: Only direct dependencies appear in `pyproject.toml`
* **Easy package management**: Simple `uv add` and `uv remove` commands
* **Development dependencies**: Separate development packages with `--dev` flag
* **Automatic synchronization**: Team members can instantly replicate environments

## The new development workflow

uv transforms project setup from a multi-step manual process into a streamlined workflow:

### Traditional workflow pain points

```bash {filename="Terminal"} theme={null}
# The old way - multiple steps, slow process
mkdir new-project && cd new-project
python -m venv venv
source venv/bin/activate  # or venv\Scripts\activate on Windows
pip install package1 package2 package3
# Wait... and wait... for slow installations
pip freeze > requirements.txt
```

### The uv way

```bash {filename="Terminal"} theme={null}
# Initialize project with everything configured
uv init "new-ai-project"

cd "new-ai-project"

# Add dependencies instantly
uv add openai pydantic fastapi

# Add development tools separately
uv add ipykernel pytest --dev

# Run your code
uv run hello.py
```

This workflow reduces project setup time from minutes to approximately **15 seconds**.

## Essential uv commands

### Project initialization

```bash {filename="Terminal"} theme={null}
# Create new project with boilerplate
uv init "project-name"
```

This command automatically creates:

* Project directory structure
* `.gitignore` file with Python excludes
* `pyproject.toml` configuration
* Sample `hello.py` file
* README template
* Virtual environment

### Dependency management

```bash {filename="Terminal"} theme={null}
# Add production dependencies
uv add requests pandas numpy

# Add development dependencies  
uv add pytest black flake8 --dev

# Remove packages
uv remove pandas

# Sync environment from pyproject.toml
uv sync
```

### Running code

```bash {filename="Terminal"} theme={null}
# Execute Python files directly
uv run script.py

# Run with environment automatically activated
uv run python -m pytest
```

## Comparison with traditional tools

### uv vs pip

| Feature | pip | uv |
| - | - | - |
| **Installation Speed** | Slow (minutes) | Ultra-fast (seconds) |
| **Dependency Resolution** | Basic | Advanced |
| **Virtual Environments** | Manual management | Automatic |
| **Project Structure** | Manual setup | Auto-generated |
| **Clean Dependencies** | Bloated requirements.txt | Clean pyproject.toml |

### uv vs Poetry

While Poetry provides excellent dependency management, uv combines Poetry's capabilities with superior speed and simpler workflows. uv's faster installation and automatic environment handling make it more suitable for rapid development cycles.

### uv vs Pipenv

uv surpasses Pipenv in both speed and reliability. Where Pipenv sometimes struggles with dependency resolution, uv handles complex dependencies effortlessly while maintaining its performance advantage.

## Getting started with uv

### Installation

Choose your preferred installation method:

**macOS (recommended):**

```bash {filename="Terminal"} theme={null}
brew install uv
```

**macOS/Linux (curl):**

```bash {filename="Terminal"} theme={null}
curl -LsSf https://astral.sh/uv/install.sh | sh
```

**Windows:**
Follow the official installation guide at [docs.astral.sh/uv](https://docs.astral.sh/uv)

Verify installation:

```bash {filename="Terminal"} theme={null}
uv --help
```

### Migrating existing projects

uv maintains backward compatibility with existing Python projects:

**From requirements.txt:**

```bash {filename="Terminal"} theme={null}
uv pip install -r requirements.txt
```

**Convert to uv project:**

```bash {filename="Terminal"} theme={null}
uv init --existing-project
uv add $(cat requirements.txt | grep -v '^#' | tr '\n' ' ')
```

## Advanced features

### Python version management

uv can manage Python installations directly:

```bash {filename="Terminal"} theme={null}
# List available Python versions
uv python list

# Install specific Python version
uv python install 3.12

# Use specific version for project
uv init --python 3.12 my-project
```

### Team collaboration

uv makes team collaboration seamless:

1. **Share project**: Simply commit `pyproject.toml` to version control
2. **Setup for teammates**: `uv sync` creates identical environments instantly
3. **No configuration drift**: Locked dependencies ensure consistency

## Integration with development tools

uv works seamlessly with modern development environments:

* **IDEs**: VS Code, PyCharm, Cursor automatically detect uv environments
* **CI/CD**: Simple integration with GitHub Actions, GitLab CI
* **Docker**: Excellent containerization support
* **Version Control**: Clean `pyproject.toml` files work perfectly with Git

## Deploying Python applications with uv on Upsun

uv's speed advantages make it perfect for cloud deployments. Here's how to deploy Python applications using uv on Upsun's platform:

### Project structure

Your uv-based project should have this structure:

```bash {filename="Terminal"} theme={null}
my-python-app/
├── .upsun/
│   └── config.yaml
├── pyproject.toml  # Created by uv
├── main.py
└── src/
```

### Essential Upsun configuration

Create `.upsun/config.yaml` with uv-optimized settings:

```yaml {filename=".upsun/config.yaml"} theme={null}
applications:
  app:
    source:
      root: "/"
    
    type: "python:3.12"
    
    # Use uv for dependency management
    dependencies:
      python3:
        uv: "*"
    
    # uv build process
    hooks:
      build: |
        # Use uv for fast dependency installation
        uv sync --frozen
        
        # Optional: compile Python files for better performance
        # python -m compileall .
    
    # Web server configuration
    web:
      commands:
        # We add --no-sync to prevent uv from trying to write the uv.lock at runtime 
        start: "uv run --no-sync uvicorn app:app --reload --host 0.0.0.0 --port $PORT"
    
    # uv cache optimization
    variables:
      env:
        uv_CACHE_DIR: "/tmp/uv-cache"
        PYTHONPATH: "."

routes:
  "https://{default}/":
    type: upstream
    upstream: "app:http"
```

### Key configuration benefits

**Fast builds**: uv's speed dramatically reduces deployment time compared to pip-based builds.

**Dependency optimization**: The `uv sync --frozen` command ensures reproducible builds with locked dependencies.

**Cache efficiency**: uv's intelligent caching works perfectly with Upsun's build process.

### Deployment workflow

1. **Initialize your project locally:**

```bash {filename="Terminal"} theme={null}
uv init my-app
cd my-app
uv add fastapi gunicorn
```

2. **Create your application:**

```bash {filename="app.py"} theme={null}
# main.py
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"message": "Hello from uv on Upsun!"}
```

3. **Deploy to Upsun:**

```bash {filename="Terminal"} theme={null}
git add .
git commit -m "Setup FastAPI with uv"
upsun push
```

The uv-powered build process will install dependencies in seconds rather than minutes, making your deployment pipeline significantly faster.

<Note>**Compatibility**: Most Python packages work seamlessly with uv, but complex enterprise environments may require testing. </Note>

## Conclusion

uv transforms Python development from a series of manual, time-consuming tasks into a streamlined, efficient workflow. The dramatic speed improvements alone justify adoption, but uv's comprehensive project management capabilities make it essential for modern Python development.

The question isn't whether you should try uv, it's how quickly you can integrate it into your development workflow. With its backward compatibility, minimal learning curve, and transformative performance benefits, uv represents the future of Python package management.

**Ready to transform your Python workflow?** [Deploy your Python uv app on Upsun now](https://console.upsun.com/) and experience lightning-fast builds with uv's package management.


# Why setting your PHP memory limit to 60GB won't help
Source: https://developer.upsun.com/posts/insights/why-setting-your-php-memory-limit-to-60gb-wont-help

When you see a PHP memory limit error, your instinct shouldn't be to just increase the limit. Learn what PHP memory_limit actually does and why blindly increasing it can hurt your site's uptime.

<PostMeta />

You see this error in your logs:

```
PHP Fatal error: Allowed memory size of 134217728 bytes exhausted
```

You Google it. You check Stack Overflow. You ask an AI. The universal answer? "Just increase `memory_limit` in your php.ini."

But that's not always the right thing to do. In fact, it can actively hurt your site's uptime if you're not careful.

## What does PHP memory\_limit actually do?

The PHP memory limit (`memory_limit` in php.ini) is not about allocating resources to your application. It's a per-request safety cutoff. It kills individual requests that try to use too much memory.

On Upsun, the default is 128MB. That means if a single PHP request tries to use more than 128MB, PHP stops executing the script and logs that error you saw above.

This is a feature, not a bug.

## The PHP memory limit: quality of service, not a resource

Imagine you have 10 PHP-FPM workers running at 25-35MB each. Then a page comes in with a bug - someone wrote a loop that doesn't clear memory properly. That request starts consuming 200MB, 300MB, 500MB.

Without a memory limit, that single request could consume all available container memory, causing the Out Of Memory killer to randomly terminate processes. Data gets corrupted. Things don't shut down cleanly. Your site crashes unpredictably.

With a memory limit, that single buggy request gets killed. The other 9 workers keep running fine. You see an error in your logs telling you exactly which page caused the problem.

That's when you can fix it.

## Why you shouldn't be setting PHP memory\_limit to 60G

When you see that memory exhausted error, your instinct should not be to increase the limit, but to dig into the underlying code using that much memory.

There are use cases where it's justified to increase `memory_limit` - image processing, report generation, large data exports. But generally speaking, you don't want to run them on the web thread. And don't blindly increase it. Especially not beyond the container size.

Setting the memory limit higher than your container memory doesn't give you more memory. It removes the protection mechanism that prevents runaway requests from crashing your entire application.

If someone sets `memory_limit: 60G` on a container with only 512MB of RAM, they've removed the guardrail. Now a single buggy request can consume all 512MB of container memory, crash the entire container, and take the site down. The Out Of Memory killer will terminate random processes to try to reclaim memory, causing unpredictable failures and data corruption.

### Side note: crons and workers

Cron runs do not have a memory\_limit by default. But if your crons are using a lot of memory, they are probably going to run a lot better as a worker. See the [workers documentation](https://docs.upsun.com/create-apps/workers.html#workers-vs-cron-jobs) for more details.

## Best practices for memory-intensive tasks

Sometimes you legitimately need more memory for a specific operation - image resizing, report generation, large data exports.

Don't do this on the web thread. Use workers.

**Workers** (separate background processes):

* Spin up a dedicated worker for heavy tasks
* Set a higher memory limit on that specific worker
* Use a queue system (RabbitMQ, Redis, or even database-backed queues)
* Process tasks sequentially, not all at once
* Predictable memory usage, no spiky traffic

The entire industry invented workers to solve this problem: offload heavy, unpredictable tasks to a separate process where you can control resource usage explicitly.

## Keep your memory limit reasonable

The PHP `memory_limit` setting is a safety mechanism, not a resource allocation. It protects your application from catastrophic failures caused by runaway requests.

When you see a memory exhausted error, resist the temptation to just bump up the limit. Instead:

1. Investigate the code that's consuming excessive memory
2. Fix the underlying issue if it's a bug
3. Move legitimate memory-intensive operations to workers
4. Only increase the limit if absolutely necessary, and keep it well below your container's total memory

Your `memory_limit` should be set based on what a typical request reasonably needs - not the theoretical maximum your container can provide. A good rule of thumb: keep it under half your container's total memory to leave room for multiple concurrent requests.

And whatever you do, don't set your memory limit to 60GB.

## Ready to get started?

If you're dealing with 502 errors and worker exhaustion issues, check out our companion article: [When PHP-FPM Runs Out of Workers: A 502 Error Field Guide](/posts/how-it-works/when-php-fpm-runs-out-of-workers-a-502-error-field-guide).

Want to see how Upsun handles PHP-FPM configuration automatically? [Sign up for a free trial](https://upsun.com) and deploy your first project.


# Why you can't just add infinite PHP-FPM workers
Source: https://developer.upsun.com/posts/insights/why-you-cant-just-add-infinite-php-fpm-workers

Workers need memory. Learn how PHP-FPM sizing hints work, why you can't just add infinite workers, and how to tune your worker count based on actual memory usage.

<PostMeta />

After reading about [PHP-FPM worker exhaustion and 502 errors](/posts/how-it-works/when-php-fpm-runs-out-of-workers-a-502-error-field-guide), the obvious question is: why not add more workers?

If workers are like highway lanes, why don't we build highways with 20 lanes? Because lanes need space. They have to sit somewhere. For PHP-FPM workers, that space is measured in memory.

Here's the math: if each request needs 50MB of memory to process, and your container has 512MB of memory total, you can theoretically fit 10 workers (10 × 50MB = 500MB, with 12MB left over).

That's an oversimplification - nginx needs memory, SSH needs memory, the container itself needs overhead. But that's the basic constraint: workers consume memory, and you only have so much memory available.

## What Upsun does automatically

On Upsun, we calculate your worker count automatically using this formula:

```
worker_count = (container_memory - reserved_memory) / request_memory
```

For example, with a 256MB container using default settings (45MB request memory, 70MB reserved memory):

```
worker_count = (256 - 70) / 45 = 4.13 → 4 workers (rounded down, minimum 2)
```

With a 512MB container:

```
worker_count = (512 - 70) / 45 = 9.8 → 9 workers
```

You can see the full details in the [PHP-FPM documentation on Upsun docs](https://docs.upsun.com/languages/php/fpm.html).

The defaults (45MB request memory, 70MB reserved memory) work fine for most Drupal and WordPress sites. But they're not always right for your application.

## When the defaults don't fit

If you're running Magento, 45MB per request might not be enough - you're going to run out of container memory before you run out of workers. Your metrics will show 100% memory utilization and Out Of Memory kills.

If you're running a lightweight API, you might only need 4MB per request. The system is assuming 45MB, so you're underutilizing your memory and running fewer workers than you could support.

This is when you want to adjust sizing hints.

### Understanding sizing hints

Sizing hints are exactly that: hints. They're not limits or restrictions. They tell Upsun how to calculate the number of workers to allocate.

You configure them in your `.upsun/config.yaml`:

```yaml theme={null}
web:
  sizing_hints:
    request_memory: 45  # MB per request
    reserved_memory: 70 # MB reserved for non-worker processes
```

Here's the counterintuitive part: **you lower request memory to increase worker count**, because it's a division. If you set `request_memory: 35` instead of `45`, you get more workers for the same container size.

Some people get this backwards and think "more is better." It's not. Lower request memory tells the system "my requests are lighter, I can support more workers."

### Finding your actual memory usage

You can check how much memory your requests actually use by analyzing your PHP access logs:

```bash theme={null}
upsun log --lines 5000 php.access | awk '{print \$6}' | sort -n | uniq -c
```

This shows memory usage for each request. You'll see output like:

```
    342 2048
    856 4096
   1205 8192
    234 16384
     12 32768
```

Those numbers are in kilobytes. Most requests hover around the same range. Take a representative average and use that as your `request_memory` value (converted to MB).

This isn't an exact science. Not all requests use the same memory. Some take 40MB, some take 20MB, some take 100MB. You're not utilizing all workers at the same time. The goal is to find a reasonable average that keeps your memory utilization under 100% while maximizing worker availability.

### Tuning in small increments

If you decide to adjust sizing hints, do it gradually:

1. Start with your current value (default is 45MB)
2. Lower it by 10MB (to 35MB)
3. Check your metrics - are you still under 100% memory utilization?
4. Wait a day and verify the system is stable
5. If you need more workers, lower it another 10MB
6. Repeat until you find the right balance

If you go too low, you'll see high memory utilization in your metrics dashboard and potentially Out Of Memory kills in your logs. Back it off by 10MB and stabilize there.

Also watch your CPU usage. More workers mean more CPU load. Upsun's container profiles balance CPU and memory, so this usually isn't an issue if you're using the right profile. But if you're manually adjusting container resources, keep an eye on it.

### CPU limits and worker caps

To ensure that Upsun doesn't add more workers than the CPU can handle, a CPU limit applies as soon as the number of set workers equals or exceeds 25. This limit is calculated as: **number of vCPU cores × 5**.

For example, with 8 vCPUs, you can have a maximum of 40 workers (8 × 5 = 40) - even if you have enough memory to support more.

Why? Because the CPU has to switch between all these processes. If you give it too many workers, context switching overhead becomes a problem. When 8 vCPUs are juggling 40 different tasks (5 per vCPU), they're already working hard. Going beyond that makes things slower, not faster.

## Sizing hints vs memory limit

Let's clarify the difference between sizing hints and PHP memory limit, since they're often confused:

**Sizing hints** (`request_memory`, `reserved_memory`):

* Used to calculate worker count
* Not enforced as limits
* Hints for capacity planning
* Lower values = more workers allocated

**PHP memory limit**:

* Enforced per-request by PHP itself
* Kills requests that exceed the limit
* Protects the container from runaway processes
* Logs violations for debugging

If you set `request_memory: 45` but one request uses 50MB, nothing bad happens. The sizing hints are averages, not hard limits.

If you set `memory_limit: 128M` and a request tries to use 200MB, that request gets killed. See our article on [why you shouldn't set your PHP memory limit to 60GB](/posts/insights/why-setting-your-php-memory-limit-to-60gb-wont-help) for more details.

## Finding the right balance

When you understand what these settings actually do, you can tune them appropriately for your application. The goal is to find the sweet spot where:

* Your workers have enough memory to handle typical requests
* You have enough workers to handle concurrent traffic
* Your memory utilization stays under 100%
* Your CPU isn't overwhelmed by context switching

Start with the defaults, measure your actual usage, and adjust gradually. Don't try to optimize prematurely - let real-world traffic patterns guide your tuning.

## Ready to get started?

If you're dealing with 502 errors and worker exhaustion issues, check out our companion article: [When PHP-FPM Runs Out of Workers: A 502 Error Field Guide](/posts/how-it-works/when-php-fpm-runs-out-of-workers-a-502-error-field-guide).

Want to see how Upsun handles PHP-FPM configuration automatically? [Sign up for a free trial](https://upsun.com) and deploy your first project.


# Why you should replace PostgreSQL with Git for your next project
Source: https://developer.upsun.com/posts/insights/why-you-should-replace-postgresql-with-git-for-your-next-project

Explore how Git's internal architecture makes it a surprisingly capable database alternative. Learn Git's data structures through a practical todo app implementation that might make you reconsider your database choices.


<PostMeta />

Every developer knows the pain of choosing the right database for their project. PostgreSQL offers robust relational features, but what if there was a database you're already using every day that could handle your data storage needs?

Meet Git – the version control system that's been hiding its database capabilities in plain sight. Before you close this tab thinking we've lost our minds, consider this: Git provides built-in versioning, handles concurrent access, supports atomic transactions (commits), and offers lightning-fast data retrieval. It even comes with its own query language (Git commands) and built-in backup system (distributed repositories).

While this approach isn't suitable for production applications, exploring Git's internal architecture reveals fascinating insights into how modern databases work. Let's build a todo application using Git as our storage layer to understand these core concepts.

## Git's data model: The foundation

Git organizes data using four fundamental types:

* **Blobs**: Raw data storage (equivalent to table rows)
* **Trees**: Hierarchical organization (like directory structures)
* **Commits**: Transaction records with metadata
* **References**: Pointers to specific data states (like table indexes)

This structure makes Git more similar to hierarchical databases like Apache ZooKeeper than traditional relational systems. Let's experiment with these concepts by building our own "database".

## Setting up your Git database

```bash theme={null}
$ cd $(mktemp -d)
$ git init
```

### Working with blobs: Your data records

Blobs store raw data – think of them as individual database records. Unlike traditional databases, blobs are content-addressable, meaning their unique identifier is derived from their content.

Create a blob containing data:

```bash theme={null}
$ echo 'foo bar baz' | git hash-object -w --stdin
1aeaedbf4ee8dccec5bc2b1f1168efef19378ffd
```

Git stores this blob in its object database using the hash as the filename:

```bash theme={null}
$ ls -al .git/objects/1a/eaedbf4ee8dccec5bc2b1f1168efef19378ffd
-r--r--r-- 1 ralt ralt 26 Sep 22 10:38 .git/objects/1a/eaedbf4ee8dccec5bc2b1f1168efef19378ffd
```

The file contains compressed, binary data. Git provides tools to retrieve the original content:

```bash theme={null}
$ git cat-file -p 1aeaedbf4ee8dccec5bc2b1f1168efef19378ffd
foo bar baz
```

### Trees: Organizing your data structure

Trees group related blobs together, similar to how database tables organize related records. Create a tree by specifying which blobs it should contain:

```bash theme={null}
printf '100644 blob <hash>\t<filename>' | git mktree
```

Using our existing blob:

```bash theme={null}
$ printf '100644 blob 1aeaedbf4ee8dccec5bc2b1f1168efef19378ffd\tbody' | git mktree
d9d24a5d3ea8407a90f87b136283358e6ff30a87
```

Examine the tree structure:

```bash theme={null}
$ git cat-file -p d9d24a5d3ea8407a90f87b136283358e6ff30a87
100644 blob 1aeaedbf4ee8dccec5bc2b1f1168efef19378ffd	body
```

The tree now references our blob with a meaningful name.

### Commits: Transaction records with metadata

Commits wrap trees in transactional context, providing metadata about when and why changes occurred:

```bash theme={null}
git commit-tree [-p <parent>] -m 'message' <tree hash>
```

Create our first transaction record:

```bash theme={null}
$ git commit-tree -m 'first commit' d9d24a5d3ea8407a90f87b136283358e6ff30a87
ba4c8e52fb092cdb810c913004c82f6ae5eae4c9
```

Inspect the commit metadata:

```bash theme={null}
$ git cat-file -p ba4c8e52fb092cdb810c913004c82f6ae5eae4c9
tree d9d24a5d3ea8407a90f87b136283358e6ff30a87
author Florian Margaine <xxx@platform.sh> 1758530691 +0200
committer Florian Margaine <xxx@platform.sh> 1758530691 +0200

first commit
```

Commits automatically include comprehensive metadata:

* Tree reference (data snapshot)
* Author and committer information
* Timestamp for audit trails
* Descriptive message

### References: Making data discoverable

Without references, commits become "dangling" and get garbage collected. References act like database indexes, making specific data states discoverable:

```bash theme={null}
$ echo ba4c8e52fb092cdb810c913004c82f6ae5eae4c9 > .git/refs/heads/foo
```

This creates a "branch" reference pointing to our commit. Git uses different reference namespaces (`.git/refs/heads` for branches, `.git/refs/tags` for tags) similar to database schemas.

You can now query your "database":

```bash theme={null}
$ git log foo
commit ba4c8e52fb092cdb810c913004c82f6ae5eae4c9 (foo)
Author: Florian Margaine <xxx@platform.sh>
Date:   Mon Sep 22 10:44:51 2025 +0200

    first commit
```

## Building a todo application with Git

Now let's apply these concepts to build a functional todo application, demonstrating how Git's architecture compares to traditional database operations.

### Defining our data schema

Our todo application needs a simple data model:

* **Task Title**: The task description
* **Task Status**: Current state (todo/done)

Using Git's architecture, we'll store each field as a separate blob and organize them in trees, with commits representing state changes.

### Creating task data

Create blobs for task titles:

```bash theme={null}
$ echo 'I need to buy a car' | git hash-object -w --stdin
17fa051a3dd27c8e759b6eae068400b81e9279de
$ echo 'I need to sell my house' | git hash-object -w --stdin
831f49497c435f1e38765bc99bd015ec44ed436e
```

Create status value blobs:

```bash theme={null}
$ echo 'done' | git hash-object -w --stdin
19f86f493ab110b8dc8279a024880e44203968d8
$ echo 'todo' | git hash-object -w --stdin
258cd5725da9a125878490703e64117560b11872
```

### Organizing data with trees

Create a task record by combining title and status blobs in a tree:

```bash theme={null}
$ printf '100644 blob 17fa051a3dd27c8e759b6eae068400b81e9279de\ttitle
100644 blob 258cd5725da9a125878490703e64117560b11872\tstatus' | git mktree
b235f13ebd645de5c3dc87e2302ee81bfb77c70d
```

Verify the task structure:

```bash theme={null}
$ git cat-file -p b235f13ebd645de5c3dc87e2302ee81bfb77c70d
100644 blob 258cd5725da9a125878490703e64117560b11872	status
100644 blob 17fa051a3dd27c8e759b6eae068400b81e9279de	title
```

### Creating transactions with commits

Commit the task to create a permanent transaction record:

```bash theme={null}
$ git commit-tree -m 'Add first task: buy a car' b235f13ebd645de5c3dc87e2302ee81bfb77c70d
fcfe7e22edfe12170a48fd802580ebcb05e36d6c
```

Create a reference to make the data discoverable:

```bash theme={null}
$ echo fcfe7e22edfe12170a48fd802580ebcb05e36d6c > .git/refs/heads/todo-list
```

### Querying your Git database

View the complete transaction history:

```bash theme={null}
$ git log -p todo-list
commit fcfe7e22edfe12170a48fd802580ebcb05e36d6c (todo-list)
Author: Florian Margaine <xxx@platform.sh>
Date:   Mon Sep 22 11:04:16 2025 +0200

    Add first task: buy a car

diff --git a/status b/status
new file mode 100644
index 0000000..258cd57
--- /dev/null
+++ b/status
@@ -0,0 +1 @@
+todo
diff --git a/title b/title
new file mode 100644
index 0000000..17fa051
--- /dev/null
+++ b/title
@@ -0,0 +1 @@
+I need to buy a car
```

## Why Git makes sense for specific use cases

While this exploration started as a thought experiment, Git offers genuine advantages for certain applications:

* **Built-in audit trails**: Every change includes timestamp and author information
* **Atomic transactions**: Commits ensure data consistency
* **Distributed architecture**: Multiple nodes can sync data changes
* **Content addressing**: Automatic deduplication and integrity checking

## Real-world applications at Upsun

At Upsun, we leverage Git's database-like properties for specific scenarios where its strengths outweigh traditional database benefits. For developer-facing configuration management, Git provides:

* Automatic versioning for all configuration changes
* Distributed synchronization across development environments
* Native integration with existing developer workflows
* Built-in rollback capabilities through commit history

However, Git has significant limitations as a general-purpose database:

* Limited concurrent access (worse than SQLite)
* No complex query capabilities
* Poor performance with large datasets
* No built-in indexing for non-content searches

## Start building with proper databases on Upsun

While Git makes an interesting database alternative for specific use cases, your production applications deserve better. Upsun provides managed [PostgreSQL, MySQL, and other database services](https://docs.upsun.com/add-services.html) with:

* Automatic scaling and performance optimization
* Built-in backup and disaster recovery
* Multi-environment support for development and staging

[Create a free Upsun account](https://upsun.com/) to deploy your applications with proper database infrastructure that scales with your needs.


# AGENTS.md: Why your README matters more than AI configuration files
Source: https://developer.upsun.com/posts/insights/why-your-readme-matters-more-than-ai-configuration-files

AGENTS.md promises to standardize AI coding assistant configuration, but the real solution is writing better READMEs that serve both humans and AI agents

<PostMeta />

The `AGENTS.md` specification emerged in July 2025 as an attempt to solve a real problem: developers maintaining separate configuration files for each AI coding tool (`.cursorrules`, `.windsurfrules`, `CLAUDE.md`, and more). Created by Sourcegraph's Amp team, `AGENTS.md` promises "one file, any agent". A vendor-neutral standard to unify AI assistant configuration. But a surprising truth has emerged: **the proliferation of AI configuration files has inadvertently revealed that most projects have terrible documentation, and fixing your README is more important than adopting any new standard**.

<Note>Read the specification on [ampcode.com](https://agents.md/)</Note>

## The problem AGENTS.md tries to solve

As AI coding assistants proliferate, developers find themselves maintaining duplicate configuration files. GitHub Copilot wants `.github/copilot-instructions.md`, Claude needs `CLAUDE.md`, Cursor uses `.cursorrules`, each containing largely the same information. `AGENTS.md` proposes consolidating these into a single Markdown file that all tools can understand.

The specification defines a hierarchical system where files can exist at multiple levels (user, project, subdirectory), with more specific files overriding general ones. It includes an `@-mention` system for referencing external documentation and promises backward compatibility through symbolic linking.

Technically, it's well-designed. But it's solving the wrong problem.

## The real issue: your README was always inadequate

Here's what early AGENTS.md adopters discovered: **the content of a good AGENTS.md file looks exactly like the documentation that should have been in the README all along**. After explaining project context to AI agents 100 times, developers finally wrote the comprehensive documentation they'd been avoiding for years.

AI agents need the same context a human developer needs:

* Project architecture and structure
* Build and test commands
* Coding conventions and patterns
* Key design decisions
* Development workflow

**AI agents already read your README**. They don't need this information duplicated in `AGENTS.md`. What they need is for your `README` to actually be good.

## What really belongs in AGENTS.md

If you write a comprehensive `README`, `AGENTS.md` should be tiny - perhaps 20-30 lines containing only AI-specific operational details:

* CI/CD tools available in the agent's runtime environment
* Environment variables and secrets the agent can access
* Modified test commands for non-interactive execution
* Warnings about operations requiring human intervention
* Agent-specific API endpoints or service configurations
* **MCP (Model Context Protocol) server configurations** the agent can connect to and use
* Resource limits or permissions specific to MCP-connected services

For example, if your AI agent has access to MCP servers for PostgreSQL or GitHub integration, document those connection details in `AGENTS.md`, not how your database schema works (that's `README` content). The distinction is clear: MCP configuration is about what tools the AI can use, while your `README` explains what your project does and how it's built.

**If information would help a human developer, it belongs in the `README`, not `AGENTS.md`**. Duplicating your `README` content in `AGENTS.md` wastes context window tokens and creates maintenance burden.

## Potential security issues

Security researchers have identified ["Rules File Backdoor"](https://www.pillar.security/blog/new-vulnerability-in-github-copilot-and-cursor-how-hackers-can-weaponize-code-agents) attacks where malicious actors inject hidden instructions into `AGENTS.md` files using Unicode characters and evasion techniques. Since `AGENTS.md` content gets injected directly into system prompts, it creates an attack vector that works across different AI assistants. So be careful what you include in there. Don't copy paste rules without getting a good understanding at what you are doing.

The more comprehensive your `AGENTS.md` file, the larger your attack surface. Another reason to keep it minimal.

## Why the standards war doesn't matter

`AGENTS.md` now competes with [OpenAI's `AGENTS.md` format](https://agentsmd.net/), fragmenting the market it aimed to unify. But this misses the point entirely. **Good AI coding tools should let you configure which context file to read**. If your tool demands a specific filename with no configuration option, that's vendor lock-in, not standardization.

Tools that can't handle basic configuration like "read context from this file" are acting anti-competitively. Demand flexibility from your vendors instead of waiting for a universal standard that may never come.

## The practical approach for development teams

1. **Fix your `README` first**. If you're repeatedly explaining the same context to AI agents, your `README` is inadequate. A good `README` should enable any developer - human or AI - to understand and contribute to your project.

2. **Keep `AGENTS.md` minimal**. Include only truly AI-specific operational context. This typically means environment details, runtime configurations, and automation-specific commands.

3. **Treat both files as code**. Subject them to code review, security scanning, and version control. But prioritize `README` quality over configuration standardization.

## What this means for Upsun users

For teams deploying on Upsun, the Git-driven infrastructure approach already encourages good documentation practices. Your `.upsun/config.yaml` file define infrastructure as code, making it natural to document these choices in your README.

Focus on documenting:

* How your preview environments work
* Your multi-app architecture decisions
* Resource allocation strategies
* Environment-specific configurations

Let your AI agents learn from this documentation rather than maintaining separate configuration files. If you need `AGENTS.md`, use it only for platform-specific details like environment variables available during deployment or CLI commands specific to your Upsun setup.

## The bottom line

`AGENTS.md`'s greatest contribution isn't standardizing AI configuration, it's forcing developers to finally write decent documentation. The irony is striking: AI agents have done more to improve `README` quality in one year than decades of best practice guidelines.

**Your `README` should be your single source of truth for both humans and AI agents**. Write it well, and you'll need minimal AI-specific configuration regardless of which standard wins. The projects that succeed with AI assistance aren't those with the best `AGENTS.md` files - they're those with the best documentation, period.

The path forward is clear: invest in documentation quality first, treat configuration standards as secondary. Make your `README` genuinely useful. Use `AGENTS.md` or alternatives sparingly, only for operational details unique to automated agents. This approach delivers immediate value while sidestepping the standards war entirely.

After all, the same context an AI agent needs to understand your project is what a human developer needs. Get that right, and everything else becomes trivial.

***

**Ready to improve your development workflow?** Start with better documentation and let Upsun's preview environments help you test changes with confidence. Create your free account at [upsun.com](https://upsun.com) and see how good documentation combined with powerful deployment tools accelerates development.


# It's out of the Oven: Bun 1.0 support on Platform.sh
Source: https://developer.upsun.com/posts/releases/bun-support-is-here

Bun 1.0 support is now available on Platform.sh. Discover our comparison results against Yarn and how to test Bun 1.0 out for yourself in this article.

<PostMeta />

Today [Bun](https://bun.sh/) 1.0 is being announced—one of our friends in the ‘**.sh’** tld—so it’s an absolute pleasure
to share a small celebration and our first thoughts on this fully-baked runtime.

For those not in-the know Bun is an all-in-one JavaScript (JS) runtime and toolkit designed for speed; complete with a
bundler, test runner, and Node.js-compatible package manager. It’s written in Zig which is kind of the “other Rust” and
one of the cool new compiled languages that is getting some traction—with Bun helping it a lot in gaining legitimacy.
Bun’s server-side JavaScript ecosystem—of which Deno and Node.js are also a part of, runtimes which Bun has previously
compared itself to—is hugely active and feels like something new and exciting that we can’t wait to test.

In this article, we’ll take a look at Bun’s origins and what Bun 1.0 has to offer so without further ado, let’s get
started and cheers to [Jarred-Sumner](https://github.com/Jarred-Sumner), Bun’s author and maintainer, may Bun live
long and prosper!

## **In the beginning there was Rhino**

Even though Bun certainly feels new and exciting, did you know that server-side JS is actually a quarter century old
now? It has actually been a thing since 1997! And as many good things that have happened to the web: it started at
Mozilla with [Rhino](https://p-bakker.github.io/rhino/history.html). A JavaScript engine I’m all too familiar with.

Back in 2009 I was looking for a way to run some server-side JS for a particular project and after trying to get Rhino
to work and suffering quite a bit—at the time it was allergic to Java—I then discovered Node.js. And it was awesome.

It was version 0.1.x and even though everything broke with every release—I still remember with unease when `promises`
were removed—it was still an incredible, liberating experience to work with it. Being able to do cheap concurrency
without Netty or Erlang, which was exceedingly complex to run at the time, was a lifesaver.

In 2010, I had the pleasure of hosting Ryan Dahl, creator of Node.js, for [a talk in Paris](https://vimeo.com/13264164)
and I was enamored with his vision. This was a serious network developer that was used to writing high-performance
network daemons in C and his approach was nothing if not revolutionary. It was all about simple concurrency, not
tight-loop multi-core performance, sometimes simple abstractions win. And now Bun, in a way, is returning to these roots
and asking why can’t we have both with Bun 1.0?

**The results from testing Bun 1.0**

I tested out and compared Yarn and Bun 1.0 with a small project, and generated the following figures:

* Yarn install: first run: 2458 packages installed \[**209.15s**]
* Yarn install: second run: 2458 packages installed \[**161.90s**]
* Yarn install: third run: 2458 packages installed \[**62.90s**]
* Bun install: first run: 2458 packages installed \[**71.53s**]
* Bun install: second run : 2458 packages installed \[**37.65s**]
* Bun install: third run : 2458 packages installed \[**14.64s**]

So it seems that **Bun 1.0 is 3x faster than Yarn, and even more with caching**. Sweet!

### **Where to host Bun?**

You can host your Bun application on Platform.sh at Bun 1.0 as our Node.js images now carry it—no install needed. In
your `.platform.app.yaml` simply:

```yaml {filename=".platform.app.yaml"} theme={null}
# choose nodejs version 20 or above
    type: 'nodejs:20'
    # override the default nodejs build flavor
    build:
    	flavor: none
    # use bun to install the dependencies
    hooks:
    	build: bun install
    # In the start command replace node with bun
    web:
    	commands:
    		start:'bun app.js'
```

Copy the snippet\
And that’s it, happy testing everyone!


# One project, many needs: How Composable Image embraces real-world diversity
Source: https://developer.upsun.com/posts/releases/composable-image-embraces-real-world-diversity



<PostMeta />

Applications rarely fit inside a single tidy runtime box. They evolve through experiments, architectural shifts, quick MVP spikes that outlast their intended lifespan, and the continuous layering of new business needs.

The result? Most apps are **hybrids**, part PHP or Node, part Python, part “we need this binary to generate PDFs,” part “our frontend is static but built with three tools,” and part “this tiny script powers an entire workflow.”

This is the reality we developers live in today. And this is exactly the reality that Composable Image was designed for.

Composable Image, now fully GA, offers a simple promise:

**Build exactly the environment you need: no more, no less, without the complexity of custom Dockerfiles or the limitations of single-runtime images.**

Let’s explore the three main patterns where Composable Image shines and why it’s becoming the preferred choice for modern Upsun applications.

## 1. Multiple runtimes in the same application container

This is the most common and most transformative use case.

Apps today routinely combine a primary runtime with secondary ones. A PHP application with a Node build toolchain. A Node backend enriched with a Python script for ML preprocessing. A Python API that relies on Ruby or Go utilities for legacy workflows.

Composable Image makes these multi-runtime setups **declarative, predictable, and frictionless**:

<Warning>
  **Important: Keep your Nix channel up to date**

  Nix releases new channels twice a year, and only the current channel receives active support and security updates. When a new channel is released, the previous one is immediately deprecated.

  Always verify you're using a [currently supported Nix channel](https://docs.upsun.com/create-apps/app-reference/composable-image.html#supported-nix-channels) before deploying or updating your configuration.
</Warning>

```yaml {filename=".upsun/config.yaml"} theme={null}
type: "composable:25.11"
stack:
  runtimes:
    - "php@8.4"
    - "nodejs@24"
    - "python@3.13"
  packages:
    - yarn
    - python313Packages.yq
    - python313Packages.jupyterlab
    - package: wkhtmltopdf
      channel: unstable

```

**No Dockerfile**.<br />\
**No multi-stage build arcana**.<br />\
**No risk of environment drift** between development, CI, and production.

The first declared runtime is the primary one; all are available inside your container. Each runtime is built in isolation, ensuring there are **no hidden system dependencies** and **no side effects**.

This solves one of the biggest pains of modern app development: your environment finally reflects the *actual* complexity of your app, without compromising clarity.

## 2. Zero runtimes for pure static applications

Not every project needs PHP, Node, Python, or any interpreter. Some applications are simply **static sites**, a collection of HTML, CSS, JS, and assets that don’t require a runtime to execute.

Composable Image supports these projects cleanly: you can deploy a fully static site with **no runtime declared at all**.

```yaml {filename=".upsun/config.yaml"} theme={null}
type: "composable:25.11"
stack: []
```

For many teams, that’s all they need: a fast, predictable deployment of static assets.

But even static applications sometimes rely on **non-runtime build tools** during the build phase. Not full programming languages, just command-line utilities powered by Nix packages. For example:

* `html-tidy` for HTML cleanup
* `jpegoptim` or `pngquant` for image compression
* `curl` or `jq` for fetching and massaging external data

```yaml {filename=".upsun/config.yaml"} theme={null}
type: "composable:25.11"
stack:
  runtimes: []
  packages:
    - html-tidy
    - pngquant
    - jpegoptim
    - curl
    - jq
```

No interpreters.\
No language runtime.\
Just the utilities your static project requires, nothing more.

Behind the scenes, Nix provides each tool in isolation, with no hidden dependencies and no risk of drift across environments. This gives static projects the same benefits as complex apps: **reproducibility, clarity, and control**, with an absolute minimum footprint.

## 3. Local env setup

Below is a beginner-friendly, **step-by-step tutorial** (no flakes) to install Nix locally and reproduce your Upsun toolchain **(curl, jq, tidy, pngquant, jpegoptim, html-tidy)**.

### 3.1 Install Nix

The most reliable installer is Determinate Systems is to run:

```bash {filename="Terminal"} theme={null}
curl -L https://install.determinate.systems/nix | sh -s -- install |
```

When it finishes, **close your terminal and open a new one**, you can verify the installation:

```bash {filename="Terminal"} theme={null}
nix --version 
```

### 3.2 Create a project folder (or go to your repo)

Go to the repository where you want the tools available:

```bash {filename="Terminal"} theme={null}
cd /path/to/your/repo 
```

### 3.3 Create a `shell.nix` file (no flakes)

Create a file named `shell.nix` at the root of your repo:

```bash {filename="Terminal"} theme={null}

cat > shell.nix <<'EOF'
let
  # Pin nixpkgs for reproducible installs
  nixpkgs=builtins.fetchTarball{ url="https://releases.nixos.org/nixos/25.11/nixexprs.tar.xz"; };
  pkgs = import nixpkgs {};
in
pkgs.mkShell {
  packages = with pkgs; [
    curl jq html-tidy pngquant jpegoptim
  ];
}
EOF
```

<Note>
  **Note**: you can add in this packages list any useful package you want to install from [https://search.nixos.org/packages](https://search.nixos.org/packages)
</Note>

### 3.4 Enter the Nix environment

From the repo directory, run:

```bash {filename="Terminal"} theme={null}
nix-shell
```

This drops you into a shell where the tools are available (without installing them globally on your system).

### 3.5 Verify the tools

Still inside `nix-shell`, run:

```bash {filename="Terminal"} theme={null}
tidy -v
pngquant --version
jpegoptim --version
curl --version | head -n 1
jq --version
```

If all commands respond, you’re good.

### 3.6 Use the tools (example commands)

Inside `nix-shell`, you can use:

HTML tidy:

```bash {filename="Terminal"} theme={null}
tidy -q -e index.html
```

Optimize PNG:

```bash {filename="Terminal"} theme={null}
pngquant --force --output image.png --quality=65-80 image.png
```

Optimize JPEG:

```bash {filename="Terminal"} theme={null}
jpegoptim --strip-all --max=85 photo.jpg
```

### 3.7 Exit the environment

When you’re done:

```bash {filename="Terminal"} theme={null}
exit
```

## 4. Embedding specific or niche packages and binaries

Every app eventually hits the need for “that one CLI tool”:

* `wkhtmltopdf` for invoices
* `ffmpeg` for videos
* `ghostscript` for documents
* `imagemagick` for media processing
* a low-level CLI for LDAP, or cryptographic utilities
* even niche or experimental packages from the Nix ecosystem

Traditionally, this meant custom Dockerfiles, artisanal system package installs, or awkward workarounds.

With Composable Image, adding such dependencies is trivial:

```yaml {filename=".upsun/config.yaml"} theme={null}
type: "composable:25.11"
stack:
  packages:
    - wkhtmltopdf
    - ffmpeg
    - ghostscript
```

Need the very last version available on Nix? Also trivial:

```yaml {filename=".upsun/config.yaml"} theme={null}
type: "composable:25.11"
stack:
  packages:
    - package: jupyterlab
      channel: unstable
```

Because Upsun’s Composable Image is built on Nix, **each package is isolated and reproducible**. There are no hidden dependencies, no unexpected version conflicts, and no surprises at runtime.

You get the tools you need, exactly as you declared them, clean, explicit, and portable.

## Why This Matters: Clarity, Control, Confidence

Composable Image is not just a feature. It’s a shift in how developers think about application environments:

**Clarity:** Your entire environment is visible in a single `config.yaml`. No more guessing what’s inside your container.

**Control**: You decide which runtimes, versions, binaries, and extensions your app needs. Upsun simply builds it for you.

**Confidence**: Thanks to Upsun’s reproducible build model, what you declare runs exactly as you expect, in dev and in production.

## **Limitations and Responsibilities**

Composable Image offers a high degree of flexibility and control. But, as with any powerful tool, it also comes with responsibilities that teams should be aware of.

### Nix channels evolve quickly.

Composable Image relies on a single Nix channel per version. When a new channel is released, the previous one enters deprecation and is eventually decommissioned. This means teams using Composable Image must **monitor new Nix channel releases** and update their configuration accordingly.

Upsun ensures new channels are supported shortly after their official release, but the update action remains on the project owner’s side.

### Deprecated channels stop receiving updates.

Once a Nix channel is deprecated, its packages may no longer receive feature updates or security patches from upstream maintainers. Staying on an outdated channel exposes applications to potential security risks or missing improvements.

Regularly upgrading to the latest channel ensures your application benefits from the newest features and safest versions of your dependencies.

### More flexibility means more maintenance.

Unlike Single Runtime images, where Upsun fully manages runtime updates, security patches, and version lifecycles, Composable Image gives you the keys to your environment.

The trade-off is that **you must track and maintain the versions you declare**. If you need an environment that updates itself seamlessly without configuration changes, Single Runtime images may still be the best option.

In short:

**Composable Image gives teams maximum control, but with great power comes the responsibility to keep configurations up to date and secure.**

## A platform built for real applications

Composable Image embraces the diversity that naturally emerges in real-world projects.

It acknowledges that applications evolve, stacks grow, and tools accumulate, and instead of forcing developers into rigid constraints, it empowers them to shape their environment as needed, with clarity and predictability.

Whether you’re running multiple runtimes, deploying a lightweight static site, or adding niche packages to power specialized features, Composable Image gives you the flexibility you need without compromising simplicity.

**Your application is unique.**

**Now your runtime can be, too.**


# Composer 2.9 lands on Upsun PHP Images: Here’s what you need to know
Source: https://developer.upsun.com/posts/releases/composer-2.9

Remote code execution vulnerability in Next.js 15.x and 16.x App Router requires immediate patching. Learn how to secure your applications.

<PostMeta />

[Composer](https://getcomposer.org/) just shipped one of its most meaningful improvements in years: **automatic blocking of insecure and vulnerable PHP dependencies**.

This is great news for the PHP ecosystem. It’s also something you’ll want to understand before your next deploy suddenly stops mid-build, shouting about abandoned packages you forgot existed. (It happens to the best of us.)

Here’s the full breakdown.

## **What Changed in Composer 2.9?**

Composer 2.9 introduces [**Automatic Security Blocking**](https://blog.packagist.com/composer-2-9/). When installing without a `composer.lock` file, or updating dependencies, Composer now:

* Fails the build if a dependency has a known security advisory
* Can fail if a dependency is abandoned (optional, but available … and recommended)
* Provides a clear audit report of what’s wrong

This behaviour is **on by default**. Upsun doesn’t override it, because it makes everyone safer.

## **“But I didn’t change my dependencies… why is my build failing now?”**

Two reasons:

### 1. Your config file requires Composer 2 latest version.

A rebuild may pick up the latest version of Composer even if you’re still on the same PHP version. Boom: your dependencies are audited automatically. And, that’s great news!

### 2. Vulnerabilities are published continuously

Your dependencies might have been “fine” yesterday but vulnerable today. Composer 2.9 is simply letting you know about problems that already existed.

## **Why we ship Composer 2.9 as-is**

Short answer: because it’s good for you.

Longer answer:

* It prevents vulnerable or abandoned packages from silently entering your production chain.
* It pushes the ecosystem toward more secure baselines.
* Many users *want* this protection; they rely on it.

So instead of turning the feature off, we’re giving you the tools to use it effectively.

## **Your options if your build fails**

Let’s be straight: **The best fix is to patch or upgrade the affected dependencies.**

This is the healthiest thing you can do for your codebase, your users, and your future self. But you do have escape hatches.

### 1. Ignore specific advisories

```yaml {filename=".upsun/config.yaml (Upsun Flex) or .platform.app.yaml (Upsun Fixed)"} theme={null}
dependencies:
  php:
    config:
      audit:
        ignore:
          - "PKSA-yhcn-xrg3-68b1"
          - "PKSA-2wrf-1mxk-1pky"
```

### 2. Disable automatic blocking (not recommended, but available)

```yaml {filename=".upsun/config.yaml (Upsun Flex) or .platform.app.yaml (Upsun Fixed)"} theme={null}
dependencies:
  php:
    config:
      audit:
        block-insecure: false
```

### 3. Ignore vulnerabilities based on their severity rating (low/medium/high)

```yaml {filename=".upsun/config.yaml (Upsun Flex) or .platform.app.yaml (Upsun Fixed)"} theme={null}
dependencies:
  php:
    config:
      audit:
        ignore-severity:
           low:
             apply: all <-- ignore all low severity findings
```

## How Upsun handles Composer

A common question is whether you can revert to an older Composer version to avoid these checks.

### The Build process “catch-22”

Every Upsun PHP image includes a pre-installed, global Composer binary. Currently, this is version 2.9 or newer, which orchestrates your entire build:

* The pre-installed global binary (always the latest Composer version available) is what initiates your build process.
* Because this global binary is version 2.9+, it automatically performs a security audit before executing any other commands.
* Even if you specify an older Composer version in your dependencies block, that version is installed by the global 2.9 binary.
* The result: The security audit triggers and fails the build before your requested older version is even downloaded.

### The Solution

Since you cannot bypass the global binary, you should not attempt to downgrade the tool. Instead, use the `audit` configuration to ignore specific IDs or severities.
The most robust long-term solution remains keeping your dependencies updated and secure.

## **A gentle nudge: Keep those dependencies fresh**

Security blocking may feel strict at first, but here’s the upside:

* You learn about vulnerabilities early, before they sneak into production.
* Your app becomes more resilient.
* Your future upgrades stop being archaeology expeditions.

In other words: **modernizing your dependencies regularly is now a power move, not a chore**.

Composer 2.9 also allows you to block abandoned packages. Go the extra mile and secure your PHP apps' future.

```yaml {filename=".upsun/config.yaml (Upsun Flex) or .platform.app.yaml (Upsun Fixed)"} theme={null}
dependencies:
  php:
    config:
      audit:
        block-insecure: true
        block-abandoned: true
```

## **What you should do today**

* Run `composer audit` locally to see what’s coming.
* Review your project’s dependency tree (yes, even the old stuff).
* Decide whether to upgrade, ignore advisories, or temporarily opt out.

And remember: your next deployment might use Composer 2.9 unless you pin it explicitly.

## **If you need help, we’re here!**

Hit us up on the [community forum](https://community.upsun.com/) or open a [support ticket](https://docs.upsun.com/learn/overview/get-support.html). We want this transition to be smooth, and this feature actually makes your apps safer and easier to maintain in the long term.

And hey: if this blog post saved you an afternoon of head-scratching, go upgrade a dependency today. Your future deployments will thank you.


# Context driven navigation
Source: https://developer.upsun.com/posts/releases/context-driven-navigation



<PostMeta />

You may have noticed some changes to navigation and user settings on your Platform.sh dashboard.
That’s because we’ve been listening!
Our product design team has taken stock of all the feedback you’ve shared about our navigation over the years.
And together, we’re creating a better user experience as we scale.

More recently, we’ve needed to introduce new organization settings pages for user management, teams, and security—but where could we fit them?
Instead of crowding the existing user widget further, we thought it was time to implement your feedback and improve the overall navigation experience.

## What we've heard

1. That it’s difficult to find and change the organization you’re working in. Why? We used to have an organization picker at the top left, beside our logo, and our organization settings pages in the user widget.
2. When we moved the organization settings pages to our user widget dropdown (along with a range of other profile settings pages), it became more difficult to find.

## Here's what we changed

### Organization picker

<img alt="Organization picker. Found in the upper left-hand corner to the Upsun Management Console." />

We’ve combined organization selection and organization settings into one dropdown menu, located at the top left of your header bar.
Now you can create a new organization, toggle between organizations, and access organization settings from the same dropdown menu.

We also wanted to provide users with one-click access to the following pages (depending on your permissions):

* Projects
* Settings
* Billing
* Security
* Teams
* Users
* Invite a new user

### Organization selection

After we shipped our new organization picker, we heard this from you:

> By listing organizations in the order they were added—rather than most frequently used or most recently used—users often had to scroll through every organization to get to the one they needed most.

But don’t worry; we listened.
Now, by default, users are sent back to their most recently active organization.
Just sign in and get straight back to work!

We also leave the org picker open after you select a new one, in case you want to access a settings page in that new organization.
Once you’ve made a selection, the org picker closes, and you can also close it by clicking outside of the dropdown.

### User widget

<img alt="Updated User widget options. Found in the upper right-hand corner to the Upsun Management Console." />

Along with the latest improvements to our organization picker, we’re taking the opportunity to make your user widget even better, too.
Now, **My profile** page links are accessible directly from the user widget.
Previously, you had to navigate to the **My profile** page to get these links; this change makes it much easier.

Plus, due to high demand from our developers, it’s now easier than ever to change the console theme between light, dark, and WCAG accessibility mode ;)
You can thank them for that!

Your updated user widget now features all of the following links, so you can access them with one click:

* My profile
* Connected accounts
* Authentication
* API tokens
* SSH keys
* Theme selection

And that’s not all!

### New help dropdown

<img alt="Help dropdown. Found in the upper right-hand corner to the Upsun Management Console." />

With all of the changes to your navigation, we wanted to ensure you have easier access to the pages that matter most when you’re stuck and needing a hand.
That’s why we’ve also created a new **Help** dropdown linking directly to:

* [Documentation](https://docs.upsun.com)
* Support
* Our [community forum](https://community.upsun.com/), where you can chat with members of our team and other Upsun users for support and ideas
* [Submit an idea](https://next.platform.sh/tabs/4-under-development/submit-idea), to share product ideas with us directly

## What do you think of these updates?

We hope these updates have improved your navigation experience with Upsun!
Each update has been designed to provide you with more direct pathways to support, your profile pages, and to your organization settings pages.
We’re always listening to our users, so please don’t hesitate to [share your feedback or submit an idea](https://next.platform.sh/tabs/4-under-development/submit-idea)!
Our user experience team is here to continuously improve your product experience.


# Continuous profiling comparisons
Source: https://developer.upsun.com/posts/releases/continuous-profiling-comparisons

Upsun’s new continuous profiling comparisons feature provides deeper insights into application performance, enabling you to easily contrast performance metrics over time or between code versions. 


<PostMeta />

Introducing comparisons—a new feature in continuous profiling that helps you gain deeper insights into application performance by effortlessly contrasting performance metrics over time or between code versions. Quickly identify regressions, optimize application performance, and accelerate development cycles. Empower your team to make data-driven decisions. And with unparalleled visibility, deliver faster, more efficient software.

We’ve also added support for [Rust](https://docs.upsun.com/increase-observability/application-metrics/rust.html) and [Ruby](https://docs.upsun.com/increase-observability/application-metrics/ruby.html) applications to our continuous profiling toolkit.

## How it works

The comparisons feature enhances our continuous profiling capabilities by adding a *Compare* toggle to the dashboard. When activated, the dashboard switches to a comparison view mode that displays two time-frame windows (A and B) side by side. This dual view enables you to compare performance metrics between two different periods on the line graph directly.

<img alt="Continuous profiling comparisons" />

### Key benefits

* **Contrast performance across time periods.** Quickly identify performance changes by viewing two time frames simultaneously.
* **Gain enhanced insights through comparative analysis.** Dive deeper into your data to uncover trends, anomalies, or regressions.
* **Enable data-driven optimization.** Use comparative insights to make informed decisions to optimize your applications.

The comparisons feature enriches continuous profiling by providing tools that help you troubleshoot more effectively.

Here are some possible use cases:

* **Version comparisons or feature-impact analysis.** With the *Deployment* toggle, overlay deployment activities on the line graph to contrast the before-and-after effects of code changes or new app versions. This enables you to identify performance improvements or regressions.
* **Time-based analysis.** Compare profiles from different periods to investigate performance fluctuations over time. For example, peak traffic periods versus lulls can be analyzed to optimize resource allocation.

## Rust and Ruby support

We’ve expanded language support by adding continuous profiling for Rust and Ruby applications to current support for Go, Node.js, PHP, and Python. This enables developers working in Rust and Ruby to leverage our profiling tools for enhanced performance monitoring.

## New capabilities, no new costs

The new comparisons feature and language support for Ruby and Rust are free of additional costs. These enhancements continue our commitment to providing valuable tools that improve your experience and make your life easier.

## Get started

Our team is excited for you to explore these new features to see how they can benefit your development and optimization processes. For more information, dive into these support resources:

* [Comparisons feature documentation](https://docs.upsun.com/increase-observability/application-metrics/cont-prof-comparison.html)
* Continuous profiling for [Rust](https://docs.upsun.com/increase-observability/application-metrics/rust.html) and [Ruby](https://docs.upsun.com/increase-observability/application-metrics/ruby.html)


# Platform.sh–deploying the future of content with one click
Source: https://developer.upsun.com/posts/releases/deploy-strapi-on-platformsh

Platform.sh and Strapi empower developers with a headless CMS solution for streamlined digital experiences. Deploy Strapi instantly. Learn more

<PostMeta />

<Tip>
  This post was originally published on the Platform.sh blog and reflects information from the time of publication.
</Tip>

## Platform.sh enables developers to launch Strapi, the leading open-source headless CMS

Developers and content editors are faced with a choice: either invest time in configuring, running, and securing the tools they use to power digital experiences, or spend time actually building those experiences that engage users and drive revenue. Now, with the combination of [Platform.sh](/) and [Strapi](https://strapi.io), they no longer have to choose between building infrastructure and creating value.

Strapi gives developers a robust API to power anything from websites to apps to set-top boxes with an extensible, editor-friendly content management system (CMS) interface. Platform.sh now enables Strapi to deploy new, headless CMS instances on demand, with zero infrastructure investment.

## Why open-source headless CMS is the future of digital experience

Digital experience is no longer monolithic. To reach users where they are, developers need a CMS that can deliver to a wide range of channels and devices. Legacy CMS platforms force developers to use a single stack that locks the end-user and administrator interfaces together rigidly.

> “Strapi decouples CMS from the presentation layer,” said Chris Yates, VP of marketing, Platform.sh. “This provides a ‘headless’ content distribution platform (driven by APIs and technologies like GraphQL) that developers can easily integrate with a variety of front-end tools. Strapi is also open source, meaning developers can augment and extend its capabilities on their own and benefit from the contributions of an active community.”

## Running software instead of managing infrastructure and DevOps

Platform.sh and Strapi share a critical belief: that developers should be able to focus on creating value, rather than on tedious tasks like patching software, running infrastructure, and maintaining DevOps processes. Platform.sh provides an end-to-end Platform-as-a-Service that enables developers to drop in their applications and run them at scale with governance and security.

Platform.sh supports a range of programming languages—eight in all—from [Node.js](https://upsun.com/nodejs/) to [PHP](https://upsun.com/php/) to [Java](https://upsun.com/java/). It also offers a “batteries included” approach to infrastructure, including databases, networking, and storage, where services are defined as code and are deployed in moments in secure containers. Platform.sh provides all this without the expense and complexity of tools like Kubernetes or the investment of DIY solutions on public cloud providers.

## Deploying software in moments with the click of a button

> “The ability of Platform.sh to deploy and manage polyglot applications at scale gives companies like Strapi the ability to focus on their core business rather than investing in complex infrastructure to build a SaaS,” said Victor Coisne, VP of marketing, Strapi. “Now, with a click of a [Deploy on Platform.sh button](https://upsun.com/product/), a Strapi prospect or customer can get a new instance of Strapi in a few moments in whatever region (US, Canada, Australia, Ireland, Germany, UK, or France) and cloud (AWS, Google Cloud, Microsoft Azure) they choose. Almost instantly, they can be working within Strapi’s administrative tools to build their own content API.”

Try Strapi now on Platform.sh:

[<img alt="Deploy with Platform.sh" />](https://console.platform.sh/projects/create-project/?template=https://raw.githubusercontent.com/platformsh/template-builder/master/templates/strapi/.platform.template.yaml)

## About Platform.sh

Platform.sh is the end-to-end web platform for agile teams. It enables organizations to build, evolve, and scale their website fleet—with zero infrastructure management investment. Platform.sh includes application hosting, CI/CD, automated updates, global 24x7 support. And much more. Organizations like Hachette, the University of Missouri, Unity, and the world’s largest consumer products companies rely on Platform.sh to operate their website fleets.

## Contacts

For Platform.sh:

Worldwide: Ed Zitron
[ed@ezpr.com](mailto:ed@ezpr.com)

France:
Pierre Gatey
[pierre@agenceraoul.com](mailto:pierre@agenceraoul.com)


# Deploy with PHP 7.3 this Friday, er, Thursday
Source: https://developer.upsun.com/posts/releases/deploy-with-php-73-this-friday-er-thursday

Platform.sh welcomes PHP 7.3! Explore the latest features and performance improvements. Upgrade your application with a simple YAML tweak.

<PostMeta />

<Tip>
  This post was originally published on the Platform.sh blog and reflects information from the time of publication.
</Tip>

PHP continues its steady march forward, and today marks the release of the latest version, [PHP 7.3](https://php.net/releases/7_3_0.php).

It also marks its release on Platform.sh, and our first holiday gift to you this season.

## So what's new?

PHP 7.3 brings continued incremental performance improvements to the language. It's not as big as the jump to 7.0 was (few things can be), but the same code running under PHP 7.3 should be a bit faster than on 7.2.

While there's no earth-shattering additions in this version, there are a few nice pluses. Like a handful of new utility functions, such as `is_countable()`, `array_key_first()`, and `array_key_last()` (all of which are fairly self-explanatory). What's most exciting for language nerds that follow PHP's development (like yours truly)? Trailing commas in function calls are now legal, just as they have been on array definitions for years; Heredoc and Nowdoc syntax are now also more forgiving, allowing for more nicely formatted, multiline strings; the JSON utilities can now be set to throw exceptions, like most newer functionality, allowing error handling to be more consistent throughout the application.

OK, it's not going to change the world, but it's still nice.

There are also a number of deprecations around edge cases to flag behaviors that are expected to go away in PHP 8.0. (Yes, we did just say that number.) See the [Changelog](https://php.net/ChangeLog-7.php) for the full list of changes and fixes.

## Cool, so how do I do it?

As always at Platform.sh, it's just a YAML tweak away. In your `.platform.app.yaml` file (not on the master branch), change your application `type` to `php:7.3`, like so:

```
type: php:7.3
```

That's it. When next you push on that branch, you'll get the PHP 7.3 container. Test it out, and make sure everything is working (it should be fine), then merge back to master when you're ready.

Enjoy the latest and greatest PHP has to offer—any day of the week!


# Deploy your Python 3.7 code to the Moon
Source: https://developer.upsun.com/posts/releases/deploy-your-python-37-code-to-the-moon

Platform.sh now supports Python 3.7. Explore the latest features and enhancements. Update your .platform.app.yaml file and enjoy Python 3.7!

<PostMeta />

<Tip>
  This post was originally published on the Platform.sh blog and reflects information from the time of publication.
</Tip>

Python is one of the most popular programming languages of the last decade (*[hey most of Platform.sh is written in Python](https://upsun.com/jobs/)!*). It doesn't matter if you do data science, develop a video game or you just need to write a quick-and-dirty script. Python will always serve you well. This multi purpose language is also a big player in the world of web development and that's why the batteries included infrastructure for building and deploying your Python projects is available on Platform.sh, and we've just added Python 3.7 to the list of supported versions.

### **What's new in 3.7?**

The latest major release of the language introduces many cool new features. In case you are bored of writing `self.attribute = attribute` in your `__init__` methods all the time, you might like Data classes, documented in[ PEP 557](https://www.python.org/dev/peps/pep-0557/). Class definition and creation of the object, storing a bunch of data can be really easy now:

from dataclasses import dataclass

@dataclass\
class C:\
i: int\
j: int = None\
database: InitVar\[DatabaseType] = None

def **post\_init**(self, database):\
if self.j is None and database is not None:\
self.j = database.lookup('j')

c = C(10, database=my\_database)

Note the types are just documentation. They aren’t examined at runtime.

Another visible change is the new `breakpoint()` built-in function, which makes debugging your code smoother. It can be put anywhere in the code instead of `import pdb; pdb.set_trace()` line. The main benefit of `breakpoint()` is that it is configurable via the `PYTHONBREAKPOINT` environment variable. You can simply ignore all the `breakpoint()` calls in your code by setting its value to zero:

\$ PYTHONBREAKPOINT=0 python3.7 script.py

or switch to use a debugger of your choice instead of the default [PDB](https://docs.python.org/3.7/library/pdb.html):

\$ PYTHONBREAKPOINT=pudb.set\_trace python3.7 script.py

The [asyncio](https://docs.python.org/3/library/asyncio.html) standard library module has received many new features too. For example the new `asyncio.run()` function removes the burden of creating the event loop explicitly. Creating a trivial coroutine is now as simple as this:

```python theme={null}
import asyncio


async def hello_world():
    print("Hello World!")

asyncio.run(hello_world())
```

Python 3.7 brings also performance improvement, higher precision timing functions, typing enhancements and much more features and fixes, take a look at the[ official documentation](https://docs.python.org/3.7/whatsnew/3.7.html) for the complete list. Be aware that Python 3.7 final was released upstream only a couple of months ago and older versions of some Python libraries and frameworks like [Django](https://www.djangoproject.com/) \< 2.0, [gevent](https://www.gevent.org/index.html) \< 1.3.6 are not fully compatible with the latest Python version.

### **PIP 18.0**

The brand new pip 18.0 is coming to Platform.sh alongside new the Python release! Version number might be a bit surprising. We all remember using pip version 9 or 10 recently. Pip development team have switched to a Calendar based versioning scheme. This is not the only thing that changed. Support for packages specifying build system requirements in `pyproject.toml` file, aka [PEP 518](https://www.python.org/dev/peps/pep-0518/) was introduced in version 10 and improved in the latest release. Last two releases contains also a plenty of fixes, see the [relase notes](https://pip.pypa.io/en/stable/news/) for more information.

### **Try it out!**

Are you thrilled to try all these great features yourself? You can do so on Platform.sh! The only thing you have to do is to put following line into your `.platform.app.yaml` file:

type: "python:3.7"

Commit the changes, push your code and enjoy the flight!


# Apologies to the Elixir community: 1.18 release now available
Source: https://developer.upsun.com/posts/releases/elixir-118-release-available

Elixir 1.18 is now available on Upsun and Platform.sh with type checking, LSP improvements, and built-in JSON support.


<PostMeta />

To our Elixir community members: we owe you an apology. While you've been enjoying the benefits of Elixir 1.17 and 1.18 releases, our platforms have been stuck in June 2023. That changes today. Elixir 1.18 is now officially available on both Upsun and Platform.sh.

## What's in Elixir 1.18?

If you haven't been following the Elixir changelog, version 1.18 brings several significant improvements:

### Type checking of function calls

The biggest update is expanded type checking capabilities. Elixir's type system now checks function calls and gradually infers patterns and return types.

This means your code gets smarter validation without requiring explicit type annotations. For example, the system can now detect:

* Patterns that will never match any argument
* Accessing tuples at invalid indexes
* Branches in a `try` block that will never match
* Attempting to use return values from functions like `raise/2` (which by definition never return)

The type system can even identify unused private function clauses, helping you clean up dead code.

### Language Server improvements

Elixir 1.18 introduces compiler locks and listeners that improve how language servers interact with your code. Previously, your project would be compiled once for your use and again for the language server.

Now, the compiler lock ensures only one instance compiles your project at a time, while listeners allow different Elixir processes to share compilation results. This means better performance for your language servers, IEx, and Phoenix.

### Built-in JSON support

Building on Erlang/OTP 27's additions, Elixir 1.18 includes a native `JSON` module with encoding and decoding functions. The API mirrors the popular Jason library, and includes a `JSON.Encoder` protocol for customizing how your data types are encoded.

You can even derive the protocol for structs with a simple line:

```elixir theme={null}
@derive {JSON.Encoder, only: [:id, :name]}
defstruct [:id, :name, :email]
```

### Parameterized tests and ExUnit groups

Testing gets more powerful with parameterized tests that run your test modules multiple times with different parameters. This is ideal for testing code that behaves differently based on configuration.

The new ExUnit groups feature allows more efficient concurrent testing. Tests with shared state can be assigned to the same group (preventing them from running concurrently with each other), while tests in different groups can run in parallel.

## Using Elixir 1.18 on Platform.sh and Upsun

To start using Elixir 1.18 on your projects, update your `.platform.app.yaml` or `.upsun/config.yaml` file with the following runtime configuration:

```yaml {filename=".upsun/config.yaml"} theme={null}
type: 'elixir:1.18'
```

<Warning>
  You can find more information on the [Upsun documentation for Elixir here](https://docs.upsun.com/languages/elixir.html).
</Warning>

If you're using Phoenix or another framework, ensure you're also specifying the appropriate relationships and build hooks. Here's an example for a Phoenix application:

```yaml {filename=".upsun/config.yaml"} theme={null}
applications:
  myapp:
    type: 'elixir:1.18'

    variables:
      env:
        MIX_ENV: 'prod'

    hooks:
      build: |
        mix local.hex --force
        mix local.rebar --force
        mix do deps.get --only prod, deps.compile, compile        

    web:
      commands:
        start: mix phx.server
      locations:
        /:
          allow: false
          passthru: true
```

## Preview environments shine with Elixir

One of the advantages of using Elixir on Upsun is the ability to create preview environments for each branch of your repository. When you create a new branch, you get a complete clone of your production environment—including your database—allowing you to test new features in isolation.

For Elixir applications, this means you can safely test those complex Phoenix LiveView components or that new Ecto migration without worrying about breaking production.

## Moving forward

Going forward, Platform.sh and Upsun will track the Elixir release cycle closely. No more waiting months for new Elixir versions to become available on the platforms. Each new stable Elixir release will be tested and made available promptly.

The improvements in 1.18 make this functional programming language even more powerful for building scalable, reliable applications, and you can count on having access to future improvements as they become available.

If you encounter any issues with the new Elixir 1.18 runtime, don't hesitate to contact support through your Platform.sh or Upsun dashboard.

Happy coding!


# New file size limits explained
Source: https://developer.upsun.com/posts/releases/file_size_limit



<PostMeta />

To ensure the optimal performance, stability, and reliability of our Git infrastructure, we are introducing a limit on the size of individual files that can be pushed to your project repositories.

**Effective immediately, any git push operation containing one or more files larger than 100MB will be rejected.**

This practice aligns with industry standards and helps prevent issues associated with oversized Git repositories.

# Why this limit?

Git is designed for managing source code and text files, which are typically small. It's not optimized for storing large binary assets like videos, high-resolution images, backups, or compiled artifacts. Committing large files directly into Git history can lead to:

1. **Repository bloat:** The entire history, including large files (even if later "deleted" without rewriting history), is cloned by every developer and deployment process, significantly increasing repository size.
2. **Performance degradation:** Cloning, fetching, and pushing become much slower for everyone working on the project.
3. **Increased resource consumption:** Larger repositories consume more disk space and network bandwidth on build/deploy servers and local machines.
4. **Potential instability:** Extremely large pushes can strain Git server resources.

Platforms like GitHub have similar restrictions (as detailed in their [documentation on large files](https://docs.github.com/en/repositories/working-with-files/managing-large-files/about-large-files-on-github)) for the same reasons. This limit helps maintain a healthy and efficient experience for all Upsun users on our API, Console and CLI.

# What happens when you hit the limit?

If you attempt to push a commit containing a file exceeding the 100MB limit, the push operation will fail, and you will see an error message similar to this:

```shell theme={null}

❯ git push origin HEAD:branch
Enumerating objects: 5, done.
Counting objects: 100% (5/5), done.
Delta compression using up to 20 threads
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 103.78 KiB | 348.00 KiB/s, done.
Total 3 (delta 1), reused 0 (delta 0), pack-reused 0

You are attempting to check in one or more files which exceed the file size limit (100.0 MB):
File: ./linux.iso - Size: 104.0 MB - Commit: 2ef839759cac0cbda51b5f090e6ff9d775d584b7

error: remote unpack failed: push rejected
To git.ch-1.platform.sh:ptnmwvw4dhaavc.git
 ! [remote failure]  HEAD -> branch (remote failed to report status)
error: failed to push some refs to 'git.ch-1.platform.sh:ptnmwvw4dhaavc.git'

```

## Preventing large files in your repository

The best approach is to avoid committing large files in the first place:

1. **.gitignore:** Ensure large files, build artifacts, logs, vendor directories, and local backups are listed in your .gitignore file *before* you commit them.
2. **Alternative Storage:** For large assets needed by your application (e.g., media files, datasets), consider using [mounts](https://docs.upsun.com/learn/bestpractices/clean-repository.html#upload-your-files-through-mounts).

## Removing large files from existing history

If a large file has already been committed (even in past history), simply deleting it in a new commit is *not* enough. The large object still exists in the repository's history. You need to rewrite the repository's history to remove it completely.

**Warning:** Rewriting Git history is a destructive operation. It changes commit SHAs. Coordinate carefully with your team before proceeding, as everyone will need to re-clone or perform specific steps to update their local repositories. **Always back up your repository before attempting history rewriting.**

Two recommended tools for cleaning repository history are:

[**BFG Repo-Cleaner**](https://rtyley.github.io/bfg-repo-cleaner/)**:** Generally faster and simpler to use for common tasks like removing large files.

* **Example command to remove files over 100MB:**

```bash {filename="Terminal"} theme={null}
# Make a fresh clone --bare
git clone --bare <PROJECT_URL>.git repo-backup
cd repo-backup

# Download bfg.jar (see BFG docs)
java -jar bfg.jar --strip-blobs-bigger-than 100M .

# Clean up Git's internal refs and optimize
git reflog expire --expire=now --all && git gc --prune=now --aggressive

# Push the rewritten history (FORCE PUSH REQUIRED)
git push --force
```

[**git filter-repo**](https://github.com/newren/git-filter-repo/blob/main/INSTALL.md)**:** The modern, recommended replacement for the older git filter-branch. It's powerful and safer.

* **Example command remove files over 100MB:**

```bash {filename="Terminal"} theme={null}
# Make a fresh clone (not bare this time)
git clone --bare <PROJECT_URL>.git repo-backup
cd repo-backup

# Run filter-repo
git filter-repo --strip-blobs-bigger-than 100M

git push --force
```

After cleaning the history and force-pushing, all team members will need to update their local copies, typically by deleting their old local repository and re-cloning the cleaned version from Upsun.

## Conclusion

The 100MB file size limit helps ensure a smooth and efficient experience on Upsun. If you encounter the limit, use tools like BFG Repo-Cleaner or git filter-repo to clean your repository history, remembering to coordinate with your team due to the nature of history rewriting.

If you have any questions or need assistance, please reach out on the [Upsun Community Forum](https://community.upsun.com/).


# Develop on GitHub, Deploy on Platform.sh, Test on Blackfire.io
Source: https://developer.upsun.com/posts/releases/github-blackfire-platformsh

Learn how to easily integrate GitHub, Blackfire, and Platform.sh for streamlined code management, deployment, and performance testing.

<PostMeta />

<Tip>
  This post was originally published on the Platform.sh blog and reflects information from the time of publication.
</Tip>

As you know [GitHub](https://github.com/) is awesome for managing your codebase, [Platform.sh](https://upssun.com/) is awesome for deploying your application and [Blackfire](https://blackfire.io/) is awesome for testing your application performances.

<img alt="GitHub, Blackfire and Platform.sh" />

But did you know that those services can *easily be integrated together* so that you get the best of all worlds without any hassle?

What you get is that for every branch (or pull request) that you push to GitHub, Platform.sh automatically deploys your application to a dedicated environment, and Blackfire automatically profiles your application on that newly created environment.

## How it works

*A picture is worth a thousand words*:

<img alt="GitHub integration with Blackfire and Platform.sh" />

On this screenshot, I have opened a pull request on GitHub.

You can see a notification telling you that Platform.sh has deployed your pull request to an environment, and that Blackfire has profiled your application on that environment.

The two `details` links redirect to the Platform.sh environment and the Blackfire test results.

## How to configure

I have made a tutorial video which explains how you can configure it on your project, and also how it works in real life.

*A video is worth a thousand words*:

If you face any issue setting up those integrations, don’t hesitate to [contact us on our public Slack channel](https://chat.platform.sh/).


# Go[lang] forth and deploy
Source: https://developer.upsun.com/posts/releases/golang-forth-and-deploy

Discover the full support for Go 1.11 on Platform.sh. No more GOPATH required. Easy setup and deployment for Go applications with Go modules and Platform.sh.

<PostMeta />

<Tip>
  This post was originally published on the Platform.sh blog and reflects information from the time of publication.
</Tip>

Platform.sh aims to support your applications, whatever they may be. We've supported PHP, Python, Ruby, and Node.js for quite some time now. Golang support has also been available as a beta for over a year.

Why just beta all this time? It worked and ran fine, but there was a catch: The bane of every Go developer's existence, the GOPATH. Making the GOPATH design play nicely with a build pipeline that focused on your code, rather than on code in some fixed parent directory, wasn't easy. It was possible with some intricate Makefile dancing but it was never something we really felt comfortable calling fully supported.

Fortunately, the new release of [Go 1.11](https://blog.golang.org/go1.11) has solved that problem for us. Amongst its other improvements are support for [Go modules](https://golang.org/cmd/go/#hdr-Modules__module_versions__and_more). The link there has far more detail for Go developers, but in short Go dependencies can now be managed in almost the same way as in other dependecy-managed languages like PHP (Composer), Ruby (Bundler), or Node.js (npm). No GOPATH required!

Specifically:

* Dependencies can be specified in a separate file (`go.mod`), and don't have to be checked into Git.
* Dependencies can be downloaded on the fly during build, reliably and repeatably.
* Everything is local-directory relative. No more GOPATH!
* Compiling Go is still embarrassingly fast.

<h3>I'm sold, how do I use it?</h3>

It's surprisingly easy now.

First, include a `go.mod` file in your project. You can create one with `go mod init` and then modify it yourself or have Go populate it for you based on your source code.

When you run `go build` locally, it will generate a `go.sum` file that is a hash of the code you've downloaded for later validation checks. <strong>Add both the `go.mod` file and `go.sum` file to Git</strong>.

Now you can setup your [`.platform.app.yaml`](https://docs.platform.sh/overview/yaml/what-is-yaml.html) file like so:

```yaml theme={null}
name: app
type: golang:1.11

hooks:
  build: |
    go build -o bin/app

disk: 1024

web:
  upstream:
    socket_family: tcp
    protocol: http
  commands:
    start: ./bin/app

  locations:
    /:
      allow: false
      passthru: true
```

That configuration says:

* Use the Go 1.11 container image.
* Use `go build` as normal in the build step; because the Go modules files are in Git it will detect them and use those to locate and download dependencies, then stick the resulting binary at `bin/app`. (Feel free to change that output location if you want.)
* At runtime, start the Go application we build and forward all requests of any kind to it.

If the Go app stops for any reason, Platform.sh will automatically restart it.

That's it that's all, you now have a working Go app on Platform.sh.

<h3>But wait, how do I wire Go to Platform.sh?</h3>

You do need to tell your HTTP server in Go what port to listen on. Fortunately, that's easy! We have a [Go helper library](https://github.com/platformsh/gohelper) available (which is now super easy to install with Go modules) that gives you a clean struct to access all of the Platform.sh-specific environment information you need, including the port. If you're using the `net/http` web server from the standard library, it's as simple as:

```golang theme={null}
package main

import (
	"net/http"

	psh "github.com/platformsh/gohelper"
)

func main() {
	p, err := psh.NewPlatformInfo()
	if err != nil {
		panic("Not in a Platform.sh Environment.")
	}

	http.HandleFunc("/bar", func(w http.ResponseWriter, r *http.Request) {
		// ...
	})

	// Note the Port value used here.
	http.ListenAndServe(":"+p.Port, nil)
}
```

And now your Go server will accept requests forwarded from Platform.sh. Beyond that, the sky's the limit.

Welcome, Gophers, to the joys of safely deploying on Friday!


# HHVM deploys off into the sunset
Source: https://developer.upsun.com/posts/releases/hhvm-deploys-off-into-the-sunset

Platform.sh will no longer support HHVM runtime after 1 March 2018. Learn about this change and the evolution of PHP alternatives.

<PostMeta />

<Tip>
  This post was originally published on the Platform.sh blog and reflects information from the time of publication.
</Tip>

We always aim to offer our customers the best experience possible, with the tools they want to use. Usually that means expanding the platforms and languages we support (which now stands at six languages and counting), but occasionally it means dropping tools that are not being used so that we can focus resources on those that are.

For that reason, we will be dropping support for the HHVM runtime on 1 March 2018.

HHVM began life at Facebook as a faster, more robust PHP runtime. Although it never quite reached 100% PHP compatibility it got extremely close, and did see some success and buy-in outside of Facebook itself. Its most notable achievement, however, was providing PHP itself with much-needed competition, which in turn spurred the work that resulted in the massive performance improvements of PHP 7.

Similarly, Facebook's "PHP extended" language, Hack (which ran on HHVM), has seen only limited use outside of Facebook itself but served as a test bed and proving ground for many improvements and features that have since made their way into PHP itself. Like HHVM itself, though, Hack never achieved critical mass in the marketplace outside of Facebook.

Back in September, [Facebook announced](https://hhvm.com/blog/2017/09/18/the-future-of-hhvm.html) that they would be continuing development of Hack as its own language, and not aiming for PHP compatibility. Essentially Hack/HHVM will be a "full fork" of the PHP language and go its own way, and no longer try to be a drop-in replacement for PHP.

Platform.sh has offered HHVM support as a PHP alternative for several years, although as in the broader market it didn't see much use and with the release of PHP 7 the performance advantage of HHVM basically disappeared, leading people to migrate back to vanilla PHP 7. Looking at our own statistics, in fact, we recently found that HHVM was virtually unused on our system.

"Give the people what they want" also means not giving them what they clearly don't want, and the PHP market clearly doesn't want HHVM at this point. We will therefore be dropping support for it on 1 March. If Hack/HHVM develops its own market in the future and there's demand for it we may look into re-adding it at that time, but we'll wait and see.

Good night, sweet HHVM, and may a herd of ElePHPants sing thee to they REST!


# Introducing a more complete logs forwarding experience
Source: https://developer.upsun.com/posts/releases/introducing-a-more-complete-logs-forwarding-experience

Streamline monitoring with centralized log forwarding. Platform.sh now supports log forwarding to Sumologic, New Relic Logs, Splunk, and more. Discover how!

<PostMeta />

One of the key attributes of [DevOps](https://platform.sh/devops/) and SRE engineers is their ability to meticulously
observe and monitor all of their applications. A task which can be achieved more efficiently by centralizing all
generated logs to a central endpoint.

By centralizing logging, engineers can, at any time, have an accurate overview of all events which take place across
their applications, from just one place. Storing logs in an external system also allows companies to ensure compliance
with many certifications. Not to mention, centralizing can ensure logs are retained and cannot be altered by a third
party.

<img alt="Logs" />

## **Our integrations**

While we have been streaming logs on Enterprise Dedicated Generation 2 clusters for years to *rsyslog* endpoints, we are now rolling out a more complete logs forwarding experience for all customers on Grid and Dedicated Generation 3 architectures.

Every Enterprise and Elite plan with [the Observability Suite](https://platform.sh/features/observability-suite/) will now be able to forward Platform.sh logs to 3rd party endpoints such as:

* [Sumologic](https://www.sumologic.com/)
* [New Relic Logs](https://newrelic.com/platform/log-management)
* [Splunk](https://www.splunk.com/)

Also, to other 3rd party service that supports syslog as a protocol such as:

* [Datadog](https://www.datadoghq.com/)
* [Loggly](https://www.loggly.com/)
* [LogDNA](https://www.mezmo.com/)
* [Papertrail](https://www.papertrail.com/)
* [Logz.io](https://logz.io/)

Regardless of the infrastructure, we rely on the *journald* component of *systemd* to collect logs from applications and services. Custom application logs can be streamed to the integration by either writing them to the *stdout* of an application or service managed by *systemd.* Or by writing them to /dev/log over the *syslog* protocol.

The following services will also include their logs in the integration:

* MariaDB general log + slow query log
* Elasticsearch
* Redis
* RabbitMQ

While these application containers will send their own internal logs:

* Python
* Nodejs
* Php

## **Great, can’t wait to forward all the logs! How do I enable it?**

There are just a few steps you need to take to set up your log forwarding.

**Step 1:** Please reach out to our [support team](https://platform.sh/contact/) to enable the logs forwarding feature on your project.

**Step 2:** Once enabled, the integration can be configured via the CLI. We are working on making it available via the console as well in the near future.

**Step 3:** Please refer to [this documentation](https://docs.platform.sh/increase-observability/logs/forward-logs.html) for more information on how to set up the integration.

Then that’s your setup complete and ready to start centralizing your logs!

We want to hear from you so please keep on sharing your feedback with us so we can improve our user experience — reach out to us on the [Upsun Community Forum](https://community.upsun.com/). Stay tuned for more exciting updates in the future!

[image1]: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAnAAAAEMCAYAAABEG4uEAAAAAXNSR0IArs4c6QAAIABJREFUeF7svQd4XMd19/0HFtgFFsCi994rQYC9d7FJlCjJ6pZlxb189msntlNckjifnXyJHXc5clxkq1miCkWJTewNJEGCBNF7773sLjq+95zdCy5BgGhLckGe8eOHAnDLzG/OnfnPmXvPsRsdHR2FFCEgBISAEBACQkAICIF5Q8COBFyvXj9vKiwVFQJCQAgIASEgBITA/UxAo9FABNz9bAHSdiEgBISAEBACQmDeERABN++6TCosBISAEBACQkAI3O8ERMDd7xYg7RcCQkAICAEhIATmHQERcPOuy6TCQkAICAEhIASEwP1OQATc/W4B0n4hIASEgBAQAkJg3hEQATfvukwqfDcJUMSdX778Mt7eu3dG1YgMD8dL//VfcHFxmdF5crAQEAI3Ezh89DiqamoA2FkPz+goYqOjsGHdGr5md3c33n5vL0ZGRgE7K97HejWe5ZVG4a5zx5OPPXLL84dG7NE7pMHI6L3U9lkis7nTRuHm2A9XZ0f5CtXm+sZGKkRiZWhoGI6ODjZSo7tfjeraWjz72c+if2BgxpV56ac/xZK0tBmfdy+d0NffDyeN5pZN6uruxuDgIHy8ve+lpktbrEgg42ImVi5bOnZF01g1BEdHxznd5dyFi1i1fBlf46/vvIfHHn5o7JpNTc04k3EeCfFxSIyPg729/ZzudTdPLigq5jZYlv7+fpBHRyk9gxoMjlwf+0uqm5FVWI1lKZGIDJJn8272H93bDsMI0I3eLOAaGhtx6uw5REZEYNniRTfUs6W1Fd5eXjM23tLyclzJzsGm9Wv5/NmU8opKREVG8Kk0yLu5usHefvLVwakzZ9HU0ooHt22FVut8wy3zCgqRlBCPgYEB1Dc0IjIi/JZV6untRWtrKzOZrIyMjODqtRwkJyaiqKQEqSnJNxza3dMDnZvb2O+MfX04duIUdmzdwjxpEMrJy0dcTAzq6usRHRV5w/n091NnzqGxuRnbNm+Eh4fHlBiLSkrh5+sDTw8PDA4OobS8AonxsVOeRwdQewYGByeccIuKS+Dn6wtqw+lzGdi6eSMqKquwKG0hikvLeCVrN27VStd7b99H/LfxbKZVoQkOovrRwOPm6sp/vXgpC0mJ8XCdwNNlMBqhUauhUqkmvF1vrx6urrf2kFVWV7OAGxwa4sHO3d0dzc3N06r+b37yEyxNT+djqZ8XJCeBngt3nQ6+Pj7c/2czzmP1yhXcT9SuqIiIm2zX8mYlpWUorajAts2bbnomDQYjhoeHWQx5eXmOnUbXpb4oq6xESmLilHVvbGqGm6sLtzc7JxeL02cvQnv0erjdwgup1xvw8h9fgae7O1745DM32dCUlZUD7gsCFy9dxrIli7mt9Ny89tYeNDY24TMvfJLHOipk+x8eOISli9PR0dGF5KSEKdlYCsNX33wLzz31BNsgCR4nJw083T3Q19+HgqISbFi7mv82NDyMquoaRJvnJuUaJWXlCPDzg5ubaWyabunvH+BnVhmLenp64GYxb0z3Orc6jsbouJjoGw7p6dXzc66UnkEnDI6oQFH+957MxqL4UHT1GKF1VoPE3PZV1+e3zPwqRAf7wMv91uPn0PAISqqbkBgZyLe5VlqHqGDT2LfvVA4e25gGJ41JhGcX16KprRsbl8Zjz9HLWJcei2A/T7R29qK4sgkJkQE4cqEAuzelQ+0w8Ziu2Mfw8AgcJjiGru/vreP7HTiXhx2rklFa24L88gY8uDoFKhXNy8C+U9eQFBUINxcNTl4uweOb06Gyt8eF3Er0DwxicWIY3j+RjUc2LISr860XqNWN7aD6hPp7oqyuFd29RpTWtCA2zA/G/kGeW6KCfeGq1cDHY3LbscMIAnQjNws4MsC+vj6kJCXixOmz8PH2QmdXFxtrcGAQix16gEhgXMvNQ0RYKFrb2rF4URrOX8jEg9u33jRJvv/hfnh7eqCmrh6dnV1Yt2YVT146Nx10bq4goaFWq3mSCAkK5NUUXXP7A1tQW1fHEwcN7iRGaEIpKC7GJ59+kh+soMCAm4QmdchPfvEb/M3zz+LIiZMIDQlGR0cnPD090NrWhrr6Bp40I8PDcOQ4/T0EEWEhqKmtx9LFi3AtN5fbWVxSCg8Pd9Q3NsHRwYHbRaI2PCz0pueDHuI/vPoaPv/pF/D+vo/g4+sDL08PnoiD/APw4aFD2Lx+Pdra27F96xZ+6N/duw9f//IX4OTkhEtZV3Ds1Bl86pkncT7zMnY/tPOGe9Ck+w8/+CE+9+LzaG1tB4nKqupqrF21CmUVFVyn/MIixERFoqW1jbcCMi9nwWAwwNjXj8AAfxw4fATpqQsQERbGE3hSQhxowKBBLyQ46Kb7TSbgXn9rDx+bnJiAsJAQnLt4EafPZuCrX/gc/vtXv8F//uiHsB8n4KhPScC1trYhfWEqRkZHUFNTCx8fHxa2dQ31iI+JxeDQICqqqpCUkICCwiIE+PuhsKQUzz7xOBwcbvQG9uoNKC4pQXVNLdx0bjh67CSee/oJth3iRUXr7MysiNGWDetx+Wo293tMdDT0+l5czclDcGAAPj52Art3PcgDMR1DIppEandPL3Y8sJmvZSngiFlMVBQys7KwdeNGto3a+nqEBAdzv5AQLyotYRulYing/vuXL+Hhh7bjwwOHsWRRGlpaWuHr64s//vlVbHtgM3x9vLkNJHZrauuwfOkS/t348l8//yXWrV7FWzxBAQHILywECVEStBXV1UhPTUVhcTF7s+jZGhgcwOjIKIs9mlg6Ojv5OSCxR4UmpfHlYuZlZOfmITIiDDQpJcbFoa29g/vM3UPHz5VGo8aGtWtQWFQCLy8PNDQ2Y+GCGxcwdN1bCTgaFzIyaezpZ3FLdixFCExEwFLA0Tjq4OiA5pYWYNQO6QsX8ClZ2dk8TpIdvbnnXV4MrVm1gm0sJIjmgw6oHR1BC+sHd2zjxd1kAu6d9z/AurWr8Zc3/opdO7ajra0N6WkL+Zy/7nkXbR2dPF6fv3iJx4PlSxcjN68Qn3ruKfQZ+3hBRvOnTqfj+YAcB7SoomdVr9fzs7R+7Wpk5+ShuqYGCxekoLi0lF+5OHTkGL7wmU+DnkOqP/lejp44ibQFKbh8JRt+fj5wdHBEcFAgurp7eH7r7e3leYvGqKbmFh7zs67l8Nzl7eXJi+zpCrgeQx/OXCnFjtUpOHqhAJuXJyLjWjlWpkaNdc1v3jqJtYti0WvoQ1u3nkUMbT3r+wbg7OSItQujoVE7om9gEHuOZPHfAnzckV/RgCe3LEJZbSuuldQh0Mcdj21KAwm9V/ZlwNvDFSH+HiiracHA0DAWxoagubMH566WwVnjyEwfXr8QQb7uePfoFYQFeqG2qQOGvgEe457dvhQd3QYUVjaaNcko1i2KHZub9p/NQ5i/J5/z6qFMvPqvn8bf/ewdBHi74+ltixHi54n2bj2uFtXiZFYJFsYGo1vfh/T4UBZ3JLjO51QgJsQHUSG+eP3ARfzLF3exsGzt1HMd61s7oXXSIDU2GGlxIXhl33n4eeuwYXEs9p3O4fa/eTATO9amoKGlm3k5qOxxKb8auzcsZMZdvUYWsz2GfhaLVG4p4EgkLV+yGG/ueQdbNm5A1tVshIeFsfHRRE/GQuKAAJJYoMmBHhQymLDQkJueORJwXh4ePAG0tncgJjKcvTW5BQXsmfP29ERiYhza2jpYzJSXVyAgwB+P7noQdC6t+s9nXkJ/Xz9Onc1AemoKT3T0wPX09OJrX/r8BJPbr/HZT3+SHwAShyQWFqQks3AcGBjErh3b+GEzGvtY0FEbtmxcj+xruYC9Hd8rIT6WjT0lMYH/JbGTnBg/tvqzvCl5Dki0kEgsLimHwWhgTuQpfO6pT+DlP/wJcbGxyC8qwqeefgoXL2fxRE9qnFaOP/3lb1hskIAw9PVNKuDIrd/Y1ISkxATQwLJ5wzoWoCQ6nDRO8PfzwdVruXj04Qe57bSCo8GB3huhlQ7do7OzGzu3bWGP4dETp/DD7/0jvL1v9IxO5oGjAe+V197E0PAQ1q5cgbqGRqxYugTHTp5iUUrCa9fObTd5T0jAvfXO+2htb2fvZ3xsDIuLqzm5cHZyxujoCPf90kVpbBO0fevs7MSmSnV+7JGHbupjEnDZOTksWMi2iAttrcRGR+PQ0WMsNOJjo1FZXcOr4bTUFBQWl/IrLSTqyyuqEB4awoMdCTga1EiUncnIQHBQEDIuZPIC5rFHdrF4HC/gkhMScOHyZex+8EEeNMNDQ7H3wAGEh4QgMT4etOV69OTJmwTcn1//K5qbW/DApg3Iyc9HXGwMCz3ywH3+xU/jUlYWD/bUX8TEx8uL+3B8ycnNw7XcfCQlxePo8ZN46vHHUFJWhubmVri4aFkIkbf64+MnYDcKts34uFgWdCT2vD29eKFCC5aurh48+9QnbrrH5ayruHIth9tP2+nkyU1NScKFS1l4+MHt2PPuBwgJCcLjj+zi+u79aD+LOQ9395uuNZmAo/eNaPHi7OSE+LgYXmBIEQKTEbAUcP/x01/gy597kZ9xEis0hlMhIUO7NrQAau/sxMKUFFDGoYLCQqg1Gh6zXn/rHd6RoIUbiajJBBwttDesW4vX3nqbBVxDYxMWp6WySPjWP/2AF5nBwUEsqv70l9fh7+8LXx9fbNqwlhesNC9WVFXzopBEmZenJ9rb23n35dU334Zao8bzTz+JvR8dwJL0NF7E0pyrN3vRF6ctZK/9kkXpPBa8/9F+XnjRnErjJ+040LxB3hsSsB8ePIx1q1fi+MkzPIbS+dQ2ei5pfp6JgOs19OPUlRLsXJ2CY5lF8HTTwjgwiFUWAo6EnY+XGyIDvdHQ1o3s4jponRwQGuAFH3dXODqq4KZ1QkNLJzKuVeBKUQ2LNXqF8ZltS3ClqBYtHb0sAD/32Br2br26/wICvHU85ugNfSiqasJD61Lh6+GKl/ac4nEoLNAbixJC4e3ugr9+nIWW1m6kxAajub2bPXTpCWHwcteiqa0HVY1tGB4exerUKBZhtHuXkVMB2ggvq23BxYJqFnDf/vm7LASXJUewWGrvMqC4qgmHLxQgLtQX9ip7eLhqERXig9rGDhj6B7i+5KF7+d1T+NFXH8Uf9p5DVWM713/lgki4OKu5jZ/Ysgh/3nce4UHeWBAThI8vFOCZbUtZwG1fncwMdC5OXLcz2WV4dMP13Y4jFwvZaxcf7n9rAUdi5sTpM+zZIg8ZGRNNeh7uOqxYtgQ6V1d+P+ChHdvYu6PROLEXa/eunez1sNwmVB5AWk1cyrrKhtTV08OCiLxUO7Y9wJM+GSOtDI6dPM3/0vYgefc+sfthGI1GHDh8lAd2Wsk4qFSIiopgN3NhYQliYqL4uuPLsROn0dTcjAd3bEXGhYtwcHTk7dvS0jJERUYiNjqSPWuFRcXw8fFGUFAgMs5n8gBAkyF5IL19vNgjQEInLjqKH5b1a1axYBpf8vIL2U1/IfMyvzdBD6u7uw7+fn4sVmi7NMDfH9fyTO2iAebj4yfZ40gPFk289LJ7dm4u3N10iB3n4qbJkfiQuCZRQoKZPFOLFqbijbffwQObN2JocIj7IOPiJXxi9y6UV1ZhcGAQoaHBvMVZXVvHnpeEuFiuz9bNm9h7QizHb21PJuDIPkhUDAz083kkdMj7RH1DXtIAf1/2XE20hfr2ex+wwIwKD2feJM4TE+KhsrODVqtlAUYeuXPnL2DntgdYgHLf2tndtGIk/rSSbW5t5ZUweZNoRUt2SwPkgY+PwtPDHa6urqiuruHVq+JpMm1352LD+jU4+PFRrFiyGHUNDeyZu5SVzZ5JElDUR0VFJXjULB4tBRyJjSd370ZhSQnzIIFDC5KHtm7FpatXQeLuYlYWLxioWHrgyFM1ihFER0aivaMTp8+eQ9rCBSxCaRVNK+aR4WF4enmy8H7qsUd5C2d8Ia9nQ1MTdm7dgj/+5Q18+fN/w4uRXoOeBxVanFD/VFZVs2ilCY68AxkXLrENFZeVISgwkBdB/X192Lpl0033oD6h9lHf9uh7xzwKCXFxiIuJYi89icXVK5ZPqTgmE3A0BtAC7YFNG9lrLUUI3IqApYD72a9/i899+nkWafX1jWzfVMjrvvfD/ey9pjmE5hgScFlXsnlhTuMPjaVF/3cRuXvXQzyvTCbgaGeDFiQ0t9H7rzQf0OtAtENB78bRwoi86LQop+dJ7eiA2roGfrWEXt3QOjuhs7sbPd090BsMaO/sYuEYFhqKfR8d4AXVqhXLeCeBnAqb1q/j557eU6P5hxaRdE9axJEz4sP9h7B29Qp+jmNjovh3tMOwIDkZQQH+3I7BoWFEhoeyl45eudn70UFeWJOYnImAI5bvHbuKFamR8HB1RnNHD3JK6/HQWpOnk0plfRu0zo7w9dTh/eNXERbgBS+dFi5aDZzVjrBX2UGrUePNQ5lYviCKBZPGQQUnJzWSIgOh7+vH/tO52LQsAccuF+PFh1awl488Y7vWpeKNg5lYlRaF2FB/9A0OIruoBm5aZ1zKr8TjWxZhaGgEe45mISbEF35eOr4e3d/fSwetkxqnrpZCrVJhZHQUa9KieRt27/FsPLV9CT4+X4AgH3e0dum5TZfyq1BU2YSYcF9oHB3Z6/bq/otIigqAp84Fpy4X4xMPLOb2vHM0C3rjAB5atwBvH76EJ7cuYa8hMaC2k3gN9nVnEdpEojIigLefSfy9diATy5LD+XcF5Q1IjArEgbN57H1MiQmCRu3A9ZqsTOqBm+gEmghM3hAp9wsBk4AbgpNGfb80ecp2Wgq4iQ6mbXYSwiQqlS1c5ThLATfljWZ4AK28Scy6aLUzPPPOHt6jN8DN5cY60iLr0NHjcNG64PEJvKx3toZyt/lAwFLA7TtwEAP9po+KaOH88IM7Zt2EyQQcXZA82WcyLiA5IZ69WPP5I4aJBByJW8t3h5V34Kjt9B5cY2sXLhVUYWlSBHuWbkeh982GR4ZZTN/tQkJKZW9ns+/hzkjA3W2Ycn8hYAsE6BWCL3zjG8grLJxRdWh7/s3f/x4hQTe+Zziji9wDB5MXeSLPLG2HkIeQPAlShMBUBJStxvHvxE513q3+Tgugqzk5vEVKhXZmyFMWTR+43UNhROjdY3r96eGdNwpdEk+WzewbcoBh+NYv5M+Ft5w7FwKjcFINwtPFXsKIzAWjnHv/EeAvktvbZ9RwrRO9m+g3o3PkYCEgBCYmQDtC9NECLQisVWhh4e/vd8NX9+Qdpnvda4VeMdHprkdEmKx9wxwDTuLA2WL/q+xG+L19u9HR0VFyn0oRAkJACAgBISAEhIAQsH0CIuBsv4+khkJACAgBISAEhIAQuIGACDgxCCEgBISAEBACQkAIzDMCYwKO3uvhmFNTpLmZZ+2T6goBISAEhIAQEAJCwCoEjP39HKKJCsU2/d8//YVDg93JQu9rfv3LX+Q4n/wOHAk4CjA4Pnr+nayU3EsICAEhIASEgBAQArZKgEI2UTQCKpevXMVXvvktzixxpwtlXvrgrdcVAUcxYLQ2G/PkTsOR+wkBISAEhIAQEAJCwJIAed36zALu7PkL+MZ3/umuAKLECicPfSQC7q7Ql5sKASEgBISAEBAC84qACLh51V1SWSEgBISAEBACQkAImN57s3kPHOW4pOTa9LIcJd2mPJL0xQMV+tjh4JFjnIi7rq6e82BSgvvplryCQk68S/kVb1WKy8qRefkqpy1Zu3IZH1rf0Mi5Lq1RWtraOBkw1X98oX3u/KISBPj58nuBvj7e075lVU0dwkODp338ZAc2tbQiv7AYG9asnPHWNhlZc2sb58VTChndidPnsHbVCs4NSDknZ5oOhhJG+/v5ctLxW5XMrKuc2JlywCmFEstTbtj6hibOq6tzc530Ennm3IPEv7WtnXPY+fv6jNV3eHiY83pOxxbo/c4r13L53NXLl46xpJyEdQ2NCAsOnjDPqGXlyOZz8go4iXtpRSUni6dcutQOyiKg1TrPqL8pLY+dnf0tGdAFW1rbOAejJUeqN7WFPjiidzFa2joQGhw4o/tP52B6Pj4+fgqP7drJ9yJ7pJCe1IflldVIjIuZzmXkGCEgBITAPUNgOgKOcp9/9zt/h//+1UvIupo9ZdsDA/wREhKMzEtZUx6rHHDLLdTmllZ88rNfwJOP7QYl3k5dkISCohJs37IZp86ew7t79+HskYPYf+gw6KuM8opKTjZOiXspcfbaVSs5oe6Lzz/H+cQqq2pACYEp0nVuXj7aOjrwwrNP8zGUaI0myM6ubo4OTcnVP/OpT+LS1WucTzLAzw8k5hwdVGhsbkFocBAMxj7Y29vBXadDUnwsPjhwmEUW5YLs6dFzIlhKy0OpVig/HiUWpsTDJEgd1Q4YHR6Fnb0dvD09MTw6guT4WFzMyuYcbH4+3oiJjsTx0+eQGBuDa/kFiIoIQ31jMzx0OixJT8XJsxnw8vJEW1sHt5kmZHd3d0SGhaC9o4vr0tLaysne6QXHRQsXcGJ1mnyvXMuDj7cnOjq6oDcaWIjY2avgrFEjPDSEEy5TonF7O3t09/SivKoKvXoD3HVuMBgMCA8NRVhIELeJkrO7urmAxBFxpLrQvWvq6hEbHYXOri5ma+yjL2fsmB0J4rPnL3JSY73BiOBAf4SFBuPYybOcaL6mth5aZ2fYq1QYHR3B0NAwi2212pGTxRv7+rAgKYHZZ13LgdrBASR4qU/8fHw4ATwJLqq7i9YZ3l6e3A9Ux2WL0lBdV8+JpjE6yqmlGpub+dppKck4cTYD+l4D8oqKERIUyPegfqc6U8L18LAQXv2Ullegta2Dz6O6ksAg20lPTcHFy1eYlx1GObffwpRkvsfJM+fh6enOoq+3pxf+/r5cJ6obCVpaVNDXRRonDdrbO9HU0sIJoTVqNSeMJ3vydKcE9+1ITU5icU8JquvqGznJu87VFQtTknDgyDHERkdzknri5+bqiqqaWq6jm5sr9xnZXn9fP4KCApCalIiMzMsmm7YDunt7mUt7BwmzYO6/7p4eqB3VaGtv58TxJL6jIsJRWFKK0vJK+Hh58XF9/X3YtG4NTp27wPfRaBw5FRCJeWJRW98AP18fts3kxARegFH+nL6+Pu4vqiv17/rVK3jxYK+yh5urG7dlaHAQA0NkzyP8TK1ftWLag40cKASEgBC4FwhMR8B9+XOfwZ9ffxPf/fbfYnB4CPs+OojAwACef2nhHhEWhpz8PJSWVUCtUbN+WrQwFTo3N547acFOY3HGxUusCehdu7r6hhvwTSngPvX5L7GQevu9vexhC/T3ByXBJeF0NScXxz/6AB8dOoxLV66yV+b9ffvZE7F25UqeTOkLjb/7+lcRGRGOL339b3nS9vBwR0JcHAL9/dDQ2IScvHyeiMiz9g/f+ia+/28/5uO///ffQm5+ETw8dNwQOpYmDppIycMVExWJ9vYOPPrQDgwMDuDk2fMsfDzd3dHR2cX1IQ8JeVhoIiMRQZNfR1c3X8vf15cFlbHPCJ2bDhHhIXB0cERxSRns7O2xdNFCHDt1FrFRkTh38RKCgwIwMDDIAm/z+jU4eyETfX39LETJM0keoXUrl+Pw8VPsmejp1bPIeX//Qe60lMQE9oZ19+oxPDSEEhYg7ejq6mYPoIOjAwL9fdnLQR6XyLBQFjD0t6zsa+jVG1kwuLu74eips3hq9y4Ul1Ww+KPJNcDfl701q1cs5XqTMZCQIjFaVV0LvdHIAvaxh0z57y5duQaVyp7FDHka161cxuKJxO/Q8DALCWoXtZHEorOzMyJCQ5B5JRuJcbGcrJ0YX8vL5/sTJ/LY0MTe1m4SLsPDI3zO4NAgi0sSRimJ8SitqEJ9QwMWJCXyf8dGRbCwIPFz5MQpNDW3cV/GREVwnyfExTBfspm6hiYWPtV1dfy3xpZWFo0krOjnjetW4+33P+T+y8zKxo4tG1gEkrh5890P+P4kekjwkPijQjaycsliNLa0ICE2Gq++9S6LNfL4UZ1OZ1zE4oUpKK+ugZ+3N3r0emxYvZLPJeGek1/EtkSLi/WrTDZAeRVJGNL/Kb9gV3cPLx7o/uSxI7uhxUFhSRl7BU+ey2BBTwIsKCAADU3NcHV14cULieCk+DiQV5MEOV0zOSEOfn6+/NzQwocWBtSPwQH+2LB2FQ4fO4mwEJP466BzVFQPO04LRP1BXmUSkySG9XoDX3N0ZBQ19fX8rC9fnIaW1nb+sKm4tJyfaxLF9CwtSE7g/hIBdy9MR9IGISAEZkJgOgLuS5/9G3YArF+zmnd3rly9xnMEOTrUjo5o7+rC2+++j3//l+/jO9/7F9ZLq1cuR2VlNTasXYOu7i4e60lvLUpbiNNnM0A7l5bllgKuu7sHr/71LXzxMy/iV//zv/D09EBwYCBXKjsnh71KP/zeP+Jqdg5PEBcyLyGAJtj6BvaqPf2Jx0DXeHz3wzyR/PK3v+MVf3VtLby9vFjUUAWvXMthDwdN/J/+5LN8L5rtv/bFL/DfaaIgz4GPt+Jh6OftO97K8/VhEUFeJ9rqWbVsCbp6ejA0OGTyxrloUVhcyh4mJydnnlRJnAwND7GXh8QhiTLywtCESJNdCXkzvL3g6+3FgohCq5AwoK2qhuZmhAYFcUcUFJew0CLPxfDICLTOTixwSZSRMLC3V7HXMCo8jL1hQYH+7MmiSZSFo7GPf08eQ0c63s4OTho1OaVQ19DA3kz6HQkJ4jA0PAIntRq9BgN7zaIjwnjCpwmXhGpBcSlCgwJ5S48mcxK9xIXELgmfxqZm7h8SslTomuRxIbFLooKEYk5+AfcxiQdiQF5Y6hv6b2dnJ/bAkqeO+qO/f4A9SrTVSd4g2lYkL19yfBzzJa8YfVjt4uxs3uZrR0RYKLMkBsPDQ6itb0R8TBQOnziFkMBAFkt0Pa1Wy0KZRButRki4khgsr6zifiKutPVNniJSR3QLBsioAAAgAElEQVQ98pwR3+jIcPZWVdfUsYfNQ3d9+5E8lrRtS/1FHjHycpIgoRVQRWU1e3JJyJSUlUOjcWLxS/eiepMIo2NNKefs+D5UqI4Njc3o7OnmNpCXNL+omDkTDypct8Ehvg/ZbFFpOf9LAoqEvo+XJ/efs5OGxSTZ9sqlS8a8qWRb1J8k1OhvEeGhLAjDQ4JRVlnFYpS4kre3tb2D20HCnkT3KP1vZJSfO1rJ0fWpPxubWrgNZZXV8NTpUFJRgc7OLmxcu4qPSU5I4LY6OKiYL9WPnmPy4pIHNTgggK8jRQgIASFwPxGYjoAjT9qKZUtYI5w+dx6hIUEoK6/EwgXJKCou5bnAaDBi964H8dvf/5HnPJpX6RUd2qkk0UY7R3/4y2tIT6Udv7O80J62gJtth7y37yMe8B/asY0n4TtRSHjR5EVix1YLwac60oTo6jr5u19T1Z8mVd7eNAcSnOr4O/V32vZzUmvGvFrTva+ydU7Cx9baNN02WPM4XmQMDc/4nbq51oFEP4lXEuxShIAQEAJCYGIC0xFw02FHgo12xWjMH1/ob+Q0ISfSZEXCiEyHshwjBISAEBACQkAICAFz9gWb/wpVekoICAEhIASEgBAQAkLgOgFreeDmynScB46+GNTKNtZcqcr5QkAICAEhIASEwD1JgF6F6jdve9KHml/+xt/xu+t3utC70Hv/OpZKq5dfCL9T763d6cbK/YSAEBACQkAICAEhMBcCFEWAInFQITH32lt70HqLd9Xmcq9bnfvIQzuQkmROZk8vx9ML5VKEgBAQAkJACAgBISAEJiZAH2raQqFQX3ajo6OjpvAIUoSAEBACQkAICAEhIARsncANAo7ijqkcrqc+svXK20L9yGtJLzVaFlPwVttQ6LbASOogBISAEBACQkAIWImAWXeoFQ8cpWiiYHJSZk6AoitToF8qFGXZluPRzbx1coYQEAJCQAgIASFgSwTIcUQvvfEWKkXtpwCxUmZOgKLgEz8qlJ2APHBShIAQEAJCQAgIASFwOwiQ7qCsQiLg5khXBNwcAcrpQkAICAEhIASEwLQJiICbNqpbHygCzkog5TJCQAgIASEgBITAlASsKuDoYvT/+3H7UATclLYmBwgBISAEhIAQEAJWIjClgBseHsbf/+Bf8a2vfxW5+QVYuWwZv6A/MjLMX6uODI9gdNQk2hoam9Dc0oL4uFg4qBygUtnDYDByQlaKWkwv99+r4k4EnJUsUi4jBISAEBACQkAITElgSgFHVyivqMTPfvNbrFu9CqMjo6ipr0N1dS2+/pUvIjsnB+UVVfjSZ19Ee0cnysor0NTcjKaWVri6usDHy4uzOxSXlGLt6pVYuih9ykrNxwOmI+CUUCMkYi3/WwlD4ujoOGXT6djGpmYE+PtNK0zJAAlntXrK68oBQkAICAEhIASEwPwhMC0BR6kifvHSy/D388XK5cvwwf4DLOCefHw3e92CgwKxfMli1NU3IL+wCD4+XriSnYPe3l5sXLcWtXX16O7pQV9/P1549un5Q2cGNZ1KwFHbf/nSyyzcvvalL+A//vvnnDvtG1/9IgYGBvHHV1/HN77yRfT09MLHxxvd3T2ws7fj3LQdnV3sxaT/prxrb723Fz/4+29DbzDA08MDvfpeODk5cQo0CsZsb28PF60LGhob8fOXfot//e4/wtnJaQatkUOFgBAQAkJACAgBWyYwLQFHB125dg3JiYn4yxt/xeoVy9Ha1oaGxmYsWrgArm6uCPT3Z8HWazDi6PETCA8NhaenBw5+fARrV63E1Wu5WL92NeJjY2yZx6zrNpWAowuTiPv9K3/B5vXr0KPXo6WlhePuxUZH42e//i26e3vg5+uLFUsWY9+BQ/D0cMdnX3gev/ndHxAVFYEvf/Zv8Oqbb6OtvQ3VNXVwc3NBakoKLl66hG1bNiMyPAz/84dX+D6PPLQT2ddycfLMWbz2h5clPMyse1ZOFAJCQAgIASFw5wjQjqXeaESAnx/c3XWTzt/TEnCzrXZNnWmrdeWKZaAMD/dymUrAjYyO4me/egkP79wOnZsbzpw/j8amFqxduRxeXl74r1/8Gi2trfjON76G9/Z9xO8Vrli6FPFxMSgpLcf+wx/jJz/6IbKuXuN3CV95/U185oXnsG//IVTV1GDtqlVYsXQRikrKcC03D2Ghodi2ZRO++s1v4Xe//rkIuHvZ+KRtQkAICAEhcM8QUF6xot00yug0WVan2yrg7hma02jIVALOaOzD+x9+BMpbtmXjely6fAUqBxXWrFwB+lt2bi58vH1QWFyMzevX4tTZDPT06rF25Qpk5+UhODAAqSnJaGpu4Y9D2trbUVxahk3r1yHrSjZvscbGRKOzswutbe2IjozA0RMn4eKixZaNG+7Zj0em0TVyiBAQAkJACAiBe46ACDgrdelUAm4mt6Fr0ZYzfYCwdHE6VCrVTE6XY4WAEBACQkAICIF7nIAIOCt1sDUFnJWqJJcRAkJACAgBISAE7lECkwo4CldBXzEa+/ru0abPvVlBAYG8dUlFBNzcecoVhIAQEAJCQAgIgekRmFTAvbN3H77/bz8GCTkpExOIi4nBW3/+vTmwsSSzFzsRAkJACAgBISAE7gyBSQXc93/4Y+zZ+8GdqcU8vsvZIwc53Id44OZxJ0rVhYAQEAJCQAjMMwKTCrjv/fBHIC+clFsTEAEnFiIEhIAQEAJCQAjcaQIi4OZIXATcHAHK6UJACAgBISAEhMCMCcxKwD3/zFOgJPcUZG4Uo/D39cVPf/mbCW9OKZwokb2HhzsolC+ljTL2GREYEICa2roZV9jWThABZ2s9IvURAkJACAgBIXDvE5iVgNu1Yxvn4QwNCeF/+/r68OGBQzfRoujBL/3sJ/j42HHExUbD3l6FwuISZFzIxOt/fBnPvvg5ztlZ39jIaaAoXyoleqf4Z5Q/dT4UEXDzoZekjkJACAgBISAE7i0CsxZwwyMjiIgIh763F+3tHZy7c3yhJPd/+p/fYHBwAOczL7PXThFwe179Ixobm5FXVIS46Cicz7yExelp8PXxwa/+53fYt//gvCAtAm5edJNUUggIASEgBITAPUVg1gIut6CQPWV19Q3YumUTDh85dhOYR3c9hMSEOCxbvAjlVVVobm5BUUkJLmRexut/eBmVVTVwVDsgOycfaQuSMTQ8zInY29ra8Q8/+Nd5AXq6Ao5ym505n4mYqAiEBAXOi7ZJJYWAEBACQkAICAHbJDArAZe+cAGcnZzHWuSodsTJ02dvaqGriwsGh4bg5KTh9+WGhoYxNDTI78F5eXrCaDRC46RBgL8fPv3cMzh05Bhy8wvQ1dU9bwIIT1fA1dU3oqC4hNuakhhvm9YgtRICQkAICAEhIATmBYFZCbh50bI7VMnpCjiD0YirOXnw8fbiLWMpQkAICAEhIASEgBCYLQERcLMlZz5vugJujreR04WAEBAC0yZACXTs6LP/eVY47888rfs8Qy3VvQcIiICbYydOV8ANDA7yNvIIhV9RqfiDDgeVireYHR0cQB+F0L/0DqDa0ZHfB9So1SDPnZNGw6FY6F9jXz+0zk7QG43QUoiW/gFoNGrejnZ2duatZwrdQtehf3sNBrg4O/P5fD2DES4uWj7eyclp7PgevR46V9exn+nrYhetduxnui6dT9fVmq9H9ad2KfWj+lO96UviwcHBsXapVCrQO4B0/MjoKFT29txemGcZ+plSttEWu0pFoWkAezu762zMIWuImaOjGoNDg2PsiBXfi+rW18d1GaBte7UavXo9t0FhobSJ/qU2jDGyOM7EuI//TuwVlvR7Oo9eC1B+r7CmvnA134cYKccRc2Ki9BHV08HBEYPDQ3A024CKmA0NgRiNjozAjtgMEUMVcyAu9Hv6u+k1hCHTzEwc6RojI8yKuZt/Jp5kV8SG+of7hX4295/aUY2h4aGb7IvaOtYmvR5aalNfP+f7VeyI/07szPZ2k30ZjWN2Q8yIsSU7Op8Z0/l8fbO99vWZ6kf2rXXm92upfcRMQ306OGhqr7mdlu2l9tNARuwImr29HXMjW6Mv4envxE655nX7InsysVFsdoyZ2a6Un9n26RnQaJgt/azYl/Js9urJPrTc/2R3ZCdkR929vXBzcRljMd6++vv7+bpkR/Ss9tGzrlZff/bMrMeeYTNjk305on+gn+vDzwHVe2gI13oGEadVwU2j5vYRG2JCHJQQUODATib7Ik4KX7IvOtbSnhQ7Yv5s06Y6K79XxgHT+GV6RqlOPM7QeGEejwz0bNG4pNfzs6TYWw8xcnVFl96AzJ4hrHJ3ZHY0LtGzdb3tfXDRmsY5S/tSxj+6D9mR0ieK/VHfExuuh7OzyZ7IJqgvHR1veI4sn8XREbIhNitTMY9ZZFPDw2RzdkyRzhmzL2JnZkR1oXvdYEfETvk91dX8jBjpX/PvqW1j9kW/N4/lxOIm++rpgc7N7fqza7Yjxf7IbtXmZ04ZD6k+1+eUPr4+1Z/ZmZ9xZfziPiZG5jGEfs9z2ciIaa4aGmI+xIHsiJ47y+fQrMmZNz+nzI6ePUf+l9jRNeneyj0MBoOpTmZ2yrxjMFK/X+/fsTZaMGT7Ms97Sv8TS7KvsTnA/Gz2mu1OebaVsVuZhxW7Y3un+ozZF9m3iSE/e+Z5nPvSyWnsmeNx19HRNBaBxukh5qCMQfR7fi7Nz5wlK2JjZ2cK1UZjOHEbXyYVcB/sP4B//Od/Y+BSJiawIDkJf/ndS5ILVQxECAgBmyJwvKkHhqERPBjsblP1mqoyAyOj+ElhE/4hKWCqQ+XvQuC+JzCpgBsZGUVzSzMrTCkTE6CQJ7RKpCK5UMVKhIAQsBUCJ5p6kNfVh6/E+dpKlaZVDxJw382ux48WBsHBfh7uAU+rlXKQELAOgUkFHLn+eJtLyi0JkHuU3cYjI7xlQoXc3+RClyIEhIAQuBsETrf0osk4iE+Eed6N28/6niTgfpTfiK/F+sJLI2PorEHKifcFgUkFHO0B8/s2Um5JgN4pEAEnRiIEhIAtETjT0guNvR1SPZyhUdnbUtVuWRcScH+uaEOyuxNW+rjOm3pLRYXA3SAgAm6O1EXAzRGgnC4EhIDVCZCA83dyhIvKDkFatdWvf7suSALu48Zufn/viXnmPbxdTOS6QmAyAiLg5mgbMxFwldW18PRwh7vObY53ldOFgBAQApMTIAGX4OaEky09eDx0/myjkoCjuncODOOxUA/pYiEgBG5BYFYCrrW1DT4+3gIW4HAB09lCpU+0Dx8/heWL0+Er7MR2hIAQuI0ESAQt89LiF8Ut+GaCP+bL9wCKgKPQCZv83CYMnXAbscmlhcC8IjArAbf/4GFs3LAOe97biy0bN8Db24tjnUxUsq5ew8IFyahraOAX/cNDQznuSV5BEbw8PUAJ75VSVl6ByIhwjjEzX8p0BZxeb0B2Xj78/XwRHRE+X5on9RQCQmAeEiABt9LHBW9VdeDxME+o54mCUwRcgMYBvs4O8NVMPK/Mwy6RKgsBqxOYtYBraGrG8MgwYqOjYG9nj/VrV99UOfoQ4oc//k+8+Pyz2LP3AwwODGJxehqvqihgXkdnJwL8/BAQQCtEO3x87ARWr1yBxqYm6HRuaGlpxeOPPMyBRG21TFfA2Wr9pV5CQAjcewQUAUehRMK1jnBXz48vOhUBRx9fnG/V46F5Fsfu3rMkaZEtE5i1gGtt72ABFxMZwdGC16xacVM7L1+5ig8PHuaIy0nxcfxVa1BgICLCw/DGnnexZsVyXM3JRWCAH1T2KlA0boru3dTcwsdcyLyEb/4/X+YIyrZapivgKHI8CVeK7E2R4ilEi5KRgDyOSrR9iuisREDnKP4UodocXZ1+pmjrHC27nyJXUxaCIY4mb4pYTdHYTRHHiTX9SyKaIkUr0eZpK5cjqJsjk9N5HDGdIu470e/p+qaI5cpxSjRxJVq9Enl6f0MPdgS4cpRoy3pzRHclu4A5Gj4ZGkfvHhd1mvqVuZgjUivRpk3RuikDgSl6txL5W8nqMBaV35xlgOqmRO0e33YlK4HSJiVau/J7hZESTVthMsaeI5FT9G9TVgHl98pxY9HeqS8cTFHF6Tglw4ISIV+JgK/0PbWL20OZJogBRzM3haShdlNRuFD7mQlFMjc/DBxV35yJYeyaZr5KxHy6NtvZ8AgcHB14EUVZHpTMH9fbSJkaHMeisV+PYG+yB+VnSyZKZgfLSORj9mXOAKG0/brdEUtTX3E0enMEdvqZ+nDIbN/ETskaQL/nqOTmSO5KRHdLe6K4lSbbMf2rZLFgVuZsDJTpQ/Hu06GmKPAOGBkx/Z6Y0LPHzMw2zDZvjrKuPGv0dyVritJ2ekYtGdHvlSjt158t07M59gyPe7bHR3Ufb4fXn2HKTmGK/q5kc6F6UpYXxZ4y2o1Y7umEvlGgzjCIeDcN2xKN1SOjpuwdSjH93pStQrEv4qeMT/SvYsvKs0gslSwWpmfS9DMxYvsie3OgTBqm8WksM4i5v8fb11hGBmMfMrsHsdRdjV9XdODrkZ48LpmymDjw+ERtVzJAjNmXOWL/WFYNJROJeZzj+t9gX9TnpgwmSiYcy4weyjhtiqB/c1Fem2GbG7MvslnKoGLKNkNMiIGSNUT5V7Enpa6WdTZlTTGxtByXbrAvc/ad6/ZlymYylknBnB1A+ftYtgxl7B97Nq/3jXJfU5+Z5hilLy37np9RyuxhHrO5vaMjpkwVN6VAM43rpsQxpiwgyvivjE/KuKXYMtkXZ7EwPxs3ZEkxjxcOyvxmMeaP2dnY/Hg9Uwizo8wdlLloHBvF7qjNhfoh+DuMws9Vy/bloDK1VbFfJaMNjRljvzdnqeAsQtTX5p8tM07ws2m2I+X3N817nEXGlO9jLEuDOWuF6VlUTZgab1YC7q133udtUaUS9ip7xETdnKC9sroG4aEhoG3U5tZWfl+MDDtt4QKUlpejpqYWEWHh6OntQV//AKKjItDV3Y3SsgoE+vujoakJD23fyoOerZbpCjhbrf9s60VG9XdXavH95EC4q1WzvYycJwSEwG0gwB44bxeM2gHv1XTgiTCv23AX619S8cBt8nfDn8vb8GykFxzmY1JX66ORK95mAqeae1De249PR/nc5jtZ7/KzEnC0/UmKVSmkxt11OuvVah5d6X4WcC+VtCDSRY0dQfMrXc88Mi+pqhCYFQFlC5U8uv9Z0IRvJc6PDxksBVx+lxHhLmq4OMgCcVZGICfNiMDFdj0yWw34cpzvhF7XGV3sDh08KwF3h+o2L25zPwu4D+o6oR8cwbMR82N1Py8MSiopBKxAQBFwKjs77KnpwGY/HTw1ti+ELAVcc98g6EUCHyfb3YGxQlfJJWyEQGa7nncxE3Qa6BznxzujIuDmaDz3t4DrgrdahUWeWmgd5s+Xw3PscjldCNg8AUsBV28YgH54BLFutvsxmALUUsAZh0ZwpKkbu4IlHpzNG9w9UEEScCHOjshsN+DheWJzIuDmaHj3u4Bb7OnM7w2s85PgxHM0JTldCFiNgKWA6x8eQUF3H9I8tVa7/u26kKWAI2/Iv+c34ttJ/iBPohQhcDsJkIBL0DnhF8XN+E5CABzmQeidSQUcfalHX4ZIuTWB6Qo4+urm/KUrWJSaYtNhUabb3/QRwwd1XXgwUAd6F+6r8X7z5r2B6bZRjhMC85WApYCjNrxf24HdIbafkcFSwFG9f1/WiucivOA0j/K5zlebud/rTQIu2d0ZBV1GhGrV8JsHW/eTCrj7vTNn2n4CaTAa+TQKIUGfDlsW+ntJeSU8dG4czHe+F0XAPRLsjnMtvVji7TJvgoXOd/ZSfyEwFYHxAu5/y1rxfIQ3NCrb9mSNF3B5XUa4Otgj3EUzVZPl70JgTgQUAUczN22jrva13fBlSkNFwM2py6+fPJWAoxh3Hx48gg1rVyHQ389Kd717l7EUcK39Q2g0DiLFw/nuVUjuLASEwBiB8QJuf30Xlnm7wEdj2y9njxdwQyOjuNJhwFJvF+ldIXBbCSgCTquyx08Km/CNeL8b4iXe1pvP8uIi4GYJbvxpUwk4CmSoBEScT6nCJsNjKeCGR0fxH/mN+PukwHmTc9FK3S6XEQI2SWC8gGswDqCidwCrbNyrMF7AEdwD9V0SqsgmrezeqpSlgPu4sRuJOieEaNU23UgRcFbqnqkEnBJZXol6rkQ0t4ygT0GOx0ekpsjjSsRzUyYEU8T88ZGqx0fAV7IR3HScRQR8y6jwSqRqJZvBWBRvc2YGJRK6ElGd/v2ooQc7zZkYXq9oxfYgd7g72JuiwU+SiUFpP2cY4MwDpkwMVDirgDkitZJ1QIm6T1H4lWwVY9kFLCLnKxHpOar6MEVAvx7J3JKFEiFfyW6hRDi3zFahRCJXslWMZWi4KZK5OSuGObr39WjxpmwXY5kYzJH8LeuttEvJKEHto2/YlQjvisi/VSYGJRq65TkK3xuyCpgj7CuZPCgiPUXtt4x4PhYp3xzRfiwTh/KzuY2WTIjdpPalRHs3t13JTjEWFV6xQ/P1x7IK3CITg5KNQ8kYwAzNmScsI+aPz8RAP9P/Ff5jjCjTh4OKWZiyPpiyByj9ZsrUQFkFTKyUqP/jMzGM2Zc5e8n4Z8fy2bLMpqKwGMuwYMFCOc6Ros/393NkfMvjlAwQlpkYKPuJkrWCMjEs83TmzCA01lD5sKEbu4Lc+TlSMgiQzVlmYlCOVaLBKxH0FXZK9hDLbAKc4UDJVsHZIRw4Sw/VTRlPxtvX9ewllEHmehaL3r5+XOwawBovp7Hfv1HXg2dC3KGxyOBhOR4RK8ssLEr2DLruGGPqQ5VqLCPE+EwfSoR8yuhBGRomyhhjGq1M0fJvyMQAsP1wRhUap0ZNmRjYppXxyJytgjMdKOOBkh3Cgp0S7Z/GZiXbzkTjlymLiSlLipJNQGEwlt3EnPVibFwyP3Pj2fHPjo4mO7dgpDyTln3PmRjGsgqZMslY2oyyQU8foNjZmzIxKIUzXZjHOLJBhRX9a7qXKSvKDZkYlDqZx4XpPDOmTEXjMjH0X8+iY5klRbFDYnClewCxzvbw1Dqjf3AQZ9uNWONFz5DFs2/u05uyZyhZUMyZR8YyMZjnKIUD/96c652tyWIeVObDsawVlpkYVKoJ3zGflYAzBfG1Y2GhCBEr6aB5e5mpBNy8bdgkFbf0wNEhg8MjyOkyYpGXbHXca30t7Zl/BMZ74KgFhxu6sTXQtgOuT+SBo3iTK71d4etk29u/889KpMaWBCw9cPT7d2o68Fiop01/nDdjAdfX14839rzDCew/+fQT+OOrr2PXjm3w95v/73XNxZzvdwFH7P5c0YbnI71t2uDn0sdyrhCYLwQmE3Dr/Fxt+ovOiQRcZe8AOgaHkD4PwqDMF/uQet5MYLyAO9TQjXRPZ5v+GnXGAs5o7MNrb73NnuQnHnsEr/11D9zcXPD800/dRCSvoBCU0D48LBRL0tPYTUrJ67s6u7Br53Z2/ZKbm1yGtH1BrmuT+1DFruH5VETAAa9XtmNboA7eNv6i9HyyK6mrEJgNgYkE3OV2AzzVKkS52u4XnRMJOOPwCC606bFBYk3OxhTknGkSGC/gKBNIdqcRDwTYrtd6xgKOWBgMRt7fpvcAurq6oFI5wMf75nRKFy9loaqmBkajEW3tHQgKDEBDYxM6OzuRlJiA0vIK3l9etngRzl+6xHv+La1t+OwLn8TCBSnTxG4bh4mAA2oNA6gzDmK5fDFmG0YptbhvCUwk4Fr6h3CxTY8HbTh38UQCjjpRPmS4b035jjV8vICj14TeM2+j3rFKzPBGMxZwJMbeeOc93ib71DNP4a/vvA96B/2ZJx6/6dbkfXNzc2MvW1b2Nbjr3EwCrqsbOjdXhIWForKyCrt2bMfHJ06ioqIS6WmpaGpqxgvPPTPDptzdw0XAmfjvre3EIyGS+ubuWqPc/X4nMJGAGxwZxZ7qDjxjw7mLJxNw79R04rFQD3k943437NvY/vECjm51oqkHi7y00DnaZh7hGQs4Cla7b/9B9r499vAuHDl+Asa+fjy6a+dNaOl9OfrQgb4yqaqugb+/Hzo7u/iLKp2bG2rq6uDp4c7/rTcYMTQ0iJ6eXvj6+kDrPL9iik0l4OgLn9KKSoQEBcFFO7/aNtEzM/4jBuWY92o6sTNIB41ETr+NQ41cWgjcmsBEAo7OsPUPGSYTcMebujkVmKdaPmQQ2789BCYScA3GQd6+322jTokZCzhCp3wSq4QxoN8poSBuD1rbv+pUAq62rp4/H6Zt4/WrV9p+g6ao4WQCrlLfj1r9INb42X4U63nfCdIAITAJgckE3NmWHqzycbXZ8XoyAdcxMITzrQbsCLLd95HEGOc3gYkEHMU4/V1ZK74YY5vZk2Yl4OZ3N92e2k8l4CgTw7mLlxERGoz42JjbU4k7eNXJBBxFTt9T04Gnw29+J/IOVk9uJQTuawKTCbiSnj7mEuvmZJN8JhNwNJH+paIdn47ytsl6S6XmP4GJBBy1KqvDgBSdBmqV7W2jioCzkt1NJeDoNnq9AVqt87RXv5ZBEK1UTatdhgTcvrquCd93O9bYjTW+rnC0t+28i1aDIRcSAjZGgAQcZV1QmYNkK9UzDI/gjap2/E2kbQohEnBnW/XY5O92E9F9dZ14yIY/wLAxE5DqzJAA5T+ldJCUSsuyUJpIWvjQnHa3y/idThFwVuqRqQQc/X1oaHhGd2voG8TlDuOMzrHc3p7RiTM9eHSUk0xP9Gl/nXEA51v10DjcvRULx/+maOB3WUMqkd1nitdaxxMHJeq5ta45m+soGUdmc661zlGi61vrerO5zp2yh96hYTwZ6gH7ca/9U/6Tv1S0wcvp7qYImsweqI9iXDVI0t3sIaSQDjVGCiJvnWIL9qBkwbBOi2Z3FSU7wt0cKpVMKnfzVSzj0DAeCeHO418AACAASURBVHaH2pwpQaE5jFG8WtEOb6fbH9rsVvNWkoczEty1N3SyCLjZ2fxNZ00l4Kx0mykvo6TmoLQld7PYQoYOmxgclfRgd7EzbKEvlLRUdxGDTWSNsYm+GBnhVE93s4g9mOjbwhhlC3WwBQGnpL+6myJypjYhAs5Ko5hNCTgOhiwDtC0MTLbgebKFyVLJHWilx21Wl7EF8WQLdbAJezDnuJxVR1rpJFvgYAv2wMLFfryv1kqQp3kZEnBU7qbjQQTcNDvrXjzMVgTcTBX87eoL2Z6QFbalbdnCRGULgt4W6mALfWEL44Mt1MEW7MFW6kDjxd30ft2x14+mmHRn0h/igbOSgplKwGXn5iElMQEqK3zJQvcqLCkDeTXaOzo57VhocCBOZ2QiNioCFKtv3aoVoLRnJ85lwM3FBf6+vqioqsYDG9dZxTs3MDiI3PwCjgHY29sLd507IsJCkFdUjODAAM6qkZqcyHU8cvIMosLD0Nffj+bWVqxYsghurnN/IXRgYADnL2Xxu4XE1c3VBe7uOtTU1cPbywt6fS8S4+KgUavx4eEjeGDDWlRU1aC1vQOJcTFcz7kWat/FrKsc23BocBDDI6NwddGivqEROp0bs46PieaPV373yut4+rGHUVZZxVtYwUGBCArwn2sV+PyrOXn8b0dnF7p7epAYF4u6xkZ4ebjzi4DRkRFwcXbGOx/sx7Il6SgoKkFMZDg8PDzg7WmdwMsXL1/BwMAg2ru64KrVIiEuBhXV1YiJjGQb8fL05P45eOQYlqQvxNnzl7AgKYH7LyEu2iocDh49AQcHFZw0Gs7yEhjgz9ldwsNCUFPXAJ2rKyLDQ7F3/yE8uHULTp7NQGR4GFra2rFy6SKr1OHM+Uxo1I5wdnZCR0cX/Hx9YOzv48mJnkknjRoLU1Lw1nsfYNO61cjKzkFqShLKK6qwesVSq9Qht6CQpkNOX1hTW8c2SP9tMBqgUWu4LsT+4NHjSE1OwokzGXhy9y5czr7Gz6c1Sm5BEQYGB2DQG9FrMGDRwgXo6u7G6MgohkaGYQc7fg5PnjuP1KREvP/RQTy2awd/rb9jy0ZrVAE5BYXQ9+rh4OCA/oFBxMdGQ6/Xs51SXchDvnxxOo6fPofkhHhkXrmKlUsXY++BQ3jx2ZvTQ86mUkWlZejp1cPb0xMdnZ3wcNexx6uuoRGDA4M8LlJ76d4uWhfUNzZh9bLFePXtd/G5Tz03m1vedE5DUzPHWHVxcUZRSTn8fX3g4qJFcVkFPyv0quS6lcuRX1gMQ58RZZXV2LFpA46eOotHH9pulTpkZF7m9mqcNOjr6+P5kMbw/OJSaDRqOGs0WJCcCPKM7v/4GJLiY0HzDNV7+ZJF/DzPtdCzRs+Br483mltaERIUyHNYU3MLfH28+DWL2KhInk8+PHwUCbHRaGtvx/DwKBLjY03j6RwLxYMd6B+Ar683cguKEeTvBwdHB/TqDfDx9OCxKDw0hGPhHj5+EquWL0F5RTXSFiTB0fHG9/BEwM2xM5TTpxRweflISYi3ioAjA6dJqbqunidsEgPpqSk4eyGTB4f+gQFsWrcG5y5cMv1dpWJRQcJu26b1VhFw/f39qKiu5UHIaDRA7ajG8qWLUFpWAS8PD1TU1GDjmlW4cPkKmlva4O/rzQMVCZ7lSxZzfeZaKJfutdwCNLW0cnBkJycnxEVH8s+U6SOvsAjLFqWzkOno6ERURDjyCor4YaHBOtDfb65V4AEmJ78Q/X39/N9USMi2d3bxoFRRWY0laan8N5owKCsJiW/628LkJBYY1ijUVsonXFVTy/2/NH0h9AYDVPYq1NTXY0naQvT197Fwo1zD1H90HAkG6i9rFBLTVErLK3mgW5yWynXQuelQVlHB/OmeJDZdXVygc3VBU2sbkuLjEB4abI0q4L0PD/IzMDg4CI1Gw8KFFjgk6q7lFcBDp4O/ny/XIcDfjxdAxIKCjC9MTrRKHU6czYCnuzv6+gc433NUeCi0Wi06OjpQXVvP9kci4VJWNou82voGODlpOKg59ZM1SnZuPl+vsroGnd0mQe/loUNtfSOnNaQFx7JFC3E64yK/h0UCiybQgADikGSNKvCzT4skmjRJQC1MSeKg7bS46eAUjCoeE/d/fBSOjmoW/b16PcLCgpGWkmyVOpzPvMwLh+raOhYOMRER8PfzQWV1LS8me3p6OC7nvkMfw9PDg8clGq8c1Q7YtnGDVeqQnZfP41FPjx5Dw8Nsg0GB/riam8cL3eqaWjz/1Cdw9OQZZkKbifx89g/gkZ1brVIHar+7TofG5ma2N19vb0SGheL85StwVKnQ3tmJx3btxNFTZ1hckM34epsEzdZN661Sh/2Hj5qeuc5OtjkaF0mQFJeVc4QGWuiQoMovKuH5zcvTA93dvRgaHsQDG9dbRcCdybgIby9PDA4NQq83IjoqnMdImiNooU9jIS28KY97fWMzpwilZ5iOIfulbFJzLflFxexgIFuvqq5lWyBxX1lTa3JC6HQ8p7e2t3MdKPQYzbWhQYG8KLYssxJwBJ+Nv7sHTs5OCAoIsIoomCuYu3n+VAKOJgoPD3er7PETfxqgyXNA3iZ6KMiLQittR7WaRVtifAwbBw2gtQ0NcNFq4ejgaFr9WekDh7zCYhZBJOLIk0QPHE0O5HWiVWRKYjwPFn4+3mhsamajpRy6JGJoQJ9rIQ4lZeU8+dbWNTADmpwpVRt5OWh1SSs6Em80cdCg4OGhYy+Is7MztM7WiYVFK2wfb2+0d5gmxrDgILR1dPDKljx+xIH638vLE83NLdx2EnQ0GFgr40h5ZRWcNE7oH+jHyOgIosLDWTDS0ppEHXlDqQ9o5UkClwYrKm5urmP/Pdf+oD4gzwp5WKhvyNPVa/Z+kMilRQbVidpNdkG5kSk1H/EgQWeN0tjcAsoAY29vxwsGWk2Tt0XloEJOXgGv6snjR4KJnh3FXkhQW0vI0sq+R68fEwPU/1QHWryUlFfwSp740CBNkxl5Frp6etlTPlFO6dlwocG/hRZOfj680CMP1+DgEE9G5AEg7xtzUdnz5EmLQvJEeHro4OE+dy8D1Zk8J6UVFQgLCUF9YyN7XIi9wWBARXUNoiPDYWdnz1+Kt3d0wdlZw4sQGh9IfFqjUHuLS8sRERbKOxA0CdP4R3Wrra9HQIA/XLUuGBoeQnt7J1xdSUQaeJwK8rfO4orGGxojaDFBz0HagmTOUEQ7AW1t7fDz82HBT1468liSgqPxgrz2JGisUWjhRAsYsgPyziYlmHYmGpta+JmkcYHGb7ovPRskYukZonmD/maNQqK0pLxybM4gGyS7aGhsZg95S2s7e2RJXNOCjp5lKs5OTjxmWOO9bsrjXl5VzdenuqSlJPH8RXMDjVdVNXVsIzQ+0eK6rr6Bhb2zkwb0mh4tBudayP6LSsuRnBDH9pCSlMBzNi1skhPjkZtXiPSFKbzIcXdz4z4ibx2NH9QfcxZwV6/lsDpct2olSE22tbVh84abVTq5qmlCI5elg0rF/02FBi9aIdPArWRzoByp5NK11uAxV8gzPX8qATfT68nxQkAICAEhIASEgBCYjMCMPXC0Z73vwCFs3bQRv/3fP+JrX/kCLl66jOTERFbwluVS1hWEhoTw6u5sxgWsX7sKV7JzUFBczKtdB0dHTly/ecM6FJWUICIsDEsXW+f9izvd5SLg7jRxuZ8QEAJCQAgIgfuXwIwFHLkac/PysXhRGmpq65FfWIjVK5ajqqYGK5fd+AJuZtYVdp93dnXxNs7Zc+d5GykoMBBarRPSUlNx7MRJfnepoqoKG9euEQF3/9qitFwICAEhIASEgBCYJoEZCzj6amffRwew7YHNyKP9/NQUfHzsBDauW8NCzLKQKCsoLOZ3v+JjYnDp6lWEBgWjurYWSYkJKC0t43dAQoKCeB+ecoRGhIdNs+q2dZh44GyrP6Q2QkAICAEhIATuZQIzFnAEo6mlBZezrsLPz5e/4qEXuBdY6cul+QpbBNx87TmptxAQAkJACAiB+UdgVgKOmkkfIiiRrK31VeP8w3e9xiLg5nPvSd2FgBAQAkJACMwvArMWcPOrmbe/tiLgbj9juYMQEAJCQAgIASFgIiACzkqWIALOSiDlMkJACAgBISAEhMCUBETATYloegeIgJseJzlKCAgBISAEhIAQmDsBEXBzZzjmyqRUVVQoAr81Mg0oLlKKQD2dBNR0DEWLHp9oYboRrClKOsX5o2jTdA5FtKeo3NM930ooJ7wMff1cV1+Pru4exEVHcZqku1koEPW13HzuF6VQHMSoyAirZbq4m+2TewsBISAEhIBtExABZ6X+ma4H7re//xOnidm2ZRMLPfoQREntY+AUT06cV9PV1QWUnaK0vAIb1q7GqTPnsDg9DfYqe07HRelZKLcfCQlKE0X/kuCiFDCUGmdkdHRMSFBKFkriPVU58PERnDh9Fp95/jmO1/dfv/gVnn3iCU60ffjoMahUDlwXRVDShyz031R/yjVJbTEljR7A6bMZeGDTBlCKp7CQYP7ohdJsUUgZSiVCx/h4eXNKmakKXffI8ZPw9PRAaHAwh615+MHtnLWD/van197AC889w/egGIWpKck4eeYc1q1exUnUz5w/j/CwMCTExsBepeJ0VpR+jI6n/1O6qdHRkbF2TUd8n794idMwHT91Gju3PcAMKHD19ge2cAqajw59jEce3MH1O3fhIlYtX45XXn8Tn/nUcxwzkdpBNqMkJ6YcifRl95JFaYxDyVByLS8fC5IScfz0GaxfvYqPVz4eoj6nn5V25BcW3fdfg09lS/J3ISAEhMC9QkAEnJV6croC7mvf+g4WpaWhrq6exQyJB0cHFZYtWYxDR47DwVHFQoLyr5FQc3fX4ZEHd+L9D/ejrLyCkyGTJ8rN1RVaZy2WL1uMzevXcR5OL8o1ak6E3NLWfoMXkBL4Us7FWxUSI5SUnkSir48PfWrMyZUjI8Lx01/+moMsnz1/AS5aF7S0tvKlKP5fxoVMpCQnIeNiJqdXo8wczlpnfPv/fA1f+ea3sSgtlXPKbdu8EafOZWBR6kJ09XRxYvkdWx/AkvRbJ/CmeIJdXd1cj+KSUixZlM71WLNyBeczPHD4CGcGeW/fR5wHdGR4BGWVlfj5//djvPLaG3ji0UdYNP7p1TcQHxuL2NhoFnaVVdU4dvoMhgaHOOE1CU0KOv3Fz3waAVPkQaTMIpQYur6hgcVoZHg45+zbuH4tOjs78dpb7+CJ3Q/jr+++D2OfkUXWuYyLOLR3D77/bz9mT11zSws2rFmD5UsX4+cv/Q96e3qRkpyIC5lZ7AVNjI9Dbn4Bh+mhROiUcDw9NRXFJSXYtGEdLly6jId37sCrb77Fgpu8p3//zf9jJYuWywgBISAEhIAtExABZ6Xema6A+/ef/hwvfvIZnDybgYbGRgQHBnKy4CPHTrAwodyyu3Zsw96PDuDJx3ajkH7euR1vv7cXeoMBvXo9CguLEBISwinIrl7LZa9Oa2sbfH192HNDx1ByXMW7Q0309fZiMXarwl47gD08JCLp/yQ86Jp/fv1N7H7oQZT/34wZJ0+f5aDNKUmJoLy4YaHB7P1bkJKEPe/uxcMP7sSJ06fxtS99Ab9++X/h4eGBkeFhTli8OD2d25aTl4/tWzZzEOfoqIhb1ouEYXhYKK7l5HEQ6Gef+AQuXr6MTevX4cSpsyivrMDIyCgWLkhGTn4BJwknBp978QW89uZb2L51C2pqarkeJHaefHQ3mlqaUVFZjbaONk6ivCQtjX+3cd1abu9UcQ1JwFEi7A8+OohdO7ehs6sTDQ1N2LJpA9+DuDmoHLA4fSELy2VLFuHNt9/DKy//Gr9/5VWEhAQjNTkJ73/4Eb78uc/g2MnTaGxqYi8lbYGnJCWxRy8xIY5FdWFxMdatXo3X3nobn3vhefzh1dexfvVquLg4IyYqCldzcmAHO2x/YLOVLFouIwSEgBAQArZMQASclXpnugKOPEi0aUfbp2qNGkdPnMLq5cvg4uLC3h8XFy173/S9ejS3tiIwwJ+9QyTIuru7oXJQcV7Zy1ez8fkXX4BGrUZIcBALqO6ebp7EDX19/I4YCTASI64uLtA635glY6JmHz91Bh2dnUhPXQDadr18JZu9QOT5KigqNglA8zt2tEW4ZeN63r6lc/x8faFzc+V6NjY183ZndGQEaFuPBOHg4BDXkzxmkWFh7LVqam5GSHAwyDt4q0Ji7NjJU9i59QHeHm5ta2MxS1ul5NkLCgpERUUlunt64Orqyt426g/6O72XWFJWDq2zM4xGIwefdnfToaS8HC5aLTMiz5WHuw79/QPw9vLiqri53XrL+dz5i3wv2nol8bx543oUl5YhNjoKpWXliI2J5rpR0Gu6j16vx8DgIFYsXcIMjAYjeg169tzRVnBOXgFUKnuMYpQ9gtSvxNvd3Z23ZFvb2rnNAX5+aGpuYdFPHEjYku3QPamvkxLirWTRchkhIASEgBCwZQIi4KzUO9MVcONvp7zPNJNqkOAgN43a0XHsNCWwMtWDJn7LDw+mG2g5K/saMi9lYcfWLbx1u+e9vdi8Yf2E6c3o/TwSl3eq0FZlQVEJ7TizaFySnnZXPxYgUXkh8zKFtGZvJG2f5hcU4ZknH5/S03mnmMl9hIAQEAJC4N4lIALOSn07WwFnpdvLZWyAgPJRgQ1URaogBISAEBAC9zgBEXBW6mARcFYCKZcRAkJACAgBISAEpiQgAm5KRNM7QATc9DjJUUJACAgBISAEhMDcCYiAmztDvoKlgFNeQLfSpeUyQkAICAEhIASEgBC4gQC9+87RI0ZHR0fpiz36Wk/KzAlYCjj6aMDezn7mF7GhM+iLScuPJGyoalIVISAEhIAQEAL3PQGK5kCRK0TAzdEULAUcBcydKubaHG9320/v6+/nUCdShIAQEAJCQAgIAdsjQE43Z2dnEXBz7RoRcHMlKOcLASEgBISAEBAC0yUwLQGnJFI35Y005WmcbaGI+RSY9F4rIuDutR6V9ggBISAEhIAQsF0C0xJw3/nev+CzLz6PN99+l/NuUjT74KBA9PT0wNjXh6CAQFTVVCM4MIjzaDY1NfMx7e0d0OncOBMAiT/KPXn42HE8TEm+h4aRnZsLf19fBAYEcBT6qfJP2i7GGz9imO4WKok+O8qWYIMNky1UG+wUqZIQEAJCQAgIATOB6Qm47/4zR5sPCgxAREQ4auvqkJtfiMqqKjz5+KMIDQ7idEWXr1yFVqtF2oIUtLW3w95exWmWvvvtv8WhI0cxNDSE4tJypKYk4cMDhzndUER4KGcNoPya/+8PvntDBoH51Esz8cB1dnbhVMYFqNVqpCTEQ6t14tRXer0Rnh7unH4p0N8PtQ2NUDs4oqCkBAuTE2Ew9rHgJXFFie77+vs4ob3eaITO1RUajXrayCgRO53r7KRBZU0tYqMibzhXEXAGgxHdvb1wctJwiidKOVXf2ISgAH80NLVwjlVK+RXg72dKaxUYwKKeUmf5eHmiuraOj7XMyzrtSsqBQkAICAEhIATuUwLdPb3s/KI0lZXVtYgIC7lhB3RaAu6f/vnfsHXzJjg6OuDM+QtwcXZGcVkZT9g/+ufv4d29++Dg4MD5MulGq1YsR35hIYICAxEZEYEtG9ZxMvTUBSk4cPgI5/Sk3JmUG5PSMZ0+dx4atSMnP6frzMcyEwFXXVOHP7+5h3OhslCrb2Ch26s3wN/PFyTwwkKCUVPXgK2b1qGguIRF8pmMTGxatwpFpeUskCmvVGpyIppbWjm36Le/9qVpb29TTtETZzP4Y4v0Bcl8X8uiCLh9Bw/jyrU8DFGCezs7FmKd/z975wGW1ZWt/1fBQgfpvSogoDR77733aExM7z2TaXfu/O/cybRkJr0XE3vvvWBFEUUFpClI70oX6f/7LjwEDRbwS1H3fp48GDhln/fs7zvvWXuv3yophbuLMy5mZKCbpweSklMwd9pkbNi2E65OjkjLzJJanv7dfaSeat9eIZg4ZuS9eFtVn5UCSgGlgFJAKfCLKMAa5zv3haFjx07w8+kGV2fH6/pxRwZu974wjBo+FAUFhcjJy0dkVBTsbW1RUloqxi4nNxfHIk7AyspKimwfOhKOsaNGIi09Hfod9DF5/DiZbl29YRM83FxRVl4hBcSHDhqAHXv2wcjAEHX1dZgxZdIDEYErL6/Al98vl+lmWysrmJiY4FxCIi4XFct0M122sZEh0jIyERTgj8QLycgvvCR/c3ZykFqgLH7OyCUjYizSzvb0oofv2MCx7NPO/QdRdbUKY0cOk/O1ZOC279kv94pF6ktKyySK6uRgDxNTY0THxqGLhQVYF9TEyBjlV67IcVhsnW8NPfy6o7i0BME9AsRoqqYUUAooBZQCSgGlwJ0pwMDJwSPHkJaZianjx6KLhXnrDdydnQry0I5LSEJ9fR38u/vesZm40+P/mrdrTQSO10FTxGhWSwkh/BsjkYyqsUg6zRa343834kn2HjgCK0sLBAb4tUqe8ykXxQiaGBkh+lycRMlaMnAtHZRTpESMkBXHa6iuqpYp1praWonSLVuzAckXU/Hn376OqqpqmSq+HxNXWiW42lgpoBRQCigFlAKtUICza3yucqbudHQsQgJ7/HQGrhX9uu82ba2B05UAdXX1YFIwo3G6bHeTxKAZuXudhadLPdWxlAJKAaWAUkApoEsF7mgKVZcnvF+P9UsZuJ9Kz7sxcD9Vn9RxlQJKAaWAUkApoBRoVEAZOB2NBGXgdCSkOoxSQCmgFFAKKAWUArdVQBm420p0Zxs0N3CcOrzXa6FWVVehU0dVSuvO7r7aSimgFFAKKAWUAj+vApVVV2FkqGqh3rXqzQ0cExBo4t5aVYhzWdVy7CVP28LCSE/+XVpahtPR0aiprpHMU5ql0cOHCw9uy/ad8HBzE7aad1cv4b5t3blLkhosLCxw9epVTJk4HucvJONsTCwMDDojJy8P5qZmkhhhZmaKCWPH3PX1aAc4En4cjg52km1KJg0TGJzs7QUj09XTAxfT0iUTlrw4NmsrK6Smp8PP1wfn4uLh7OyEtLQMpGVkYOyoEcK7KykpQUpqGpydHGFrYyP7MQEmOvac4FOYpcykCGtLSwEd19XWYsuOXZIYw98XFRXD18cbiecvCK7Ey9NDjlFQWCg6ZOfl4vKly6LjwaPh6NbVCz7duso2zKI9fPSY7MN1g+TudezQAfodOsjfMzOzUFRSIn1LS01HN++uSEq6ADtba8TGJ8q1Bgf2fKASdHQ2mNSBlAJKAaWAUkBnCjRoxQAaGhoaGI4zNDDQ2cEfpAM1N3DM0KThmvtJDk5erBIZjv/JGVYmjQYuLiFRjE7UmbPCxaMxCQkKRM8Af6xau06MWnxSEtxcnNHDzw8pqanCeiOo18vDE4E9/LF+8xbZ/pMvvsYTjy7EN0uW4qFZM3E25hwWPjRHZ0kNV65cwcdffIUe/n4C8E1Lz4CJiREWLZiPzKxsyZDp5uWJF994S4zQmJEjcOlyEebOmIY//uWvAnGm8cvOzoaTo6MAfyOjzqChoR5eHu7yO7aqqir86/0P8ewTj2HD5q2ws7OVY7GqBduRY8cRGhSI//3HO+ju641eISGIiT0nZlZLltiwZRsSk5Lg6OCAi2lpMDM1FbAwTdvcmTPEdDGjl8YvMem8VAmhWZw6cXyTXhu3bsfEsaPx57f/gZlTJ8t2Xl6eOBF5CiOHD5X7RhOnmlJAKaAUUAooBX5JBeg76mjilIG7u9vQkoH7bH8xTqRUwbhzO/x9lhUMOzVmipKptu/AQYk6Xb58Ge3atUd9QwPmzZyGf3/0KZ5ctBA7d+8Vxl7MuTgxTYwWEX5cXFKCwQP7IT+/UPAflpYWSEtLl0gWKyYwajV7+tS7u5hmexPIfODwUWG6nYg6jbzcPMyaNlUiiCOGDsG2XbsR4OeHM9ExAmVm1HDfgUNYMHcWNm3bKZU2unt7I7+gAFZWlti5Z58YVpZiCzt4GI/MnyfGipG9xUuXS+Qu5WIqCgov4dUXnm0CO/P4AX7dZRuCj19+7mnExSeif9/eTb1dsWad8AT7hIZiz74wBPh3lyglzfQzjy+S7Wjmvvz2e9g72MHb01P6+sIzTzYd4+ixCAzo1wd79och+tw5TBg9Bjv27hWTGtgjAPsPHML8ObN0ZpB1dqPUgZQCSgGlgFLggVKgzQau0XwUyZTdvVo9QZd3uiUDd7PjUztOAzICVHHlijDVGMliubJyKVvVWSJS5LTxJ7evr2+QShg0OjLn3a4dysrKYcIoEn8aG4HVFTp17iTTirpqPDd5dDwmzQ/PK4y6qirhu/F3GsKkrq4Oenr6qK2rlWgc9+NP7sPj8Kew4/T1ZR+W2+I1aU07Jo/D1nxcUV/uw5/8j3/Tfqftz/00Xh4jbYzM8bw3Hot/47FOn41BV093mJmZNfVBOyb343bk3Gk/uRHvE69JNaWAUkApoBRQCvySCrTJwLGEFiMihoYGKLx0Cd19fCRycmPjw52mgkalJWCttj23KSsvh4mJsYBrdc00+zkEbo2B+zn6o86hFFAKKAWUAkoBpcD9q0CrDRx34LTZqGHDkJqWDjs7G+zaux/TJ0/8UcHyyFNRUvKJ02fzZs2QBeg0auZmZlJPk3VTuabou2UrZW0UoypHwo/h6ScWSXkolo5ixIaRGi7Wt7u24P3XeDuaGzhWI+Die9WUAkoBpYBSQCmgFFAK/BQKcKZIKjrd6Rq43Lx8HDsRiaAe/rCxtkF4xAmpjcl1SSOHDbmuj5FRpyWrMOL/FoBzEXqv4CB09/XBmg2bpNB50vlk/ObVl7A37IAc63LRZZw4GYWgnj1QWlYm65eGDR4khvGlZ5+SrMJfa1MRuF/rnVH9UgooBZQCSgGlwP2nQKsjcJwW3bFnL0YMGYytqpDwdwAAIABJREFUO3djYL8+CI+IxPjRo2RKtXmjcTtw5AiuXq2S6NvEsWPATEGu+crNz4OXuzuefnyRLBi3sbJG4eVLUkOTa8Ays7JgamKK8WNGYfO2HVL4/aVnnvrV4huUgbuzDwfXqXGK/FZT6nd2pFtv1Xzdmi6Op46hFFAKKAWUAkqBX5MCrTZw7Py5+HhEx8ajf59eOHQ0XKZByfi6sTG8py1e599kEXt1DUrLSpGSmo5ewYFNC9yb76t1Sp9AXC52r62FXvv2v+q1cS0ZuL9tvYyo1Cp00m+HTx+1gUnnxmlVsty27tgFdzdXQVpwjeDo4cPkOpnl6OnpjqjTZyWiadnFUgwuI5LU+UrlFUwaNxZ5+QXYtXcf/P18cTLqDAK6+4r5dXFywuCB/XU2xoiWyc8vgIODPfLz82FibIyKK5Wora2Bna2tJDKwkWen175x6ri8vAK2NtZIupAsPDWaNk6P07j/670P8cbLL8jaSf6O2Boado6TwkuXYWNtJZm2XBfJTFXy45wdHZGbny9T6vp6+sJ743HPnI1BSHCgaGHQuZNk8lZUVEi/vvruezz28AJh47FYLBM/tEb8iZGRoSQjsN9Ojg6yHMDezg5l5WWSMEI+3JFjERg2eCCycnJg1aWLbNu+fTs5vtYuFxU1JprwcxEXL5m5zBp2cXFGQUGBXCM1y80rgKuLE9IyMhGfkICxo0bKIajVh599gccfWQDWteW2HTp2kGUHNlZWws2jNiUlpZIcYmRoJNw/ImbYL774VNdUo7i4WPrFcDrHF+8LlyHwmLwmff0Osg3HnHbPdDZI1IGUAkoBpYBS4GdXoE0Gjg8UPhjPxSfAw91NImV8sD3IrTUcuKTzF2BuboYTXCMYGwdraysB5ZI/tmrdBsFtNNQ3gPVICfIlDoPrBH27dUVFZSWmTBgncF9Pd3csWbEKM6dMxur1GzB18kQkJJ7XKQeOIFyaIsk6LirC8RMn4ersLKYzJLAneoUESzbo+59+DhNjExgadBb+WoCfL9Izs9HVywPRMeeQnpGBmdOm4OvvluK1F5/Dex9/hqGDBohp6x0ShOraWuwLO4gZUycLKsTd1QXZOXnIzs3BgL59BDnCdZS79u2HtZUlpk2aiHUbN2PS+LHCwiOIl0aGmvC4HJvsH0HDfAnQkmzY1w8++wJjhg/Dzr37xHjNnjYVW3fsxKzpU7F42QoM7NcXgQH++M/Hn2LujOngUoCioiIkXUiBsZEh/vjWG2LMaKqpf/8+vWXaf8fuPbC1tRXzSVNHzh/ZcTR2hYWXBJlyJiYWWdnZeHjeHPm4lJSW4uvvlmD29Gk4HH5M9uvXu5eAnHlMmlYassXLViInN1eug/ejd2gINmzZik6dOksmrYWZudwLRsEzMrOQnpmJ2Lh4kOPHaOTs6dORkZUpZnrooIEP8kdVXbtSQCmgFLgvFGiTgbsvrlzHF9GSgXt9RYFE4PT02mHNC/awMGyMwDECxAc0H7DGhoby7yED+sPd3Q1fL/4eC+bOwb6DB+Hu6grLLl3EIIUdOoyRw4YiJi5ODM2p02clChafkAQnJ0dcSE6RigN8uC+YO1tnVxd2+Ajq6+oEzltYWIj4pPPCffN0d4WJiQl608A1NOBv//o3jI2N4ershMCePVBTXY2cPEbNDCVClpefLzDdf773gcB9ky5ckMgho2w0s4wcksk2Y8okpGdkYumqNXIsmhhG22h6T505iwljRuOzr7/Fb197BRu3bhPztG3XHnmBMDIyQs8APwH57t67H3NmTMP55BQwqYRrL9loRMnWi0tIQn19nZge9uHQkXDJgmYlB665fPrxR/H+J59Lck5qegby8vKRnZuLLubmeOrxRwWFwooaK9euw7Ahg6UqBTl0jHAxWsy/OTo64HhkJCwtughHztPDHccjT8ryAGrBRgjjmg0bJQJ78PBRiW726x0Ce3v7Jqh2VVW1mNTY+Hj89+9/gw2btwmrjuaM60KjoqMxdOAAwc6w8eXq7Xfeg1UXCzg7O8LX21sikBlZWZIUNLh/P52ND3UgpYBSQCmgFPhlFFAGTke6t2YNHE1EVk6uRNeYuMFps9q6OnlgMzuXKBVOXVpZdpGfZMUJe6yBHLIamJuZc1YQly5dlmhd4eXLsLSwQHFxCQyNDHVaTYMJK8z+dXV1kegQo1lalm1E5EnEJybB1NgYkyeM4yQ59PUbp72FH1dVJVOqNDsan43RIRomRoUYNeOxuK6S03o0F+TNyX7t2sl0IK+fU6/8HadauS2PzX2rrl4V7hy10M5J9hvvRVxiksCHub3WL83AVVZyirGRT6cdl3w96s+oJ6fuG6f7q9GRjL5r/eIUN+PMzacg+TsaXE51cnuen8eQY129KlOXenrtm/h9vB7qwWvTGo/B38m5ychjFvO1/7RteGxGCzW9DAwMwOvQOHo8b/N1hY3XLesWUF1Vjc4GnaU/1JDHUE0poBRQCigF7m0FlIHT0f1rjYHT0Sl/lsM0X8N44wl5zRooVytn9bN0Sp1EKaAUUAooBZQCD7gCysDpaABcx4H7GbIsddRtdRilgFJAKaAUUAooBe5BBVrNgbsHr/En67KWZcsT8N+chmPjNKAqL/aTya4OrBRQCigFlAJKgQdeARIT6htUMfs2DYTS8gpcvVop+xJvwXVVbFyzpQzc9ZJysT4X9+ui3Wxal1HQG9eO3cn5mh+vrce4k/O0ZRttilpb33bj/7flmPfLPjcbB9rvNa34s63l+W61hOB+0VFdh1JAKXBvKqCmUO/ivhUVl0jBdjYuDNdAxpqBu3IwDNWJcWhnZAzTWfPQ7hozjSiHsENHENQjAHEJiXBytIerqysa6uuRfPEibG1sBEHRv28fSV44dfqMGBOWHiu4dFkyL7monQkGPQP8JavS17sbklMuwt7OFi7OzndxVTcYr7o6OVenzp1RfW2RPftP59+pU8emByMX4suDkkkJdXXo2KGjJBdwMT2TAPYeOCj8Oi7i5wJ/Zq5ye5o6bsNF/eSWMUGAv+c5mBhw5UqllFGjzkwu4EGpB7NfueifWrN/fECTlRYTFy/sNm7PSKjWEpLOw9XFuZE1Z2UliQVynvp6XExNg5mZqSRrrN24WTAi1FEDUFN7bkv+GrM5me3JczPZRGu85rpr18Hr5XXwp2Yoqc9129fWik5MXtD6ym35gdTMPzXYumO3ZOGSIcf9ycXLyc3D8CGDm3hvN1uHSJ16BgRItjLXKDLppF+f3nIttbV1AtfmNRkaGMq9ZF94TmpCrdkP/psZuGamJpLly+vmmGTCiWhfUyP3XNNSS0Jh8geTO7g//xYdEysZvxoTUDOkW7bvRP++vYWdF+DXXRI1JGHnWmNUm2ODuvA8vA4mnpAneSHlInr4d2/Si9ts3Lod3X294Whnh4xrvD+CwF985im5n0z6aL5ek2OOiR3sF+8Xk0O0xuQgajhkYCPuxtHeDswI1tPXQ11tXdMLG3/H5J2Ik1Ho16cXamsa9RaG5bV/8/+1a9fZh1MdSCmgFHigFVAG7i5u/+0MXM6j81AVdVLO4Bx2DHqWVvLvCynkiRkh8tRppGVmwrBzZ3nYsKzY6nUbYGFhDj8fH0SdjRbTNHniePk99+nq5YXgwB6CybCzsxXDMW7kCGzesVOqVtDEkTemq0oHZJPFnosXBAYfRkcjTsDIwEAMwKTxYxAc2FMeTH/8n7dhYW4qMNzS8nLBotC0nD4bjdCgQLRvryeGISExEUMHD0Ji0nlkZecgNDhIKm2wz2s3bsKg/v0E48EW1DMAaemZ8gBdunI1xo0eCcsuFjgcHgEPNxfh6Lm5uEhFEHLjCAhev2krpk2egD/8v7/gz3/4nZgMtt379qNPr1ABJ9NMkFXn5uqK09HR6Onvh9i4BHh38xJzxqzayNNnhHs3avgweLi5islkFRGen0aAOg8fOgh+vr5y/A8/+1IyVAlWJvLEr7svTp46DSNjI4HvVl69ImBhNhoa8uNo3IgXycnJhaOjI/8gcN65M6fLdgQHkxHH/ycDzrtrV0Gd7D94WPh61I1mp0eAv9wDGk+t5RUUiPFKSExCReUVTBg9Cn979z38/o3XpJKKi7OT6Pq7//4fvP7SC9i0dbuYjoupqWIsvbt6oXdoMAoKL0ktYt6LsrIyMZTu7q64kHwRDvZ28qJB+DI5hkePRwgGJic3X/pJGDH1Z7++XbIMv//N6/jm+6WYM2O67MP2v/98V/iGNGq89quVV/HHt94Ug11eUYEPP/0CUyaOF+adm7MLfH26CYqFZflWrF0PD1dXvPDMk3KssrJyvP77/8L//PF3yMnNQXnFFTH6777/EX7z2stYsnI1TIyMMXPaZNk+PikJ4cdPCHom6nQ0nJ2dMO4akPxcXAJ27w9D504dZQzwXpE/+NlX38o4iktIkBcMfiaJ0+EY/+DTL/CHN1/DqvUb5DPds0eA3CtCzqnD+ZQUjBw6RGefzbv46lK7KgWUAveBAm02cBomgpGGtk5P3Ov63dbAPfYQqk5GStTIeX/4DwYuOUWYabv27oexsZE86ObNnCFRoBVr1mLs6FE4fCRc+GghQYESGVm2ag1mTJmMyFNRGDZkkBgSJwcHrNm4WR4QW7bvwvjRI5GSmoqFD83V2UOCHDjS/nleYigiTp4S0+bl6S4miNFA/v7dDz/B5AljkZBwHiFBPSVSs2T5Kjwyf+616gzl8PXxRvjxCIkQ0pDQwE0cNwZx8QnoFRIiBoBss4iTJ4XhZm9rKxGVPqEhAs2NPheHhfPmYN2mrWIQaNp4PEaBWHHguScfw/rNWzFz6mTs3LMXo0cMb4rOkKtHU8xavowAMnpDNh3xGjQBpqamuHT5skCp27VrwOr1mzB3xjR5qGt8NVa6YBR0y45dEj0lhFeD4n7y5ddiaGjivDw9BdjLCBSjTjwXDRFZcWz80H27dLkYG1aY6BUUCEYIT54+I3WFx48Z3fTR2Lx9ByaPH4fM7Gx01O8g2JhN23ZIJYaikhI42tuLOeA6CHIDNYP4nw8/wYvPPo0Va9eJ2fF0d8O7H3yMN195USDQY0eOELbf1aqr9I2IT0wUvt+OXbvFlIwcPgwff/EVXnvhOdAMMgLHyFd9AzmGWXLvD4UfExQOI4I0VmT7mRmbokeAn4zlxKQLMr5pkAkifv6px5uixjwHG00lI1vFpaXyYsDPCjmGjOTRSB4JP46E8+eRnp4h94FQa457B3t7GTc0c2+99nKTXn9++x/402/flKoT1HPIoIH46z/ewWsvvYDjJyLh69MVrs4usj1B0IHykpAhSJYJY3/QfW/YQVhadpEIHMcB76GdrY38dLCzk/vF+3n46DHMnjFNosTvffw5XnzmCTkvcTndfbxlDPOe/eUf72D29KkyDlRTCigFlAK6UKBNBo5vyixOz+gHv6QD/H0R1KPHj/pDIj3hp3x43GjyaAAJsOUD4F5ttzNwtbk5qC8tAfT10dHNg7AyuVRGc06cPAUnR0eB+vJhWFZeLg+nEyejhLZPI0aTkJKahoorFcIy4wOOD+1uXl4SxeFD18vDXaJKrEBAUCtLWHl5NBoFXbSDR4+iovwK+vQKkalGNgsLCwH0XkhJlagMp50YnWDEjTw6RhA5HcyyUewfWXCMenl36yoRIU6VscwWp8Y4hmgI3FxdcDbmnBiT8isVwrSzsbYWffgg5APTwcFOmGac9uOYYvkrwosZKWPlCpo6cvT4YD0bEyvn0abLOL1KI8AKCzR8NIolpWUybcspSkbUvDw9ZJqSerJf7COn47QyXIwS0aQQOkxAMI0JozBsNAElZWWN7Dc9PXlQEwDMcW9hbi6miGZGa9ye44dlvFi2i9EjXgenbptP49Ec8Z6St8djc8qcfeU9YLUFgoVpbDglrUW1eH3JySlimPlZZSSOpptVOmxsrAQyTLYgxxwjVGyMQBobN5Yb66DfQfpx/kIKunXzwukzZ8UIa/dSr70eomPPoZuXh4CH2S++kBAibUhgcGam3DtGXMnp4/VxqQCjuDQ2rOTBv7ExWknjS2NNw8YoL+8bG6cmz8bGit4sr0bD7O/rK1o4OznIvWWUklFMrfEz4dOtmxyXETzqpZVJu3DxohhwzehyGvZMdIzcY5Y0o0HTGs99JjpaqqTwe4zX6OPdDTXVNTA1M8XZ6Fh0sTCX6dfsnFwE9vCXMcrIJj8nvCeMSvI6+VllhPbl556+jv+ni8+nOoZSQCnw4CrQagPHHRiB4Doj0v/5hskozcypU5rWhGhysgRRbm6eRA98u3WTslt8qHGxP6dlWNuRa6D4gGuskVqGIQP73zMRPT6ALxUVyYPXzdn5R2vg7odhxfvC6ayWOG80NNr6M8KIVYMYkOaQXqWJUoDfmYxeNjfmShWlgFJAKXC3CrTawPFNeW/YAZn+4Zt1ZNQZKQzOxeYjhg6+rj+cbuPCaZZDYiSOb+6MSHDKkG/BRcXFEnFhvUpGA1isnaWStGzOu724n3p/GrhN23dgYN++8mavJTFwXZIC2/7U6qvjKwWUAkoBpYBS4MFVQFBmnJ9raGho0DIEbyUHHd/6zdswZtRwfPzZl5g7a4asU5kzY+qPIg+sXens6CBrfr789nuZguDUwvnkZKRlZEkR865enrJwOj7hPNIy0/Hhv/55Txk4lsTitNrAvn1+MHDkwDFjUjWlgFJAKaAUUAooBZQCP4ECNHBcPnPHBo594PqXPWEH8OQjC/HV90vQ1cMDk8aP/VH3mjOUuL5F44C1xLLauWefYAoG9e+rswX4P4Fe1x1SWwNHB6zXAkbkpz6/Or5SQCmgFFAKKAWUAg+mAq2eQqVMNGDMMuRCbC525gJmXUFa76XbcLskhpT8auQU16Fzx3YIdOkEvfaNRcSpHxd1c1E4F3VzoTQTGfh7TisTS8CF6lwITxwIF2FzETkXRPPvXT09ZVuuQXR3c5XF7EyIII7C3NxcMgZ12W6EmXLRNheXMwP16LEI9OvdCwlJSbJgneiJO2nMQJWszVsUVj96/AR6hQRdxwW7k2OrbZQCSgGlgFJAKXC/K9AmA3e/i3Kn13c7AzfvkxxEXqySwx3/kzOsTBqnVYnQuJiWgcLCQiSnpgoywdXFRaKPK9ask0y2dmgncFUyxAgfPXIsApaWFrDs0gVjRgwXfEJuXh4ys3JgYmyEwkuXhMHGSOfDc2frLIpJ83boaLjw2bRMYmaerly3QfqRl18gmZw+3l2xYfNWPLnoUbRv3wikXbpqNZwcHOX/mclHpAan1f18vbF0xWpMnzwRNjY2iDx1Sq7Tv7uvmFGukWQWILP6mCE6sH9fQTeophRQCigFlAJKAaVAowLKwN3FSLitgfs0B5EpVcIGO9bMwBG9YmFhhsPhx5GWni7oBbK+GM1cuWadgFnDDh2WSBsZXvodOwgAdfqkCQIGJeeNLC/iRBYvW465M6aL8SMnLj4hEQ8/NEdnmbys8kAGHbOMQ4MDm9QiRoaJLPsOHJSqAMQ5lJeXS7UDNoJl/+t/38Zf//RHrF6/UQC4NJg0ZIT7Mno7e/o0cAlmdk6OYEPItnN3c8fBI0fRr08o8vIKhBNHxMadRvbu4naqXZUCSgGlgFJAKXDPKKAM3F3cKjLHOJXMxuiUoUFjaSWtlNbp9KvILWK5pHYY4mOADnqNU6hkSn361TdShUAj2TO7d96smXjv40/x8Lw5Unrq0YfmYt+BQygsuiywVVtLK6SkpWH82FFoqKvH+i1bMXLYUGzdsQsjhw9FxIlTCPDzlYoFumyMiJHr1bydi08QXh3hqH1795KoWbt27YUHp70Z0FTOnzMLB44cRXpGpoCGv1u+Eo/Onyfw16zsbAEVHz12HGNHjZTKFESWMPpGBpu1tTVSU9Pw8EOzYWXZeFzVlAJKAaWAUkApoBRQEbi7GgNaBggPIusCr169zsDd6uDNC263tA5MUoOvHaD5GrSb/fuuLkTtrBRQCigFlAJKAaXAPaWAisDp6HZRSGJY2LQInI4OrQ6jFFAKKAWUAkoBpYBS4DoFlIHT0YBobuAagcVa/ExHJ1CHUQooBZQCSgGlgFJAKXBNAdam1tfXax0HTqn3YwVUBE6NCqWAUkApoBRQCigFfi4FVAROR0q3ZOAqqupRXduA9u3awdSgPZojz1g6zNDAQJIgWHpLq5/JQuSs4sDpWBZAZ+O/uU6OrD3W2iTwmGvhWJCd9RVZk5RF2HksFiIndkRXjdmkhZcuw9zcTHAnbWnUhkkLjg72Tbsz+5ZZqR3v8JjEkJSWlsLevnU4kZKSEpiZmTWdl31h/VYWIW9toxZMVrkVu661x1TbKwWUAkoBpYBSoC0K3JWBo5lgzU+ND9aWDtwv+7Rk4ObdBCNCI7Jr334xL6lpGSLBk48uRGl5OZavXA1/v+5IuXhR2Gtenh7YvS8MF1JSBDNCUO/YkSOQeP4Cdu/dDwcHO0THxsHDzRUFly7Byd5eypvpqm3fvQeuzk6w7GKJ2tpaMYvuri7ChiPIl/2wsuwi5TyqrlZLH48ej8CwwQMREXkKXp7uSEhMQnzSecGfcH1gSWmpVPPw8vCAk6ODdJWG9MDhI8KCu3q1Cp06dZKMVpoljrNvly5D7+AQODs7Cnaku4+PnJt/6xngL/tfLiqCuZmZmMXU9HQE9+yJDVu3IjAgQDJm2bj9jj37ENwzAO3a68HSwhx01uwXGyHFKampCA0ORtTpM4IvORl1Bt7dvLA37CC6dLHAsEGD1BS5rgaYOo5SQCmgFFAKtEmBNhm4+MQkYXXRSGzatgM9/Ltj2OBBP+oAI0JFRUWwtbFpMnk84Z0YPinS2tAgfDBGf4pLStDFwqJNF/lz7NSSgZv7SQ5OtgDyZRUGaysrHI+MxJmzMaJP/769xWSsXLsOzo5OOHn6NNzd3NDT3x+WXczx9fdLMXzoYJyIPIUnHl2IjVu2wa+7Lz7/ZjEWLXgIi5cux7xZM8TMLdQhB660rAx79ofBwMAQRJ2kp6fL/Zg1bYpE5q5cqZSKEn/4y19hZ2ODIQMHIDomFo8+PB/vvP8RFsydJfc7MysL7q6usLO1RWTUaTQ01F9n4Gis3vngI8yaOgVhh4+IERwzcgQ66OtfM3dHERLUE//8zwdSfWLowAE4efoMxo8ZBRNjY7nFG7duQ3xCkrDoWOnBiRG/do1QYWrDfvA8Z2NixaSZmpiCUOIZUyc3jckNW7Zh+OBB+M9Hn2DMyOECSrazs0HMuXi5NppKG2urn2NIqXMoBZQCSgGlgFLgpgq02sDV1tZhy/YdGDF0sDDKggJ7CH+MtVANDQ2uOxEfsHzAnzp9RsotsQwUKwYw6lJSUorBA/vDzNQMew8ckGlDlmKqqKgQo8bSTJxWrK9vQEFhIdxcXWQKrqa6Rh7ojJQE9vDHuYREIfr/0tNaLRm4FcdLkZJfC732wEujzWHYsb3oQx127d0PI0Oaojy0a98eFubmYhw++uJLPDx3DvYfPCSMN/LTyioqBPgb4NddolmjRwxDbn6B6GprbY2U1DQ42NuiqLhUzMXMqZN1NuQZ+WNJK5+uXXE6OhqZWdlyfFZJ6BMaIpE4H+9uiImNk3N7erjjcPgxzJgyCXv2H4CDvT083d2EE2drY42jx07A2dkJzo4OOBZxArOmT5V7x6jb2g0b4e7ujvSMDImmPf3Yo1JCjI3w3x7+fli1bgMuXS4SY0gWHWHCWiN3jtOcfXuHIvz4Cfh6dxOz1rFTRyycN1c2YxRx2eq1sLa0hIe7q4CRn3vy8aZjsO+MfDIaeD45BUMG9BdDyWsI8PPDsYhITJ4w9o5eQnR2E9SBlAJKAaWAUkApcIMCrTZwjMKw8PyQQf2lrNOJk1FS8onw1ZHDhlx3eEZaXJycEHb4sBi02LgEMSF86J6MikKXLl0QGhSE7bt3i1FjtGXn3n3wdHeXh7BBZwNs27Ub/XqFIuH8ebg4O8s6sPMpKegVFITY+DgYGRpjzoypMpX7S7bWJjFwHRanUBkRoklpbkB5LE5JUjPNdGh/p3nVTE1Nba1oRlOip6+P+ro6MYNcc6fa7RXgVC9NoRbBu/0eagulgFJAKaAUUAr8OhRotYGjgdi+aw8G9O2DPWEH0LdXKFhWafb0H5uoc3HxUvuy4kolqqquisnrFRqMvLx8mdbq7uMN/+7d8fEXX8LczByXii6jqKgEocE90Ss4GIfDw1FVXYPSklJYWJijY4eOqKmtQafOndHdu5vQ+jlVxvVjHTt2+EUVba2B+0U7q06uFFAKKAWUAkoBpcA9rUCrDRyvlnUsuVaI6482b9sh5ZC4aL0tjVOyMXFxCOoR0JbdfzX7NDdwzaso/Go6qDqiFFAKKAWUAkoBpcB9pQAT/to1NDQ0EFdBtMWdNBqW8ooK2Z7Tl7/0GrQ76fNPuU1zA0fchn6HXzYi+FNeqzq2UkApoBRQCigFlAK/rAIN9fWoq69vvYH7Zbv96zv7gz6FWl5eLkw6mnmuydPW6Wl3qqXfaX/Lzc+XDFZdtJudh2sNmeBwM/5b8xqzzfvB31dcuSIJJ3xJ4TIArvn8KRpfiLTzsL8aG5Dn4vji+W/2osQ6vPImdov1j3eyDV/i+ALS0ppSbd0m+0NeIfmFd9PupD83Oz7vC7+4tHWiLW13qzF3q37fbCzc7lrber7bHfdWGnCtLNcF3+56OH5utU5Y6jpf24Y/+f+tXVfM2RQ9vUZO4s+tRVs1VPspBe5lBdo0hXovX/BP1feWDNypM9EovFwkGYtD+vdtWqfHh+T+A4fg6OiApPMXYGpigiGDBqCutk6yOplxGxefgAH9+8LSwgLhESdwuai4kbdWXy/Ilrz8fEG5eHp4IPZcHLp6eQjywsHe7rrMzLu9XpqXnNxcODs6Ii+/ACYmxiBUt6q6Co729k2GiOgQA0P4WRnxAAAgAElEQVRDuDg7CT8tJChIWGxMEDA06CyZsh7ubtiwZSvmTJ8mmaQ0QjQdazdsxqKHH0JyykXY2dk2JXYQZMxsVGYlp2dmwtzUTMqGMIuXOJKLaenCqCsovIQOHTvAyMAQSRcuCBeO52NfiKHhw4RrKL/5fhmee/Ix4cQxY1YzmZcuX8bho8cQ2CMAnTt3krWWfAh1NugMNADbdu3C1EkTUVRUjCUrV+GlZ56SfXlc3gdjY2O0QzsQzkx9vl++Eo8tXNAUza6srERmdja6enriYmoarKwsJauW/XNzcZFbxAfm+s1bZVkCjRKzfH26dcXly0VyTGbpWnaxQF5BAVIupmHIwP5ND1huSyQNdc3KyRH8zKXCSwJ2dnZylGvhtP4///M+Xn72aWTn5grw2dbWBqmpaXBy4r3NR6eOnUAz3UFPD76+PpINzCSk0rJy0Gzt3h+GCWNGwdTUFLv27sPk8eOahldGZhbOxsZizIjhcl+Yaa5F86nT+QvJ8PL0RF5+nuhFLddv3iI6MZt91LChMpboPzW4c3l5BdZs2CgImBuNd2lpGY5HnkRocJDsU1ZWLufkdQBM4mmQBCvqyc8MzTA/h9SZnxsicJhNnV9QeB0WZvnqtaisvIqRw4egoQGwtbYS7atrqiVpi/oaGRoJHonnizobLWOcGc/kBfbpFSL6ciy212svWfcebm5NxppZ57U1tbCzt0NaWrpk1rM/wYE9BS3Exkz8/MJCODk4yOeERpljgOt9DQw6y/0wMzWR6+ILBU0T1xqPHz0K3yxZJln5/FxxXBNJdP7CBcHp2NvaCilA05cvNBxrVdXVqK6uQUlJMZydnRF15qyAwblGmWNnxdr1KC4uxhOPLISRkaH0kTrzMyCzDdfg4UxaY5Ia71vEyZMYN2pk04vH6g0b5XPFtdKqKQWUArpRQBk43egoX1Q3FrPfvmc/8goK5Qxzp0+WL0U2IlL4MCDoligMwmFramrx9GOPCCaDrDF9PX0B83KfoYMHYsmK1QLrrbxaiWmTJmLL9p3o6uWJxUuWY+6s6Vi2ao2w2Xi8Rxc8pLMpbSI0KsorxFTVN9QLzNbZyQkmRkboHRoiDyw2/p1sNVdnZxDnMWr4MGzdtVswKK8+/wwOHgnH8CGD8PEXX+GNl17Ad8tWoldIkFw7M5u5BnLpqjUYMWQw9h44KEaUxyBuZdigAfjo868wdtQIfL9ilRi6AX0bIcKTxo3Bux98LNfOhBgCkkODAiVT+VLhZVwqKoJB505iFP789t/xx9+8Iey8+bNnCc+O7eixCHTr6iV9+fzrb1FXx2hFe/QJDYWZmamAg4N69sA//v0+8vML8cl7/5KHF5NxiCQhmNjCzEy2JYLk06++wV/+6w9NWB2achrJ8WNHY8mKlWJEGd0g94/YFa0dORaBkMAeEvHbsmMXjA0NkZmdI/gVnt/Bzk5wLDFx8WKeaGbZIk+dQnn5FZRfqYCJkTFsbKyFG7hw3mz4d/eTa2kcd+fF0P31n+/CztZGoNBGBgbQ76AvGgQG+GPk8KFiFJggRBNAE0YUy7jRIwW5QrNE7Aqv3aFZZY2Ui6k4eDQcI4cOQWZONjIyMjF7+jQ5b1Z2No6EH8e40aNAMDRNFE02t+nfr48YXl7Pjj17JaI2oF9f+TzRZNOI+/v6SHS3eSsuKcXnXy+W/gzo10cMMY3LX//1Hzzz2COiEc0ZTQjH5dBBjWt0CWw2NTWRz88j8+dh5dr1Yio0c/fyb36HV194TgwqG6N8MbHnBHszb/ZM7Ni9F0MGDEBcYqIgdWiy+WJF88/P7pwZ07B1526UV9BkmcHE2EheqDTT9OFnX8j4pRGiyeOLRVJysuhmY20t5ww7eBg5eXlSaUW7D2Q7EmFjYc6XmQwZBwRjX7p0GZaWlgg7eBALH5qH//7r3/HK889g3aatcm6+6PCaDQwNhHlIPcidZKO5pL4cF4P79xOdiM6hYbSytLxmVg3FkPOeLVowT0gANH3//vATGcM+3l3lJYQvZ5u2bRcDT3wQXwT8fX0FQM5xTlNIY/zb11/R0TeuOoxSQCmgDJyOxkBLBi7sSDjyCy6JmZo8blQT7Z8PSH7B8wuZX/5ZObmS1evd1QtLV67GnJnT5W3ezMwEZiamYgS279or0QRG24KDeiLqTLRUA4iOOQcXF2cxhfzCpJmYP2eWjq4KCDt0RKIvBCkzGnYy6jR6h4bC08NNIofMQmbj9dPc0dCt3bhZHlqsOLEn7CCeWrQQ23fvxbRJE/DRZ1/KAyYjOxtno2Ov8QQPYvKE8fKgzM7Lk+gRo1nPPvGYYGQmjBmNmHNxYgI4zThl4nh0sTBHXHyiRBZoeHftC5PzbNu5G8GBPZCbV4CCS4USHSkvK8fUSRPkofPmKy/ig0+/ENgx2XtsjB4lX7woD2MichjVoBnjQ52RETL4nBwdsXr9Rok8vPePtxsNXH4B4hISxHi4u7iIISIf8fNvvsPrLz3fFIHiPsdPnMTEcWNAk+bm6iwGiAaym5dX071iRMnYyBB2tnZyLgtzM4ENV1dXwbtbV4ksOdrb4mjECXlQalNcjJSRt5iWkSmRGmtra2zeul36cGPjvVy6co2Mu3bt2sPfz0cyvyNPRcHdzQW9QoLlAUw8DccdjRPN0cSxY7D/0GF5kNOYUf/mjfeFIOVhgweLnrl5uZg6cYJswogtx62Tk4NExTj9SqPL8cTKG4xqjhw6FBEnT8l04KgRw8TIsX80BQSF0/QyskXsCxvHeey5eInC8WVIv4Me+vfuLRFsvsCs27RZxkCv4EAxpL17hUo0jZ9FGpLN23fgleefxYo1azFvZiPkmY0mneXa+OLEZQEMXV5ITcXsaVNgadkFmZnZYn4JMyeQm+gkbsfKHTwnjRj7VFF5Bc4OjsI85Hm1CCLB5zTkLPHGiKe1jRWysviCENAUgaOB44sHM/eLikswbNBAKZ/Ha+bnjJ+rYyciMXPqFCSnpqJ3cDA2btsmrEOO7flzZsoLU3DPHo0RVX19Ga+M4vv6dJPIuaYhSQKMmPGF6GzMOcn472TQCdaWVhIJZBR65+598tmYNX2KjEuCxFeuWYfeIcFITk2Tl7dRw4fK56CHn598jmmeQ6h9VjYC/P1kxoHGee7M6Tr7blIHUgo86AooA6ejEdCSgePDTmvN1ybx93xzNjM3k7diQwND1NXVypc8H4R8W6+qqoKZqan8ZPkqfgnzAV5bWyNTUGycRqLR4E8+uLkv37bbUufzZjJw+pbRME6l8Yua16HVAz1w6IjAfVlr9PGFCxp5dNfWwGkl1jhNw334s0PHjqi7to1Who3b8UHIyACvtRHe3LgGhzpoa2k4jSU1Xq+V1mKUgJEARok4BcQHP/ulbU9GHvfnIk82bkNjRlPE/Xie5veEf2NEi+dmY7/YRzkG11vV1ck0JP+t1YTV1g0xSsPzcxutz+yLZgr4e/aH90ab8pLjs4/N1pHxeOy/VIygTteOwfPW19WjAQ2yvXaNzdmA2lijOeJ5GNG9WU1c7q/dR60Wr7bui/2iPpwWq6lpZBWy/9Sl+TW1VE1FYxryPnI/bRsps1ZVda1fNfJ7nofn1O6Z1PptgeXI/bgNDYt3165ifti0Si3Uno39ozbsK80KdeANawkvxOuv5XpI0enHaw35O74w0LxyalS+JK/dW00n6kaTyXNpWlM3XoOmlcZkbD7OtM+DrKfk+O3YURiYrEyiTekTJu3m4iwvDewrz8nxqt1jbdzJeKyvl8+Apn3jsRokMsl+CaOTzMkOHQT3xPJ3zdenauNROybvO79jtClnass+8z9qtnTlKjy16FGZcm38nPAzx3Hf+HnU7rn2+dW+VzRtWruuTkdfz+owSoH7UgFl4HR0W+/XJAY+IAkGbmlxvDxEr+mn4ME6GkjqML8KBTQjfydl/3TdYZol7SVJ18dWx1MKKAXuHwWUgdPRvWxu4LTok44OrQ6jFFAKKAWUAkoBpYBS4DoFtGzxVnPglI7XK9DcwHG64kaMhtJLKaAUUAooBZQCSgGlgK4U4PIUWTLRWpAvw/xMxec6LaIXHvR2v06h3s19bYmn1VLt17ae41a8Lq6d4tqgu2naWqa7OUZL+97Yb21t008Jw25Jq1vpx37fuD6Mv2u+z8304XpF9Z2g61GjjqcUUAooBX4cOGoTyJfMKmYu7Q07hLkzp7W4AJlf9heSU2BkbIQrFVeEe8UvfeIzyD27WePCXXaKae5axtSv/ca1ZOB2xVTgYkENOui3w/x+pujcobHIPM3vxi3bMXhgP8nK44Jlv+6+8nAkF458LrKxpkwgKkIfu/eFyQOxi0UXJKekSBYmH67bdu3BkAH9cOhIOPr26S3Zgl6e7vDy8NCpXNpDu/lPnuC6xIxr9K3mD3lmwHGhuLlZI66D7d8ffYwXn27kqP3oGLL4ulGjls5549+YOcmsyR+2lT1ljL330ad49cXnmhZVNxekuQm52bVx+41bt0vm7C2v+1qfm5uwlrZv/jtiUsg9Y2Nf3/7Xv/HIgnnC/brxGlvq9419vtFY3XjzuT2zAomuIFtPa0ePHUefXqE3jRavWb8RM6ZNkTWQ2jmZhUz2GhEXzCwmS40tNi4e+8IO4ZknFuHv776HP771eqtBsDodtOpgSgGlgFLgPlegTWvgiAX44tvvJF1/++7dkubucC01vble/LJnhmXC+fMCaWXGk72drTCMpk+ZJHwocsLIwiK/zNPdXbAMBFqSf9XT308QDo6OjsjNzZXsSl0iMnR5b1sycHM/ycHJi1VymuN/coaVSSO360LKRckKYw1YAnstLCwE5fDC009g9foNwiNj1ueFixdRX1svHDiiObqYm8GiiwVGDx8mpo5Yg63bd2L4kMHYtW8fRg4bKnVqyYfSVTSHWai8R7wnBJMeOnwUJiYmkn02ZOAA4V/x2r/49nsYGxs1ZQIOHtgfiUnnBewZHhEpbDNCYL/89nu88fIL+G75SvQJCREwbXDPANTU1uHzb77FGy+9KBqQcVdYUIiikhIZF5FRUQIq3bl3Hzzd3DF86CDBNkybPAnvvv+RZOMyW5esNPLGzsbEiLmLOn1W+k2siWaYiELoHRosLxI0J/379saZ6FjhiREc27dXL3Tz8sTHX3yNBXNnCfurvZ6e8LJoSP/4m0ZzQsgu7wujfaXlZbC3tUO3rp7Izc0TRAnvH82rwI/LyzF+zBjsP3gIBYWFwqVjI0rji28W45H5Dwkol61/n16IT2xkcxE1woxH8sry8wvkJcjI0AB+vr4CgGWGIX/HLD+OA6JdiEQhqPfo8QjJRNRr3w6D+vdHdGwsLK2s0K93I/pl+649ch/J/GI6SkZGFqZNntj0sdi0dYdgUcKPRwirjIwzIjI4Ns/GnpN+EfpLfZm1yHFC3AhhtWR/2dvZ6fIjpo6lFFAKKAWUAs0UaJOBI7y0T0jwD2/yESfwyENzfyQsmUx8wJPXdSg8HHOnT8fi5culkgCrDhCGSXZWTk6uAFmra2tRWHAJ51OS0d3bW4CufIDs3rtfWGc0EZPHj9WZOdHlSGjJwD30WQ5OJFdJSv+x//rBwF1MTZWqBbv27BNDQJMyadxYwXUQgjt6xDB5+PLBSjYcGVAkxDMaRNNBKOmBw0fgYG+Lzdt2isHbvW+/gG9T0zLw8LzZOtOIIF+y1M7FJaC0rFTYdf369EZXT3ch8hNLwGv/f3/7lyA6aKBCQ4IEF8ILZxUG8qVYgeDxRx/GO+9/iD+8+TpOnT6DjMxsGBoawt3VWUwrSe40p+cSErH/wEG5PX17hwpBnsBRcs4ImyXc99UXnsXOPXsxaEB/gQIzIsljkftFQ8N+EvxL2Gq79u2aopLs64lTUVJdIis7F4P795VKBKeizsDE1ETOyUjmU4seEUDwlInjkJ6RJX0qKMiXKOhLzz4tiI7snFzBqPBcnK7lWCc7i4R+Li3Izc1HWUW54F0IoyUsmAb7THRM04sIo7H8PI0bNQIRJ9mvPAwZ2E8iz7zvbGS3vf/p5zgXF483X30ZxyJOCPMvJy9X4K+k9o8cMkRMLBuNLGG9xM1YW3YRaC4/O4xsU0cyu9g4ZsjoImR4z/4w9BEwc6O50wze4AH9BFBLwOv//PH32Ll3r5hSGja+dNlaW0uUky9atja2CAnqieMnIjF65HAB1qqmFFAKKAWUAj+NAm0ycIRrTpkw/ocv+t17MX70yB/1kOBJTvPxwcEHOyMPruQbOThIJIVRCsIdO3XoiLyCfIGW1tTWyAObcFsaB0798MFkasKSTAZCpNdVdEmXkrZk4Moq61Fd1wjasDDSQ/vG2UHhJm3ftVuuJT4pCVZduqCsogI9/LoLOJc0/oSkCxg6aIBMqTJK1blTZ3Tq3En4cQTVEnLK6FhocCBORJ5CcFCgPFDdXV2EXaWrRnYUgbUElpKNxcghjZtW2odGjeaF18/rYoS1sbJEjcCGWfqHPCvyrng/CWsd1L+vGDhOFTNCyzJTNDhnYmLRKzhIzsMpO18fb6kQQF1i4+Ph6+0t0VuusWLpMB6LY4UmiIaJ0+40kZ06dRaa/aQJYwSSyvHCkkVsPC6vyd3VVbhviUnJCAnuKca4T2gwYuISYNnFHCbGJjgTEyOmjMsAfLp2lX7yWgk1pWnhNdOsuLNE2OatCAkKFIN59PgJ+Hf3kX4xAkatTkfHSKSaMGJ7e9smQ8n+0Ny6u7mKJtbWVvK54FjXppm5DU0fjRmNGO8HgckRkSeFqk/mGnXXmHLsV/LFVGGAMRLH8mKc9jx1+qz0j585NgJ3Of4IwF21fgMWLXjouilnGlNGKtkvPX19mX6lUevu4wO+hDg4OMDT3U2OxfJmjFAS7rpmwyaJ1v0aP6e6+lyo4ygFlAJKgV9agTYZOH5BW1taNvU9JS0Njz08/5e+ll/0/PdrEgOjP4y2tATgFMDrNVhxI2j4wW2sxUmjdi82mkxOwWp1Lu/Fa1B9VgooBZQCD5oCbTJwD5pId3K9zQ1cY4HnB9vQ3IlmahulgFJAKaAUUAooBdqmAGdn2pSF2rbT3b97NTdwjEapkjH3771WV6YUUAooBZQCSoFfWgGhH7BSUms5cL90x39t579fp1B/bTqr/igFlAJKAaWAUkAp0IihUhE4HYyElgxcdVIi6ouLWPEZnXoGod21aVVuy8xMLsRPTUuXbD1moLIxaYNrqYjg6OHvj/bXMh+Y8ch1ShVXKgQhwfVnZG8Rt5F0PhmeHm6CcWBWorXVD+sTdXBpd30I4mPOxsTKgnhdNCJpiJ65sZWUlCAjKxv+3X1/9Lf0zEzY2diAiTVMBGjeMrKyJHGAi/SZOR3Q3VfQLje2K5WVkjDAIuY/V2PiAXExttZWaN9eD3n5+SguKUEPf7/bdiHx/AXBoTCZgG9q6RkZcHVxuW6/0tJSsOg6E0xu1kpLy9ChYwcYdO5823O2tAHHKrNrmZ17Y2MSCBmIuXn56Op55/xCrs3kPm6u11/PsRMn4ebqDEsLC0maYnF24owmjB3d6r4TkxKfkISeAX6i+a2yakXfzEy4Oju3+jxqB6WAUkAp0BYFlIFri2ot7NOSgct5dB6qok4K4tY5LBx6lo3GgWaMD5fU9HTBXOjr6cO7m5c8lFeuWQcXZ2cB9zLTlCiR8opyHDp6DPNnz8SxEycwZ8Z0HDsRiZKSUpxPThZDwoxCZjLywbZg7mwdXRUQn5iE6Nhz0reMzEyUl1egqqYaVVerJEvWzdVV3gLIZOO0MftCPlpIcKD8/vyFZDGnlVer4OzoIPiTCWNGIycvD0VFxfD08EDUmTMYPHAANmzaKky2c/HxKC+/gl6hQcIdI/R2x6496N0rRExWfNIFeLq7IuLESXT39REtbKysMHH8WKzbuBkzpkzC6g0bMWPyJEnAYCMyg4gM9qfg0iUxLPyPTD72i5gM/p2AWmY8F5eUIiExCSOHD4OVZRfJpF6/ZasYAztbW0HjELHBTFo28t1Ky8rFMKVcvCgmm1mszCYlzoP3e+rECU33hToQ3yEG/MIF+HZrzBy+XFwsaBb5d1ERvvpuCebOnIGioiLJXGVW7/6DhwXXsXPPPjg7OcHWxhoN9fWCKdEajSqvtaa2Ftk5ORjUv58Ag//wm9dBY0fDQTbefz76FI/Mn4ewQ4fF/HNbolA83N3g3bUrLhcXyT0n141ji/3u6sk+J8O7W1fEJyQI7oQ4HB53+JBBOBeXCHc3FxQVlwgjj1m73yxZhj+8+Zpk6PbtFdqUCfun//27AMG1e0KzN3XSBOHzVVfXYPmatRg6cACizp6FtaUVXF2dBX5Nk857SszOmJEj5LLLysrw+u//hP/3h9/i0uXLgu+hZuQE/vaNV7Fx6zZh9fXr00u2pxlmVjB5gWTnMZmDCB82Qqj37j8g/R82ZLC8SNHkb925SzKSef2O9nbo3NlANCLW5f1PPsfvf/MajoYfFx4fjeTp6FjJoiYjkZ91Zp6rphRQCigFdKGAMnC6UPEaUZ8RGjY+zJjE8IOBA5zDjjUZOOIWLLtY4MCho8gvLACnsUniNzEywoo1a9EzIABrN2wSBhoBrB9+/oVAVn/3xivYvH0Xnlq0EFt27IRPt274dskyPDR7BpavXocZUycLSmThvDktViBoy6UeOHwULk6OYpKIryAMlrgML08PQXfQbND0/Plv/0BIz57yEOzfr4+YgB179grHr1PHRswIUR7ffL9MOHVEZzBaNm3SRDAKRFTMp19+Iw/TFWvXYcSQQQgNDsY3S5bi0fnzBKZLs0K229qNW8Tg8uG9N+yARCPr6urx/FOPY8OWbVIdgDBdOzvbJpQFOWfBgT3lvI2w21QUFF5CSVkpegcHwdbWVswLDSIjTR9/+ZUYh5DgIDg7Oop03IfRTVbRIGw3LSMDI4YOkb999d33cHZ0EuYbDQrPV3j5ErzcPeReEImiRZhq6+rw3kefiLExMjIWfAmNMjEqJkbGmD1jatOt2rx9ByaPHycGkDoyOkvjZmNtJbBiS0srQbygAU1ZpDRnn339rYyDb5Yuh5O9PcaOHolPvvgKr77wnPSN0GdGlWLi4uFoZ4d9Bw7Cx7ubjB9TY2P07d0LxAXRPDLyy/tTWlYm95H3jeZl49YdYn4J7iXihUbUyNAIZqYmsLAwQ3V1rejJCBY5hk8/vkjK75mbmTYl+fzt3ffEMBOUTJyQsZGhVBohroUomo8+/0qQLDSOjg6OcLCzRXcfb0HVxMYlCErlrddebtLrz2//A3/67ZsyJskV7N+3D/7x7nt4/uknsXHLVol6Dx7QWAWGMGlyB/mCQnwRIcRaI2vQy8Mdh8OPY/6cmTifkiLmncaN6BrqZW9vJy8rhIvzHn/42Zd4/qkncC4hQcDlNPN2NtawtraWcR/YMwDBysC15WtI7aMUUAq0oIAycDoaFi1F4Grz8lBfWoJ2enro4OYOtG8vZyM9/+/v/AeTJ4wT7hvBszRHUyeOl7f4OTOnYf+BQ3j2iUXy90njx+Lw0WNCw+e00ezpU+SB8f2yVZg1bTKWr1kvlS327g8TiO7Ia6ZCF5dG2v+RYxF47OGHsG3nHhgZGsLG1loArjSqjPqxHT52DGlpGTIdxmkkRoQiT58R5hu3Y9klVgD4fsUqPPPYImzesRNmJiZS/SAy6oyUBPv8m8UCNKbxOX02BoP69cWesIN4eO5sLFu9Rh62yampMv08dcI4AT0zGsmpZOrPyAj/PrBfH4lkzpo+tSkCxyk8QpJZ6omRmvzCS1LZgFGukMCe2LZrN2ZMmSxGhVE8av7tkuUCqOYUJhurSSxbuQaTJozFxs3bpJoCWWtsjBBduJACV1cXiXwRTM2oKSNgNG42No2aaY3TelFnozFs8EDRi/c1MytLIkvk7GntbHQs/P188f3ylbhcVIznnnpcSqc5OzlIhQuaQEbO6uvrxNCzceqPU5MEPsclJOLAoSOyH/WiGWXklhEnmqvxY0bJPqvWrhdDwkgTOXpBPQJk7NGAv/fJ52JqaYwZZTU0NMDiZSswb+Z0pKSmorSkTCKRBQUFYlY4DU14MI0yjRjZhDTz/Xr1ElPFiJt2jTt27UW/vqE4GXUG7dAOlVVVmHhtupMm7LOvF2P65IkSKSWDji8pq9dtxJCB/eUzQENOaLDWaHg5hlat3SBRvScXLRT+nZe7m1w/XyKoi+j0f5U7WFGGEUguP2DVEK1Rw68WL0EP/+6ynKG4tEwi4JWVlcKyXLZqLdzdXcUc795/AE8++jD2HjgEPx9v4QxyG1asoFllhPJf73+El555qmm86OKzqY6hFFAKPNgKKAOno/vf2iQGRo34MOR+2holTpk2NPzw/3xANa972bzeJvfhvhpQVvvJ3+sSoMp6tIyqcOruxsZpKq6PYrSR65tudV7tenUkd4uH0bTU5fW3tr8E2rJSwS/ZB44T/scxcavWUrH61l6v2v72CjCCSRi3Fsm9/R5qC6WAUkApcHsFlIG7vUZ3tEVrDdwdHVRtpBRQCigFlAJKAaWAUqAFBdps4Lh+iGuG3FxcmmowPsgKNzdwXIDNaJpqSgGlgFJAKaAUUAooBX4KBRrQIMuEWsWBu3KlEt+vWCnls1Zv2IS5M6ZLXckbG6fNzl9IkWLizFzj+prmU4Jc4yJYBn39pikn7e+sO8maqdq0Iad76usbZPE6m/Z7+R+mmzU0yDG4vodZYQYGBjA3NZVMNi78/mGa8lpBUh2rqSJwOhZUHU4poBRQCigFlAJKgZsq0KYIHBd+n42NxbBBgyTrb+TQwTAxaSyQ3bxFnDwJU2NTmJub4eDhozAzN0VC4nnJDNu9dz9MTY3FwHGRL4txc/H9h198iS5mFjAxMYKVpRXORsfAwsIcaRmZ0NPXw5svvSCLv3ft3gc7e1tZwM2FxYwGzp42Bf98/2MBrlUAACAASURBVCPJEDx15iw83NwkS3Lzth2YPHEc9uwLE9TC+NGNC7d12VoycHX1XIvUeBa99ozK/XBGYimar4HT1itp67hofpuX4+LvNdOqVXlg8Xg9vfaShdl8vdzt1j7p8rpvdSxeI/vSvD9Ep9CY66LUGBeaM0HixkY9mE15J6y0W/WfmbQcm3fSmKFJPpyhoeFtN6+svHrdmkJmrvJzoBWjv+0B2rABNeFLzK9lbLThEtQuSgGlgFJAKdBMgTYZOGIMBg3oJxmJzJ6LOReHUcOH/khYZqMF9eghWWtr1m9EVk4ObG1sxXQwQlZeXi58qe279ggagPynv/zzHVy9clX4XhdTU+Hh7o7E8+eFbdbIlOqGDz79HC8+85Qw0YjkICuNWAVm282cNlmy58rKy/Hw3DmS/TZn+lSs3bQVHm4uAhSdM2OazgdBSwbuqW/zcDqtSrLrdrzhAEvjxigl0QPsNxe8F5UUS5SQWXVmpmbCU/N0d5drJW/M3t4WVyuvSqRz8vixOBeXgFnTpwhCgdgGLpCmAWjfrr1kuHXu3Fk4aLpqjIQei4iU/p0+Gy2cNyYvkJM2bNBAWFlZirE8Ex3TWPSemYFpaRg+ZDCYwdqvT2/h3jFyyizMf773If7rrTcEC8HF/rx35JjVNzTgxMlTwisj1oHYjAF9+4A4h2FDBuFYxAlhk5Gpdy4uHuPHjMb+Q4cwbtRI7A07KKDbmro65OflC7tt3cZNmDppoiAuaFyYFcjGvnK8ebi7SoYkQa1kf23ZvhNDBg5AXGKiXEOAvx/27D8gmm/buQs9ewTIywejycyG1ZIUwiNOCBOvV2iwXC8zHLft2C3g2OORkcIOY+YjcReTxo/D5m07UVl5BXNnzZD+5OTk4p0PPsIbL7+A6Ng4yUimHkePR8jLh2WXRgYd+8ksWGaKRp48hYnjxmD3vjCEBgXiytVKGQ/DBw+U7E7yzXhecsf4cpOVmws/bx+Enzgh/fu1gZ51NVbVcZQCSgGlwIOkQJsMHPEIxBZwnVd9Qz2MDAxbpOyXlZVj38FDYHF3B3t7mUKlISBegNBT4gX4sOFDxtzcHH1CQ7Bi9Tp07NRRAJxVVVeFPcXQ1cC+fYRFNmzwIJC2TrBpI/KgE2xtbCRSQkNErICATRsahCPFv9FQcK2ekZGhIA96BNyeYt/aQdCSgZv7SQ5OXqySQx3/kzOsTBoNHAGxRFMcPRaBlNQ0QTQMHtgfvt7dsHLtekFz0CwxUkWG1oq162Vq+LevvYKV69bj6cceFUZXd29vfLn4ezw8bw6WrFgl/LDYc/FY+NBcnUVayIGjyYpLSBBTSUQCeWFkwznY2QsUldf+7gcfSxSWTC+acUJyidCwMDcTBASxGYsWzMeXi7/D6y+9IPw6VlMg4LdvaDBqausEo8GoGc0Uo2uEExOGyul3jjlWcmCklesvH1+4AFt37BJDsnLtOpDBx4gkOXK+3l3FbBF2W1ZeIWbL7hpwl3396rul6Onvh4NHw4X1RezIuk1bhAPG8Upg7LjRI/DO+x+JUWLE+fSZaGRkZ8PCzAxvvPIiWO+WTLOde/aKWaNhojHkTxdncvM4RouFBZaUkgIrC3MMGTQQBQWFwnvTXiJowJesXI2xI4cj5ly84GT69g6RzF8aeC5NIO6Cfc7KyhJ+G19oeoWGIDYuTiDQhkaGCA0MlExgRmf5gsDxcelyETp27CBRag1eS13GNMNutHacq+2VAkoBpYBS4NehQJsMHLtOCCgjM3wwMJLyoLeWDNx3R0uRklcDvfbA6+MsYNSpMbGhuLgYh8KPiwEtLipuLGVkYizg2C8XL5HoDA0PWVyMWvbr3UvgrWXlZTJlGBTYU4xvXEKSsNQYVeQ09dWqqzA3NRMQqq4aI2WZmVmNfLPkZGRl5sDX11vMAiOw5JbRLH/8xVdipmm8ySajMYlPOi9gVhp0miiS/z/+4mu8/PwzUn2BBp8wYFYNCA0OwobNW8WMMgLHqC4rATC6SGAvKf+VV69KFI9luRhppdEjnJfROb4UdDYwEOYaI0xkhT39+KNyLE4bBvYIEEl4n1jdgdOYTDbhywLPc/rsWdjZ2oHluLKys4W+v2TlKkyZMB6Rp07BwtxCpvEJqZ05dYoYK17jqvUbxMiSl7Z+0xaZoifElVUKaOD4OWElh4rKSgzu30+AxFx4qkFj2R9G0oYMGiAGkFHMoB7+EulkNJWNRnjxkmVSuWPWtGliphmdY9TT2ckRZRUVEokj1022r6nF8tVrRFsaSo4z9ivqTLRs31KpMV2NF3UcpYBSQCmgFPh5FGizgft5unfvnKW1SQx8KHPNFCsIaMkdNBrN17Npa+Q0xpvwvWQ9XaMR5L40EiT783fa+jldrnM6l5AoNURZOUJLMNHuSuSpKDGRNJ+EEN/JeRklY5+bH+vG4zbn3TVPemk+Gppz1ppvr21zK8ZZS+e+8Ty3O752npbO3fxY2nFa+t2No7ulY914Hu3/taQc/v/tmHN3cu5755OmeqoUUAooBZQCWkBCFbPXwVhorYHTwSnVIZQCSgGlgFJAKaAUeEAVUBE4Hd345gaOC/JVUwooBZQCSgGlgFJAKfCTKdAAIRq0igP3k3XmHj5wcwPHpA2uZVJNKaAUUAooBZQCSgGlwE+hgIrA6UjVtk6h3rj+S+vOzX7fvLu/prVNzBYmA43r+ri4n1yz5k37XUvr3VhIXMN83O3tqK6paZGnVlVVjZqaahgbG7d4CmZ66nfoIP2/UWMiaZhhS4wfEymYNXyr1pp71/x+y3mMG6HTzPhlUojWblfntbyczDrDW66HY6Yu+36rNXNk3/G8LXH6rl5lnzrK/i3d4zu57ua6cczwetlu1qeb1dDlubj2k9nAN2s3WwfJfW/kLDa/D7y25trf6Zi82di73f6t1a15X7V1sLf6LuDfOH40fmRL/RE9a2vlxZPa8P+1MSAPCWp9m5dSJs9wfauMjxs+h9SUx7uTdbK300v9XSmgFGhUQBk4HY2ElgzcqbMxuMws03btMLh/nyZjwQoU23fvETwGsyTJ+urft7fgVojLcHVxwqnTZyWzkYajrrYOew8chIO9HVJT0zBv9kzBTTB7sbtPN8ku7O7rLbgUFycnDB7QX0dXBckUZSass6ODnNPA0EC4dFXV1cIsMzQwkHMdDj8mmZNuri44dCRcuHHJF1NhbGwkSIz4xET4+/piw5atgtAgCoQPSTICV6xZh6cWPYILySmCfeGxO3TQl8xS8uCIwSAexszMVHh3xHo4OTmKFs7OTsjNzUNng84wMTKWDNW+vUMFXcK+FF66hPq6euEEfvb1Yrz83NOSTepob9f0QOLxmNHaOzREMjn5oOHDjoaIJOZV6zZg4fx5yMvLw9ffL8Xv33hNtqFBIOqE/eIDjxmzzMheumI1Fj38UBMEmLzD7Nw8QYpcIFLE0hJnomMlI9RT2HaNH8Tvlq3E3JnTxCQSVh3cs4dcPzNJyyuuCB6HXDtqQXyK9oCNS0jErn1heGLhAmTn5kgmcE5eHqqrqkUDgTz/30n+/Ne/4a3XXgENM/EiRPukpqXB0cFB8CzMKr6Yli4a+HX3FX25/+XiYmHdMYN20oSxsLa0FEzJrGlTm8ZZWnoGzsaew5gRw6R/jo4OTeaMOl1IvghPDzdhAnJMMPP46++W4LUXn8f+Q0cwatiQJtOkjSmayW+WLMcTjywQbmTzRg4hM6QJ7SYbsKKiHK4uLkjLyIBe+0YTcfT4cUybNFGSfWg8eU95n8gNzC8owPw5s6Q/hIhrBnLZqjUyNpmUw0Qjjkcem8k3trY2SE/PkM8ks4v5eeTnl+PEz8cHB44cFRh5emamaKmN1a5enk1d5984HskGTLmYCidHRxw6ehRBPXsINoaNxpZ8TaJ6+Jnjy1AXgZlnwNDAUBiXpqYmaKhvAKvidO7cEafORGP8mFGC55k2aQL09TuguKRYvg/InGSzt7ODibFRk868vuqqKkH28IWBWByORyYn8WXMv3t3gY8vX71WNHnp2aeaQNUZmZno0LEjDDp1kp+EUJODyM9QWVmZfI+xH1qS1uKlK2BkbChsTtWUAkoB3SigDJxudJQHMCMcbER98OG6fc9+5BUUyu/mTp/cFLmJT0wStETkqdM4deYMXJydxbzNnDoZq9dvgLmZuWR28kucSIyEpAuSqbpowUNiJgg1ZnUJH++u+Pq7pVgwZ5awxGZPm4rYeN1y4AhFNjTojNz8fHmYLV62HN08PSUz1d3dTRAnbHxIp6SminlYvX6jmMjIqNM4czYav3n1JTGbI4YNwZfffoeXnn1aHgoE9NbW1KLw8iX4+foKU40w3fWbt8rDcdTwYWIMewcHy3n5MCabjZy17j4+YpiGDxkkv3vi0YeFm7dz7z4E+PmhtLQEp8/G8NmOTh06Yd7sGfjff7yD375Olt4GTB43Vh6CbOTxEbPBh+SyVWtRebVSIg59QkPFnGVn5yCwZwD+/eEnKCouwbtv/4/c37y8fGzdtRvJySlihmgEQoIC8dXiJfjzH95qMlgEWtPEkum3buMWdOjYQXh5RJvQzGntyLEIhAT2ALOKqAEfjjRzNFsD+vYVSO+VKxU4F58o161FMzieKiquiNEm1454lG+WLMMbL78o40fbjg9+mpgPP/2iEZ5c32gkKioqxWBTAxpvAoBZyYLg5NLSMsGWLJg3ByvWrIdB50544pGHJcLSPBLJscrrJN5EM6AEaLMRy3I+5SL6hoZg34FDoDELDQlGfn6+YGCWr14nLL0tO3ZKBJTYGMKtCVum8fX39RED1zxSRQO3fM1agYHTbB0+Go7RI0bg3x99gt++9jIiTkYhNzdXxmNKWhoG9OktXDyaR7540LA/Mn8etu3cjXGjRzZVMnn5N7/Day88hx179knmNU3N2ZgY2YcvHidORsmLFVmOp6NjEdjDX+47z8PP5Pixo6XqDMe0hZm5jGPyHbWINF8ArLtYoqqmWgwtGtohKycbI4YMbjJHYQcPi3kkIzInJwft9fQwb9Z0McE0Vjm5uUi6kIxnHl8EGime4+CRcMyePhVv/+vfeOX5Z4UnaWFhJrqxb/ys8DPq5e4u8G02vtzwHDR4hFPzPpMT6OhoLyaYn3kaUX6uCSNfMHeWGE727aPPv0RdTS18fbzF5JPpuP/gIfk+OBx+HJcuXYa7u6uYVJ+uXog4eUpKIb75yos6+sZVh1EKKAWUgdPRGGjJwO07fFTeoPl2P2382KY6rnzrLy0rxZHw47CyshKOGx/cfAtnFGb+3FmIOn1WDAbfpBmR27Rlu5g6ZycnODnaSwSHDzQ+aB3sbZGckirsMT7QaPBuh5a408tmdKSkuBgVVyrlCz/8RAQG9euPrl4eEiHjA5uN188IzcD+fbF63QYxcIxSMDL0/JOPY8uOXZg5dRLe+eBjvPXqS8jIysbp6BiMHj4Ue/YfxKRxY+QBkp6ZJZUe+N+rLzyHtRs2S2WJ6NhY0OAQAD1l4liJdPGBRqC0VRdL7A47gGefeAxbtm9HSFAQGBEqv3JFzCejiDzGvz/8GG++8hL++s938eyTj0nkk43mIzrmHHx9usk1MAJIg80HHh9IfIBRdwKDs7Jy8PmH/2kycDTMW3fukuiPlYUFxowagY8++xK/fePVJoOTlZ0jRn3CmNESpWFUhFqyVi8fgFoLP35CFqQyqkigNSHIZLkxOkL2Xnu0h4ODHQ4fPYaxo0Y0GcS09HS5P4ysseIFjey6zVvw1qsv/+g201x9v2yFlKkjZ47Q4/zCQpw8dVoA0oxebtm+S0rZcQx1Me8ClsRjdIcPZhJsZkyZLNHW5o0GYe2GTWIEEs5fQElpiRhuNt4zVg2xs7EGK1dcrawSM3+56LKY7W+XLpeKGmT/EYfDKi80mjw/X1gCA/xhaWkpka3/3955gEd1XVt4qVdUUUdIiI5AdBBd9N57dXfiEjtOsV+S57y8xCmO7ec4jjs4gDFggzG9994RAgSoICFUQQLUUAFJL2sPVx5jGUYwFON9vs+fjHTn3HvWvdKs2Wfvf7dv01rmpIE7dvyEzEeTSqh4z25dQPD0E49MEwNDo9OnZ0/kXLgg5tm4ZvZnZiSYHyxmzp6LJx+dUW1y//bWP6R1n4+PDy7mXZSuMQQsM1pHGDRB5IyU8Vnl9fI+5F8uQJfoTtJthl09NtOAXb0qH8yYGsB1G0w/sg45DyOq/JDASDLX1bFNG/j5mTSlgcvKyZZrSjuXIYaRUVhGLWmC+OGEnTomjh8rvwM0xl8uWYYnH50mBnbG5InSjYYfJhhpZBSZBpIGlp1vGPnl4Hwr164HdwRienSTDzz8XaHuPIZ/X/jBctHXS8XcU4PZ8xbihWeekkh0dKeOEpEkf3LowIFYvX49olq2xMHDsci5cF6ikfzdIhdy1foNcHd1w/TJEyz906PHqQKqwC0UUANnpUekJgPH77EilblT5vkn/MPINxfCYfMLC+SNnmBZHx9vAfT6eHvLH1Ju+/GPLP94M3rCPC3mmTBSRPgvP+UySkCz4+3tLd0auJ1j5BVZY2l8o+D5uf3HrgZ8Q2P0iZGSvfsP4lRiopyP0Qlu/fAPPiORjEI6OjpJrhQHt2kIweUauHXKN3wewze2zOxsBAcGSgcBmla+hlEozmvknHGb01gXDQHNI8HGNHI0iqZtNxtcKbkiW4DGdibzpCSfx86u+nu8Th5jno9D6C63cxlZ4ve5DtmqqlNHXi/gX1sbiT4Y4GreX+YNmfJ7HFBWzjV6CLjYzt6+esuca77C++vtJd1CuH7RgCBjT4/q28Q3dEbSuH1MDXmMg72DnJ9vkvy58SxQC+P6TTlL0rBEtODzw9czenLjkLlKuRbTfeQWPzU3cs24FcY5mPNXUFAga+W9u3b1quQIMg+Kc9TUt5W68px8PXUzcqZ4D6gvn1VqSm1pKKgfr4EGgs9zTbmFfLYdHRxxLiNDooaG6TZytmiUOBix4wccIzIoHVwAuY4bB7cdqSe15LnN+93yfvI553Y+9WzdqqXcY+b/UScjl4z3kc8uI1zUic8Tf1d5z6gl9eEzQENKrY0PVDTj/Df/HnAOXoNsZZaXVz/fjGRyrYyc8T7ynJyfa+ZWeFVlpbyG0Wtqy+eKH9y4Dl6r0WeZJpEfAngeRm/5obBdm6jq+8L5+DeD28v8u3L12lW5Bj6D7nXcq/ML+YGG2/E8jh9wCArnfeR1cb183vncX76cb8pzs7NFZUWFnNMY+QWEkDveVm6hNf6O6RyqwMOowG0ZuBsTrB9GYWq7ptstYqjtee718TdLnjfAs7wma0X87vX69HyqQE0K3AyqfLcVu1XByt0+v86vCqgCPwwFbsvA8VMY80Y2btkqvUm/r7qJn9yYD8I3dyNnx8hj4Yn56ZqfGl2cXeTTrkGXZ+5U8yaNJVmYx0sS9nW2Go/hVlFCcjLcXFzkE53RJsk47n6YCXMDRz202uqH8QugV6kKqAKqgCqgCvwQFaAvknSTqqqqKobrjQqwmy2GFWgedTwk/6pT+7Zo0zqqxi0VNj6PCA+XMP6cBQtlaycrK0eajG/ZvkO2D7hFw+0pNndn1dK8hV9i974Dcgx/xq1GVsQlJCaJoZsyfize/fBjBAcFSy4Ik2NHDBkseTdtWkXibFo6xo4afs/7sz6sEbgf4kOt16wKqAKqgCqgCjzsCtxWBI4Gjon3LI9vGB6O2Z8vwC9+9ux38k2YP9WwQQP5/rqNm6QMnoYuv7AQIcGByMrKRrMmTaQyjeXnPbpG4x/vfSgJ5MwBY4NvT09PzP5sPvr3jZFzjhkxDBs2b4WXpwcOHYmVSilGAZnMGxjoLwmzPOe9HmrgLFOcOlkrOnkzfhZz6IyesZZd2XePul0+163OVxML735EjW+1vprulflrvm8d38duu5Uu+nNVQBVQBVQByxW4LQNHxAGr1Zh4vnTFKjnbiKGDv/PGzARjVg7aO9gjwM9PTBfRGSw7pxlr2aI5kpKTpYKMCdKdO7TD3gMHceFCLuqFBEvkbf2mzWgd2RJrNm5C9y6d0aJZU6SmpUkCfHbOBUks51YtE+BZzs8KPm9PT8sVsNKRNRm4RQcKkZRzFQ72NniujydcHE1N6JlkTFwF2Vc79uyV6r9O7dtJUnDc8Xgxt6vXbcDk8eMEIcHKs/0HD0qCNtEV48eMksRyU9VbH6zbsBG9Y3ph774DUtXYskUzK62KBWwm6CnDtMYburQKu761bRgP/swYxrY3GWbOTs6CbuDgse988CGee/opQV1w35zfY5EHh/E6o/iDBoxGjAUIvAbzpH1eD/EObaKi5LqM7XfDVLz38Sw8+/QTpvPckKPHxG9+n68xgK5G4rckil9fGz90DOzX95t1X1+jecqAcV3G6/gzzs9rN9/2Nz8PkQ+sLOTg+v7xrw8E0UCkiLFGQ2tDX2N+82s218RIrjd0NG92b0pXuCQVquZJ/Xv27ReMh4G4MNZt3MelK1dJdNt8sPKSif0EB2/YsqW60pQVxXz+Hps+Ff/84CP5QFcTDNhqD6ZOpAqoAqrAj1yB2zJwySnEN1QJc+rv/3gXjRtGCFDTAFFaW1O+sTAiZ3C7rD2/NearycBNej8LB1PKZPq9vw9F3Tomyj8hs6zoio07JjypwIBAqR4d3L+v4A/IgSN+gHgBP18fnM/NQ25unpTxL1+9BpPGjcG6jZsR4F8XS1euRr/evbBuwxb069MLqWnnBCNgrYjOnv0HpIqN1YVOjk5Yu4l8LB+4u7oK9oT5h1z7zDmfiVHjMazmjIqMlIgrYcWE69LMEUXx6dzP8dLzz4DAVGIfUs6eQ9uoVrhacQ1r123ExHGjsejrZTIv+VT5l/PRtGljHImNw5iRw/D1ilViIDq0bSPcsCED+uOT2Z+JniyuIa+rR7euiDt2HB3atcWZM6mwsbVBq8gWoj2vdfHSZejetQs2b90m1ZuE4hKGS5gyESi9e/UU0O9Hn87G+NEjpdq2pKxMtvGZd/nSC8+JqWRl7Ib/YFIu5OWJuQ4NDhZWHismacb4oYLXRe4beWojhgzCodijksM5Y8okuR5WLn4yey6mTZwgSAx+6GH6APEL1IDVhzTrX361VJAQfC6of3j9UEFFcM3kbZEP1rFdW0mBIEKF3z8YG4tr5VfFUPaNiRFoL01c544d5NxrN2ySKlhWf7Kikc/bmJHDq38dyEpjdHvP/v0geoMsvX0HDgoQlucgfoQfzGg6WWWYnZMtHyiI7WjRtIkcp0MVUAVUAVXg7ihwWwbO/FJYvs7Bkvof8yfumgzck7NycCCFyAZg48v14OtuMnCpZ9MEL7Jrz14TT+zCBYwcOkTI658t+AKDB/QHox80QYzOkfZOI0WDR+SGAG537YaXl5dsPzNySaZct67Rsi093YoGbsuOnYIT4Bs2QbHMe6R5atQwQtAB5MBx7X/86xuo4+GO0OAQdGjfVrATBUQbuLqKYSGd/5Gpk/DWP9/D717+JTaRhp+bK9vlQf8xS0EBAdJ9gmaUXQgI9fXx9pFoIrfduV1+Kf+ymLdFS5bh1Vd+jWUrV4kRW7J8hZDyaU5oYmjidu7eJ3BYQmRpZgka5eCHAcJ3S66UiAGjCSU4dtnK1QJcJR6BjL1nn3ocb7zzL4wZMVTYdCkpZ5GRnQVfbx8BERP1wW4HpNbHHj0myAgy1Uie55r4YSY9PROFxSb8S3j9+mLIyA8jE23KhPFyPYyiff7lYgzq11fYXjTLjDQTDEzzxkED9877H+L06US89LNnsXLNWvSN6SUdJRip5jPRr1evaiQJz0fWnYenh3RNYKpDaEiIsNkIliafi2Pdps2ICA8T7Xg/GFWn6TUG2X29e3THgkWLBfj6yi9eFIwE7xVNMeG8DeqbOj2cSkgQjEePLl0EvkyzzpxXHaqAKqAKqAJ3R4E7NnB357J+eLPWZODyr1SgqKwK9raAv4e9VNoab9qMJPENk5GievXqgTDWbtGdsWrdBnSL7iRE9D4xPSVKF92xA+JPJ4gZYSSnS6cOcHBwlDdK5g0SsMq5eCzz/2hIrDXIpCI3i4BeUtVp1GksCJwlkJgMKPLe7B3spHUQzYu7m7tsE5MWzy1g8uzI8mKUcc++A+jSuZMYGUapyNFioQo5c4wA0awlJp+h1ZK1HDxyBE0bN5bvkSLPtk5kd9HYMiLGCBIZVYzO0kTRMDI6tnHrdoED06TRwLFgxjBwB48cRVhoPdnmpDGJbNFMQMGtW7ZCYnKyzMk10rQy4nUuPRPh9etJtIy8N5LvjS1KbikSekrjzWgVczBpAGkYuU17rbICTg6O0umgY/t2AksNCvSvjk7RUDI6Scgso4DUj9uc3NY0tmrJ/kpKSpZIGjldjMRFtWqJE/EnxSRRQy8vz+o+rpyTAGkab5LD+IGhZWQLOZ7XZ3DPWAXO9bJlErfjH5025VuRWxYI0ayz0wMje0xzyM3NFahxekYGQoKC4O/vJ7rS+PL5YKSTEU622bJWFNhaz7LOowqoAqrAw6SAGjgr3U0tYrCSkDqNKqAKqAKqgCqgCtxSATVwt5TIsgPMDRxJ8z/m7WTLFNOjVAFVQBVQBVQBVeB2FZAiQxbx1YYDd7sne5hfZ27g2ELo++DGD7MGujZVQBVQBVQBVUAVuDcKsK2e0BzUwN2Z4LqFemf66atVAVVAFVAFVAFVwHIFdAvVcq1uemRNBu5UVjkuFpEJZoP24U6wtzNVMfBYIjKkgjArW6o5ybDj95nQzo4TTDxv2qSxJKYzTMrjmNjPRttMRDeKBFhxyWR7JtITPcHG1iwOsNZg0QQLCZgEz4pGDianVzPhKquqizOMn5lz43gsG9LvO3AIMT26VSf/sziCDDc2uDeGOdfMmMv4GfVgFWqbVq2qr8Gc2cZvGgw4c2Yaix+IiuxElwAAIABJREFUuTES6nkONnBnscCN5zDmMOfRscLSWGtRcbEUF9TUyN1aeus8qoAqoAqoAqqAJQqogbNEJQuOqQ0HLiMjE8WlV3A07jiKi6+gvPxqNYB3/peLpcovwK+udKwgLJnHbN25C49NnSxgZPLQWIFace0aDsXGSaXk6cREtGzeXColrYkRISuMZieiQTj2HzoskOWu0Z2xeet2DOzfB+s3bkHjRhFIOnNGqlCJ5SDPbOqEccKGG9y/H04lJuLkqQQ8PmMqvL28BaPB6tBGERFiYjloSHk8e+ayq4avrzc6tG0rW9HEaLzxzrvo0Lq1VGKSdffYtMlYsOgrqeYcNnigmLeDh48grH597Dt4EImJyejbuxc2btkmVbDUhIOctfc+nokWzZrBwd4ODSMiZH3kqHGs37RFINOtW0Vi1969GDVsqCBGCJUm3oTVrOTsWaubhAWPlh6iCqgCqoAqoAp8RwE1cFZ6KGpj4AjvZe/XDZu3obKyQthtv3jhOTErZG51i47GBzM/FcBs/z4x+MubbyMxKRmv/f53WLl2HZ558nEB+rIN2adzPsPUSRMwd/4XmDR2NI7Fxwsk1loGQzAX/zFt67dsRXl5uaAiCOp9/idPISU1Dfb2dgKVffu9D9Cre1dBf3w4czZ+/vxPBcgbGhKMZk2bICMzS/Ab5KMdOHxEOjk0bBAuZpWDXLz3PqKxaoozqanw9/MTlhhRGBw0he3btMZrr7+JqFaRiGoZKecf1L9v9R0khHfz9p0YOWywcNpCgoJxOjEJ5WVlGDd6pGhCA5eckorj8SelR2/8yVN4/qdPV0foyDnjnL/9nz9h2uQJgmZhx5Bde/djYL8+8K9bV3hnOlQBVUAVUAVUgfupgBo4K6lfk4E7nlGGnPwKONoBXRq5VG+hkpJPw9WxfVuJ6pBJdjYtHcOGDMTHn87BuFEjBBBLcj9bi5nAvXuEk3alpERMHWAjbcZ6de+GLdt3CFCX/DFGw8iTs9Zg6664+HiTsUpJlWghzROZYm1atwI5aDRlly5dli1eAmhPJyQiulNHiYSR6+bj4y3sNka5Dscelcgb26qdTEgUzhi3N9nJgDBi8uDIObtSUirdPQwjmnP+vJg6Gi8CgHt0icb56y3XjLUSMky2W2BggBiveiEhyMvLE606d2xvMoqVldi9d59sM7N6hxw48uKMQb4ZX5eekYnTSUliGo8cjRMQr59fXYkkdmhnumYdqoAqoAqoAqrA/VJADZyVlNciBisJeQ+nYaQvLDRUK4bvoeZ6KlVAFVAFVAHrKKAGzjo6SmSH0TEOZycn5cBZSVedRhVQBVQBVUAVUAW+q4AaOCs9FeYGzgY2wmbRoQqoAqqAKqAKqAKqwN1RoErICMqBu0N1NQJ3hwLqy1UBVUAVUAVUAVXAYgU0AmexVDc/sLYGzpxZVlNCvPHzG89q/v1bzWGlpX1nGhYcZOfkIDSkHtLOnRMUSEFhoST2e3l6WnRagxV3s4PZRD44KEBz1CxSVA9SBVQBVUAV+DEpoAbOSne7JgP3k3/nYP+ZMtjZAet/HQIfNzs5W17eRcSdOIHS0lLknM+V6s3OHTsgJCgQXy1bgYYRDZBfYGLA+dX1FUbaqnUb0K93L6mInDJhHI7Hx+PU6UThopETx2pNojNcXJwxduQIK63KNM2Ro8fQJqpldeVlbl4eFn+9DP36xCA7+zyKS64gIjwMazduxnNPPSHXQj1WrlkLG1tbBPj5CfetS+dOWLt+o/DZ3v3wE2HENW/WBMeOx8u1kyGXcjYNhYWFyDl/AQlJybL+4UMGCexYhyqgCqgCqoAqoAqYFFADZ6UnoTYcuJOnTwvGYteefUhNS4O7mzuiO3ZAZItmWLj4K0Q0aIAzKSlwdXVD65aRWLpytUS4XnjmaTFOTz46A8tXrRb47yf/notHpkzCnPkLMZEcuBMnMWOK9UCzCYlJ+PzLxRg3aiRaRTavVmvV2vUYOmgANm3bju7RnUE0ytlz6WgV2UKOYYTtN3/4I1579Xf4evkq1K3ri6AAf4SF1cehw7GybhpRctnOZWSIETyZkABfHx8B8kZ36oDEpDOC+CDQuHMHEwZEhyqgCqgCqoAqoApYYOBIwZ+7YCGeemQGVqxZJ2/CbaJaCbeLkRa2FeLW2bVrFbh67SqcHB2lApPQ17Lycri7ueHqtWsCbmWTd7Z9Itts0rgx8nO+gbu6uKD4yhWp3iSbi8cy6uPu7gZHRwf41/XD8ZMnxeTwvC7OzvI6gm8JgGWEinPcz1GTgZu1LR9Hz5XDxQH4/ShfuDnZyiWyW8LeA4dQVlaK4uJiLleAuIP798esufPE2OzZtx8d2rWVDgcE+67ZsBH5+fnSVYCttM7n5iExKUnMX2ZODrw9PcVEeXp6Cj/OmoOsN8Jszbd6yYRjdwYaRhq7S5cuwcbGFl5epi1U6jH78wV4fPpULFu1GleulKBnt644cPgwolq2xNm0NNluJXNt+85dGNC3N7bu2AUnJyfk5xfA09MDl/PzhR9HoHF4WH1rLknnUgVUAVVAFVAFftAKWBSB++0fXsMLzzwlpqqwqEhMWEFRkby5EiTrWacOtuzYKW/ivXv2wKjhQ7FizVrpNDBt0nh8vWKlGLxO7dth974DaNqoIX765GP4w59fR35hAfr3jhHDQnNWWFwsxP7kM6no2qkjKiorkHfxEnx9vEVotjkaMqAfVq5dLwaAr6FJfP4nT95XuOq9yoEzf9puzIH7vry5H/QTqhevCqgCqoAqoAqoAt9RwCIDl5J6Fp8t+ALTJk3A4qXLpRl4uzZR1Q3VXVxc0CgiHCfiT0lT9qceewT//OAjMVeedTwQ07MbFi1ZJttowwcPEnP39GOP4Fe//T1+/fOfYd7CL4WqX1hchAu5eZg/6yPJBSPB383FVVon8fwhQUFo0riRmMWJY0bho0/nSMN3mr83XvvfH5SB02dRFVAFVAFVQBVQBVSB21XAIgNHI/a3t/6Bl3/+s+uRtsuyzTVl4jgcOhKLnAsX0L1LF4m0cVtt2MAB+OKrr6X1EpuAsx3R5u3bZbsvKfmMtEsaOWwIXnrld9KeiD00N2zeAnt7B9l6/Z/fvCyNzeu4u6Nbl85YsmwFAvz94ezsjOzsHPTo1kUauC9buQa2drZiJKdPmmC1/p+3I+a3OHDCgFMO3O3oqK9RBVQBVUAVUAVUAUsUuE0OHA3LjQ3Tzb/H7TyOGxEZ5scwIX/IwAHSHP3G+cxfb/yM3+N/5uf9vvNYsnRrHlPbLVRrnlvnUgVUAVVAFVAFVIEflwIWReB+XJLc3mpv18A9zHlrjIzSwLPYxBjEgxANcqP5vx3VS0pKwO37GwfvBZvR1w+tdzvTVr+Glb8edepYNMely5eloMfNze2Wx7PlmnnRDV/Lf7OA424NVgXzXlhD97t1jTqvKqAKqAKqgOUKqIGzXKubHlmTgfvVwgvYfqoErk42WPZiCDxdTVWoLP5gtSmLOvbsP4DgoCAMHtAPx+NPYv2mzcJH27ZjF6ZMHA8fby/JO+QbcLs2rbH/0GE8+ch0ZOXkYP4Xi2TrevO27ega3QlHj51A08YNMbBfXyutClIlm5t3UapfWRVqVBizKMXf308qgjmYu0hzYGtrIxWnAf5+UkHLtVVcqxAT5+rmij+//ib++5VfSc4jDQv5bzQvNLLnL1xAUGCgMONYZezj7Y3s8+cR6O8v89ep447KigoppAkKDJKK1i6dOiIzKxtOTo4yBytxAwMC8Mmcz6QCtqy0VNqacTveGBmZWVLhTENTQN5eUKAYPl4z18hrJXdu/eatGNS/r8zv5VEHl/MLZH0hwcHVc/GaKyoqRZf9hw5hQJ/eyMzORlBAIPIuXpTrYnV13qXLqBcchPTMTEk7GDVsqMxBff/0+pv45YvP49rVa3B2dhJTmpeXh7p160pVN5+tS5fzRRM3VxdcvMy5gqWgx8vTQyq3CwuL5PpZ6U1j6+jkhOKiYlyruIaS0lKwvVtRcRHq16snqQg6VAFVQBVQBX7YCqiBs9L9qw0HLv7UaYlCHY6Nw9YdO9G6VUs4Ojhi1PAhmDlnniBF+vbqKWYtODAAxVdKcD43F+np6aiCDX7zy59j6cpVaNmiBT6aNRuPTpssyA6iWQjFtSYHjgUjNFIsZGkQVh//+vATREY2Q73gEDE+XTt3EoPx1rvvS7TK1dkZLZo3hZeXlxiqOu5uOHHqNOLiTsh1kin33NNPYPa8+RgxdDAOHI5FdMf2uHr1mvDf+veJkYKVQf374fMvFsn6fX19QXbeY9On4v2PZ2H08GFo0rghVq1Zh549umHOvAUg7obmrUfXLoJZIWeuRfNm0jGCeJNGEQ3kTtPsLF6yDAP798HHn86RLhId2rYWM9S5U0fMnD0Xk8eNhbe3F97653uSq8k5CFDOyMqSopyXf/EiHOztpZiHaQC8b/5+flizfgO8vbzE4B2KPSqvGz96FL5evgJ16tRBn549wGjbgcNHMHXieLkeIna4Thr42KPHkJGZKWacpjY4OBj2dnYCfJ45dx6ysrLRIDxMoMoO9g44FBsrrLwO7duiXesoMWc0n7zOhIRExMYdF5NKs9qvdwyY1JCYlCzIFh2qgCqgCqgCP2wF1MBZ6f7VZOBemn8Bm+OvwN3ZFqt/GQJPF1MELuf8eYk2HTgUK2+u/HeTRo1QXn4V9vYsyqiQSI+Liys8Perg4OFY2Z5zdXWFv7+JA0cTWFZWjpSzZ+Hh4YGcnPPyBl5+tVyqha01tmzfKZHBgAA/HDp8FIlnktG7Rw80bhQhho0GjkbtxV//Bm5urtJNgfw6mo4du/dKhMjYSh07agT++ub/4dX/ehlLV6wSrh1NSk5ODoYMGoCPZv4br/zi59i0bRt27NqNzh064EJeHrpFd8auPXulqjkstD5WrVuHV1/5NT74ZBZ69egunDl2e/D19UHbqFYIDa2HlWvWCeB4z74D0g2iZ7cuIgnv08JFX0lUjuxBLw9PdO8Wja+XrxQTlJaejoSkM5g+aTz+/Mb/4alHZ2D7rj2yNXouPV3M7AvP/EQih9wK/eubbyOqZSTGjx6JN995Fx3bt0dySgqaNm4ERvq4RhpQRsUmjBmFufO/kKjYTx5/1GQoKyrE1I4eNhQz534GJwdH9OvTS0ygm6urHCOFPX/+G44eO46XX3pBIoOTx47Gpm075DxXSkvQL6ZXdbcK8hX/8ve3RA+idhiV431av3mLHE8enw5VQBVQBVSBH7YCauCsdP9qMnAVlVWoqDLVozrYfVOVSsNDA8ZoSmZmlrzRknVH01ZUVCxRIW4xMmrEr3a2thI5YjQrO+e8oFr4pswoU4PwcJw9myamJTMrSwyGpf1ILVn6wSNHpGsEzSEjXHb29nI9NEAn4k8iNe2cRIsYNWK0iBEgbqVyjYwuSQ6cra185X+MdAUG+Mu2nkCgbW1l65BbjWwLxsgWz8Ph6OgoJovbtKWlZbK9SMPDLUsez/l5LumrKtu3pvPw3GfPnUNEeLjoRuXNc7+KiopM24g2NigtKZUiGrYjowFlJM/ezh529nZiPLk1yuvhVqZRMMPvGYOmu7KqUrZJDbg0jR3NF02bvYOD6MJtZZp1rseAXRtzGH1hS0pKxRgaOYPmBUC8BkNDGllqTk3sHexNW9fX9TXmpJbGE0etjevhujUPzpInX49RBVQBVeDBVkAN3E3uT20KDG63iOHBfjz06lQBVUAVUAVUAVXgQVTAIgPHSMe59Axpo1VT1R8XZiShk9dmDCaEWzMadK8FZK5S/XohwqC71TA3cIyOmVde3uq1+nNVQBVQBVQBVUAVUAVqo0BVpWmLz6aqqqrqRryBMRGrIFs0aypbTUyM5v+HhdaTllpnzqYhKrI5jsQdAxufv/T8s0hJTeWmFXLz8iQhn9tSgf5+skVma2MneUZMgGc+zoM8aMrYEWJAnxjpMXqzoRG4B/lO6rWpAqqAKqAKqAIPlwIWReCYM0Qjw+gbc7f86/rC2cUVLs5OSM/MEsTD5PFjsHvvPjz39JN4/e130LhhQ0Ey7D94CH5160pVH1EHzOviHEzoZvXlgz5YGUmzSRyGGrg7v1s1AaDvfNbvzsDcN8nV03HbChi5ebWd4HZfV9vz6PGqgCqgCvyYFbDIwO07cAgnTyfAw6OObKWSR5Z85gyGDhog1X7hYfWlUpEmZ+zI4Th8NE6SqsmuyszOgq2NrSTdM2n/0qXLkojv6+stvLMHeRyOPSqJ9C1bNL/lZdYUgft4az6OpJYJB+5PY33h6mgyFIxEkuEW3amj4ClYlMDKwCOxR7Hv4CEMHjgAm7ZsxbjRI6XSc8OmLbhaUYFWLZpj1969mDRurLDQ2GIspkd34cB17xqNw0fipDqU98dag1vjXBu3hPnVKBIwOmIYifZGgj/Pa+QO0sBTP3No7bsffYJnn3y8OpHePFHfmNM4J5Ptbzw35ze+l3wmBQ0jGlQXF5hfw6dz5wl2xEjYNz+PAbU11sJjeE9o+Mw7e3ALnaw+83Xz/OZFADX9jPMbxxhaGGvj8Tt370XP7qZKUP77g5n/xtQJ4+T3y7hOw+ia68vmJuzSVpMm5h1KzM8p5/hPlfCli5fg7OIMdzPQMDE1baJaSeGIMcx1WrVuvfyOmn/vzH/6IjdsEC5FH5t37MDwQQPlpfyglpB8BmNHDJM2eD994jH5ndehCqgCqoAqcHcUsMjAGW80RnWh+R90442GbxI0bTWNG4sBalMccHeWbdmsrCq09E2oNhw4Am4ZzSQe5ExKiuQJMkrZt3cvfH0dr0GeGXvJEs6akZUt8F++abK7AJlhazdsRmCgv+AviJ1Yt34T+vfpjZS0NMFn3NjCzLIVf/eonXv24WxaGkKCg5CbmyfmnFBcFxdn9OzeTdAbXPt7H88S0K5UOdrYoFt0JxyKjRPG28EjscJMGz54IGbO/gy/fOE5vPfxTHTp3AmXL+ejQ9s2UlG6fNUaTJ88AfO++BL1goJBHMaphEQxOxu3bMWYEcOxbecuOf+YEcMw/8vFmDR+LP714ceC+WBFqI+PF4YPHoQjR4+hU4d2SEhKluuhUTE9x1X4cNaniOneHfsOHkRhUTHGjx6BVWvXC1x3weKv0KFdG0RFRuKdDz7CY9OmCLaDJodmmwbod6/8SipL+WHkq2XLUVJWJtBcPz9fNG7YCIdjY9EqMhI0mKw8Jf6FCJJHp07Gxi3bxHzPmDJJroedKd7/ZBaemDFN1sbevh3btUVCYjK6d4mGl5enIFnmfbFI+gAzfeFyQQFiunfDkuUrxfQFBgaAuRB9enYX3hyZfUyH4AcQVqoWFReLdrHH4oRXR/gxx5r1G6WCl/BkPutMbWBk3BjLV69F757dsWPXHpxOTMTEsaOx98AhMc1xx0/I/WkYHiZmNSMjU+DShEgTZNzqP4xCfjDRoQqoAqqAKnB3FLDYwN2d0z88s9Zk4B6fmYOdCSVwtLfB9t/Vg4+bqaVU6tk0edMjY41GiAy34UMHCcw2Ni4Ozk7OYpiIECHXbNuu3YKycHR0QHj9+hIR3L57D+r6+ErnBhqhbbt2oVe3rtJRYPrkiVYzcFt37EJVVSUyM7ORnJqKpOQz6Ni+3bc4cFw7OWU0VozGkgN3tbwcmdk5YmAuXrwIRm5ohv7+j3fx6iu/wvpNW6TDAbenfX28ERZWH0fjjoth4LY1zUNovRCEhoSgdatI7Nl/EPkFBWjfJgqfzv0cf/nDq/hyyVIxOUtXrRaTRhNHM0iTS9MxbPBAOQdRJRHhYdcNXKXMTUNMdEtk86bymvmLlqBtVEuwfRYN57NPPYG/v/1PkF2XnpGBtHPpgkAx58AR1Ltr734ci48XQ9cgLKw64tioYQTS0tJRWFwk3RZYCNOjazQOHjkqhthg9RkcuMH9+2LLth1ithhNDQkKFqwJB3NI3373fTGzv/75z7Bw8RIxw4lnUiQlgeBecw4cj3/t9Tfg7eklqQuh9eqhaZNGgplhGgONPse6jZtNSBp7e2zYslV4e+3btjEzcGvQp1dPYdedO5eOF5/9CRiVqx8aKs/E2fQMeHt6yrOclZ0NN1c39OnVA4Q/jxgySKDGOlQBVUAVUAXujgJq4Kyka22KGBiBnLfwSwwbNBA79+xFZPNmEimyd7BDSuo5xPToKhGkkUMH49iJeIkCMpJCPhy3vaI7dpA3d5q3IQP6Y8PmrWJ8du/fj6aNGstWtbXGrr37BBDLyA8NFJls7GzASNHphETZUnd1cUabqChhp5HtRk4a9SDXzMbWRrhnBsOMUSFGw7i96u7uLtuWNKc0X6Vl5ZJXyQgVt925RkKOyaFj+ygfLy+B2hJ0zJ+RrcYiGUZ/hT8nvT651VuBzdt3YFC/vhJZ4r6jsU1I7Rn1orHh8dImzN9PTDRbcF3Kvww3FxeZz2DP0VRxK5tzcR3cFjYinLIONzfMnb8Qo0cMk2hqXt5FiZwZ27E0OMwTJf+OhT2ci3MYg2vivzkXeW2mlmQmpp0xeA0GT6+o+Arq+vpI9JIfAHg/yI8zP57RSNPLbXDp0kVpy8UuELw+o0Ka62G7L+o7f9FXmDF54rceG0YcCSnmuXkPOfghgzw+GkGac2MdvN98PvisMIrMCKm1osDWepZ1HlVAFVAFHiYF1MBZ6W7WxsBZ6ZT3ZBojx6umN2P+jOaJPuHHjk35ISfum+c53pOHSk+iCqgCqoAqcMcKqIG7iYS1qZg0N3A3kvbv+C7pBKqAKqAKqAKqgCqgCpgpwA/f0m3oZhw4bpOxIo+5QsxLYh9PbkO1imxRXZXIPBxucTFh27wa0DgXt8m4jcTk6oKCAkm2btww4lsVfYzy3KwY4l7fuWPxJ2U7LKZHt1ue2tzASSsmO0VY3FI0PUAVUAVUAVVAFVAFbksBKQhlus3NDNymrduk/yRzsJh87uDogLo+PpIbExwYKIYuv6BQcq+YXP1/774v0F+y4FiRF9GggSSNMweH1ZaHY+PQplVLlJSVSr9J5lUxr4nVbWzOThQJ84Tu96A4RKgEBQUgLDT0ppfzsG6h3u97oOdXBVQBVUAVUAVUge8qYNEWKqNrF/MuYcHiJVIdSXzFxYuXJCGalZGeHkyMtkVwYBAaRoTjk3/PhaeXJ9LT0+Hr6ys5Uky2P3r8uCSNEylhZ2uDgsIiMW2s8BvUr49U063esAm/euE5BFrQvupu31AmghMv0a93L0Fk3GzUZOASssuRV1gBezsbtA1zkq8cNIZEibAykXowCd7fr65oej43V6KcGZlZaBBWXwoYiGWoqqyUqj6iGho2aCDJ5GxmTwOdmZONQD9/5F7Mg2cdD/j4eFtVmhuxL4xKnk5KRGTz5lIZyQpProNJ8UZU9lYXwOpQJvXfrLE6mXcd27eXwggdqoAqoAqoAqqAKvCNAhYZuJKSEqSmnatGFhAXQd4XkRXBgQFiyLy8vAQXwSjcJ7PnYuSQwYCtDSquXpNqNVYZciuWyIjiK1fg7OwCW1sb5OfnizGRSsuyMkE13Li1er9u2Nadu9C1U8dvVQx+37XUhgNH4+Vg7yCdKyoqK1BQUCRVkUMH9seO3fsQd+IE+vbqIVowEpmWniH9zlhJ2TemJ3x9fARBwkrMTVu2oW3rKOzed0DYa6zatCZGhOZt6YpVGDlsyLfgtLM/XyDXy8pJduMgl2zWnHl44tHpUt3JpP7/+v3/IiAgAH6+vhKlnTRujEBep04cj7f/9b5UiRJJQqyHm4szxowcLriQrJxsQXA4OTvLep5/+kmE1b95BPR+PSN6XlVAFVAFVAFV4H4oYJGBq+2FfV9P1drOc7+Prw1wuDYG7nRiEry9PAXqSqPDrWiaGiIZvvjqa+GpkX0WfyoB/WJ6illjV4vKigqEhYWCkF9GBhtFRGDu/AUYP2aUREfHjRyB+FOn8MjUyVZDODBSRu4YeWjsf2uMA4cOi/nasWs3unftgouXLoFGv15IiBzCdf3+tb/iT6/+Fou+XiaoCkbcaPD3HzwsLLQpE8bJcTwHNVi5Zi3Cw8Jw4uQpjB4+DDTQIwYPxOX8AoHy6lAFVAFVQBVQBVQBkwJ3xcD9GMWtycDFnStD1uUKONoDPZq4VG+hMtK4Zv0G2QpNOpMiEarcixclcsXoZNMmjZGQmCRgXnZWIAiWHQTIKaPxIWy1ouKatN0i8Z85hQTSEpYbGhIsxsqag6wwRv3MB6+XeZAGjJc5jixCYYcJDppfdpro2L6ttFkjIJetwA4fPSbmlAyzq9euShcAdixo3rQJUlLThC9HDcpKSyXKS9hu+7athS+mQxVQBVQBVUAVUAXUwFn1GahtEYN5v8qaGGuWRP9uNYdVF6iTqQKqgCqgCqgCqsADo4BG4Kx0K5QDZyUhdRpVQBVQBVQBVUAVuKUCFnHgbjmLHiB70cz94zC1jVIOnD4WqoAqoAqoAqqAKnCXFKiqhANbO96MA3eXTv1QTVvbLdQ7WXxNoOQ7mU9fqwqoAqqAKqAKmCugvYwf/OdBt1CtdI9qMnCFJZUoLquEnR1Q153Nxr85GZlvnp4eUn3JxH+yzshRYwI/E/YLCgrh4WGCGbPogfMTeExsB7ErNHEsDCBmpKio+Hpz9ytwcnKSZvLWGjxvSupZBAUGSJeN2xmcI/7UabRs0bz65YeOxKJ5s6ZwvV70cKt58/MLkJ6ZicjmzW516Ld+TgwJeXvGYDEICy6ItqntIHSaPV/1D1ttldPjVQFV4EFXwNK/a5Ye96Cv92G4PjVwVrqLNRm4x2ZmY8fpUqlC3fnfofBxs5Oz5eblYf+hw2IECDEmA4+dKch127x1B+r6+qD86lU0bdxYTBx5cTQe9UNDxED06t5NKjuPnYgXNlthYaGYNv4/O2AQ+WGtsWXbDjGQUS0jkZubh/yCArRo1hSKZhFtAAAEx0lEQVSxcceEP3fwSGx1Nw6ugx0rEpKS0a1LJ2zdvlOqZNldgxWzTz4yHe7u7gImPp2QKPOwuwcH9eO5aOpycs4LODmiQbisicb20znzpDqX0OOcCxfQr3cMtmw3adWhXVugCkhOSUFISDCOHT8h19qieTOs3bAJzZs2Rc/uXeQ8BCAvWrIUkS2aif71goNlTkcnR/l57NFjYpIJJz5+8pRwAMnYI4fuxKnT8PX2Qp+YnmrirPWA6TyqgCrwQChgI8j9747vM2xq5O7/bVMDZ6V7UBsO3MmEBEFw7Nl3AHHx8QgKCEDn9u3RtEkj/HvefImqderQHrFxcWKSaHbY6SDv0iWJWD0xYxqWrVotxmTWnM8wbdJ4zFu4CONHjxRjN33KRKvl4DFatWT5SuG4ZWfn4MzZVNT18ca0yZOQkZGJ0rJSNGvaFH/62xsIrx8qhi07J0e6VyxZtgLdukYLtDgzKwshwcEICPDHocNHRHUy4ULrmdhy5eXl+GrpcnTq2EGMn39dXwwa0E/MLd3Z7r37BSfy2utvoVmTxoju1FEM7PChg2BnazLGNGbscMEWbrwfTo5OKCsvk3ZtkyeME9NFA3c6IQGnk5Lg7ekl1zp5/FjpJ8exYtUaDBnUH3/66xsYNXwYks4ko0F4OMi9698nRlrBmSKjNf+xs9LjpNOoAqqAKnBXFTDfEarRuNXwN64m06ZG7q7epptOrgbOStrXZOBmbc/H/uRS1HGxxR/H+MLV0WQSuD26e/9+lJaWorjoCiqqKiXKhKoqiQaxFVZ6RhZat2yBnNxcnEvPhBP7z/r6oLS0DK1aReLixctiRNiyjFE8Gp7i4ivw8fbGsCGDTKuqqrrj1dEQ7tyz1xRtO3xETNyEcaMFxtsvpheWr14j0bm44/EI8K+LJo0aSf/YMSOGYeW69YgIC0PjRg0l6ujr64PV6zegdWRLhIQEYcPmrXhkCqHDQElpKRYuWiJRuTOpqcKXe/G5n8Ke+8+AGFNun877YpGs94Vnnsap0wnfYt59uWSpGL62Ua3kPOTOHT95Wtq90fRyEBw8c/Zn0q6MEb4du/bgqcdmVOvEdREavGP3HnCbd8TQwQJNZjSU69y4ZasAiG/WAuyORdcJVAFVQBW4mwqw0O775jdzduYmz/wVauTu5s2xfG41cJZrdUsnbFShOluQh0YjQRPAG8BfBqMwwWC7VVZVwY4/r6qU83ILVY67fjz//1pFhemY698zvlr7E5E5b47XYlyv+VeTX7x+jTd8NRfOnG93I+uupvPUJHptGXnGNRtzGa9nF4kunTt9b85gTZw9S85tpUdKp1EFVAFV4J4ocON7RvW/azBzhpFTE3dPbs0tfUcF3/+lCvXKldtOVL//S7m/V8BtOuaKcVhi4MzNRI3/j6pvAmjXI2nmJs8wTOZfb/z/+6uInl0VUAVUAVXgQVfA3IgZ/2/+9UYzZ3i67zNy1g4gPOj63c/r+1YEjhWRTJJnVEeH5Qpwo5IGzjBY3PazdIvNHAlSbdDk1N82cPyZbIjyq/n/X7/Mb6NFrm+dVkluvw5VQBVQBVQBVeCbbVPZP/1mE9X0T9O/hWN6/d/8KobM/HvXX1ajgbvZ1qzqb3UF+P5Or/H/x3EJsA725GsAAAAASUVORK5CYII=


# Introducing the Upsun Developer Center
Source: https://developer.upsun.com/posts/releases/introducing-dev-center



<PostMeta />

This month our Developer Relations and Advocacy teams are excited to share with you our latest resource: the Upsun Developer Center.

## What's it for?

In short, the Developer Center is meant to act as the central resource, a primary hub, for all technical content you as an Upsun, Platform.sh, and Blackfire user will need to be successful using our tools. Whether that's training, reference documentation, technical articles, example code, demos, talks, or community news. Everything happening in the world of Upsun resources will be found right here on the Upsun Developer Center, or will be accessible from here.

## Why do we need one?

I've worked at Platform.sh for over 6 years, always in some capacity within Developer resources, training, and public documentation. In that time we've produced a lot of helpful things for (and with) the community:

* the [public documentation](https://docs.upsun.com), and the [API documentation](https://api.upsun.com/docs/)
* [many, many templates](https://github.com/platformsh-templates/), [example repositories](https://github.com/?q=topic%3Aupsun-example+org%3Aupsun\&type=Repositories), and [public](https://github.com/platformsh?q=config-reader\&type=all\&language=\&sort=) [libraries](https://github.com/platformsh?q=platformsh-client\&type=all\&language=\&sort=)
* [awesome repositories](https://github.com/platformsh/awesome-platformsh) of helpful [snippets](https://github.com/platformsh/snippets)
* [Upsun Community Forum](https://community.upsun.com/)
* talks, demos, podcasts and livestreams on our [YouTube channels](https://www.youtube.com/@upsun_com)
* our [Upsun](https://upsun.com/blog/), [Platform.sh](https://platform.sh/blog/), and [Blackfire](https://blog.blackfire.io/) blogs

Now while these resources are available to you, and while my colleagues and long-time users may understand where these pieces are and how they fit together to answer questions like:

* Can I deploy Meilisearch on Upsun?
* How do I set up load testing?
* Why is the file system read-only at runtime?

you do kind of have to know where all these resources are - on top of the "rules" of Upsun in the first place - to put the pieces together to answer questions like these ones.

As you can imagine, the problem isn't made simpler with the three brands of Upsun, Platform.sh and Blackfire.

This is not what we want for users in their first days working with our platform (or on any day for that matter). While our resources are excellent they can be difficult to find unless you know exactly where to look. They should be more discoverable, more intuitive to navigate, and it should be much clearer how different kinds of documentation fit together via common product concepts.

## What's in the MVP?

Today in the Upsun Developer Center you can find:

* **[A new landing page](/)** with quick access to the most useful documentation and resources
* **[New search](/)** combining Developer Center, documentation, and blogs in one place
* **[A new technical blog](/posts)** containing tutorials, how-to guides, and in-depth discussions about how Upsun works under the hood
* **[Tutorials](/tutorials)** to bring visibility to all our talks, demos, livestreams and podcasts
* **[Upsun Community Forum](https://community.upsun.com/)** with details around community programs, product roadmap feedback, and more.

## What's next?

This MVP is just that -- an MVP. It's only the beginning, but we have big plans for this site. Some of the things we see ahead include:

* Continue to improve the search experience, especially as it brings together resources across all of our sites, and code examples on GitHub.
* Integrate and bring visibility to public code examples, but also forum discussions, FAQs, and popular topics on the [Upsun Community Forum](https://community.upsun.com/).
* Improve the way we interact with our users within the Developer Center - not just in retrieving product and documentation feedback, but also in providing ways that you can contribute yourself to the resources seen here.
* Modernize [the Upsun Documentation](https://docs.upsun.com) by folding it into the Developer Center.
* Introduce new community programs and sponsorships, details of and submissions to which will also be found here in the Developer Center.
* Expand training, certifications, CLI/API reference docs, and much, much more.

This launch is an exciting first step in our team's efforts to better enable our community with the resources you need to succeed on our platforms. Be sure to join us on the [Upsun Community Forum](https://community.upsun.com/) to stay tuned for updates and to share with us what you'd like to see on this site.

Be seeing you!


# Introducing developer.upsun.com: Upsun docs, rebuilt for developers and AI agents
Source: https://developer.upsun.com/posts/releases/introducing-developer-upsun-com

The Upsun documentation has moved to developer.upsun.com with a complete infrastructure rebuild focused on agent-readiness. 244+ pages of structured, machine-readable content with llms.txt support and built-in AI assistance.

<PostMeta />

The Upsun documentation has a new home. Today we're launching **[developer.upsun.com](https://developer.upsun.com)**, a complete rebuild of our docs infrastructure with 244+ pages of structured, agent-ready content.

We rebuilt the docs with AI agents as a first-class audience. Structured metadata, llms.txt support, built-in AI assistance and a cleaner content architecture that makes it easier for both humans and machines to find accurate answers.

If you're building on Upsun and using AI coding assistants, the documentation just got significantly more useful.

<img alt="The new developer.upsun.com homepage" />

## What's new

**llms.txt support.** The ne