diff --git a/docs/03-services/07-box.md b/docs/03-services/07-box.md deleted file mode 100644 index 59e7bb70..00000000 --- a/docs/03-services/07-box.md +++ /dev/null @@ -1,3 +0,0 @@ -# Box Service - -Documentation Coming Soon diff --git a/docs/03-services/07-box/_category_.json b/docs/03-services/07-box/_category_.json new file mode 100644 index 00000000..65b6086b --- /dev/null +++ b/docs/03-services/07-box/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Box Service", + "position": 7 +} diff --git a/docs/03-services/07-box/index.md b/docs/03-services/07-box/index.md new file mode 100644 index 00000000..498a643a --- /dev/null +++ b/docs/03-services/07-box/index.md @@ -0,0 +1,134 @@ +--- +sidebar_label: Overview +title: Box Service +description: Development environment for your applications with presets, Web IDE, and deploy workflows. +--- + +# Box Service + +The Box service is a development environment for your applications. It provides a pre-configured environment with popular languages, frameworks, and tools, allowing you to develop directly in a web-based IDE and deploy your application simultaneously—no local setup required. + +## Box Service Presets + +When you create a Box service, you choose one of the following presets. Each preset comes with the runtime, tooling, and dependencies needed to build and run that type of application. + +| Preset | Description | +|-----------|-------------| +| **PHP** | For PHP-based applications. Includes PHP runtime, Composer, and common extensions. Use for custom PHP sites, APIs, or legacy PHP apps. | +| **Node.js** | For JavaScript and TypeScript applications. Includes Node.js, npm, and yarn. Use for Express, Fastify, or any Node-based app. | +| **Laravel** | PHP framework for web artisans. Includes PHP, Composer, and the Laravel CLI. Use for full-stack Laravel apps, APIs, and Laravel-based projects. | +| **Next.js** | React framework for production. Includes Node.js and the Next.js toolchain. Use for React apps, static sites, or server-rendered Next.js applications. | +| **WordPress** | Popular content management system. Includes PHP, WordPress CLI, and typical WordPress dependencies. Use for blogs, sites, or headless WordPress. | + +Choose the preset that matches your project type. You can develop in the Web IDE, run commands in the console, and deploy from the same environment. + +:::tip +The Box service eliminates the need to install development tools on your local machine. Everything runs in the cloud, accessible from any browser. +::: + +## When to Use Box Service + +The Box service is ideal for: + +- Developing applications directly in the browser without local setup +- Quick prototyping and experimentation with different frameworks +- Learning and exploring PHP, Node.js, Laravel, Next.js, or WordPress +- Developing when you don't have access to a local development environment +- Simultaneously developing and deploying your application + +## Web IDE + +The Box service includes a built-in web-based IDE that allows you to: + +- Edit your code directly in the browser +- Access a terminal for running commands +- Manage files and folders +- Install packages and dependencies (Composer, npm, etc.) +- Run development servers (e.g., `php artisan serve`, `npm run dev`) + +## Environment + +Configure environment variables for your development environment. These variables will be available at runtime. + +:::info +The following "magic" environment variable is available within your Easypanel project: + +- `$(PROJECT_NAME)`: This will become the project name. +::: + +## Mounts + +Persist your code and data using mounts. There are three types of mounts available: + +**Volume** + +- Creates a directory in `/etc/easypanel/projects/[project]/[service]/volumes/[volume]` +- The `name` field is the name of that volume +- The `mountPath` field is the path inside your container + +**Bind** + +- Binds a path on the host machine to a path inside your container +- The `hostPath` field is the path on your host machine +- The `mountPath` field is the path inside your container + +**File** + +- Binds a file to a path inside your container +- The `content` field is the content of your file +- The `mountPath` field is the path inside your container + +:::warning +Make sure to configure volumes for your project files to ensure your code persists across restarts. +::: + +## Domains & Proxy + +When your application is ready to be accessed, you can configure domain names to expose your development server or production build: + +- Add your domain name in the Domains section +- Configure the proxy port (the port your application listens on) +- Easypanel will automatically provision SSL certificates via Let's Encrypt + +## Ports + +For non-web services or additional ports, you can expose them directly: + +- **Published** - The port on your host machine +- **Target** - The port inside your container + +## Logs + +View real-time logs from your Box service to monitor your application output, debug issues, and track development server activity. + +## Console + +Access a full terminal directly in your browser. Use it to: + +- Run framework CLI commands (e.g., `php artisan`, `npm run dev`, `npx create-next-app`) +- Install dependencies (Composer, npm, yarn) +- Execute scripts +- Manage your application + +## Development Workflow + +1. **Create a Box service** in your Easypanel project and select a preset (PHP, Node.js, Laravel, Next.js, or WordPress). +2. **Access the Web IDE** to start coding. +3. **Run your development server** using the terminal. +4. **Configure a domain** to preview your application. +5. **Continue developing**—changes are live. + +## Data Location + +Your project files and volumes are stored at: + +``` +/etc/easypanel/projects/[project]/[service]/volumes/[volume] +``` + +## Best Practices + +1. **Use volumes for your code** - Ensure your project files persist across restarts. +2. **Commit regularly** - Even though your code is in the cloud, use Git for version control. +3. **Use environment variables** - Keep sensitive data like API keys in environment variables. +4. **Monitor resources** - Development environments can consume significant resources. diff --git a/docs/03-services/07-box/quickstart.md b/docs/03-services/07-box/quickstart.md new file mode 100644 index 00000000..61e09b74 --- /dev/null +++ b/docs/03-services/07-box/quickstart.md @@ -0,0 +1,65 @@ +--- +sidebar_label: Quickstart +title: Box Service Quickstart (Operator) +description: 60-second operator cheat sheet for Box Service—setup, daily ops, UI locations, and troubleshooting. +--- + +# Box Service Quickstart (Operator) + +60-second summary: **Box Service** = flexible custom service in Easypanel with deploy scripts, process management, logs/console, IDE, and domain routing. + +## Fast setup + +1. **Go to:** Project → Create Service → **Box** +2. Set **service name** +3. Choose **preset** (PHP, Node.js, Laravel, Next.js, WordPress) or **No Preset** +4. **Install repo** (or Skip) +5. **Deploy** +6. Open **Logs** + **Console** to verify +7. **Add domain** if needed + +## Daily operations + +| Action | Use for | +|--------|--------| +| **Deploy** | Run latest deployment logic | +| **Stop / Restart** | Recover process state | +| **Logs** | First place to check for failures | +| **Console** | Inspect runtime manually | +| **Rebuild Docker image** | Fix environment-layer issues | + +## Where to look in the UI + +| Section | What you’ll find | +|---------|------------------| +| **Overview** | Controls + runtime stats | +| **Deployments** | Deployment script, history, trigger URL | +| **Git** | Repo + branch | +| **Processes** | App/worker command control | +| **Scripts** | Reusable ops scripts | +| **Domains** | Public routing | +| **IDE** | Quick edits | +| **Modules** | Runtime/web stack settings | + +## Quick troubleshooting + +**If deployment looks wrong:** + +1. Check **Logs** +2. Verify **Processes** are correct and running +3. Test **Open URL** +4. If still inconsistent → **Rebuild Docker image** then redeploy + +**If the UI shows an error but the app seems to work:** +Trust logs, metrics, and process state over the toast message only. + +## Minimal runbook + +1. **Before changes:** open Logs +2. **Deploy** your change +3. **Verify:** URL + logs + process status +4. **If failed:** Restart → if still failed, **Rebuild image** → redeploy + +--- + +For full reference, see [Box Service (Overview)](/docs/services/box). diff --git a/docs/03-services/08-compose.md b/docs/03-services/08-compose.md deleted file mode 100644 index fb78dc57..00000000 --- a/docs/03-services/08-compose.md +++ /dev/null @@ -1,3 +0,0 @@ -# Compose Service - -Documentation Coming Soon diff --git a/docs/03-services/08-compose/_category_.json b/docs/03-services/08-compose/_category_.json new file mode 100644 index 00000000..68e38af8 --- /dev/null +++ b/docs/03-services/08-compose/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Compose Service", + "position": 8 +} diff --git a/docs/03-services/08-compose/index.md b/docs/03-services/08-compose/index.md new file mode 100644 index 00000000..136e7815 --- /dev/null +++ b/docs/03-services/08-compose/index.md @@ -0,0 +1,224 @@ +--- +sidebar_label: Overview +title: Compose Service +description: Deploy multi-container Docker Compose stacks with Git or inline compose files, domains, and operational controls. +--- + +# Compose Service + +The **Compose Service** in Easypanel lets you deploy and run multi-container applications using Docker Compose. You get built-in controls for deployment, domains, security, maintenance, and integration with Git—all from the panel. + +:::caution Beta +Compose Service is currently in **Beta**. Use staging or non-critical workloads first, and keep backups and a rollback plan. +::: + +## When to Use Compose Service + +Compose Service is **especially recommended** when **App Service limitations** prevent a successful deploy—for example when your stack requires options that App Service cannot map, such as **running a container as root** (user/security context in Docker Compose). In those cases, Compose gives you full control over the compose file and runtime. + +Compose is also a good fit when you: + +- Have an existing `docker-compose.yml` (or `compose.yaml`) and want to run it in Easypanel +- Need multiple containers that work together (e.g. app + database + cache) +- Want to connect the stack to a Git repo and redeploy on changes +- Prefer panel controls (deploy, restart, logs, console, domains) over CLI-only workflows + +:::important +**Networking:** Services inside a Compose stack run on a **separate network** from other apps in the same project. They can talk to each other by service name within the stack, but they are isolated from non-Compose services in the project. +::: + +:::info +For a single container or simple app without these needs, the [App Service](/docs/services/app) or [Box Service](/docs/services/box) may be simpler. +::: + +## Creating a Compose Service + +1. Open your **project** +2. Go to **Service** → choose **Compose (Beta)** +3. Enter a **service name** +4. Click **Create** + +The Compose service is created immediately. You must configure **Source** before you can deploy. + +## Source Configuration + +You can provide your Compose configuration in two ways. + +### Inline compose file + +- Use the built-in editor to paste or edit your `docker-compose.yml` (or `compose.yaml`) content. +- Click **Save** to store the configuration. + +:::warning +Deploy will fail with **No source provided** if the compose source is empty or not saved. Ensure the editor has valid content and you have saved before deploying. +::: + +### Git source + +Connect a Git repository that contains your Compose file and optional build context: + +| Field | Description | +|-------|-------------| +| **Repository URL** | Git repository URL (required) | +| **Branch** | Branch to use (e.g. `main`, `master`) | +| **Build Path** | Path in the repo where the Compose file and build context live (e.g. `/nginx-flask-mysql`) | +| **Docker Compose File** | Compose filename (e.g. `compose.yaml`, `docker-compose.yml`) | + +For **private repositories**, use **Generate SSH key** and add the public key to your Git provider. + +Example: + +- **Repository:** `https://github.com/docker/awesome-compose` +- **Branch:** `master` +- **Build Path:** `/nginx-flask-mysql` +- **Docker Compose File:** `compose.yaml` + +After saving, **Deploy** will sync the repo, build images if needed, and orchestrate the stack. + +## Service Interface + +For a Compose service, the left navigation typically includes: + +| Section | Purpose | +|--------|--------| +| **Overview** | Summary, controls, and runtime metrics (CPU, memory, network) | +| **Source** | Inline compose editor or Git configuration | +| **Deployments** | Deployment history, detail logs, and deploy trigger URL | +| **Environment** | Environment variables for the stack | +| **Domains** | Public URLs and routing | +| **Redirects** | Redirect rules | +| **Security** | Security-related options | +| **Maintenance** | Maintenance and cleanup options | + +### Top action bar + +- **Deploy** – Run the deployment pipeline (sync Git if used, build, create/start containers). +- **Stop** – Stop the stack. +- **Restart** – Restart the stack. +- **Logs** – View logs (deployment and/or runtime). +- **Console** – Open a shell in the service context. +- **Open** – Open the service URL in a browser. +- **Destroy** – Remove the Compose service and its resources (use with care). + +## Deployment Lifecycle + +1. **Deploy** runs the pipeline: Git sync (if configured), image pull/build, network and volume creation, container create/start. +2. **Deployments** shows each run; **View** opens the detailed action log for that deployment. +3. A unique **deploy trigger URL** is available for the service (e.g. for CI/CD or webhooks). You can **regenerate** the deploy token if it is exposed or rotated. + +:::tip +Treat the deploy trigger URL as a secret. Rotate it (regenerate token) if it is ever exposed. +::: + +## Warnings and Errors + +### No source provided + +- **Cause:** Deploy was run without a valid source (inline compose empty/unsaved or Git not configured). +- **Fix:** Add and save your compose content in **Source**, or complete and save Git settings, then deploy again. + +### Compose configuration warnings + +Easypanel may show warnings such as: + +- **"ports is used in [service]. It might cause conflicts with other services."** + +Published `ports` in your Compose file expose containers on the host and can conflict with other services or with panel-managed routing. + +- **Prefer:** Use internal networking between services and expose only what you need via **Domains** and panel routing. +- **If you need host ports:** Ensure they are unique and document why they are required. + +Resolve or acknowledge these in the Compose configuration, then redeploy if you made changes. + +## Volumes and Data + +Volumes defined in your Compose file are managed by Easypanel. Data is stored under: + +``` +/etc/easypanel/projects/[project]/[service]/volumes/ +``` + +:::warning +Only data in defined volumes is persisted. Data written elsewhere in containers will be lost on restart or redeploy. +::: + +## Networking + +Services in the same Compose stack can reach each other by **service name** as hostname. Easypanel sets up a **dedicated network for that Compose stack**—separate from other apps and services in the same project. So Compose services can talk to each other inside the stack, but they are not on the same network as App or Box services in the project. + +Example: if you have services `backend` and `db` in the stack, the backend can connect to the database at `db:5432` (or the port you define). + +## Environment Variables + +Configure variables in the **Environment** tab and/or in your Compose file (`environment` or `env_file`). + +:::info +Easypanel project “magic” variable you can use: +- `$(PROJECT_NAME)` – project name +::: + +## Security and Production + +1. **Deploy trigger URL** – Treat as a secret; rotate (regenerate) if exposed. +2. **Git** – Prefer a dedicated branch and, for production, private repos with SSH key authentication. +3. **Ports** – Avoid unnecessary `ports` in Compose; use Domains and panel routing for HTTP/HTTPS where possible. +4. **Beta** – Use staging first, keep backups, and have a rollback plan. + +## Troubleshooting + +| Situation | What to do | +|-----------|------------| +| Deploy fails | Open **Deployments** → **View** on the failed run and check the action logs (sync, build, create/start steps). | +| Warnings in UI | Read the Compose issues panel; address port conflicts or other reported issues, then save and redeploy. | +| Service not reachable | Check **Domains** and **Open** URL; verify the app listens on the port you configured. | +| Unclear state | Check **Logs** and **Console**; **Restart** the stack, or **Rebuild** (if available) and redeploy. | + +## Example Compose Snippet + +```yaml +version: "3.8" +services: + web: + image: nginx:alpine + volumes: + - ./html:/usr/share/nginx/html + depends_on: + - api + + api: + image: node:18-alpine + working_dir: /app + command: node server.js + environment: + - DATABASE_URL=postgres://db:5432/myapp + depends_on: + - db + + db: + image: postgres:15 + environment: + - POSTGRES_DB=myapp + - POSTGRES_USER=user + - POSTGRES_PASSWORD=password + volumes: + - db_data:/var/lib/postgresql/data + +volumes: + db_data: +``` + +Prefer **Domains** in Easypanel to expose the web front instead of publishing host ports in Compose when possible. + +## Best Practices + +1. **Pin image tags** – Avoid `latest` for reproducible deployments. +2. **Use `depends_on`** – Make startup order explicit. +3. **Externalize config** – Use environment variables for environment-specific settings. +4. **Minimize host ports** – Rely on internal networking and panel Domains/redirects. +5. **Health checks** – Add `healthcheck` in Compose where supported for more reliable orchestration. + +## See Also + +- [Compose Service Quickstart](/docs/services/compose/quickstart) – Short operator runbook +- [App Service](/docs/services/app) – Single-container or build-from-repo apps +- [Box Service](/docs/services/box) – Development environments with presets diff --git a/docs/03-services/08-compose/quickstart.md b/docs/03-services/08-compose/quickstart.md new file mode 100644 index 00000000..05d18ae5 --- /dev/null +++ b/docs/03-services/08-compose/quickstart.md @@ -0,0 +1,80 @@ +--- +sidebar_label: Quickstart +title: Compose Service Quickstart (Operator) +description: Short operator runbook for Compose Service—setup, deploy, and troubleshooting. +--- + +# Compose Service Quickstart (Operator) + +Compose Service (Beta) runs Docker Compose stacks in Easypanel with Git or inline source, deployment history, trigger URL, and panel controls. + +## Fast setup (Git workflow) + +1. **Create:** Project → **Service** → **Compose (Beta)** → set service name → Create +2. **Source:** Open **Source** → choose **Git** +3. **Configure:** Repository URL, Branch, Build Path, Docker Compose File → **Save** +4. **Deploy** → check **Deployments** for status and logs +5. **Verify:** **Open** URL, **Logs**, **Console** if needed +6. **Domains:** Add and configure in **Domains** for public access + +## Top actions + +| Action | Use for | +|--------|--------| +| **Deploy** | Run pipeline (sync Git, build, create/start containers) | +| **Stop** | Stop the stack | +| **Restart** | Restart the stack | +| **Logs** | Inspect deployment and runtime logs | +| **Console** | Shell into the service context | +| **Open** | Open service URL in browser | +| **Destroy** | Remove the Compose service and resources | + +## Where to look in the UI + +| Section | What you’ll find | +|---------|------------------| +| **Overview** | Controls, CPU/memory/network metrics | +| **Source** | Inline compose editor or Git (repo, branch, path, compose file) | +| **Deployments** | History, detail logs, deploy trigger URL, token refresh | +| **Environment** | Environment variables | +| **Domains** | Public routing | +| **Redirects** | Redirect rules | +| **Security** | Security options | +| **Maintenance** | Maintenance and cleanup | + +## Quick troubleshooting + +**Deploy fails with “No source provided”** + +- Inline: add compose content and **Save** +- Git: set Repository URL, Branch, Build Path, Docker Compose File and **Save** +Then run **Deploy** again. + +**Warnings: “ports is used in [service]…”** + +- Host ports can conflict with other services. Prefer internal networking and **Domains** for HTTP/HTTPS. +- If you need ports, keep them unique and redeploy after changes. + +**Deploy failed or inconsistent state** + +1. Open **Deployments** → **View** on the failed run → read action logs +2. Fix **Source** (compose or Git) if wrong +3. **Restart** or **Deploy** again + +## Minimal runbook + +1. **Before changes:** Check **Logs** / **Deployments** for current state +2. **Change:** Edit **Source** or **Environment** → **Save** +3. **Deploy** +4. **Verify:** **Open** URL + **Logs** + process state +5. **If failed:** Check deployment detail logs → fix source/config → **Restart** or **Deploy** again + +## Security reminders + +- **Deploy trigger URL** = secret; rotate (regenerate token) if exposed +- Prefer **private repo + SSH key** for production +- Use **Domains** and panel routing instead of unnecessary host `ports` in Compose + +--- + +For full reference, see [Compose Service (Overview)](/docs/services/compose).