add back cloud templates #633
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,56 @@ | ||
| --- | ||
| title: Cloud Templates - Best Practices | ||
| description: Proven tips and workflows to get the most out of cloud templates in Factory | ||
| --- | ||
|
|
||
| Cloud templates let you spin up consistent, production-ready development environments in seconds. Below are field-tested practices that keep templates fast, predictable, and team-friendly. | ||
|
|
||
| ## 1. Smart Setup Script Practices | ||
|
|
||
| | Practice | Why it matters | How to do it | | ||
| | ---------------------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | ||
| | **Order commands by dependency** | Later commands may depend on earlier installs. | Run package installation first: `npm ci && npm run build` or `pip install -r requirements.txt && pytest -q` | | ||
| | **Use exact package managers** | Consistent lockfiles prevent version drift. | Use `npm ci` (not `npm install`), `pnpm -w i`, or `pip install -r requirements.txt` for reproducible builds | | ||
| | **Add error handling** | Stops build on first failure, saves debugging time. | Start your script with `#!/usr/bin/env bash` and `set -euo pipefail` for proper error handling | | ||
| | **Make scripts executable early** | Avoid permission errors mid-build. | Add `chmod +x ./scripts/setup.sh && bash ./scripts/setup.sh` or use `bash ./scripts/setup.sh` directly | | ||
| | **Keep scripts idempotent** | Re-running setup shouldn't break things. | Use flags like `pip install --no-deps` or check for existing files before creating them | | ||
| | **Minimize heavy operations** | Long builds slow down template creation. | Focus on essential setup; defer optional tools to manual installation later | | ||
|
|
||
| > **Tip:** Test your setup script locally first. The script runs with `bash` at the repo root, and you can add `set -euo pipefail` for strict error handling. | ||
|
|
||
|
|
||
| --- | ||
|
|
||
| ## 2. Workflow Patterns That Scale | ||
|
|
||
| <AccordionGroup> | ||
|
|
||
| <Accordion title="Spin-Up-Per-Task"> | ||
| Treat remote sessions as disposable: create one per ticket or PR, then archive when merged. | ||
| **Benefits:** perfect isolation, zero “works on my machine” drift. | ||
| </Accordion> | ||
|
|
||
| <Accordion title="Parallel Environments"> | ||
| Need to test multiple branches? Launch two separate sessions; switch context without killing processes. | ||
| </Accordion> | ||
|
|
||
| </AccordionGroup> | ||
|
|
||
| --- | ||
|
|
||
| ## 3. Team Collaboration Tips | ||
|
|
||
| | Tip | Details | | ||
| | --------------------------- | ------------------------------------------------------------------------------------------------------------------- | | ||
| | **Name templates clearly** | Name templates according to the tracked repository, e.g. `factory-mono` to work on the `factory-mono` GitHub repo. | | ||
| | **Document entry commands** | Add an `AGENTS.md` file with common tasks (`npm run dev`, `pytest`). Droid automatically reads this file. | | ||
|
|
||
| ## 5. Troubleshooting at a Glance | ||
|
|
||
| | Symptom | Resolution | | ||
| | ---------------------------- | ---------------------------------------------------------------------------- | | ||
| | **Rebuild is slow** | Verify `.dockerignore`, cache heavy installs in image, use lighter base. | | ||
| | **Git asks for credentials** | Ensure repository integration is enabled in **Integrations → Repositories**. | | ||
| | **Out-of-disk errors** | Prune package caches (`npm cache clean --force`) or rebuild template. | | ||
|
|
||
| Following these practices keeps your cloud templates fast, secure, and collaborative—so you can focus on shipping code, not configuring machines. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,50 @@ | ||
| --- | ||
| title: Cloud Templates | ||
| description: Spin-up instant, cloud-hosted templates that mirror your local dev setup. No install required | ||
| --- | ||
|
|
||
| Cloud templates let you code **anywhere** without the “works on my machine” dance. Each template is a pre-configured environment that lives in the cloud, boots in seconds and can be customized to run setup commands. | ||
| ## Why use cloud templates? | ||
|
|
||
| | Benefit | What it means for you | | ||
| | ----------------- | ------------------------------------------------------------------------------------------------------- | | ||
| | **Zero setup** | Open a session and start coding; no local installs or VM juggling. | | ||
| | **Consistency** | Every teammate (and CI job) runs the _exact_ same environment. | | ||
| | **Speed** | Heavy builds run on powerful cloud CPUs; your laptop fan stays silent. | | ||
| | **Isolation** | Experiments live in disposable templates, keeping your local machine clean. | | ||
| | **Collaboration** | Share a template link; reviewers jump into the _live_ environment with code and ports already running. | | ||
|
|
||
| ## Get Started | ||
|
|
||
| <CardGroup cols={2}> | ||
|
|
||
| <Card title="1 · Create a Template" icon="rocket" href="/web/machine-connection/cloud-templates/installation-and-usage"> | ||
|
Contributor
There was a problem hiding this comment. [P1] Fix incorrect navigation path (Settings → Session vs Templates) This page tells users to use Settings → Session to create a template, but later says Settings → Templates; at least one is wrong, which will block users from finding the feature. |
||
| Use the **Settings → Cloud Templates** page to spin up a new cloud template from your repository. | ||
| </Card> | ||
|
|
||
|
|
||
| <Card title="2 · Add setup script" icon="toolbox" href="/web/machine-connection/cloud-templates/setup-script"> | ||
| Configure a setup script to run during template creation. | ||
| </Card> | ||
|
|
||
| <Card title="3 · Follow Best Practices" icon="lightbulb" href="/web/machine-connection/cloud-templates/best-practices"> | ||
| Optimize performance, cost, and team workflows with proven tips. | ||
| </Card> | ||
|
|
||
| <Card title="4 · Troubleshoot Like a Pro" icon="bug" href="/web/machine-connection/cloud-templates/troubleshooting"> | ||
| Quickly resolve provisioning, connection issues. | ||
| </Card> | ||
|
|
||
| </CardGroup> | ||
|
|
||
| --- | ||
|
|
||
| ### More to Explore | ||
|
|
||
| - [**Installation & Usage** – step-by-step setup guide](/web/machine-connection/cloud-templates/installation-and-usage) | ||
|
|
||
| - [**Best Practices** – performance, cost, collaboration](/web/machine-connection/cloud-templates/best-practices) | ||
|
|
||
| - [**Troubleshooting** – common fixes & FAQs](/web/machine-connection/cloud-templates/troubleshooting) | ||
|
|
||
| Ready? Head to **Settings → Cloud Templates** and launch your first cloud template. Happy coding! | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,109 @@ | ||
| --- | ||
| title: Cloud Templates – Installation & Usage | ||
| description: Set up, connect to, and use Cloud Templates inside Factory sessions | ||
| --- | ||
|
|
||
| A **cloud template** is a fully-configured, on-demand development environment that lives in the cloud. Cloud templates give you the same tools and dependencies you'd expect locally, so you can build, test, and run code directly from Factory. | ||
|
|
||
| <Note> | ||
| To get the most out of cloud templates, configure environment variables and a setup script during template creation. The setup script installs dependencies and prepares your development environment automatically, ensuring every team member has an identical setup. | ||
| </Note> | ||
|
|
||
| ## System Requirements | ||
|
|
||
| - A repository enabled in Factory | ||
| - Manager role or higher to create cloud templates | ||
|
|
||
| <Steps> | ||
|
|
||
| <Step title="Open Cloud Templates Settings"> | ||
| 1. In Factory, click the **Settings** icon from the left sidebar. | ||
| 2. Select **Cloud Templates**. | ||
| </Step> | ||
|
|
||
| <Step title="Create a New Cloud Template"> | ||
| 1. Click **Create Template**. | ||
| 2. Enter the repository you want to use. | ||
| 3. Give your template a friendly name (e.g., “frontend-template”). | ||
| 4. (Optional) Configure a setup script to run during template initialization. | ||
| 5. Click **Create**. | ||
| <Note> | ||
| Factory clones your repo and prepares the environment—this can take a minute for large projects. | ||
| </Note> | ||
| </Step> | ||
|
|
||
| <Step title="Verify Template Ready"> | ||
| The new template appears in the list with a status indicator. Once it shows **Ready**, you can use it from any session. | ||
| </Step> | ||
|
|
||
| </Steps> | ||
|
|
||
| --- | ||
|
|
||
| ## Launching a Cloud Template inside a Session | ||
|
|
||
| <Steps> | ||
|
|
||
| <Step title="Open or Start a Session"> | ||
| Join any Factory session as usual. | ||
| </Step> | ||
|
|
||
| <Step title="Connect to Cloud Machine"> | ||
| 1. On the session start page, click the Machine Connection button. | ||
| 2. Choose **Remote** tab. | ||
| 3. Select the template you created earlier. | ||
| 4. Factory attaches the cloud template to your session. | ||
|
|
||
| <Frame> | ||
|  | ||
| </Frame> | ||
| </Step> | ||
|
|
||
| <Step title="Confirm Connection"> | ||
| A green indicator and remote working directory appear on the top-right next to your profile dropdown menu. You’re now interacting with the cloud template. | ||
| </Step> | ||
|
|
||
| </Steps> | ||
|
|
||
| --- | ||
|
|
||
| ## Everyday Usage | ||
|
|
||
| <CardGroup cols={2}> | ||
|
|
||
| <Card title="Run CLI Commands" icon="terminal"> | ||
| Use the **Terminal** toolkit to execute commands like: | ||
| <pre>npm run dev | ||
| pytest | ||
| git status</pre> | ||
| Output streams live into chat and logs. | ||
| </Card> | ||
|
|
||
| <Card title="Edit & Save Files" icon="file-code"> | ||
| Open files from the repo, make changes, and save. | ||
| Files persist in the cloud template and can be committed upstream when ready. | ||
| </Card> | ||
|
|
||
| <Card title="Auto-Save Controls" icon="save"> | ||
| Auto-save is disabled by default—enable it from the **Session Settings** panel whenever you want live file syncing. | ||
| </Card> | ||
|
|
||
| </CardGroup> | ||
|
|
||
| --- | ||
|
|
||
| ## Troubleshooting & Help | ||
|
|
||
| <AccordionGroup> | ||
|
|
||
| <Accordion title="Can't connect from session"> | ||
| Ensure you: | ||
| 1. Selected **Remote Machine** (not Local). | ||
| 2. Refresh the page, or try again in a different session | ||
| </Accordion> | ||
|
|
||
| </AccordionGroup> | ||
|
|
||
| <Card title="Need More Help?" icon="life-ring" href="/web/machine-connection/cloud-templates/troubleshooting"> | ||
| Visit the full Cloud Template Troubleshooting Guide | ||
| </Card> |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
[P1] Fix docs map labels not updated to Cloud Templates
This section still lists “Remote Workspaces” items but links to
/cloud-templates/..., which will confuse users and breaks navigation consistency (label and destination now disagree).