Назад в каталог
Средне
Проверка ИИ-оптимизации • 20.07.2026
Редакционное резюме ИИ
Create tls.crt using the certificate file information (replace xxxx with the actual certificate file information). добавлен по независимой проверке международного каталога. На момент аудита AI-готовность домена sealos.io оценена в 35/100: llms.txt доступен. Расширенный llms-full.txt не обнаружен; карточка сформирована по фактическим данным сайта и его публичным файлам.
107 519Токены llms.txt
—Токены llms-full.txt
ai.txt
sitemap.xml
Проверки ИИ-оптимизации
llms-full.txt
Полная версия не найдена
ai.txt
Файл ai.txt не найден
Sitemap в robots.txt2 шт.
Найдено карт сайта: 2
Schema.org (JSON-LD)
Разметка Schema.org не найдена на главной
OpenGraph
OpenGraph теги не найдены на главной
Доступ ИИ-ботов
На основе анализа robots.txt
GPTBotНе упомянут
OAI-SearchBotНе упомянут
ChatGPT-UserНе упомянут
Google-ExtendedНе упомянут
ClaudeBotНе упомянут
Claude-SearchBotНе упомянут
Claude-UserНе упомянут
BytespiderНе упомянут
CCBotНе упомянут
PerplexityBotНе упомянут
Perplexity-UserНе упомянут
file: ./content/docs/community.en.mdx
meta: {
"title": "社区",
"description": "欢迎加入 Sealos 开源社区"
}
file: ./content/docs/index.en.mdx
meta: {
"title": "Sealos Docs",
"description": "Find quickstart guides, tutorials, best practices, deployment templates, system design docs, self-hosting solutions and more cloud native resources."
}
import { Text, Code, Play, Database } from 'lucide-react';
import { templateDomain } from '@/config/site';
<Cards>
<Card icon={<Text />} href="/docs/overview/intro" title="How Sealos DevBox works">
Understand what Sealos DevBox is and what it can do, include the key
features and advantages.
</Card>
<Card icon={<Code />} href="/docs/guides/devbox" title="Guides">
Learn how to create and manage your Projects, develop your application,
create releases, and deploy your application.
</Card>
<Card icon={<Play />} href="/docs/quick-start" title="Quickstarts">
Develop & deploy in minutes. Jump start your development with Sealos DevBox.
</Card>
<Card icon={<Database />} href="/docs/guides/databases/postgresql" title="Databases">
Step-by-step guides on how to deploy and connect to databases in Sealos
DevBox.
</Card>
</Cards>
***
<br />
<center>
<h1>Comprehensive development stack support</h1>
</center>
<center>
Launch specialized development environments for any framework or language.
</center>
<br />
import {
NodejsIcon,
GoIcon,
JavaIcon,
PHPIcon,
PythonIcon,
RustIcon,
} from '@/components/ui/icons';
<Cards>
<Card icon={<NodejsIcon />} href="/docs/guides/databases/postgresql/nodejs" title="Node.js">
Node.js is a runtime environment that allows you to run JavaScript code
outside of a browser.
</Card>
<Card icon={<GoIcon />} href="/docs/guides/databases/postgresql/go" title="Go">
Go is a statically typed, compiled programming language designed at Google.
</Card>
<Card icon={<JavaIcon />} href="/docs/guides/databases/postgresql/java" title="Java">
Java is a high-level, class-based, object-oriented programming language that
is designed to have as few implementation dependencies as possible.
</Card>
<Card icon={<PHPIcon />} href="/docs/guides/databases/postgresql/php" title="PHP">
PHP is a popular general-purpose scripting language that is especially
suited to web development.
</Card>
<Card icon={<PythonIcon />} href="/docs/guides/databases/postgresql/python" title="Python">
Python is an interpreted, high-level, general-purpose programming language.
</Card>
<Card icon={<RustIcon />} href="/docs/guides/databases/postgresql/rust" title="Rust">
Rust is a systems programming language that runs blazingly fast, prevents
segfaults, and guarantees thread safety.
</Card>
</Cards>
<br />
<center>
<a href="/">View all supported languages and frameworks ></a>
</center>
***
<center>
<h1>Deploy your application in minutes</h1>
</center>
<center>Quickly deploy applications via the App Store.</center>
<br />
<Cards>
<Card href={templateDomain + '/deploy?templateName=fastgpt'} title="FastGPT" />
<Card href={templateDomain + '/deploy?templateName=wordpress'} title="Wordpress" />
<Card href={templateDomain + '/deploy?templateName=flarum'} title="Flarum" />
<Card href={templateDomain + '/deploy?templateName=headscale'} title="Headscale" />
<Card href={templateDomain + '/deploy?templateName=teable'} title="Teable" />
<Card href={templateDomain + '/deploy?templateName=s-pdf'} title="Stirling-PDF" />
</Cards>
<br />
<center>
<a href={templateDomain} target="_blank">
View all apps >
</a>
</center>
file: ./content/docs/quick-start.en.mdx
meta: {
"title": "Quick Start Tutorial",
"icon": "Album",
"keywords": [
"Sealos DevBox",
"Next.js",
"cloud development",
"Kubernetes",
"OCI image",
"Cursor IDE",
"remote development",
"cloud deployment",
"containerization",
"DevOps"
],
"description": "Learn how to create, develop, and deploy a Next.js app using Sealos DevBox. This guide covers project setup, remote development with Cursor IDE, and cloud deployment."
}
import { AppDashboardLink } from '@/components/docs/Links';
Sealos DevBox is an all-in-one platform designed for integrated online development, testing, and production. It offers a seamless solution for creating environments and database dependencies with just a single click, allows developers to work locally using their preferred IDEs while streamlining setup processes and enabling automatic application deployment.
**In this guide We'll demonstrate how to how to create a minimal Next.js demo project with Sealos DevBox.**
## Create a DevBox Project
<div className="fd-steps [&_h5]:fd-step">
<h5>
Click on the "DevBox" icon from your <AppDashboardLink />, then click on the
"Create New Project" button to create a new project.
</h5>
<h5>
In the "Runtime" section, choose "Next.js" as the development framework. Use
the sliders to set the CPU cores and memory for the project.
</h5>
<h5>
After setting up the basic environment, you'll need to configure the network
settings for your project:
</h5>
* Scroll down to the "Network" section of the configuration page.
* Container Port:
* Enter "3000" in the Container Port field. This is the default port that Next.js uses for development.
* If you need additional ports, click the "Add Port" button and specify them.
* Enable Internet Access:
* Toggle the switch to enable internet access for your DevBox. This allows external users to access your Next.js application through the public internet using the provided domain.
* Domain:
* By default, Sealos provides a subdomain for your application.
* If you want to use a custom domain, click on "Custom Domain" and follow the instructions to set it up.
Remember that the container port (3000) should match the port your Next.js application is configured to run on. If you change the port in your Next.js configuration, make sure to update it here as well.
<h5>Click on the "Create" button to create your project.</h5>
</div>
## Connect with Cursor IDE
After creating your project, you'll see it listed in the DevBox List. Each project has an "Operation" column with various options.
<div className="fd-steps [&_h5]:fd-step">
<h5>To connect to your project's DevBox runtime using Cursor IDE:</h5>
* Locate your project in the DevBox List.
* In the "Operation" column, click on the dropdown arrow next to the VSCode icon.
* From the dropdown menu, select "Cursor".
* Click on the "Cursor" option that appears.
<h5>
When you click on "Cursor", it will launch the Cursor IDE application on your
local machine. Within Cursor, a popup window will appear, prompting you to
install the DevBox plugin for Cursor. This plugin enables SSH remote
connection to the DevBox runtime.
</h5>
* Follow the instructions in the Cursor popup to install the DevBox plugin.
* Once installed, Cursor will establish a remote connection to your DevBox runtime.
</div>
<Callout type="info">
You can switch between different IDE options (VSCode, Cursor, or VSCode
Insiders) at any time by using the dropdown menu in the "Operation" column.
</Callout>
## Develop
<div className="fd-steps [&_h5]:fd-step">
<h5>
After the connection is established, you'll be able to access and edit your
project files directly within the Cursor IDE environment.
</h5>
This remote connection allows you to develop your Next.js application using Cursor IDE, with all the benefits of a cloud-based development environment: - Your code runs in the DevBox runtime, ensuring consistency across development and production environments. - You can access your project from anywhere, on any device with Cursor installed. - Collaboration becomes easier as team members can connect to the same DevBox runtime.
<h5>You can start debugging your Next.js application:</h5>
* Open the terminal within Cursor IDE.
* Navigate to your project directory if you're not already there.
* Run the following command to start the Next.js development server:
```bash
npm run dev
```
* This command will start your Next.js application in development mode.
<h5>To access your running application:</h5>
* Return to the Sealos DevBox List in your browser.
* Find the project you just created.
* Click on the "Detail" button on the right side of your project's row.
<h5>In the project details page:</h5>
* Look for the "Network" section.
* You'll see an "External Address" field.
* Click on this external address.
<h5>
This will open your Next.js application in a new browser tab, allowing you to
view and interact with your running service.
</h5>
</div>
## Release
After you've developed and tested your Next.js application, you can release it as an OCI (Open Container Initiative) image. This allows you to version your application and prepare it for deployment.
1. In the Cursor IDE terminal, navigate to your project directory and run the build command:
```bash
npm run build
```
This command creates a production-ready build of your Next.js application in the '.next' directory.
2. Navigate to your project's details page:
* Go to the Sealos DevBox List in your browser.
* Find your project and click on the "Detail" button on the right side of your project's row.
3. On the project details page, look for the "Version" section.
4. Click on the "Release" button located in the top right corner of the "Version" section.
5. A "Release" dialog box will appear. Here, you need to provide the following information:
* Image Name: This field is pre-filled with your project's image name.
* Tag: Enter a version tag for your release (e.g., v1.0).
* Description: Provide a brief description of this release (e.g., "Initial release" or "Bug fixes for login feature").
6. After filling in the required information, click the "Release" button at the bottom of the dialog box.
7. The system will process your release. Once completed, you'll see a new entry in the "Version" section of your project details page, showing the tag, status, creation time, and description of your release.
By following these steps, you've successfully created an OCI image of your Next.js application. This image can now be used for deployment or shared with other team members. Each release creates a snapshot of your current code, allowing you to maintain different versions of your application and easily roll back if needed.
<Callout type="info">
Remember to create new releases whenever you make significant changes or reach
important milestones in your project. This practice helps in maintaining a
clear history of your application's development and facilitates easier
deployment and collaboration.
</Callout>
## Deploy
After releasing your Next.js application as an OCI image, you can deploy it to Sealos Cloud for production use. Here's how to do it:
1. In your project's details page, locate the "Version" section.
2. Find the release you want to deploy and click the "Deploy" button in the "Operation" column.
3. This will redirect you to the App Launchpad application within Sealos.
4. In the App Launchpad application, follow the deployment wizard to configure your application settings. This may include:
* Selecting the appropriate environment
* Setting resource limits (CPU, memory)
* Configuring environment variables if needed
* Setting up any required volumes or persistent storage
5. Once you've configured all necessary settings, click the "Deploy Application" button in the top right corner to start the deployment process.
6. You'll be taken to the application details view within App Launchpad.
7. Once the status is "Running", Click on the address provided under "Public Address". This will open your deployed Next.js application in a new browser tab.
By following these steps, you've successfully deployed your Next.js application to Sealos Cloud using the App Launchpad application. Your application is now accessible via the public address, allowing users to interact with it from anywhere on the internet.
<Callout type="info">
You can always update your application by creating a new release in DevBox and
repeating this deployment process with the new version using App Launchpad.
</Callout>
This workflow allows you to develop and debug your Next.js application in a cloud environment while still using your preferred local IDE. The external address makes it easy to share your work with team members or clients, as they can access your running application from anywhere with an internet connection.
file: ./content/docs/AI/mcp.en.mdx
meta: {
"title": "MCP (Model Context Protocol)",
"description": "Learn how to use Model Context Protocol (MCP) services on the Sealos platform to connect AI models with external tools and data sources through standardized interfaces.",
"keywords": [
"MCP",
"Model Context Protocol",
"Sealos",
"AI integration",
"large language models",
"tool calling"
]
}
## What is Model Context Protocol (MCP)?
The [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) is a game-changing standard that lets AI models talk to external tools and data sources seamlessly. Instead of building custom integrations for every service, developers can integrate once and connect to any MCP-compatible system.
### The Problem MCP Solves
Here's the challenge: AI models are smart, but they're isolated. They can't access your databases, check your billing, or run code in your development environment. To make AI truly useful, you need to connect it to real-world systems.
The traditional approach? Build custom integrations for every single service. Each one has different APIs, authentication methods, and data formats. It's a maintenance nightmare that gets worse as you add more tools.
### MCP Changes Everything
MCP is like having a universal translator for AI integrations. Here's how it works:
**For Developers**: Write one MCP integration and connect to any MCP-compatible service. No more custom connectors for every tool.
**For Service Providers**: Build one MCP interface and instantly work with any MCP-enabled AI application.
**Think USB-C for AI**: Just like USB-C replaced dozens of different charging cables, MCP replaces dozens of different API integrations with one standard protocol.
### How MCP Works: The Three-Part System
MCP uses a simple client-server model with three key components:
* **MCP Host**: Your AI application (like Cursor, VS Code, or ChatGPT)
* **MCP Client**: The connection bridge that your AI app creates
* **MCP Server**: The external service that provides tools and data (like Sealos)
**Simple Example**: Your Cursor editor (Host) creates a connection (Client) to talk to Sealos services (Server). Want to connect to multiple services? Your editor just opens multiple connections.
## Sealos MCP: Your Cloud Platform, AI-Ready
Sealos has built MCP servers for all its major platform capabilities. Using StreamableHttp communication, these servers work seamlessly with any MCP-compatible IDE or AI application.
**Bottom line**: You can now control your entire Sealos infrastructure through natural language conversations with AI.
### What You Can Do with Sealos MCP
Here's what's available right now:
* **🛠️ DevBox**: Spin up development environments and run code
* **🗄️ Database**: Query and manage your databases
* **💰 Cost Center**: Check billing and manage expenses
* **📊 Observability**: Monitor performance and view logs
**Note**: Service availability varies by region. Check your Sealos console to see what's available in your zone.
### Quick Authentication Setup
Sealos uses your KubeConfig for authentication. Here's the simple 3-step process:
**Step 1: Get Your KubeConfig**
1. Go to [Sealos Console](https://os.sealos.io)
2. Click your profile picture (top right)
3. Select "KubeConfig" and copy the content
**Step 2: URL Encode It**
Choose any of these methods to URL-encode your KubeConfig:
**Method 1: Online Tool (Easiest)**
1. Open [URL Encoder](https://www.urlencoder.org/) or search "URL encoder"
2. Paste your KubeConfig content
3. Click "Encode"
4. Copy the encoded result
**Method 2: Browser Console**
1. Press `F12` on any webpage to open developer tools
2. Go to "Console" tab
3. Type this and press Enter:
```javascript
encodeURIComponent(`paste your KubeConfig here`)
```
4. Copy the encoded output
**Method 3: Python (if installed)**
1. Open terminal
2. Type `python3` to enter Python
3. Run this code:
```python
import urllib.parse
kubeconfig = """paste your KubeConfig here"""
encoded = urllib.parse.quote(kubeconfig)
print(encoded)
```
4. Copy the encoded result
**Step 3: Use It**
Add this header to your MCP configuration:
```
Authorization: <your-url-encoded-kubeconfig>
```
**Example**: `apiVersion: v1` becomes `apiVersion%3A%20v1`
**Pro Tip**: Save your encoded KubeConfig somewhere safe—you'll use it for all MCP configurations.
## Ready to Get Started?
### Before You Begin: Two Things You Need
**1. Your MCP Service URL**
* Log into [Sealos Console](https://os.sealos.io)
* Find the MCP services section for your region
* Copy the URL for the service you want to use
**2. Your Authentication Token**
* Follow the authentication steps above to get your URL-encoded KubeConfig
* Keep it handy—you'll paste it into your IDE configuration
**That's it!** Now let's connect your favorite AI tool to Sealos.
## Connect Your AI Tool to Sealos
### Cherry Studio Setup
[Cherry Studio](https://cherry-ai.com/) makes MCP configuration visual and straightforward.
**Quick Setup:**
1. **Settings** → **MCP Servers** → **Add Server**
2. **Fill in the details:**
* **Name**: `Sealos` (or whatever you prefer)
* **Type**: `Streamable HTTP (StreamableHttp)`
* **URL**: Your Sealos MCP service URL
* **Headers**: `Authorization=<your-url-encoded-kubeconfig>`
3. **Hit the green start button** and wait for "Connected" status
**Start Using It:**
Once connected, just chat normally. When you need Sealos functionality, select the MCP tools and ask.
### VS Code Setup
VS Code gets MCP powers through extensions. Here's the streamlined setup:
**Quick Setup:**
1. **Open AI Chat** (right sidebar) → **Agent Mode** → **Tools icon**
2. **Find MCP settings** → **Gear icon** → **Add new server**
3. **Configure:**
* **Name**: `Sealos Platform`
* **URL**: Your Sealos MCP service URL
* **Headers**:
```json
{
"Authorization": "<your-url-encoded-kubeconfig>"
}
```
4. **Save** → VS Code auto-connects
**Code While You Chat:**
Now you can ask your AI assistant to interact with Sealos while you code.
### Cursor Setup
[Cursor](https://www.cursor.com/) has the best native MCP support. Setup is super clean:
**Quick Setup:**
1. **Settings gear** (top right) → **MCP Servers** → **New MCP Server**
2. **Paste this config** (replace the URL and auth token):
```json
{
"name": "Sealos MCP",
"url": "https://your-sealos-mcp-endpoint.com",
"headers": {
"Authorization": "<your-url-encoded-kubeconfig>"
}
}
```
3. **Save** → Cursor auto-verifies → Look for "Connected" status
**AI-Powered Development:**
Now your AI coding assistant can manage your entire Sealos infrastructure.
### Trae Setup
Trae keeps it simple with manual JSON configuration.
**Quick Setup:**
1. **Gear icon** (top right) → **MCP** → **Add** → **Manual Configuration**
2. **Paste this config** (update URL and auth):
```json
{
"name": "Sealos MCP",
"url": "https://your-sealos-mcp-endpoint.com",
"headers": {
"Authorization": "<your-url-encoded-kubeconfig>"
}
}
```
3. **Confirm** → You're connected!
**Explore Your Tools:**
Click your server name to see all available Sealos tools and what they do.
### Cline Setup
[Cline](https://github.com/cline/cline) is a powerful AI coding assistant that runs directly in VS Code with native MCP support. It can write code, execute commands, browse the web, and more.
**Setup Steps:**
1. **Install the Cline extension** in VS Code and restart
2. **Add server via interface**:
* Click **"MCP Servers" icon** (purple button) → **"Remote Servers" tab**
* **Server Name**: `sealos`
* **Server URL**: `https://your-sealos-mcp-endpoint.com`
* Click **"Add Server"**
3. **Complete configuration**:
* Click **"Edit Configuration"** to open `cline_mcp_settings.json`
* Add the complete configuration for the `sealos` server:
```json
{
"mcpServers": {
"sealos": {
"type": "streamableHttp",
"url": "https://your-sealos-mcp-endpoint.com",
"headers": {
"Authorization": "<your-url-encoded-kubeconfig>"
},
"disabled": false,
"autoApprove": [],
"timeout": 60
}
}
}
```
**Important**: Replace `<your-url-encoded-kubeconfig>` with your actual URL-encoded KubeConfig from the steps above.
4. **Save** → Cline auto-verifies → Look for "Connected" status
**What You Can Do:**
Now you can ask Cline to manage your entire Sealos infrastructure.
**Pro Tips:**
* Add trusted tools to `autoApprove` for faster workflows
* Use environment variables for sensitive auth tokens
* Set appropriate `timeout` values for long-running operations
## When Things Don't Work
### "Connection Failed" - Fix It Fast
**Most Common Cause**: Wrong URL or bad auth token
**Quick Fixes:**
1. **Double-check your MCP service URL** - Copy it fresh from Sealos console
2. **Re-encode your KubeConfig** - Authentication tokens can get corrupted
3. **Test your network** - Can you reach sealos.run in your browser?
4. **Check the obvious** - Typos in configuration happen to everyone
### "Authentication Error" - Get Back In
**What Happened**: Your KubeConfig is invalid or expired
**Fix It:**
1. **Get a fresh KubeConfig** from Sealos console
2. **Make sure you copied the whole thing** - Missing characters break everything
3. **Re-encode it properly** - Use a reliable URL encoder
4. **Check your header format** - Should be `Authorization: <encoded-config>`
### "Tool Calls Failing" - Restore Functionality
**Likely Issues**: Permissions or service availability
**Solutions:**
1. **Verify your account permissions** - Do you have access to the service you're calling?
2. **Check service status** - Is the service running in your region?
3. **Look at error messages** - They usually tell you exactly what's wrong
4. **Try a simple test** - Start with basic operations before complex ones
### Pro Debugging Tips
* **Check connection status first** - Your IDE shows if MCP is connected
* **Enable verbose logging** - More info = faster fixes
* **Test one thing at a time** - Don't change multiple settings simultaneously
* **When in doubt, restart** - Sometimes IDEs need a fresh start after configuration changes
## Resources & Next Steps
### Essential Links
**Learn More:**
* [Official MCP Documentation](https://modelcontextprotocol.io/) - Deep dive into the protocol
* [Sealos Platform Docs](/docs) - Everything about Sealos
* [AI Proxy Service](/docs/guides/ai-proxy) - Sealos AI integration options
**Compatible Tools:**
* [Cherry Studio](https://cherry-ai.com/) - Clean AI chat interface
* [Cursor](https://www.cursor.com/) - Best-in-class AI code editor
* [VS Code](https://code.visualstudio.com/) - Works with MCP extensions
* [Cline](https://github.com/cline/cline) - AI coding assistant for VS Code
* [Claude Desktop](https://claude.ai/) - Anthropic's desktop app
* Any other MCP-compatible application
### Need Help?
**Stuck? Here's where to go:**
1. **Start here** - Re-read the troubleshooting section above
2. **Community help** - [Discord](https://discord.gg/wdUn538zVP) for peer support
3. **Bug reports** - [GitHub Issues](https://github.com/labring/sealos/issues) for technical problems
4. **Direct support** - Contact Sealos support for urgent issues
file: ./content/docs/advanced/architecture.en.mdx
meta: {
"title": "Architecture"
}
Sealos DevBox is an advanced development environment solution that leverages cloud-native Container and Kubernetes technologies to offer a unified and flexible development Runtime. Its key feature is simulating a traditional virtual machine experience while maintaining containerization benefits.
## Architecture
Sealos DevBox is built on a layered architecture, comprising these key components:
## Control Flow
DevBox implements a decoupled front-end and back-end design:
1. Users trigger actions via the web interface or plugins
2. DevBox Controller receives and processes these requests
3. Controller translates the processed instructions into Kubernetes API calls
4. Kubernetes executes the corresponding Container operations
## State Persistence Mechanism
DevBox employs an intelligent state preservation system to maintain user environment consistency:
### Automatic Saving
* System auto-saves user environment changes under specific conditions
* Changes are packaged as image layers
* New layers are appended to the base image as commits
* Updated images are securely stored in an isolated internal registry
### Environment Recovery
* On subsequent startups, system boots from the most recent image
* Ensures full preservation of historical changes
### Optimization
The Container-shim layer provides automated maintenance:
* Regularly merges image layers to optimize storage
* Automatically cleans up redundant data
* Optimizes image size and layer count for optimal system performance
file: ./content/docs/examples/build-your-own-discord-bot.en.mdx
meta: {
"title": "Build Your Own Discord Bot",
"description": "Build an AI-powered Discord bot using DevBox. You'll create a bot that can respond to messages using AI capabilities powered by FastGPT."
}
## Overview
This example demonstrates how to build an AI-powered Discord bot using DevBox. You'll create a bot that can respond to messages using AI capabilities powered by [FastGPT](https://tryfastgpt.ai), showcasing how to integrate multiple services and APIs in a DevBox environment.
**Technologies Used:**
* Node.js
* Discord.js
* FastGPT API
* DevBox development environment
**Expected Outcome:**
* A functioning Discord bot that:
* Responds to basic commands
* Integrates with FastGPT for AI-powered responses
* Handles real-time message events
* Processes natural language queries
## Prerequisites
* A Discord account with administrator privileges
* Basic knowledge of JavaScript/Node.js
* Access to [FastGPT platform](https://cloud.tryfastgpt.ai)
* The following credentials:
* Discord Bot Token
* FastGPT API Key
* FastGPT Base URL
## Step-by-Step Guide
### 1. Setting Up Discord Application
<div className="fd-steps [&_h4]:fd-step">
#### Create Discord Application
1. Visit the [Discord Developer Portal](https://discord.com/developers/applications)
2. Click "New Application" and choose a name for your bot. This name will be displayed in your Discord server
#### Configure Bot Permissions
1. Navigate to the "Bot" section
2. Enable required intents:
* Server Members Intent
* Message Content Intent
These permissions allow the bot to:
* Access member-related events
* Read and process message content
3. Copy your bot token by clicking "Reset Token" and then "Copy"
* Keep this token secure and never share it
* You'll need this token to authenticate your bot
#### Set Up OAuth2
1. Go to OAuth2 section
2. Select "bot" scope
3. Choose "Administrator" permissions
4. Copy the generated OAuth2 URL
5. Use the URL to add the bot to your server
</div>
### 2. Creating DevBox Project
<div className="fd-steps [&_h4]:fd-step">
#### Initialize Node.js Project
1. [Create a new DevBox project](/docs/guides/devbox/create-a-project)
2. Select Node.js as the runtime
3. Configure project resources:
* Set appropriate CPU cores
* Allocate required memory
#### Set Up Development Environment
1. [Connect to Your Development Environment](/docs/guides/devbox/develop#connect-to-your-development-environment)
2. Install required dependencies:
```bash
npm init -y
npm install discord.js axios dotenv
```
3. Update `package.json` to enable ES modules:
```json
{
"type": "module",
"scripts": {
"start": "node src/index.js"
}
}
```
#### Project Structure
Create the following file structure:
```
project/
├── src/
│ ├── index.js
│ ├── services/
│ │ └── aiService.js
├── package.json
└── README.md
```
</div>
### 3. Implementing the Bot
<div className="fd-steps [&_h4]:fd-step">
#### Basic Bot Setup
Create `src/index.js`:
```javascript title="src/index.js"
import { Client, GatewayIntentBits } from 'discord.js';
import 'dotenv/config';
import aiService from './services/aiService.js';
const client = new Client({
intents: [
GatewayIntentBits.Guilds,
GatewayIntentBits.GuildMessages,
GatewayIntentBits.MessageContent
]
});
client.on('ready', () => {
console.log(`${client.user.tag} is ready!`);
});
client.on('messageCreate', async message => {
if (message.author.bot) return;
if (message.content === '!ping') {
message.reply('Pong!');
}
if (message.content.startsWith('!ask ')) {
const question = message.content.slice(5).trim();
if (!question) {
message.reply('Please enter your question after !ask. For example: !ask what is Sealos?');
return;
}
try {
message.channel.sendTyping();
const response = await aiService.getChatGPTResponse(question);
message.reply(response);
} catch (error) {
console.error('Error getting AI response:', error);
message.reply('Sorry, I cannot answer right now. Please try again later.');
}
}
});
client.login(process.env.DISCORD_TOKEN);
```
#### AI Service Integration
Create `src/services/aiService.js`:
```javascript title="src/services/aiService.js"
import axios from 'axios';
class AiService {
constructor() {
this.openaiAxios = axios.create({
baseURL: process.env.FASTGPT_BASE_URL,
headers: {
'Authorization': `Bearer ${process.env.FASTGPT_API_KEY}`,
'Content-Type': 'application/json'
}
});
}
async getChatGPTResponse(message) {
try {
const response = await this.openaiAxios.post('/v1/chat/completions', {
chatId: "session_" + Date.now(),
stream: false,
detail: false,
messages: [{
role: "user",
content: message
}]
});
return response.data.choices[0].message.content.trim();
} catch (error) {
console.error('AI API call failed:', error);
return 'Sorry, I cannot answer right now. Please try again later.';
}
}
}
export default new AiService();
```
#### Configuration Setup
Create `.env` file in the project root with your credentials:
```ini title=".env"
DISCORD_TOKEN=your_discord_bot_token
FASTGPT_API_KEY=your_fastgpt_api_key
FASTGPT_BASE_URL=your_fastgpt_base_url
```
Update `src/index.js` to include dotenv configuration:
```javascript
import 'dotenv/config';
import { Client, GatewayIntentBits } from 'discord.js';
// ... rest of the existing code ...
```
Start the bot with:
```bash
npm start
```
</div>
### 4. FastGPT Integration
FastGPT is an open-source LLM application development platform that allows you to build AI applications with knowledge base capabilities. In this section, we'll walk through the process of setting up FastGPT to power our Discord bot with custom knowledge.
<div className="fd-steps [&_h4]:fd-step">
#### Dataset Creation
1. Log into your FastGPT account at [FastGPT](https://tryfastgpt.ai)
2. Navigate to the "Datasets" section and click "Create Dataset"
3. Choose "General Dataset" as the dataset type
4. Select "Text Dataset" for document processing
5. Upload your documentation files (supports PDF, TXT, Word, etc.)
6. Configure chunking settings if needed (default settings work well for most cases)
7. Wait for the training process to complete - this may take several minutes depending on the size of your documentation
#### Application Setup
1. Go to the "Applications" section and create a new FastGPT application
2. In the Flow Editor, add a "Dataset Search" module
3. Connect your trained dataset to the search module
4. Add an "AI Chat" module and connect it to the search module
5. Configure the AI Chat module settings:
* Set temperature (0.7 recommended for balanced responses)
* Adjust max tokens as needed
* Customize the system prompt
#### API Publication
1. Once satisfied with the configuration, click "Publish Channel" to make your application live
2. Go to the "API Request" section of your application
3. Generate new API credentials if you haven't already
4. Save these important details for the next steps:
* API Base URL: The endpoint for your FastGPT API
* API Key: Your authentication token
These credentials will be used in the `.env` file we created earlier to connect our Discord bot to the FastGPT backend.
</div>
file: ./content/docs/guides/ai-proxy.en.mdx
meta: {
"title": "AI Proxy",
"description": "Take the shortest safe path to your first AI Proxy API call on Sealos with one OpenAI-compatible request, one endpoint, and one API key.",
"keywords": [
"AI Proxy",
"Sealos",
"first API call",
"OpenAI-compatible",
"endpoint",
"API key"
]
}
This is the start-here guide for AI Proxy on Sealos.
Follow this page when you want the shortest safe path to one first
OpenAI-compatible request.
By the end of this page, you will collect the minimum credentials, run one
first API call, and know where to confirm that the request reached Sealos.
## What AI Proxy is
AI Proxy is the Sealos entry point for making OpenAI-compatible AI requests
through one managed endpoint.
## Why use AI Proxy
For a first call, AI Proxy gives you one place to get credentials, one request
shape to start with, and one place to confirm that the request reached Sealos.
## Before You Begin
Use this page if all of the following are true:
* You can sign in to Sealos.
* You can open the AI Proxy product surface in the Sealos console.
* You are ready to copy an endpoint and API key into shell environment
variables.
* You will use the fixed `cURL` example in this page for the first request.
The goal is first success, not full AI Proxy coverage.
## Get your endpoint and API key
Collect the two values needed for the first request.
1. Sign in to Sealos and open the AI Proxy surface.
2. Use the current console action to create or reveal an API key.
3. Copy the endpoint shown in AI Proxy.
4. Copy the API key value and keep both values ready for the shell example
below.
The next section places those values into shell environment variables.
## Make your first API call
Export the three placeholder variables first and run the request second.
```bash
export AI_PROXY_BASE_URL="replace-with-the-endpoint-shown-in-ai-proxy"
export AI_PROXY_API_KEY="replace-with-your-api-key-value"
export AI_PROXY_MODEL="replace-with-a-model-available-in-your-workspace"
curl "$AI_PROXY_BASE_URL/v1/chat/completions" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $AI_PROXY_API_KEY" \
-d '{
"model": "'"$AI_PROXY_MODEL"'",
"messages": [
{"role": "system", "content": "You are a concise assistant."},
{"role": "user", "content": "Reply with one short sentence about Sealos."}
],
"temperature": 0
}'
```
Replace the three placeholders with the values you copied from Sealos.
A successful response should return generated text in the response body.
The next section explains only the three fields used in this request.
## Understand the request fields
These are the only fields you need to understand for the first call:
* `model` selects the AI model the request should use. This page keeps the
starter model neutral until later verification.
* `messages` carries the conversation input for the request. The first request
keeps it minimal so the response is easy to recognize.
* `temperature` controls response randomness. This first request keeps it low
and simple for a predictable first success.
## Check logs and usage
Check these in order after the first call:
* Confirm the request returned successfully and the response contains
recognizable generated text.
* Find the same request record in AI Proxy logs. This is the primary
Sealos-side signal.
* Use usage or billing visibility as supporting confirmation only.
The next section covers only the first set of failure checks.
## If the first call fails
Check these first:
* wrong endpoint root or wrong path
Look here first: keep the AI Proxy endpoint unchanged and confirm the request
still targets `/v1/chat/completions`.
* wrong API key
Look here first: re-copy the current key and confirm the request still sends
`Authorization: Bearer $AI_PROXY_API_KEY`.
* unsupported or unavailable model
Look here first: replace the placeholder with a model that is available in
your workspace.
* no log record
Look here first: if the request does not appear in AI Proxy logs, it may not
have reached AI Proxy at all.
* missing balance or usage visibility
Look here first: if the request reaches AI Proxy but does not complete,
confirm the workspace still has usable balance or visible usage data.
## What this page does not cover
This page does not cover a model catalog, deep billing or deep logs guidance,
or advanced proxy features such as caching, routing, quotas, or failover.
It is the shortest path to a first successful call.
file: ./content/docs/guides/object-storage.en.mdx
meta: {
"title": "Object Storage",
"description": "S3-compatible object storage on Sealos -- create a bucket and upload your first file through the console.",
"keywords": [
"object storage",
"S3",
"bucket",
"file upload",
"credentials",
"Sealos"
]
}
This is the start-here guide for Object Storage on Sealos.
On this page, you create a bucket, retrieve its credentials, upload your first
file, and confirm the upload succeeded -- all through the Sealos console.
By the end, you have a working bucket with one file stored in it and the four
credential values you need for any future programmatic access.
## What Object Storage Is
Object Storage is the Sealos service for storing and managing unstructured data
such as files, images, documents, and backups. It is S3-compatible and built on
MinIO, and Sealos manages the underlying infrastructure so you work with
buckets and files instead of servers.
At a high level, you use Object Storage to upload files into buckets, download
them when you need them, and control who can read or write each bucket through
access permissions. Every bucket also exposes endpoints and credentials that
work with MinIO-compatible SDKs when you are ready to integrate it into an
application.
## Create a Bucket
In this section, you create your first bucket and set its access permission.
The bucket is the container that holds your files, and its permission level
controls who can read or write its contents.
<div className="fd-steps [&_h4]:fd-step">
<h4>Open the Object Storage app</h4>
Sign in to the Sealos console and open the Object Storage app from the
application launcher. The app lists any buckets you have already created
and provides the entry point for creating a new one.
<h4>Create a new bucket</h4>
Use the bucket creation action in the app, enter a name for your bucket,
and choose `private` as the access permission. Apply the change to create
the bucket. The new bucket then appears in your bucket list.
</div>
<Callout type="info">
Object Storage supports three permission levels. Choose `private` for your
first bucket unless you have a specific reason to make it public.
* **`private`**: only authenticated users can access bucket contents.
Recommended for the first bucket and any bucket containing sensitive
data.
* **`publicRead`**: anyone can read objects without authentication; write
operations still require credentials. Suitable for content delivery and
static website hosting.
* **`publicReadWrite`**: fully open read and write access. Use with
caution; production environments should avoid this level.
</Callout>
## Get Your Credentials
In this section, you retrieve the four values needed to access the bucket
programmatically. The first upload in this guide uses the console, so you do
not paste these values anywhere right now, but having them on hand prepares
you for any future SDK or API access.
Select your bucket in the bucket list and use the access key action to open
the credential display. A popup shows four values tied to this bucket: the
Access Key, the Secret Key, the Internal endpoint, and the External endpoint.
Read the values directly from the popup when you need them.
<Callout type="tip">
The two endpoints serve different access paths. Pick the one that matches
where your client runs.
* **Internal endpoint**: for services running inside Sealos. Traffic stays
on the internal network, which gives lower latency and avoids external
traffic charges.
* **External endpoint**: for access from outside the Sealos environment,
such as a local development machine or a service hosted elsewhere.
</Callout>
## Upload Your First File
In this section, you upload a test file into the bucket you just created. The
entire flow happens inside the Sealos console, so you do not need any command
line tools or SDK setup yet.
<div className="fd-steps [&_h4]:fd-step">
<h4>Open the bucket</h4>
In the Object Storage app, select the bucket you created earlier from the
bucket list. The bucket view opens at its root directory, which is where
your first file will land.
<h4>Upload a file</h4>
Use the upload action in the bucket toolbar to open your operating
system's file picker. Pick a small test file for your first upload -- a
plain text file or a small image under 1 MB works well and keeps the
transfer fast. Confirm the selection in the picker to start the upload.
<h4>Confirm the upload</h4>
Wait for the upload progress to finish. When it completes, the new file
appears in the bucket's file list at the current directory.
</div>
## Verify Your Upload
First success for this guide is defined by two signals inside the console.
Check them in order.
* File row in the bucket's file list
Open the bucket you just uploaded into and confirm a row for your file shows
the expected file name, its size, and the upload timestamp.
* Object detail view showing an addressable object path
Open the file's detail view from that row and confirm the view shows the
object's path or URL. This proves the object exists at an addressable
location. The bucket is private, so the URL itself is access-controlled;
this guide does not ask you to make the bucket public or generate a signed
URL.
If both signals are present, the first upload is confirmed.
## If the first upload fails
Check these first, in order:
* wrong or missing bucket
Look here first: confirm the bucket exists in your current workspace and
region, and that you opened the bucket you actually uploaded into.
* permission denied
Look here first: confirm the bucket's permission level is not blocking your
session, and that the upload action is available in the current context.
* wrong endpoint
Matters when you move to SDK or CLI access: the Internal and External
endpoints are separate values; pick the one that matches where your client
runs.
* wrong credentials
Matters when you move to SDK or CLI access: re-read the Access Key and
Secret Key from the credential popup and confirm the pair was copied
exactly.
* upload size or file-name issue
Look here first: use a small test file and avoid file names with characters
the bucket rejects.
## What's Next
You now have a working bucket with your first file stored in it and the four
credential values ready for any future programmatic access.
Object Storage supports more than the console upload flow. Beyond this guide,
you can use MinIO-compatible SDKs to read and write objects from your
applications, enable static website hosting for buckets with public read
access, and watch resource usage through the built-in monitoring views. These
are capabilities to explore once you are comfortable with the console basics,
not walkthroughs you need to follow right now.
file: ./content/docs/k8s/QA.en.mdx
meta: {
"title": "常见问题",
"keywords": [
"Sealos",
"镜像构建",
"Kubernetes运行时",
"版本兼容性",
"文件目录位置"
],
"description": "了解Sealos常见问题及解决方案，包括镜像构建、Kubernetes运行时选择、版本兼容性和文件目录位置调整。"
}
file: ./content/docs/k8s/lifecycle-management.en.mdx
meta: {
"title": "K8s 集群生命周期管理",
"keywords": [
"Kubernetes集群",
"Sealos工具",
"集群生命周期管理",
"分布式应用",
"Kubernetes安装"
],
"description": "使用Sealos工具轻松管理Kubernetes集群生命周期，支持分布式应用和自定义集群镜像，提供高可用性和离线安装功能。"
}
file: ./content/docs/msa/privacy-policy.en.mdx
meta: {
"title": "Privacy Policy"
}
**Effective Date:** May 9, 2026
## 1. Introduction and Data Controller
Labring Inc. ("we," "our," or "us"), a Delaware corporation, is the data controller for the information collected through Sealos Cloud services and related websites (collectively, "Services"). We are committed to protecting your privacy and ensuring a transparent processing of your personal data.
## 2. Information We Collect
* **Personal Information:** Name, email address, phone number, account credentials, and billing/payment information.
* **Technical Information:** IP addresses, browser type, device identifiers, log data, and performance metrics.
* **Usage Data:** How you interact with our Services and your configuration preferences.
## 3. How We Use Your Information
We process your information to:
1. Provide, maintain, and secure our Services.
2. Process payments and prevent fraud.
3. Provide technical support and critical service communications.
4. Comply with legal obligations and enforce our Terms of Service.
## 4. International Data Transfers
Labring Inc. is headquartered in the United States. Data collected may be transferred to and processed in the U.S. or other countries where our service providers maintain facilities.
**Data Transfer Mechanisms:**
* **Standard Contractual Clauses (SCCs):** For transfers of data from the EEA, UK, or Switzerland, we utilize European Commission-approved SCCs to ensure an adequate level of protection.
* **Data Privacy Framework:** We comply with the EU-U.S. Data Privacy Framework (EU-U.S. DPF), the UK Extension to the EU-U.S. DPF, and the Swiss-U.S. Data Privacy Framework (Swiss-U.S. DPF) as set forth by the U.S. Department of Commerce.
## 5. Data Security
We implement industry-standard security measures, including:
* AES-256 encryption for data at rest and TLS for data in transit.
* Strict Role-Based Access Control (RBAC).
* Regular security audits and vulnerability assessments.
## 6. Your Privacy Rights
Depending on your location (e.g., GDPR in the EU or CCPA in California), you may have the right to:
* Access, correct, or delete your personal data.
* Object to or restrict the processing of your data.
* Data portability.
* Withdraw consent at any time.
To exercise these rights, please contact **[privacy@sealos.io](mailto:privacy@sealos.io)**.
## 7. Children's Privacy
Our Services are intended for professional use and are not directed to children under 16. We do not knowingly collect information from children.
## 8. Contact Information
For privacy-related inquiries or to reach our Data Protection Officer:
* **Email:** [privacy@sealos.io](mailto:privacy@sealos.io)
* **Data Protection Officer:** [dpo@sealos.io](mailto:dpo@sealos.io)
* **Urgent Security Matters:** [fanux@sealos.io](mailto:fanux@sealos.io)
file: ./content/docs/msa/terms-of-service.en.mdx
meta: {
"title": "Terms of Service"
}
**Last Updated:** May 15, 2026
These Sealos Cloud Terms of Service (this "Agreement") are entered into by and between you (the "User" or "Customer") and **Labring Inc.** (referred to as "the Company," "we," or "us") regarding the use of our cloud services (the "Service").
**PLEASE READ THIS AGREEMENT CAREFULLY.** By using the Service, you agree to be bound by these terms.
## Article 1: Scope of Services
1. Labring Inc. provides cloud computing services including compute resources, storage, network services, and container orchestration via the Sealos platform.
2. We reserve the right to modify or enhance the Service. Material changes will be communicated via the website or email.
## Article 2: Service Level Agreement (SLA)
1. We strive for a Monthly Uptime Percentage of 99.9%.
2. Service credits may be issued for verified outages as defined in our full SLA documentation.
3. Scheduled maintenance is not counted toward downtime.
## Article 3: Account Management
1. You must provide accurate information during registration and are responsible for maintaining the confidentiality of your credentials.
2. Labring Inc. is not liable for any loss resulting from unauthorized access to your account due to your failure to secure your credentials.
## Article 4: Acceptable Use Policy
By using the Service, you agree to comply with this Acceptable Use Policy. You shall not use, or encourage, promote, facilitate, or instruct others to use the Service for any illegal, harmful, or offensive use.
You agree not to use the Service for:
* **Illegal Activities & Fraud:** Any illegal acts, fraudulent schemes, phishing, or the distribution of prohibited, deceptive, or malicious content.
* **Copyright & Intellectual Property:** Hosting, sharing, or distributing material that violates the intellectual property or copyrights of others. We maintain a zero-tolerance policy for copyright infringement.
* **Gambling:** Operating, promoting, or facilitating unauthorized online gambling, lotteries, betting pools, or any platform related to unlicensed wagering.
* **Adult Content:** Hosting, distributing, or transmitting pornography, sexually explicit material, or any adult-oriented content.
* **Cryptocurrency Mining:** Any form of cryptocurrency mining, blockchain validation, or related resource-intensive digital asset generation. This is strictly prohibited; there are no exceptions.
* **Unlicensed Regulated Activities:** Engaging in any activity that requires a government or regulatory license (including financial services, medical advice, or legal services) without possessing and maintaining all valid, necessary licenses.
* **Infrastructure Abuse:** Distributing malware, executing denial-of-service (DoS) attacks, or attempting to disrupt, probe, scan, or "stress test" our infrastructure without prior, express written authorization from us.
* **Resource Abuse:** Any activity that imposes an automated, disproportionate, or abusive load on our infrastructure or interferes with the performance of the Service for other users.
**Enforcement:**
We reserve the right, at our sole discretion, to determine what constitutes a violation of this Policy. We may take immediate action—including the suspension or permanent termination of your account and the deletion of data—without prior notice or liability if we believe you have breached any of these terms.
## Article 5: Data Ownership and Privacy
1. **Your Data:** You retain all rights, title, and interest in the data you upload to the Service.
2. **Our Privacy Policy:** We process data as described in the Labring Inc. Privacy Policy, which is incorporated here by reference.
## Article 6: Fees and Payment
1. Fees are based on usage and your selected tier.
2. Payments are due within thirty (30) days of the invoice date.
3. Failure to pay may lead to account suspension and, eventually, data deletion after a grace period.
## Article 7: Limitation of Liability
To the maximum extent permitted by law, Labring Inc. shall not be liable for any indirect, incidental, special, or consequential damages. In no event shall our total liability exceed the amounts paid by you to Labring Inc. for the Service in the twelve (12) months prior to the event giving rise to the claim.
## Article 8: Term and Termination
1. You may terminate your account at any time.
2. We may terminate or suspend your access for material breach of these terms.
3. Upon termination, you have thirty (30) days to retrieve your data before it is permanently deleted from our active systems.
## Article 9: Governing Law and Jurisdiction
This Agreement shall be governed by and construed in accordance with the laws of the **State of Delaware**, USA, without regard to its conflict of law principles. Any legal action arising out of this Agreement shall be brought exclusively in the courts located in Delaware.
## Article 10: Contact
For legal notices or questions regarding these terms, please contact:
* **Legal Department:** [legal@sealos.io](mailto:legal@sealos.io)
file: ./content/docs/overview/intro.en.mdx
meta: {
"title": "What is Sealos?",
"icon": "Info",
"keywords": [
"Sealos",
"cloud platform",
"Kubernetes",
"cloud development environment",
"DevBox",
"managed databases",
"app store",
"multi-tenancy",
"AI deployment",
"container platform"
],
"description": "Sealos is a cloud platform that unifies the entire application lifecycle—from development in cloud development environments to production deployment—powered by Kubernetes, without the complexity."
}
Sealos is an AI-native cloud development platform designed to unify the entire application lifecycle, starting with cloud development environments and one-click deployments, extending to managed databases and full Kubernetes power—all without the complexity.
## Everything You Need to Build and Scale
Unify the entire application lifecycle, from development in cloud development environments to production deployment and management.
### AI-Native Infrastructure
Build and scale modern AI applications simply by describing them.
### Cloud Development Environments
Zero-setup, collaborative development in the cloud. Eliminate local environment inconsistencies with DevBox.
* Connect with your favorite IDE (VS Code, JetBrains, Cursor)
* Pre-configured runtime environments for any language
* Instant collaboration with teammates
### Extensive App Store
Deploy complex applications with a single click. No YAML configuration, no container orchestration complexity—just point, click, and deploy.
* 100+ pre-built templates
* One-click deployment for popular applications
* Community-contributed app catalog
### Managed Databases & Storage
Production-ready databases and storage, fully managed with automated backups and high availability.
* **Databases**: PostgreSQL, MySQL, MongoDB, Redis
* **Object Storage**: S3-compatible, built-in
* High availability and automated backups
### Full Kubernetes Power
Access the full power of Kubernetes without the complexity. K8s-native from day one.
* Raw Kubernetes access when you need it
* Automatic container orchestration
* Native integration with cloud-native ecosystem
### Enterprise Multi-Tenancy
Workspace-based isolation with granular permissions for secure collaboration.
* Workspace-based resource isolation
* Granular RBAC controls
* Per-workspace resource quotas
***
## Getting Started
Ready to ship your first app?
<Cards>
<Card href="/docs/quick-start" title="Quick Start">
Deploy your first application in under 5 minutes.
</Card>
<Card href="/docs/guides/devbox" title="DevBox Guide">
Set up a cloud development environment.
</Card>
<Card href="/docs/guides/databases" title="Databases">
Launch a managed PostgreSQL, MySQL, or MongoDB.
</Card>
</Cards>
file: ./content/docs/self-hosting/faq.en.mdx
meta: {
"title": "常见问题",
"keywords": [
"Sealos Cloud",
"常见问题",
"部署问题",
"证书更新",
"域名更换",
"用户注册",
"集群管理",
"Kubernetes"
],
"description": "探索Sealos Cloud部署和使用中的常见问题解决方案，包括系统配置、证书更新、域名更换等关键操作指南，助您轻松管理Kubernetes集群。"
}
file: ./content/docs/self-hosting/install-v1.en.mdx
meta: {
"title": "Sealos 集群部署 - 旧版",
"description": "了解如何使用 Sealos 一键部署 Kubernetes 集群，支持多种安装方式，确保通信安全，适用于大规模集群和企业生产环境。"
}
file: ./content/docs/self-hosting/install.en.mdx
meta: {
"title": "Sealos 集群部署",
"description": "了解如何使用 Sealos 一键部署 Kubernetes 集群，支持多种安装方式，确保通信安全，适用于大规模集群和企业生产环境。"
}
file: ./content/docs/system-design/billing-system.en.mdx
meta: {
"title": "计费系统",
"keywords": [
"Sealos 计费系统",
"云成本管理方案",
"Kubernetes 资源计费",
"容器计费架构",
"云原生计费设计",
"实时资源计量",
"自动费用计算",
"精准账单系统",
"跨集群成本优化",
"FinOps 实践",
"云资源计价模型",
"分布式计费方案"
],
"description": "深度剖析 Sealos 云操作系统的计费系统架构设计，详解基于 CRD 的实时资源计量模型、多维度费用计算算法及分布式账单生成机制，涵盖CPU/内存/存储/网络等全资源类型的精准计价策略，提供 Kubernetes 集群成本优化最佳实践与 FinOps 落地指南。"
}
file: ./content/docs/system-design/devbox-architecture.en.mdx
meta: {
"title": "Architecture"
}
Sealos Devbox is an advanced development environment solution that leverages cloud-native Container and Kubernetes technologies to offer a unified and flexible development Runtime. Its key feature is simulating a traditional virtual machine experience while maintaining containerization benefits.
## Architecture
Sealos Devbox is built on a layered architecture, comprising these key components:
## Control Flow
Devbox implements a decoupled front-end and back-end design:
1. Users trigger actions via the web interface or plugins
2. Devbox Controller receives and processes these requests
3. Controller translates the processed instructions into Kubernetes API calls
4. Kubernetes executes the corresponding Container operations
## State Persistence Mechanism
Devbox employs an intelligent state preservation system to maintain user environment consistency:
### Automatic Saving
* System auto-saves user environment changes under specific conditions
* Changes are packaged as image layers
* New layers are appended to the base image as commits
* Updated images are securely stored in an isolated internal registry
### Environment Recovery
* On subsequent startups, system boots from the most recent image
* Ensures full preservation of historical changes
### Optimization
The Container-shim layer provides automated maintenance:
* Regularly merges image layers to optimize storage
* Automatically cleans up redundant data
* Optimizes image size and layer count for optimal system performance
file: ./content/docs/system-design/monitor-system.en.mdx
meta: {
"title": "监控告警系统",
"keywords": [
"Sealos 监控系统",
"云原生告警体系",
"Kubernetes 监控方案",
"容器集群监控",
"VictoriaMetrics 实战",
"Loki 日志管理",
"Grafana 可视化",
"PrometheusAlert 集成",
"实时指标监控",
"日志聚合系统",
"多平台告警推送",
"运维自动化",
"分布式系统监控",
"可观测性最佳实践"
],
"description": "深度解析 Sealos 云原生监控告警系统架构设计，详解基于 VictoriaMetrics 的实时指标采集方案与 Loki 日志管理系统的集成实践，涵盖多可用区高可用部署、Grafana 可视化配置、飞书/微信多平台告警推送等核心功能，提供云原生环境下的全栈监控与日志分析最佳实践。"
}
file: ./content/docs/system-design/system-application.en.mdx
meta: {
"title": "系统应用",
"keywords": [
"Sealos系统应用架构",
"云原生桌面系统设计",
"Kubernetes CRD 应用管理",
"分布式费用中心实现",
"定时任务调度系统",
"KubeBlocks 数据库集成",
"多租户对象存储方案",
"云原生应用开发平台",
"微服务模块化设计",
"系统组件交互协议",
"容器化应用生命周期管理",
"可观测性系统集成"
],
"description": "主要介绍 Sealos 当前各个系统应用的基本原理与实现。"
}
file: ./content/docs/system-design/system-architecture.en.mdx
meta: {
"title": "系统架构",
"description": "深度解析 Sealos 云操作系统的分层架构设计与核心组件实现。"
}
file: ./content/docs/system-design/user-system.en.mdx
meta: {
"title": "用户系统",
"description": "深度解析 Sealos 云操作系统的分层架构设计与核心组件实现。"
}
file: ./content/docs/guides/app-deploy/add-a-domain.en.mdx
meta: {
"title": "Domains and Public Access",
"keywords": [
"custom domain",
"public access",
"CNAME",
"Sealos",
"App Launchpad"
],
"description": "Make an existing Sealos app reachable on the public internet and attach a custom domain when you need one."
}
## When to use this
Use this page after your app already exists and you need a stable public address.
You might only need the Sealos-generated public URL, or you might need to attach your own domain after DNS is ready. This is the right page for both jobs.
## Before you change this
If your app is deployed in mainland China, make sure the custom domain can legally resolve in that region before you switch traffic to it.
If your domain requires filing or provider-specific ICP compliance, complete that first. You also need control of your DNS provider so you can create a `CNAME` record that points to the Sealos-generated address.
## Add Public Access during deploy or redeploy
1. Open the app create or change form in the App Launchpad UI.
2. Find the network section and enable **Public Access**.
3. Record the public address that Sealos generates for the app.
4. Finish the deploy or redeploy so the public endpoint becomes active.
If the app is already deployed, you can reopen the same settings from the app details page and enable **Public Access** there before saving the change.
## Attach a custom domain
1. Open your app details page and confirm the Sealos-generated public address is already available.
2. At your DNS provider, create a `CNAME` record that points your domain or subdomain to the Sealos-generated address.
3. Wait for DNS propagation before you continue.
4. Back in Sealos, open the **Custom Domain** action from the app details page.
5. Enter the domain you want to bind, then confirm and redeploy if Sealos asks you to apply the change.
If you are switching an existing production domain, keep TTL and rollback steps in mind before you update the DNS record.
## Verify
Use this checklist before you treat the change as complete:
* The app still shows a healthy `running` state after the change.
* The Sealos-generated public URL still opens the app.
* The custom domain resolves to the expected `CNAME` target.
* Opening the custom domain loads the same app content you expected to publish.
If this fails, see [Custom Domain and TLS Issues](/docs/guides/app-deploy/custom-certificates/).
## Related Tasks
* [Update and Redeploy](/docs/guides/app-deploy/update-apps/) if you need to reopen the app settings later for additional changes.
* [Ports and Networking](/docs/guides/app-deploy/expose-multiple-ports/) if the app needs more than one externally reachable endpoint.
file: ./content/docs/guides/app-deploy/app-does-not-reach-running.en.mdx
meta: {
"title": "App Does Not Reach Running",
"keywords": [
"app not running",
"startup failure",
"image pull failure",
"App Deploy",
"Sealos"
],
"description": "Recover when an App Deploy workload never reaches running because of image, startup, or configuration problems."
}
## When to use this
Use this page when Sealos creates the app, but the instance never reaches `running`.
This usually means the app failed before it could start normally. Common causes are a wrong image, a bad startup command, or optional settings that broke the container.
## Check the failure surface
1. Open the app details page in App Deploy.
2. Check the instance status first so you know whether the app is still waiting or already failed.
3. Open the instance details view to inspect the startup failure surface.
4. Open the instance logs to see whether the container pulled, started, and exited with an error.
If the image name is wrong or unavailable, the failure usually appears before the app starts.
If the container starts and then exits, the logs usually point to the broken command or missing runtime configuration.
## What to fix
Work through these checks in order:
1. Re-check the image name and tag you entered.
2. Remove or correct the startup command if you added one.
3. Re-check any environment variables, config files, storage mounts, or extra ports you added beyond the basic happy path.
4. If you changed several settings at once, roll back to the last known working combination before you try again.
For a first deploy, the lowest-friction baseline is still a public `nginx:latest` container on port `80` with no startup command and no optional configuration.
## Verify
Treat the issue as resolved only when all of the following are true:
* The instance state changes to `running`.
* The details view no longer shows the previous startup failure.
* The logs stop showing the earlier fatal startup error.
* If the app should be public, you can continue to the next reachability check.
## Related Tasks
* [Public URL Does Not Open](/docs/guides/app-deploy/public-url-does-not-open/) if the app reaches `running` but still is not reachable.
* [Update and Redeploy](/docs/guides/app-deploy/update-apps/) if you need to reopen the settings and correct a broken deploy.
file: ./content/docs/guides/app-deploy/autoscaling.en.mdx
meta: {
"title": "Scaling",
"keywords": [
"scaling",
"autoscaling",
"HPA",
"CPU",
"memory",
"Sealos"
],
"description": "Configure scaling rules for a Sealos app so instance count can grow or shrink with load."
}
## When to use this
Use this page when the app already works with one instance but traffic or workload may change over time.
Scaling is a better fit for stateless or horizontally safe services than for apps that assume only one writer or one local filesystem.
## Before you change this
Scaling changes both capacity and cost.
Before you enable autoscaling, confirm the app can safely run on more than one instance and that shared state is stored outside the container if needed.
## Configure scaling
1. Open the app details page and reopen the settings with the **Update** or **Change** action.
2. Find the scaling section in the App Launchpad UI.
3. Set the minimum instance count (`min`) and maximum instance count (`max`).
4. Set the target CPU or memory threshold that should trigger scale decisions.
5. Save the change and redeploy the app.
## How Sealos reads usage
Sealos makes autoscaling decisions from average usage across running instances.
* If two instances use 60% CPU and 40% CPU, the average CPU value is 50%.
* The same idea applies to memory thresholds.
* If the average rises above the target, Sealos can add instances up to the configured max.
* If the average stays below the target, Sealos can reduce instances down to the configured min.
## Verify
Check the result after the change:
* The app returns to `running`.
* The saved scaling policy still shows the expected min and max range.
* The configured CPU or memory target is visible after you reopen the form.
* Under load, the app can increase instance count instead of staying fixed at one instance.
If you are not testing with real traffic yet, at least verify that the policy persists correctly and does not conflict with the app's current resource settings.
## Related Tasks
* [Update and Redeploy](/docs/guides/app-deploy/update-apps/) if you need to adjust image or resources together with scaling.
* [Persistent Storage](/docs/guides/app-deploy/persistent-volume/) if the app still writes important data inside the container and is not ready for multi-instance behavior.
file: ./content/docs/guides/app-deploy/configmap.en.mdx
meta: {
"title": "Config Files",
"keywords": [
"config files",
"ConfigMap",
"Sealos",
"file-based configuration"
],
"description": "Mount a configuration file into your Sealos app when environment variables are not enough."
}
## When to use this
Use this page when your app expects a real file such as `nginx.conf`, a YAML config, a JSON settings file, or another structured config artifact inside the container.
Choose this approach when environment variables are too small or too awkward for the setting you need to change. In Sealos, this is usually implemented with a ConfigMap-backed file mount.
## Before you change this
Mount the exact target file path, not just a folder.
Sealos mounts a **single file** into the container. If you enter only a directory path, or if you choose the wrong file path, the app may start with the wrong config or fail to boot.
## Add a config file
1. Check the image documentation so you know the exact file path the app expects inside the container.
2. Prepare the file content locally first if the config is large or easy to break.
3. Open the app details page and choose the action that reopens the app settings.
4. Find the config file section in the App Launchpad UI.
5. Enter the full in-container file path and paste the file contents.
6. Save the change and redeploy the app.
For example, an Nginx container usually expects a file path such as `/etc/nginx/nginx.conf`. That is a single file path, not a directory.
## Verify
Confirm the config change after redeploy:
* The app reaches `running`.
* The new behavior matches the file you mounted.
* If the app exposes logs, the logs do not show a syntax or startup error caused by the new file.
If the app fails immediately after redeploy, compare the mounted file path and the pasted contents with the image documentation before you retry.
## Related Tasks
* [Environment Variables](/docs/guides/app-deploy/environments/) if the setting can be expressed more safely as key-value pairs.
* [Update and Redeploy](/docs/guides/app-deploy/update-apps/) if you are changing config files together with the image or resources.
file: ./content/docs/guides/app-deploy/create-app.en.mdx
meta: {
"title": "Create App",
"keywords": [
"create app",
"App Deploy",
"legacy route",
"Sealos"
],
"description": "Legacy handoff page for older App Deploy links. Use the canonical first-deploy guide instead."
}
This page is kept only for older App Deploy links.
The canonical onboarding guide is now [Deploy Your First App](/docs/guides/app-deploy/first-deploy/).
## Start here instead
If you want the current zero-to-one path, open [Deploy Your First App](/docs/guides/app-deploy/first-deploy/) and follow that walkthrough instead of using this legacy route.
file: ./content/docs/guides/app-deploy/custom-certificates.en.mdx
meta: {
"title": "Custom Domain and TLS Issues",
"keywords": [
"custom domain certificate",
"TLS issue",
"cert-manager",
"ingress patch",
"App Deploy"
],
"description": "Recover when a custom App Deploy domain is configured but the certificate is missing, invalid, or still not secure."
}
## When to use this
Use this page when the Sealos-generated public endpoint works, but the custom domain still fails TLS checks or shows an insecure certificate state.
This recovery path is only for domain and certificate issues after the app is already reachable enough to continue.
## Confirm the basic prerequisites
Before you change the certificate flow, confirm all of the following:
* The app already has a working public endpoint in App Deploy.
* You already configured the custom domain in Sealos.
* Your DNS provider already points the domain or subdomain to the Sealos endpoint with the correct `CNAME` record.
* You already have the certificate and private key files if you need to apply your own TLS secret.
If the generated public endpoint does not work yet, return to [Domains and Public Access](/docs/guides/app-deploy/add-a-domain/) and confirm the base routing first.
## If Sealos did not issue a certificate
If the custom domain is configured but the certificate is still missing or insecure, the most common problem is that cert-manager did not issue the certificate successfully.
Re-check the domain value, the current `CNAME` target, and whether DNS propagation has actually finished before you apply manual certificate steps.
If those checks are already correct and you still need a manual recovery path, continue with your own TLS secret.
## Apply your own TLS secret
Open the terminal from the App Launchpad UI, then run the TLS secret steps with your own certificate data.
```bash
# Create tls.crt using the certificate file information (replace xxxx with the actual certificate file information).
cat > tls.crt <<EOF
-----BEGIN CERTIFICATE-----
xxxx
-----END CERTIFICATE-----
EOF
# Create tls.key using the certificate private key information (replace xxxx with the actual private key information).
cat > tls.key <<EOF
-----BEGIN RSA PRIVATE KEY-----
xxxx
-----END RSA PRIVATE KEY-----
EOF
# Create a secret using tls.crt and tls.key.
kubectl create secret tls network-test --cert tls.crt --key tls.key
# Check the ingress for the corresponding application.
kubectl get ingress
```
Then patch the ingress so the custom domain points to that TLS secret. Replace `xzy-dev.sealos.run` with your own domain and replace the ingress name with the one that belongs to your app.
```bash
kubectl patch ingress network-twvuqmjzckur -p '{"spec":{"tls":[{"hosts":["xzy-dev.sealos.run"],"secretName":"network-test"}]}}'
```
## Verify
Treat the issue as resolved only when all of the following are true:
* The app still stays `running`.
* Opening the Sealos-generated public endpoint still works.
* Opening the custom domain now loads the expected app content.
* The browser no longer reports the old insecure certificate state.
## Related Tasks
* [Domains and Public Access](/docs/guides/app-deploy/add-a-domain/) if you still need to re-check the domain binding or `CNAME` target.
* [Public URL Does Not Open](/docs/guides/app-deploy/public-url-does-not-open/) if the base public endpoint is still broken before the custom domain layer.
file: ./content/docs/guides/app-deploy/docker-compose-migration.en.mdx
meta: {
"title": "Migrate from Docker Compose",
"keywords": [
"Docker Compose",
"migration",
"Sealos",
"WordPress",
"environment variables",
"persistent storage"
],
"description": "Move an existing Docker Compose workload to Sealos by translating services, ports, storage, and environment variables into App Deploy and related Sealos products."
}
## When to use this
Use this page when you already have a working Docker Compose setup and want to move that workload into Sealos.
This is not the default first deploy path. If you are starting from scratch, use [First Deploy](/docs/guides/app-deploy/first-deploy/) instead. If you are already running the app on Sealos and only need one follow-up change, use the manage task pages instead of a full migration flow.
## Check for a ready-made template first
Before you do a manual migration, check whether Sealos App Store already has a maintained template for the workload you want to run.
If a tested template exists, start there. Manual migration is most useful when you have a custom app or when no template matches the services in your `docker-compose.yml`.
## Translate Compose concepts into Sealos
Use this table to map the main Docker Compose concepts into Sealos building blocks:
| Docker Compose | Sealos target |
| -------------- | ---------------------------------------------------------------- |
| `services` | Separate app deployments or managed services |
| `ports` | App Deploy network configuration |
| `volumes` | [Persistent Storage](/docs/guides/app-deploy/persistent-volume/) |
| `environment` | [Environment Variables](/docs/guides/app-deploy/environments/) |
| `depends_on` | Deployment order and dependency planning |
| `image` | Container image field in App Deploy |
| `command` | Startup command or runtime command field |
Most migrations become easier if you split stateful services and app services instead of trying to force the entire stack into one first deploy.
## Plan the migration
1. Read the existing `docker-compose.yml` and list every service, image, port, volume, environment variable, and startup command.
2. Decide which services should stay together in App Deploy and which should become a dedicated Sealos product such as a managed database.
3. Identify every persistent path before you redeploy anything.
4. Move external dependencies first so the application can connect to them when the app service starts.
## Example: WordPress migration
A typical WordPress stack in Docker Compose has one app service and one database service.
In Sealos, a practical migration path is:
1. Create the database first by using the Sealos database product that matches the Compose stack.
2. Record the database host, username, password, and database name.
3. Deploy the `wordpress:latest` app in App Deploy.
4. Expose port `80` publicly so you can reach the site.
5. Attach persistent storage to `/var/www/html` so uploads and content survive a redeploy.
6. Add the WordPress database settings as environment variables before the first app start.
That keeps the migration clear: stateful data is handled separately, while the web app moves into the App Deploy workflow.
## Verify
Use this checklist before you call the migration complete:
* Every Docker Compose service has a clear Sealos target.
* Persistent data paths were moved to persistent storage where needed.
* The migrated app returns to `running`.
* The public endpoint opens the migrated workload successfully.
* The app can still reach the services it depended on before the migration.
If the migrated app does not reach running, see [App Does Not Reach Running](/docs/guides/app-deploy/app-does-not-reach-running/).
If the public endpoint does not open, see [Public URL Does Not Open](/docs/guides/app-deploy/public-url-does-not-open/).
## Related Tasks
* [Persistent Storage](/docs/guides/app-deploy/persistent-volume/) if the original Compose stack used `volumes`.
* [Environment Variables](/docs/guides/app-deploy/environments/) if the migrated app still needs runtime settings.
* [Update and Redeploy](/docs/guides/app-deploy/update-apps/) if you need to adjust the migrated app after the first successful move.
file: ./content/docs/guides/app-deploy/environments.en.mdx
meta: {
"title": "Environment Variables",
"keywords": [
"environment variables",
"Sealos",
"App Launchpad",
"runtime settings"
],
"description": "Configure runtime settings for a Sealos app with environment variables instead of rebuilding the image."
}
## When to use this
Use this page when your image is correct but the app still needs runtime settings such as ports, hosts, credentials, feature flags, or service endpoints.
Environment variables are the fastest way to change small pieces of configuration without rebuilding the image. If your app needs a full config file instead of key-value pairs, use [Config Files](/docs/guides/app-deploy/configmap/) instead.
## Update environment variables
1. Open the app details page for the running app.
2. Click the action that reopens the app settings. Depending on the current UI, this may be labeled **Update** or **Change**.
3. Find the environment variable input area.
4. Paste one variable per line, then review the values before you save.
5. Redeploy the app so the new environment variables are applied to the next running instance.
## Supported input format
Sealos accepts bulk input, so you can paste several variables at once.
These formats are interpreted correctly:
```shell
host=127.0.0.1
port:3000
name: sealos
- username=123
- password:123
# Comments like this line are ignored because they do not contain = or :
```
This format is risky because the inline comment becomes part of the value:
```shell
host=127.0.0.1 # This entire right side is treated as the value
```
Use plain key-value lines only. Do not rely on inline comments after the value.
## Verify
Check the result after the redeploy:
* The app returns to `running`.
* The changed settings still appear in the environment variable section when you reopen the form.
* The app behavior matches the new values, for example by connecting to the right host, binding the expected port, or enabling the intended feature.
If the app fails after the change, compare the pasted values with the expected application format before you try a larger rollback.
## Related Tasks
* [Config Files](/docs/guides/app-deploy/configmap/) if the app needs structured file content instead of simple key-value settings.
* [Update and Redeploy](/docs/guides/app-deploy/update-apps/) if you are changing the image or several runtime settings at the same time.
file: ./content/docs/guides/app-deploy/expose-multiple-ports.en.mdx
meta: {
"title": "Ports and Networking",
"keywords": [
"multiple ports",
"Add Port",
"networking",
"HTTP",
"HTTPS",
"gRPC",
"Sealos"
],
"description": "Add and manage more than one application port in Sealos when a single endpoint is not enough."
}
## When to use this
Use this page when one app needs more than one listener, for example HTTP plus HTTPS, an app port plus an admin port, or a public API plus a private metrics endpoint.
This is also the right page when you need to decide which ports stay internal and which ports should become public.
## Before you change this
Every public port creates another externally reachable endpoint.
Before you expose more ports, decide which ones should remain internal and which ones really need internet access.
## Add more than one port
1. Open the app details page and reopen the settings with **Update** or **Change**.
2. Go to the network section.
3. Use **Add Port** to create the first additional port mapping.
4. Enter the container port and decide whether that port should be public or internal only.
5. Repeat the same process for each required port.
6. Save the change and redeploy the app.
Common examples include:
* HTTP and HTTPS on separate ports
* A user-facing service plus an admin service
* A REST API plus a gRPC endpoint
* An app service plus a `/metrics` port that should stay private
If you expose a port publicly, Sealos assigns a separate externally reachable endpoint for that port, usually through its own sub-domain.
## Verify
Check the network result after redeploy:
* The app returns to `running`.
* Every required port appears in the current app configuration.
* Each public port receives the expected external address or sub-domain.
* Internal-only ports are not accidentally exposed to the public internet.
If a public endpoint opens the wrong service, re-check the port mapping before you change domains or application code.
## Related Tasks
* [Domains and Public Access](/docs/guides/app-deploy/add-a-domain/) if one of the public endpoints now needs a custom domain.
* [Update and Redeploy](/docs/guides/app-deploy/update-apps/) if you are changing image, env, or storage together with networking.
file: ./content/docs/guides/app-deploy/first-deploy.en.mdx
meta: {
"title": "Deploy Your First App",
"keywords": [
"App Deploy",
"App Launchpad",
"Sealos",
"first deploy",
"nginx",
"nginx:latest",
"public URL"
],
"description": "Deploy your first app on Sealos App Deploy with one exact walkthrough using nginx:latest, port 80, and a public URL."
}
This is the start-here App Deploy tutorial for new users.
Follow this page when you want the shortest zero-to-one path to one public single-container web app on Sealos.
By the end of this guide, you will deploy `nginx:latest`, wait for the instance to reach `running`, and open its public URL in your browser.
## Before You Begin
Use this tutorial if all of the following are true:
* You can sign in to the Sealos console.
* You want one public single-container web app, not a multi-service setup.
* You will use the exact demo image `nginx:latest`.
* You will expose container port `80` to a public URL.
For this first deploy, skip startup commands, environment variables, config files, persistent storage, scaling rules, and multiple ports.
The goal here is first success, not full configuration coverage.
## What You Will Deploy
This tutorial uses one exact demo so you do not have to choose values along the way.
You will deploy a small Nginx container as a fixed one-instance app and verify that its welcome page opens from a browser.
| Field | Value |
| -------------- | --------------- |
| App name | `nginx` |
| Image | `nginx:latest` |
| Deploy mode | Fixed instances |
| Instance count | `1` |
| CPU | `0.1` |
| Memory | `128 MiB` |
| Container port | `80` |
| Public access | Enabled |
## Step-by-Step Deployment
### 1. Open the Sealos console
Open [Sealos Console](https://cloud.sealos.run) and sign in.
Then open the App Launchpad module from the workspace.
### 2. Start creating the app
Click the button or action that creates a new app.
After you submit that action, wait for the app creation form to open.
### 3. Fill the basic app information
Set the app name to `nginx`.
Set the image to `nginx:latest`.
Use the exact image value in this guide.
Changing the image means you may need different ports, commands, or config later.
### 4. Choose one fixed instance
Set deployment mode to a fixed number of instances.
Set the instance count to `1`.
Keep this tutorial on the simplest path.
Do not enable scaling yet.
### 5. Set small compute resources
Use a small resource allocation such as `0.1` CPU and `128 MiB` memory.
That is enough for the Nginx demo page in this walkthrough.
### 6. Configure networking
Add container port `80`.
Enable public access so Sealos can generate a public URL for the app.
Use port `80` exactly for this first deployment.
The verification step later assumes this port is the one exposed to the browser with public access enabled.
### 7. Leave optional sections empty
Do not set a startup command.
Do not add environment variables.
Do not add config files.
Do not add persistent storage.
Those fields matter for later jobs, but they are intentionally outside the happy path for this first deploy.
### 8. Deploy the app
Click the deploy action in the form.
After you submit the form, wait for the app detail page to open.
### 9. Wait for the app detail page to show a healthy instance
On the app details page, watch the instance list and status.
Wait until the instance state becomes `running`.
If this fails, see [App Does Not Reach Running](/docs/guides/app-deploy/app-does-not-reach-running/).
## Verify the Deployment
Use this checklist before you call the deployment complete:
* In Sealos, the instance status is `running`.
* The app details page shows a public URL.
* Opening the public URL loads the Nginx welcome page in your browser.
* The welcome page is the demo page for this tutorial, so you know the container is reachable from the public internet.
If this fails, see [Public URL Does Not Open](/docs/guides/app-deploy/public-url-does-not-open/).
For this walkthrough, the correct combination is container port `80` with public access enabled.
## Success
Your app is running.
Your first app is deployed on Sealos App Deploy.
The instance is healthy in Sealos, and the app is reachable through its public URL.
If you ever need the shortest App Deploy start-here path again, come back to this tutorial and reuse the same exact values.
## Next Steps
After your first successful deploy, move to one focused App Deploy job at a time:
* [Domains and Public Access](/docs/guides/app-deploy/add-a-domain/)
* [Environment Variables](/docs/guides/app-deploy/environments/)
* [Config Files](/docs/guides/app-deploy/configmap/)
* [Persistent Storage](/docs/guides/app-deploy/persistent-volume/)
* [Update and Redeploy](/docs/guides/app-deploy/update-apps/)
* [Scaling](/docs/guides/app-deploy/autoscaling/)
* [Ports and Networking](/docs/guides/app-deploy/expose-multiple-ports/)
This page is the canonical first deploy path.
After this point, use the guides above instead of reopening every deployment option at once.
file: ./content/docs/guides/app-deploy/index.en.mdx
meta: {
"title": "App Deploy",
"keywords": [
"App Deploy",
"App Launchpad",
"first deploy",
"Docker Compose migration",
"manage app"
],
"description": "Choose the right App Deploy path in Sealos: first deploy, migrate from Docker Compose, or manage an existing app."
}
App Deploy is the Sealos documentation section for deploying and managing container apps.
In the product UI, you will usually see this area labeled **App Launchpad**. This guide uses **App Deploy** as the canonical docs name and only uses `App Launchpad` when the exact UI label matters.
Choose the path that matches your job right now.
## First Deploy
Start here if you want the shortest path from zero to one running public app on Sealos.
[Go to First Deploy](/docs/guides/app-deploy/first-deploy/)
## Other paths
### Migrate from Docker Compose
Choose this path if you already have a `docker-compose.yml` and need to translate an existing workload into Sealos without treating it like a brand-new first deploy.
[Go to Migrate from Docker Compose](/docs/guides/app-deploy/docker-compose-migration/)
### Manage an existing app
Choose this path if your app already exists and you need to change one thing at a time, such as networking, storage, configuration, or scaling.
[Go to common next jobs](#after-your-first-deploy)
## After your first deploy
Use one focused task page at a time instead of reopening every deployment option at once:
* [Domains and Public Access](/docs/guides/app-deploy/add-a-domain/)
* [Environment Variables](/docs/guides/app-deploy/environments/)
* [Config Files](/docs/guides/app-deploy/configmap/)
* [Persistent Storage](/docs/guides/app-deploy/persistent-volume/)
* [Update and Redeploy](/docs/guides/app-deploy/update-apps/)
* [Scaling](/docs/guides/app-deploy/autoscaling/)
* [Ports and Networking](/docs/guides/app-deploy/expose-multiple-ports/)
If you are moving an existing workload rather than starting fresh, use [Migrate from Docker Compose](/docs/guides/app-deploy/docker-compose-migration/) instead of the default first-deploy path.
If a deploy is failing, start with [Troubleshooting](/docs/guides/app-deploy/troubleshoot/).
file: ./content/docs/guides/app-deploy/persistent-volume.en.mdx
meta: {
"title": "Persistent Storage",
"keywords": [
"persistent storage",
"persistent volume",
"data retention",
"Sealos"
],
"description": "Keep application data across restart and redeploy operations by attaching persistent storage to a Sealos app."
}
## When to use this
Use this page when your app writes data that must survive a restart, replacement, or redeploy.
Typical examples include uploaded files, databases, CMS content, and any app that stores user data inside the container filesystem.
## Before you change this
You need the exact in-container data path before you attach storage.
If you mount storage to the wrong location, the app may still start, but the real data path will remain ephemeral and your data will not survive a restart or redeploy.
## Attach persistent storage
1. Identify the path inside the container where the app stores durable data.
2. Open the app create form or reopen the app settings from the app details page.
3. Add a storage entry and enter the in-container mount path.
4. Set a storage size that matches the app's expected data growth.
5. Save the change and redeploy the app.
For example, a Nextcloud container usually stores durable content under `/var/www/html`. That is the path you would mount if you want user files and app data to survive replacement of the container.
## Verify
Check the result after the redeploy:
* The app returns to `running`.
* The storage mount still appears in the app configuration.
* Data written before a restart remains available after the app comes back.
* Data also remains available after a redeploy that replaces the container instance.
If the data disappears after a restart or redeploy, re-check the exact mount path before you increase storage size or change other settings.
## Related Tasks
* [Update and Redeploy](/docs/guides/app-deploy/update-apps/) if you need to reopen the app settings to change image, resources, or other runtime options at the same time.
* [Migrate from Docker Compose](/docs/guides/app-deploy/docker-compose-migration/) if you are translating existing volume mounts from a Compose stack.
file: ./content/docs/guides/app-deploy/public-url-does-not-open.en.mdx
meta: {
"title": "Public URL Does Not Open",
"keywords": [
"public URL issue",
"public access",
"container port",
"App Deploy",
"Sealos"
],
"description": "Recover when an App Deploy app is healthy in Sealos but the public URL still does not open in the browser."
}
## When to use this
Use this page when the app already exists, but the public endpoint still does not load.
This page is for reachability problems after deploy. Start here only after you confirm the app itself is already healthy enough to keep running.
## Check the basic state first
1. Open the app details page and confirm the instance is already `running`.
2. Confirm that the app details page shows a generated public endpoint.
3. If the app is not `running`, stop here and use [App Does Not Reach Running](/docs/guides/app-deploy/app-does-not-reach-running/) first.
## What to fix
Check these inputs in order:
1. Re-check the container port you exposed in the deploy or update form.
2. Confirm **Public Access** is enabled for that port.
3. Make sure the generated endpoint still matches the current app configuration after the last redeploy.
4. Retry the endpoint in the browser after the app has fully settled in `running`.
If you exposed the wrong port or disabled **Public Access**, the endpoint may exist but still not serve the app correctly.
If the app uses a custom domain instead of the generated endpoint, move to the domain/TLS recovery path after you confirm the base public endpoint works.
## Verify
Treat the issue as resolved only when all of the following are true:
* The instance is still `running`.
* The exposed container port matches the port your app actually serves.
* **Public Access** is enabled for the correct endpoint.
* Opening the generated public URL loads the expected app content in the browser.
## Related Tasks
* [Domains and Public Access](/docs/guides/app-deploy/add-a-domain/) if you now need to attach a custom domain after the base public endpoint works.
* [Custom Domain and TLS Issues](/docs/guides/app-deploy/custom-certificates/) if the generated endpoint works but the custom domain is still broken.
file: ./content/docs/guides/app-deploy/troubleshoot.en.mdx
meta: {
"title": "Troubleshooting",
"keywords": [
"App Deploy troubleshooting",
"app not running",
"public URL issue",
"custom domain TLS",
"Sealos"
],
"description": "Find the right App Deploy recovery path when a deploy does not become healthy, the public URL does not open, or a custom domain has TLS issues."
}
Use this page when a deploy or public endpoint failed and you need the shortest recovery path.
This is the App Deploy troubleshooting router. It helps you pick the right symptom page. It is not the normal onboarding path for a first successful deploy.
## App Does Not Reach Running
Use this when the app never becomes `running`, keeps waiting, or fails during startup.
[Go to App Does Not Reach Running](/docs/guides/app-deploy/app-does-not-reach-running/)
## Public URL Does Not Open
Use this when the app is already deployed, but the generated public endpoint still does not load in the browser.
[Go to Public URL Does Not Open](/docs/guides/app-deploy/public-url-does-not-open/)
## Custom Domain and TLS Issues
Use this when the Sealos-generated endpoint works but your custom domain is missing a valid certificate or still shows an insecure connection.
[Go to Custom Domain and TLS Issues](/docs/guides/app-deploy/custom-certificates/)
file: ./content/docs/guides/app-deploy/update-apps.en.mdx
meta: {
"title": "Update and Redeploy",
"keywords": [
"update app",
"redeploy",
"Change",
"Update",
"Sealos"
],
"description": "Reopen a deployed Sealos app, change its settings, and redeploy the new version safely."
}
## When to use this
Use this page when the app already exists and you need to change something without creating a new deployment from scratch.
Typical updates include a new image tag, different resources, changed environment variables, extra ports, or attached storage. This is the standard day-2 path for modifying a running app.
## Before you change this
If the app is stateful or already serving traffic, confirm that the new settings are safe before you redeploy.
A bad image, wrong port, or missing storage path can turn a healthy app into a broken one during the next rollout.
## Update the app
1. Open the app details page for the deployed app.
2. Use the top-right action that reopens the settings. Depending on the current UI, this may be labeled **Update** or **Change**.
3. Modify only the sections you actually need to change.
4. Review image, resources, networking, environment variables, config files, and storage before you submit the redeploy.
5. Save the change so Sealos can redeploy the app with the new configuration.
If you are changing several risky settings at once, record the previous values first so you can roll back quickly.
## Verify
Check the result from the app details page after the redeploy:
* The new instance returns to `running`.
* The app details page reflects the setting you changed.
* The public URL still works if the app is meant to stay externally reachable.
* The app behavior matches the new version or configuration you intended to ship.
If this fails, see [App Does Not Reach Running](/docs/guides/app-deploy/app-does-not-reach-running/).
If the public URL stops working, see [Public URL Does Not Open](/docs/guides/app-deploy/public-url-does-not-open/).
## Related Tasks
* [Environment Variables](/docs/guides/app-deploy/environments/) if the change is mainly runtime key-value configuration.
* [Config Files](/docs/guides/app-deploy/configmap/) if the change belongs in a mounted config file instead of the image or basic form fields.
file: ./content/docs/guides/app-store/index.en.mdx
meta: {
"title": "App Store",
"description": "The App Store is a feature in the Sealos cloud operating system for managing application installation, updates, deletion, and other operations."
}
The [App Store](https://sealos.io/products/app-store) provides a collection of ready-to-use application templates that enable rapid deployment of websites and applications. These templates span blogs, AI applications, low-code platforms, cloud storage, instant messaging tools, middleware, and more—designed to streamline development by eliminating the need to build projects from scratch or manually manage application dependencies.
## Submitting an App
All applications in the Sealos App Store are synchronized in real-time from the following GitHub repository:
import { Github } from 'lucide-react';
<Cards>
<Card icon={<Github />} href="https://github.com/labring-actions/templates" title="Sealos Application Repository">
All applications in the Sealos App Store are sourced from this repository
</Card>
</Cards>
To submit an application to the Sealos App Store, simply open a Pull Request (PR) in the [Sealas Application Repository](https://github.com/labring-actions/templates).
For new application submissions, refer to the [template.yaml file](https://github.com/labring-actions/templates/blob/main/template.yaml) as a starting point. The system includes numerous built-in environment variables and functions available for use in templates. These features enable you to write templates using GitHub Actions-style syntax—for example, setting template parameters with environment variables like `${{SEALOS_NAMESPACE}}`. For detailed information about built-in environment variables, consult the [Template Documentation](https://github.com/labring-actions/templates/blob/main/example_zh.md).
If you're unfamiliar with writing YAML application templates, you can also submit an Issue in the [Issues section](https://github.com/labring-actions/templates/issues) describing the application you'd like to add. Our maintenance team will help you prepare and submit the application template. When creating an Issue, please include as much detail as possible:
* Application name and brief description
* Official website or GitHub repository URL
* Deployment requirements (e.g., required environment variables, storage needs, etc.)
* Any other relevant information
This helps us better understand your requirements and accelerates the template creation process.
file: ./content/docs/guides/cronjob/delete-cronjob.en.mdx
meta: {
"title": "Delete a CronJob",
"keywords": [
"CronJob",
"delete CronJob",
"Sealos",
"future scheduled runs"
],
"description": "Remove an existing CronJob in Sealos when you no longer need it and stop future scheduled runs from starting again."
}
Use this page when a CronJob already exists and you need to remove it fully.
This is the delete task page for an existing CronJob in Sealos.
Keep this page focused on removing the CronJob and verifying that future
scheduled runs stopped.
## When to use this
Use this page when you are sure the CronJob should no longer stay available in
Sealos.
This is the right path when you do not want to keep the current CronJob for
later edits or a later resume action.
Typical reasons include removing an outdated schedule, deleting a test CronJob
after validation, or cleaning up a task that should never run again.
## Before you delete this
Deleting the CronJob stops future scheduled runs.
This action should remove the saved CronJob from the relevant Sealos view.
If you may need the CronJob again later, consider updating it or pausing it
instead of deleting it now.
Before you confirm the delete action, make sure you are removing the correct
CronJob and that you no longer need its future schedule.
## Delete the CronJob
1. Open the existing CronJob from the CronJob list or details page in Sealos.
2. Choose the delete or remove action for that CronJob.
3. Review the CronJob name and visible details so you are deleting the correct
item.
4. Confirm the delete action in Sealos.
5. Wait for the list or details view to refresh after the delete completes.
After deletion, the CronJob should no longer remain available for normal
lifecycle actions in Sealos.
## Verify
Use both checks below before you treat the deletion as complete:
* Confirm the CronJob is gone from the relevant Sealos list or detail view.
* Keep watching through the next expected schedule interval and confirm the
next expected scheduled run does not appear afterward.
The deletion is only complete when the CronJob is no longer visible and future
scheduled runs stop.
## Related Tasks
* [Update a CronJob](/docs/guides/cronjob/update-cronjob/) if you only need to
change future behavior instead of removing the CronJob.
* [Pause or Resume a CronJob](/docs/guides/cronjob/pause-resume-cronjob/) if
you want to stop future scheduled runs temporarily instead of deleting the
CronJob.
* [Create Your First CronJob](/docs/guides/cronjob/first-cronjob/) if you need
the fixed first-success walkthrough again.
file: ./content/docs/guides/cronjob/first-cronjob.en.mdx
meta: {
"title": "Create Your First CronJob",
"keywords": [
"CronJob",
"scheduled task",
"visit a URL",
"Webhook.site",
"Sealos",
"first CronJob"
],
"description": "Create your first CronJob on Sealos with one fixed visit a URL walkthrough that uses Webhook.site and exact field values."
}
This is the canonical zero-to-one `CronJob (scheduled task)` tutorial for
Sealos.
Follow this page when you want one fixed first-success path instead of choosing
among different task types.
By the end of this guide, you will create one `visit a URL` task that calls a
unique `https://webhook.site` URL and stays easy to repeat with the same exact
setup pattern.
## Before You Begin
Use this tutorial if all of the following are true:
* You can sign in to the Sealos console.
* You can open `https://webhook.site` in another browser tab.
* You will use the task type `visit a URL`.
* You will use one copy-paste schedule value: `*/5 * * * *`.
Keep this first run narrow.
The goal is to complete one visible success case with the exact values in this
page, not to explore every CronJob option on the first pass.
## What You Will Configure
This tutorial uses one fixed setup so you do not have to choose values while
you are learning the basic Sealos flow.
Open `Webhook.site`, keep the generated target page available, and use the
exact values below in the Sealos form.
| Field | Value |
| ------------ | -------------------------------------------------- |
| CronJob name | `first-cronjob-url-check` |
| Task type | `visit a URL` |
| Target URL | `the unique URL generated by https://webhook.site` |
| Schedule | `*/5 * * * *` |
The name, task type, and schedule stay fixed for this walkthrough.
The only value you generate during setup is the unique URL from `Webhook.site`.
## Create the CronJob
1. Open `https://webhook.site` in a browser tab.
Let the page generate a unique URL for you.
Keep that page open so you can copy the exact target URL into Sealos.
2. Sign in to the Sealos console.
Start from the workspace where you want this CronJob to run.
3. Open the CronJob module.
Stay on the CronJob surface for the full setup so the flow remains simple
and consistent with this tutorial.
4. Click the action that adds or creates a CronJob.
Wait for the creation form to open before you start entering values.
5. Set the CronJob name to `first-cronjob-url-check`.
Use this exact name so it is easy to recognize later in the CronJob list.
6. Choose the task type `visit a URL`.
For this first-success path, do not choose `run a command`.
For this first-success path, do not choose `scale an app`.
7. Paste the unique `Webhook.site` URL into the target URL field.
Use the exact URL from the open `https://webhook.site` page so the request
later arrives at the page you are already watching.
8. Paste the schedule `*/5 * * * *` into the schedule or Cron expression field.
Keep this exact value for your first run so you can copy and paste one known
schedule instead of inventing a new one.
9. Review the form and save or deploy the CronJob.
After you submit it, keep the same `Webhook.site` page open because the next
phase of this tutorial uses that page to confirm the request arrived.
This page gives you one exact setup path.
Once the CronJob is created, continue with the later verification guidance for
checking that Sealos recorded the run and that `Webhook.site` received it.
## How the Schedule Works
The schedule `*/5 * * * *` means this CronJob is scheduled to run every 5
minutes.
For this guide, wait for the next run to appear in Sealos instead of expecting
an exact-second execution time.
This page is not a full Cron expression reference.
## Verify the CronJob
Use both checks below before you call the first run successful:
* [ ] In Sealos, wait for the next run to appear and confirm a new run or
history entry shows for `first-cronjob-url-check`.
* [ ] In Webhook.site, confirm a request appears for the unique URL you
configured.
The request timestamp should be later than the time you created or saved the
CronJob.
Do not treat Sealos history alone as full proof for this `visit a URL`
tutorial.
## Success
You completed your first CronJob run and verified that the request arrived.
## Next Steps
* [Update a CronJob](/docs/guides/cronjob/update-cronjob/) when the CronJob
already exists and you need to change future behavior.
* [Pause or Resume a CronJob](/docs/guides/cronjob/pause-resume-cronjob/) when
you need to stop future scheduled runs temporarily and allow them again
later.
* [Delete a CronJob](/docs/guides/cronjob/delete-cronjob/) when you no longer
need the CronJob and want to stop future scheduled runs completely.
* Reuse the same workflow with a new Webhook.site URL if you want to repeat
the first-success check.
file: ./content/docs/guides/cronjob/index.en.mdx
meta: {
"title": "CronJob",
"keywords": [
"CronJob",
"scheduled task",
"visit a URL",
"Sealos",
"first CronJob",
"start here"
],
"description": "Choose the right CronJob path in Sealos, starting with one clear first-success tutorial for a scheduled task."
}
CronJob (scheduled task) is the Sealos guide surface for creating, checking,
and later managing recurring jobs.
This page helps you choose the right path in Sealos without turning the section
root into the full tutorial.
The current English guide starts with one fixed first-success path.
## Start Here
Start here if you want the shortest path from zero to one verified CronJob
success.
[Start First CronJob](/docs/guides/cronjob/first-cronjob/)
This is the shortest path from zero to one verified CronJob success.
## Other Paths
### Manage an existing CronJob
Use this path when you already have a CronJob and need to update, pause,
resume, or delete it.
* [Update a CronJob](/docs/guides/cronjob/update-cronjob/)
* [Pause or Resume a CronJob](/docs/guides/cronjob/pause-resume-cronjob/)
* [Delete a CronJob](/docs/guides/cronjob/delete-cronjob/)
### Troubleshoot CronJob problems
Use this path when a CronJob did not run, produced the wrong result, or failed
after triggering; this English path arrives later in this guide surface.
file: ./content/docs/guides/cronjob/pause-resume-cronjob.en.mdx
meta: {
"title": "Pause or Resume a CronJob",
"keywords": [
"CronJob",
"pause CronJob",
"resume CronJob",
"Sealos"
],
"description": "Temporarily stop future scheduled runs for an existing CronJob in Sealos and allow them again later when you are ready."
}
Use this page when a CronJob already exists and you need to temporarily stop
future scheduled runs and allow them again later.
This is the lifecycle control page for an existing CronJob in Sealos.
Keep this page focused on state control for an existing CronJob, not on
troubleshooting or reference details.
## When to use this
Use this page when you want to pause scheduled starts without deleting the
CronJob or replacing it with a new one.
This is useful when you want a temporary stop during maintenance, testing, or
any period when future scheduled runs should not begin.
Keep the goal narrow.
You only need to open the existing CronJob, change its running state, and then
verify the visible outcome in Sealos.
## Pause the CronJob
1. Open the existing CronJob from the CronJob list or details page.
2. Choose the pause or suspend action for that CronJob.
3. Review the action so you are pausing the correct CronJob.
4. Confirm the change in Sealos.
After the change is saved, the CronJob should show a paused state or another
clear suspended state in the UI.
While paused, no new scheduled runs should start.
Pausing is a future-run control.
It should stop new scheduled starts while the CronJob stays paused, without
rewriting earlier run history.
## Resume the CronJob
1. Reopen the same CronJob in Sealos.
2. Choose the resume or unsuspend action.
3. Confirm the change so Sealos allows scheduling again.
In practice, after you resume, scheduling can continue again and a later run
can appear again after resume.
Verify the real timeline in Sealos and do not assume exact timing for the next
run or exact next-slot behavior.
## Verify
Use both checks below before you treat the state change as complete:
* Confirm the CronJob shows the paused state after you pause it.
* Keep it paused over a normal schedule interval and confirm that no new scheduled run appears while it remains paused.
* Resume the CronJob and confirm the state changes back from the paused state
to the normal active state in Sealos.
* After resume, verify that a later run can appear again after resume.
Always verify the real timeline in Sealos and do not assume exact timing.
## Related Tasks
* [Update a CronJob](/docs/guides/cronjob/update-cronjob/) if you need to
change future behavior instead of only changing the running state.
* [Create Your First CronJob](/docs/guides/cronjob/first-cronjob/) if you need
the fixed first-success walkthrough.
* [CronJob](/docs/guides/cronjob/) if you want to return to the section router
and choose another CronJob path.
file: ./content/docs/guides/cronjob/update-cronjob.en.mdx
meta: {
"title": "Update a CronJob",
"keywords": [
"CronJob",
"update CronJob",
"future runs",
"Sealos"
],
"description": "Reopen an existing CronJob in Sealos and change future behavior safely without rewriting work that already started."
}
Use this page when a CronJob already exists and you need to change it without
creating a replacement from scratch.
This is the default edit entry point for an existing CronJob in Sealos.
This page is not a continuation of the fixed `visit a URL` walkthrough. Use it
for any existing CronJob you need to change, no matter which task type you set
up earlier.
## When to use this
Use this page when the CronJob already exists and you need to adjust the
schedule, target, task type, or other saved settings.
Typical changes include switching to a different target URL or command,
changing the schedule, or correcting values after the first setup.
Keep this page task-focused.
You only need enough detail to reopen the current CronJob, change the fields
that matter, and save a clean update.
## Before you change this
Changes affect future runs.
They do not rewrite a Job that already started, is currently running, or
already finished.
If you are changing several risky fields at once, note the previous values
first so you can compare the saved configuration after the edit.
## Update the CronJob
1. Open the existing CronJob from the CronJob list or details page.
2. Use the action that reopens the edit or change form for that CronJob.
3. Modify only the settings you actually need to change.
4. Review the task type, target, schedule, and any other changed fields before
you save.
5. Save the CronJob so Sealos records the new configuration for future runs.
You may see different editable fields depending on the task type, but this page
is not a field-by-field reference.
Focus on the values that changed and confirm they still describe the behavior
you want the CronJob to use the next time it is scheduled to run.
## Verify
Use both checks below before you treat the update as complete:
* First, confirm the saved configuration changed in the CronJob details page
or list view.
* Second, wait for the next future run and confirm that run reflects the new
configuration or target behavior.
Do not treat a saved form alone as full success.
The update is only complete when the next future run shows the change you
intended to make.
## Related Tasks
* [Create Your First CronJob](/docs/guides/cronjob/first-cronjob/) if you need
the fixed first-success `visit a URL` walkthrough.
* [CronJob](/docs/guides/cronjob/) if you want to return to the section router
and choose another CronJob path.
file: ./content/docs/guides/databases/database-migration-guide.en.mdx
meta: {
"title": "Database Migration Guide",
"description": "Your first document"
}
file: ./content/docs/guides/devbox/create-a-project.en.mdx
meta: {
"title": "Create a Project",
"description": "Learn how to create a new project using Sealos DevBox with AI assistance"
}
import { AppDashboardLink } from '@/components/docs/Links';
This guide will walk you through the steps to create a new project(development environment) using Sealos DevBox. With AI-powered project creation, you can simply describe what you want to build, and Sealos will automatically set up your development environment.
## Access Sealos DevBox
1. Sign up for [Sealos](https://os.sealos.io/signin) if you haven't yet.
2. In the [Sealos Dashboard](https://os.sealos.io/?openapp=system-brain%3Ftrial%3Dtrue), simply describe your requirements, and Sealos will automatically configure your development environment.
## Create a New Project
<div className="fd-steps [&_h4]:fd-step">
<h4>Describe Your Requirements</h4>
In the [Sealos Dashboard](https://os.sealos.io/?openapp=system-brain%3Ftrial%3Dtrue), describe what you want to build. For example:
* "I want to create a Go app"
* "Create a Python Flask API project"
* "Set up a Next.js web application"
Sealos will understand your intent and generate a development environment card with the recommended configuration.
<h4>Review the Development Environment Card</h4>
After you describe your requirements, Sealos will present a development environment card with the recommended configuration, including:
* **Name**: A suggested project name based on your description
* **Runtime**: The appropriate framework or language version (e.g., Go 1.23, Python 3.11, Next.js)
<h4>Customize or Deploy</h4>
You have two options:
* **Edit**: Click the "Edit" button to customize the project name or port settings
* **Deploy**: Click the "Deploy" button to create the development environment with the recommended settings
<h4>Access Your Project</h4>
Once deployed, Sealos will automatically provision your development environment and start the development server. You can:
* **Preview your application**: Click on the public URL link to view your running application in the browser
* **Connect via IDE**: Use the Cursor or VS Code integration to start coding immediately
</div>
## What Happens Next?
After your project is created, you'll have a fully configured development environment ready to use. The setup includes:
1. A running development server
2. A public URL for previewing your application
3. Pre-configured build and development scripts
Your project will appear in the Project List, where you can manage, pause, or modify it at any time.
## Next Steps
With your project created, you're ready to start developing. The next step is to connect to your project using an IDE and begin building your application. Refer to the "[Develop](./develop)" guide for detailed instructions on how to connect and start coding.
file: ./content/docs/guides/devbox/deploy.en.mdx
meta: {
"title": "Deploy",
"description": "Learn how to deploy your project from Sealos development environment directly to Sealos Cloud"
}
After releasing your application as an OCI image, you can deploy it directly to Sealos Cloud for production use with just a few clicks.
## Deploy Your Release
<div className="fd-steps [&_h4]:fd-step">
<h4>Access the Projects</h4>
Navigate to the Projects in your [Sealos Dashboard](https://os.sealos.io/?openapp=system-brain%3Ftrial%3Dtrue).
<h4>Open the Releases Panel</h4>
* Find your project in the Projects list and click on the project card to enter the project canvas.
* Click on the DevBox card to open the detail panel.
* In the detail panel, click the **Releases** tab.
* Find the release you want to deploy and click the **Deploy** button on the right side of the release row.
<h4>Add a New Deployment</h4>
A **Deploy to...** modal will appear. Click the **+ Add new deployment** button. The system will automatically start deploying your release with default configurations.
<h4>Wait for Deployment to Complete</h4>
Navigate back to your project canvas. You'll see the DevBox card connected to the newly deployed app instance with a dashed line indicating the version deployed (e.g., v1). Wait until the status changes to **Running**.
</div>
## View and Adjust Your Deployment
Once the deployment is complete, you can view and adjust your deployment settings.
<div className="fd-steps [&_h4]:fd-step">
<h4>Open the Detail Panel</h4>
Click on the app card in the project canvas to open the detail panel.
<h4>Adjust Deployment Settings (Optional)</h4>
In the detail panel, you can click on different buttons to modify the corresponding settings:
| Button | Description |
| ------------------- | ------------------------------------------------------------------------------------- |
| **CPU / Memory** | Adjust CPU cores and memory allocation |
| **Mode / Replicas** | Change deployment mode and scale the number of instances |
| **Network** | Configure port mappings and network settings |
| **Advanced** | Access additional configuration options like environment variables, volumes, and more |
<h4>Access Your Deployed Application</h4>
Click on the public URL shown at the top of the app card to access your deployed application in a new browser tab.
</div>
<Callout type="info">
Remember that you can always update your application by creating a new release
in DevBox and repeating this deployment process with the new version using app.
</Callout>
## Conclusion
You've successfully deployed your application from DevBox to Sealos Cloud. The entire workflow—from development to production—happens seamlessly within Sealos:
1. **Develop** in your cloud development environment
2. **Release** your code as an OCI image
3. **Deploy** directly to production with one click
Your deployed application is now running and accessible via its public URL. You can scale, update configurations, or redeploy new versions at any time from the project canvas.
file: ./content/docs/guides/devbox/develop.en.mdx
meta: {
"title": "Develop",
"description": "Learn how to develop your project using Sealos DevBox and Cursor IDE"
}
After creating your DevBox project in Sealos, you're ready to start development. This guide will walk you through the process of connecting to your development environment using Cursor IDE and running your application.
## Connect to Your Development Environment
<div className="fd-steps [&_h4]:fd-step">
<h4>Access the Projects</h4>
Navigate to the Projects in your [Sealos Dashboard](https://os.sealos.io/?openapp=system-brain%3Ftrial%3Dtrue).
<h4>Connect with Cursor IDE</h4>
* Find your project in the Projects and click on the project card to enter the project canvas.
* Click on the DevBox card to open the detail panel.
* In the detail panel, click the dropdown arrow (▾) next to the IDE icon in the top-right corner.
* From the dropdown menu, select your preferred IDE (e.g., Cursor, VSCode, or Kiro).
<h4>Install the DevBox Plugin</h4>
* When you click on "Cursor", it will launch the Cursor IDE application on your local machine.
* A popup window will appear in Cursor, prompting you to install the DevBox plugin.
* Follow the instructions in the Cursor popup to install the DevBox plugin.
* Once installed, Cursor will establish a remote connection to your DevBox runtime.
</div>
<Callout type="info">
You can switch between different IDE options (VSCode, Cursor, or Kiro) at any time by using the dropdown menu in the detail panel.
</Callout>
## Develop
Once connected, you'll be able to access and edit your project files directly within the Cursor IDE environment.
This remote connection offers several benefits:
* Your code runs in the DevBox runtime, ensuring consistency across development and production environments.
* You can access your project from anywhere, on any device with Cursor installed.
* Collaboration becomes easier as team members can connect to the same DevBox runtime.
## Run Your Application
<div className="fd-steps [&_h4]:fd-step">
<h4>Open the Terminal</h4>
Open the terminal within Cursor IDE.
<h4>Navigate to Your Project Directory</h4>
If you're not already there, navigate to your project directory.
<h4>Start Your Development Server</h4>
Run the appropriate command to start your development server. For example, if you're using Next.js:
```bash
npm run dev
```
This command will start your application in development mode.
</div>
## Access Your Running Application
In the project canvas, you'll see the public URL card connected to your DevBox card. Simply click on the URL card to open your running application in a new browser tab.
<div style={{maxWidth: '300px'}}>
</div>
## Next Steps
As you continue developing your project, your next step is to configure how your application starts. Check out the [Entry Point](./entrypoint-sh) guide to learn how to set up `entrypoint.sh` for your application.
Once your entry point is configured, you can proceed to [Release](./release) your application as an OCI image, and then [Deploy](./deploy) it to production.
file: ./content/docs/guides/devbox/entrypoint-sh.en.mdx
meta: {
"title": "Entry Point",
"description": "Learn how to configure startup commands for your DevBox project"
}
In Sealos DevBox, `entrypoint.sh` is a special script file that defines how your application starts after deployment. This guide will help you understand how to properly configure this file to ensure your application starts and runs correctly in the deployment environment.
## What is entrypoint.sh
In a DevBox project, `entrypoint.sh` is your application's entry point that:
* Defines the startup command for your application
* Executes automatically after application deployment
* Ensures your application starts correctly
* Serves as a key component when publishing your project as an OCI image
<Callout type="warn">
`entrypoint.sh` should only be responsible for starting your application, not building it. All build steps should be completed in the development environment.
</Callout>
## Building in the Development Environment
Before configuring `entrypoint.sh`, complete your application build in the development environment. This approach:
* Reduces application startup time
* Avoids installing build dependencies in production
* Ensures you're deploying verified build artifacts
<div className="fd-steps [&_h4]:fd-step">
<h4>Build Your Application</h4>
Execute the build in your development environment:
```bash
# Next.js app
npm run build # generates .next directory
# TypeScript app
npm run build # generates dist directory
# Go app
go build -o main # generates executable
```
<h4>Verify Build Results</h4>
Confirm your build artifacts were generated correctly:
```bash
# Check build directory
ls -l dist/ # or .next/, build/, etc.
# Test build artifacts
node dist/main.js # or other startup command
```
<h4>Configure Startup Command</h4>
Configure `entrypoint.sh` based on your build artifacts:
```bash title="entrypoint.sh"
#!/bin/bash
# Next.js
NODE_ENV=production node .next/standalone/server.js
# TypeScript Node.js
node dist/main.js
# Go
./main
```
</div>
## Common Configuration Scenarios
### Pre-built Web Applications
```bash title="entrypoint.sh"
#!/bin/bash
# Next.js (pre-built)
NODE_ENV=production node .next/standalone/server.js
# Vue (pre-built)
node server/index.js
# React (pre-built)
serve -s build -l 3000
```
### Compiled Backend Services
```bash title="entrypoint.sh"
#!/bin/bash
# Go (compiled)
./main
# Java (packaged)
java -jar app.jar
# Rust (compiled)
./server
```
### Interpreted Backend Services
```bash title="entrypoint.sh"
#!/bin/bash
# Python
python app.py
# Node.js (pre-built)
node dist/index.js
# PHP
php -S 0.0.0.0:8000
```
## Best Practices
<div className="fd-steps [&_h4]:fd-step">
<h4>Ensure Pre-building</h4>
* Complete all build steps in the development environment
* Verify the integrity of build artifacts
* Test that the built application starts correctly
<h4>Use the Correct Port</h4>
Ensure your application listens on the correct port:
* Use the port from environment variables (if available)
* If manually specified, use standard ports (like 3000, 8080, etc.)
* Make sure to listen on 0.0.0.0 rather than localhost
<h4>Handle Environment Variables</h4>
If your application depends on environment variables:
* Configure environment variables during deployment via the Application Management interface
* Don't hardcode sensitive information in `entrypoint.sh`
</div>
<Callout type="warn">
Don't add background processes or daemons in entrypoint.sh. If you need to run multiple services, create and deploy separate DevBox projects for each.
</Callout>
## Common Issues
### Build-related Problems
If you encounter build-related issues:
1. Ensure all build steps are completed in the development environment
2. Check that build artifacts are complete
3. Verify runtime dependencies for your build artifacts
### Startup Failures
If your application fails to start:
1. Check if the startup command points to the correct build artifacts
2. Confirm all required environment variables are configured
3. Review application logs for detailed error information
### Permission Issues
If you encounter permission errors:
* Ensure `entrypoint.sh` has execution permissions:
```bash
chmod +x entrypoint.sh
```
* Check if the permissions for build artifacts are correct
## Testing and Validation
Before publishing your application:
1. Complete the build in the development environment
2. Test the build artifacts
3. Verify that `entrypoint.sh` starts your application correctly:
```bash
./entrypoint.sh
```
## Next Steps
After completing your application build and configuring `entrypoint.sh`, you're ready to [publish](./release) your application. During the publishing process:
1. Ensure all build artifacts are correctly generated
2. The system will use your configured `entrypoint.sh` as the application's startup entry point
3. After publishing is complete, during the [deployment](./deploy) phase, your application will start according to the method defined in `entrypoint.sh`
file: ./content/docs/guides/devbox/index.en.mdx
meta: {
"title": "DevBox",
"index": true,
"description": "Orient yourself to Sealos DevBox and the end-to-end workflow from project creation through deployment"
}
DevBox is Sealos's fully managed cloud development environment built on Kubernetes. It delivers production-ready runtimes you can reach from Cursor, VS Code, JetBrains Gateway, or a browser terminal—no local setup or infrastructure to maintain.
Use this overview to understand how DevBox fits together and jump into the detailed guides.
## Why DevBox
* SaaS, zero-ops: sign in, describe what you want, and start coding while Sealos handles orchestration, scaling, and networking.
* Works with your IDE: connect via SSH from Cursor, VS Code, or JetBrains, or use the built-in terminal for quick fixes.
* Faster, consistent builds: server-grade resources with dev/prod parity reduce "works on my machine" issues.
* Integrated shipping path: release OCI images directly from your runtime and deploy to Sealos Cloud with one click.
* Predictable pricing: fixed-resource subscription tiers keep costs clear.
## Core Components
| Component | Purpose |
| --------------- | ----------------------------------------------------------------------------------------------------- |
| Project | The unit that tracks everything your app needs—runtime, dependencies, and configuration—in one place. |
| Dev environment | A cloud runtime with CPU, memory, and storage that you access through your preferred IDE. |
| `entrypoint.sh` | The startup script your release uses to boot the built application. |
| Release | A versioned OCI image built from your project, ready for deployment or rollback. |
| Deploy | A running app instance on Sealos Cloud created from a chosen release. |
| Template Market | Shared or private templates that standardize DevBox runtimes for fast reuse. |
## End-to-End Flow
1. [Intro](./intro): See what DevBox is, who it's for, and how it differs from other CDEs.
2. [Create a project](./create-a-project): Describe what you want to build or pick a template; Sealos provisions a DevBox runtime with the right language/framework.
3. [Develop](./develop): Connect from Cursor/VS Code/JetBrains, code against the remote runtime, run your dev server, and preview via the public URL.
4. [Configure `entrypoint.sh`](./entrypoint-sh): After building in the dev environment, set the exact startup command your release will run (no build steps here).
5. [Release](./release): Open the Releases tab, tag a version, add notes, and let DevBox build an OCI image from your project.
6. [Deploy](./deploy): Click Deploy on a release to spin up an app on Sealos Cloud, adjust CPU/memory/ports, and launch via the public URL.
7. [Template Market](./template-market): Turn proven versions into reusable templates or start new runtimes from community and private templates.
By following these guides you'll move from zero to a running production deployment entirely within DevBox—without managing infrastructure or piecing together a separate CI/CD chain.
file: ./content/docs/guides/devbox/intro.en.mdx
meta: {
"title": "What is DevBox?",
"keywords": [
"Sealos",
"cloud platform",
"Kubernetes",
"cloud development environment",
"DevBox",
"managed databases",
"app store",
"multi-tenancy",
"AI deployment",
"container platform"
],
"description": "DevBox is a fully-managed cloud development environment that works with any IDE, runtime, and framework—eliminating local setup and environment drift."
}
DevBox is a fully-managed cloud development environment built on Kubernetes. It provides consistent, production-ready workspaces accessible from any device, through your favorite IDE.
Unlike self-hosted solutions, DevBox is a SaaS offering—no infrastructure to manage. Just sign up, create a project, and start coding in seconds.
## IDE Support
Connect with the tools you already use:
* **Desktop IDEs**
* [Cursor](https://cursor.sh/) – AI-powered coding with remote DevBox connection
* [VS Code](https://code.visualstudio.com/docs/remote/ssh) – Full remote development via SSH
* [JetBrains Gateway](https://www.jetbrains.com/remote-development/gateway/) – IntelliJ, GoLand, PyCharm, WebStorm, and more
* And others
* **Browser-based access**
* Web terminal for quick fixes
* SSH access from any terminal client
## Why Remote Development?
Remote development offers significant benefits for both individual developers and teams:
* **Faster performance**
* Server-grade hardware accelerates builds, tests, and heavy workloads like monorepos or AI model training.
* **Consistent environments**
* Every developer gets the exact same setup—no more "works on my machine" debugging.
* **Dev/prod parity**
* Development containers mirror production, reducing deployment surprises.
* **Enhanced security**
* Source code stays on cloud infrastructure, not scattered across developer laptops.
* **Work from anywhere**
* Access your full development environment from any device with an internet connection.
Explore how leading engineering teams are adopting cloud development environments on [our blog](/blog), the [Slack engineering blog](https://slack.engineering/development-environments-at-slack), or [from OpenFaaS's Alex Ellis](https://blog.alexellis.io/the-internet-is-my-computer/).
## Why DevBox?
DevBox differentiates itself from other cloud development platforms in several ways:
| Feature | DevBox | Traditional CDEs |
| ------------------------- | ------------------------- | --------------------------- |
| Setup time | Seconds | Minutes to hours |
| Infrastructure management | Fully managed | Often self-hosted |
| Runtime options | 20+ pre-configured | Limited or BYO |
| Deployment | One-click to Sealos Cloud | Separate CI/CD required |
| Pricing | Simple subscription plans | Complex pay-per-use billing |
Key advantages:
* **Zero infrastructure overhead** – No Kubernetes expertise required. DevBox handles orchestration, scaling, and networking.
* **Integrated deployment pipeline** – Release as OCI images and deploy directly to Sealos Cloud with one click.
* **Predictable pricing** – Simple monthly subscriptions with fixed resources. No surprise bills.
* **Template marketplace** – Start from community templates or convert your projects into reusable templates.
## How Much Does It Cost?
Sealos uses simple subscription pricing with four tiers:
| Plan | Price | Resources |
| ------- | ------------ | ------------------------------ |
| Starter | $7/month | 2 vCPU, 2Gi RAM, 1Gi Disk |
| Hobby | $25/month | 4 vCPU, 4Gi RAM, 10Gi Disk |
| Pro | $512/month | 16 vCPU, 32Gi RAM, 200Gi Disk |
| Team | $2,030/month | 64 vCPU, 128Gi RAM, 500Gi Disk |
No complex metering, no surprise bills. View the [pricing page](/pricing) for full details.
## How Does DevBox Work?
1. **Create a project** – Choose from 20+ pre-configured runtimes (Node.js, Python, Go, Java, Rust, etc.)
2. **Connect your IDE** – One-click connection from Cursor, VS Code, or JetBrains
3. **Develop** – Code in a cloud environment with production-grade resources
4. **Release** – Package your application as an OCI image with semantic versioning
5. **Deploy** – Push to Sealos Cloud with a single click
Your workspace persists between sessions. Stop and resume anytime without losing state.
## What DevBox Is Not
* **DevBox is not a local development tool**
* Your code runs in the cloud, not on your machine. You need internet connectivity.
* **DevBox is not a CI/CD platform**
* While you can build and deploy from DevBox, it's optimized for interactive development, not automated pipelines.
* **DevBox is not self-hosted**
* DevBox is a managed service on Sealos Cloud. For self-hosted solutions, consider [Coder](https://coder.com/) or [Gitpod](https://gitpod.io/).
* **DevBox is not just an online IDE**
* It's a full development environment. Connect your preferred local IDE via SSH—no browser required.
## Who Is DevBox For?
* **Solo developers** who want to code from any device without environment setup
* **Teams** that need consistent development environments across members
* **Startups** looking to ship faster without infrastructure overhead
* **Agencies** managing multiple client projects with different tech stacks
* **Educators** providing students with instant, reproducible dev environments
## Up Next
<Cards>
<Card href="./create-a-project" title="Create a Project">
Set up your first cloud development environment in under 2 minutes.
</Card>
<Card href="./develop" title="Start Developing">
Connect your IDE and start coding.
</Card>
<Card href="./release" title="Release Your App">
Package your application as an OCI image.
</Card>
<Card href="./deploy" title="Deploy to Cloud">
Go live with one-click deployment.
</Card>
</Cards>
file: ./content/docs/guides/devbox/release.en.mdx
meta: {
"title": "Release",
"description": "Learn how to release your project using Sealos DevBox"
}
After you've developed and tested your application, the next step is to release it as an OCI (Open Container Initiative) image. This process allows you to version your application and prepare it for deployment.
## Prepare Your Application for Release
<div className="fd-steps [&_h4]:fd-step">
<h4>Open the Terminal in Cursor IDE</h4>
In the Cursor IDE terminal, navigate to your project directory if you're not already there.
<h4>Prepare Your Application (if necessary)</h4>
Depending on your project's language or framework, you may need to prepare your application for release. This step varies widely between different technologies:
* For compiled languages (e.g., Java, Go):
Run your build command (e.g., `mvn package`, `go build`)
* For interpreted languages with build steps (e.g., TypeScript, some JavaScript frameworks):
Run your build or transpilation command (e.g., `npm run build`, `tsc`)
* For interpreted languages without build steps (e.g., Python, Ruby):
Ensure all dependencies are listed in your requirements file (e.g., `requirements.txt`, `Gemfile`)
If your project doesn't require any preparation, you can skip this step.
<h4>Review and Update entrypoint.sh</h4>
Each DevBox project has an `entrypoint.sh` file that defines the startup command for your OCI image. Before releasing, ensure this file correctly starts your application.
<Callout type="info">
The `entrypoint.sh` file is crucial for your application's startup in the OCI image. For detailed configuration instructions, common scenarios, and best practices, see the [Entry Point](./entrypoint-sh) guide.
</Callout>
</div>
## Release as OCI Image
<div className="fd-steps [&_h4]:fd-step">
<h4>Access the Projects</h4>
Navigate to the Projects in your [Sealos Dashboard](https://os.sealos.io/?openapp=system-brain%3Ftrial%3Dtrue).
<h4>Open the Releases Panel</h4>
* Find your project in the Projects list and click on the project card to enter the project canvas.
* Click on the DevBox card to open the detail panel.
* In the detail panel, click the **Releases** tab.
<h4>Add a New Release</h4>
In the Releases panel, click the **+ Add new release** button.
<h4>Configure Release Details</h4>
A new input row will appear. Fill in the following information:
* **Release tag**: Enter a version tag for your release (e.g., v1, v1.0.0).
* **Description**: Provide a brief description of this release (e.g., "Initial release" or "Feature update: user authentication").
Then click the **✓** (checkmark) button on the right side to start building the image.
<h4>Wait for the Build to Complete</h4>
The system will start building your OCI image. You can monitor the build progress in the Releases panel. Once the build is successful, your release will be listed with:
* The tag you assigned
* The creation time
* The release notes you provided
* A **Deploy** button to deploy this version
</div>
## Best Practices for Releasing
1. **Semantic Versioning**: Consider using semantic versioning (e.g., v1.0.0) for your tags. This helps in tracking major, minor, and patch releases.
2. **Descriptive Releases**: Provide clear and concise descriptions for each release. This helps team members understand what changes or features are included in each version.
3. **Regular Releases**: Create new releases whenever you make significant changes or reach important milestones in your project. This practice helps in maintaining a clear history of your application's development.
4. **Pre-release Testing**: Always thoroughly test your application before creating a release. This ensures that the released version is stable and ready for deployment.
5. **Consistent Build Process**: Ensure your build process is consistent and reproducible. Consider using build scripts or Makefiles to standardize the build process across your team.
## Next Steps
After successfully releasing your application as an OCI image, you're ready to move on to the deployment phase. The OCI image you've created can be used for deployment or shared with other team members.
Check out the "Deploy" guide for information on how to deploy your released application to a production environment.
file: ./content/docs/guides/devbox/template-market.en.mdx
meta: {
"title": "DevBox Template Market",
"description": "Create and manage DevBox runtime templates with the Sealos DevBox Template Market"
}
This guide walks you through the Sealos DevBox Template Market—your hub for creating, managing, and deploying DevBox runtime templates.
## What is the DevBox Template Market?
The Template Market transforms how you set up DevBox runtimes. Instead of configuring from scratch every time, you can save your perfectly tuned setups as templates and deploy them instantly whenever needed.
With the Template Market, you can:
* **Launch projects in minutes**: Skip the setup and dive straight into coding with pre-configured runtime templates.
* **Standardize team workflows**: Give your entire team the same optimized runtime, eliminating "works on my machine" issues.
* **Share proven setups**: Turn your battle-tested configurations into templates that benefit other developers.
* **Version your runtimes**: Create different template versions for various project phases or requirements.
Whether you're flying solo or leading a team, the Template Market eliminates repetitive setup tasks and accelerates your development workflow.
The DevBox Template Market offers two template types:
* **Public templates**: Community-shared templates accessible to all users for creating common DevBox runtimes.
* **Private templates**: Your personal templates, visible only to you.
## Creating Templates
<div className="fd-steps [&_h4]:fd-step">
<h4>Select a Version</h4>
1. In the [Sealos Desktop](https://os.sealos.io), click on the "DevBox" icon to enter the DevBox application.
2. Navigate to your project details page and click "Version History"
3. Locate the version you want to convert into a template
4. Click the "More" button (three dots) next to that version
5. Select "Convert to Template"
<h4>Configure Template Details</h4>
Fill out the template creation form:
* **Name**: Choose a descriptive name for your template
* **Version**: Set the template version (e.g., v1.0.0)
* **Public**: Decide who can use your template
* Enable: Available to all users
* Disable: Only you can access it
* **Tags**: Select 1-3 tags to categorize your template
* Use cases (e.g., Blog, Operating System, Tools)
* Programming languages (e.g., Python, Java, Go)
* **Description**: Briefly explain what your template does and when to use it
<h4>Finalize Creation</h4>
Review your settings and click "Create" to publish your template.
</div>
## Creating Environments from Templates
<div className="fd-steps [&_h4]:fd-step">
<h4>Choose a Template</h4>
When creating a new project, browse and select the template that fits your needs
* "All Templates": Browse public community templates
* "My Templates": Access your private templates
<h4>Apply the Template</h4>
After selecting a template:
1. The template appears under the "Runtime" tab
2. Configure additional project parameters (resources, networking, etc.)
3. Complete the standard project creation flow
</div>
## Managing Private Templates
The "My Templates" page lets you:
* View all your private templates
* Launch new runtimes from templates
* Manage existing templates
Note: Once you make a template public, you cannot make it private again.
## Next Steps
With your templates ready, you can:
* Spin up new DevBox runtimes in seconds
* Share public templates with your team
* Create multiple template versions for different use cases
Check out the "[Develop](./develop)" section to learn how to start coding in your newly created runtimes.
file: ./content/docs/k8s/advanced-guide/build-image-using-registry-sync.en.mdx
meta: {
"title": "镜像构建改进指南",
"keywords": [
"Sealos镜像构建",
"镜像缓存",
"registry-proxy",
"skopeo copy",
"镜像仓库同步"
],
"description": "了解Sealos镜像构建的改进指南，提升构建效率，使用registry-proxy和skopeo copy实现镜像仓库同步，优化镜像管理。"
}
file: ./content/docs/k8s/advanced-guide/dual-stack-cluster.en.mdx
meta: {
"title": "使用calico安装双栈集群",
"keywords": [
"双栈集群",
"calico安装",
"sealos",
"Kubernetes",
"IPv6配置",
"Clusterfile",
"k8s双栈",
"网络配置",
"Kubernetes集群",
"Calico双栈"
],
"description": "使用calico安装双栈集群，详细步骤包括生成和编辑Clusterfile，添加IPv6的pod和svc的CIDR范围，确保Kubernetes集群的双栈网络配置。"
}
file: ./content/docs/k8s/advanced-guide/image-build-standardized.en.mdx
meta: {
"title": "镜像构建与标准化目录配置",
"keywords": [
"Sealos镜像构建",
"Kubernetes部署",
"目录结构标准化",
"Kubefile参数",
"容器镜像管理",
"集群初始化",
"应用配置",
"Helm chart",
"环境变量设置",
"镜像仓库配置"
],
"description": "学习Sealos镜像构建的标准化目录配置，掌握Kubefile参数使用，优化Kubernetes部署流程。本指南助您规范化构建过程，提高效率，降低错误率。"
}
file: ./content/docs/k8s/advanced-guide/sealos-run.en.mdx
meta: {
"title": "Sealos Run 的工作原理",
"keywords": [
"Sealos Run",
"Kubernetes集群部署",
"容器编排",
"节点管理",
"镜像分发",
"集群初始化",
"证书管理",
"IPVS规则",
"Kubeadm配置",
"Clusterfile"
],
"description": "深入解析Sealos Run命令的工作原理，包括节点检查、镜像分发、集群初始化等九大步骤，助您轻松部署和管理Kubernetes集群。"
}
file: ./content/docs/k8s/advanced-guide/template-function.en.mdx
meta: {
"title": "模板引入与函数增强",
"keywords": [
"Sealos模板渲染",
"集群镜像构建",
"模板函数增强",
"Kubernetes配置管理",
"动态生成资源清单",
"semverCompare",
"多版本Kubernetes支持",
"镜像构建灵活性"
],
"description": "探索Sealos的模板渲染功能，了解如何在集群镜像构建中动态生成配置、脚本和Kubernetes资源清单，以及如何使用增强的模板函数实现多版本Kubernetes支持。"
}
file: ./content/docs/k8s/quick-start/build-ingress-cluster-image.en.mdx
meta: {
"title": "构建一个 Ingress 集群镜像",
"keywords": [
"Ingress集群镜像",
"sealos",
"helm",
"nginx-ingress",
"镜像缓存代理",
"Dockerfile",
"集群镜像构建",
"镜像列表",
"镜像registry"
],
"description": "学习如何使用sealos和helm构建Ingress集群镜像，包括下载chart、添加镜像列表、编写Dockerfile、构建和推送镜像，以及运行集群镜像的完整流程。"
}
file: ./content/docs/k8s/quick-start/deploy-kubernetes.en.mdx
meta: {
"title": "安装 K8s 集群",
"keywords": [
"Kubernetes安装",
"Sealos",
"K8s集群部署",
"离线安装K8s",
"Containerd",
"集群镜像",
"高可用K8s",
"节点管理"
],
"description": "使用Sealos快速部署Kubernetes集群，支持在线和离线安装，适用于amd64和arm64架构。轻松管理节点，安装分布式应用，支持Containerd和Docker运行时。"
}
file: ./content/docs/k8s/quick-start/install-cli.en.mdx
meta: {
"title": "下载 Sealos 命令行工具",
"keywords": [
"Sealos命令行工具",
"Sealos安装",
"Kubernetes集群部署",
"二进制下载",
"包管理工具安装",
"源码安装",
"版本选择",
"Linux系统"
],
"description": "本文详细介绍了如何下载和安装Sealos命令行工具，包括版本选择、二进制下载、包管理工具安装和源码安装等多种方法，助您快速部署Kubernetes集群。"
}
file: ./content/docs/k8s/reference/image-cri-shim.en.mdx
meta: {
"title": "image-cri-shim 使用指南",
"keywords": [
"image-cri-shim",
"Kubernetes",
"容器运行时",
"CRI",
"kubelet",
"镜像自动识别",
"容器部署",
"中间件",
"镜像仓库"
],
"description": "image-cri-shim 使用指南，简化Kubernetes容器部署，自动识别镜像名称，提高操作便利性，支持CRI API v1alpha2和v1。"
}
file: ./content/docs/k8s/reference/lvscare.en.mdx
meta: {
"title": "LVScare 使用指南",
"keywords": [
"LVScare",
"Sealos",
"Kubernetes高可用性",
"IPVS负载均衡",
"健康检查工具"
],
"description": "LVScare是一款基于IPVS的轻量级负载均衡和健康检查工具，与Sealos集成，提升Kubernetes集群的高可用性和稳定性。"
}
file: ./content/docs/guides/databases/kafka/go.en.mdx
meta: {
"title": "Go",
"description": "Learn how to connect to Kafka in Sealos DevBox using Go"
}
This guide will walk you through the process of connecting to Kafka using Go within your Sealos DevBox project.
## Prerequisites
* [A Sealos DevBox project](/docs/guides/devbox/create-a-project) with Go environment
* [A Kafka cluster created using the Database app in Sealos](./)
## Install Required Packages
In your Cursor terminal, install the necessary packages:
```bash
go get github.com/joho/godotenv
go get github.com/confluentinc/confluent-kafka-go/v2/kafka
```
This command installs:
* `github.com/confluentinc/confluent-kafka-go/v2/kafka`: The Confluent Kafka client for Go
## System Dependencies
The `confluent-kafka-go` package requires `librdkafka` as a system dependency. In Sealos DevBox, you might need to install it manually. Run the following commands in your Cursor terminal:
```bash
sudo apt-get update
sudo apt-get install -y gcc libc6-dev librdkafka-dev
```
## Connection Setup
<div className="fd-steps [&_h4]:fd-step">
#### Set up the environment variables
First, let's set up the environment variables for our Kafka connection. Create a `.env` file in your project root with the following content:
```ini title=".env"
KAFKA_BROKER=your_kafka_host:9092
KAFKA_GROUP_ID=group-id
KAFKA_TOPIC=topic-name
```
Replace the placeholders with your actual Kafka broker address, group ID, and topic name from the Database app in Sealos.
#### Create the main.go file
Create a new file named `main.go` with the following content:
```go title="main.go"
package main
import (
"fmt"
"log"
"os"
"github.com/confluentinc/confluent-kafka-go/v2/kafka"
"github.com/joho/godotenv"
)
var (
broker string
groupId string
topic string
)
func loadEnv() error {
// Load environment variables from .env file
err := godotenv.Load()
if err != nil {
log.Fatal("Error loading .env file")
}
broker = os.Getenv("KAFKA_BROKER")
groupId = os.Getenv("KAFKA_GROUP_ID")
topic = os.Getenv("KAFKA_TOPIC")
return nil
}
func startProducer() {
p, err := kafka.NewProducer(&kafka.ConfigMap{
"bootstrap.servers": broker,
"allow.auto.create.topics": true,
})
if err != nil {
panic(err)
}
go func() {
for e := range p.Events() {
switch ev := e.(type) {
case *kafka.Message:
if ev.TopicPartition.Error != nil {
fmt.Printf("Delivery failed: %v\n", ev.TopicPartition)
} else {
fmt.Printf("Delivered message to %v\n", ev.TopicPartition)
}
}
}
}()
for _, word := range []string{"message 1", "message 2", "message 3"} {
p.Produce(&kafka.Message{
TopicPartition: kafka.TopicPartition{Topic: &topic, Partition: kafka.PartitionAny},
Value: []byte(word),
}, nil)
}
}
func startConsumer() {
c, err := kafka.NewConsumer(&kafka.ConfigMap{
"bootstrap.servers": broker,
"group.id": groupId,
"auto.offset.reset": "earliest",
})
if err != nil {
panic(err)
}
c.Subscribe(topic, nil)
for {
msg, err := c.ReadMessage(-1)
if err == nil {
fmt.Printf("Message on %s: %s\n", msg.TopicPartition, string(msg.Value))
} else {
fmt.Printf("Consumer error: %v (%v)\n", err, msg)
break
}
}
c.Close()
}
func main() {
if err := loadEnv(); err != nil {
fmt.Println(err)
return
}
startProducer()
startConsumer()
}
```
Let's break down the main components of this code:
1. **Imports and Variables**: We import the necessary packages and define global variables for the broker address, group ID, and topic name.
2. **startProducer function**:
* Creates a new Kafka producer
* Uses a goroutine to handle delivery reports
* Produces sample messages to the specified topic
3. **startConsumer function**:
* Creates a new Kafka consumer
* Subscribes to the specified topic
* Continuously reads messages from the topic and prints them
4. **Main function**: Calls both `startProducer()` and `startConsumer()` to demonstrate producing and consuming messages.
</div>
## Usage
To run the application, use the following command in your Cursor terminal:
```bash
go run main.go
```
This will execute the `main` function, demonstrating both producing and consuming messages with Kafka.
## Best Practices
1. In a real-world scenario, separate the producer and consumer into different applications or services.
2. Use environment variables for Kafka configuration instead of hardcoding values.
3. Implement proper error handling and logging.
4. Implement graceful shutdown to properly close Kafka connections.
## Troubleshooting
If you encounter connection issues:
1. Verify your Kafka broker address in the `broker` variable.
2. Ensure your Kafka cluster is running and accessible.
3. Check for any network restrictions in your DevBox environment.
4. Confirm that the required packages and system dependencies are correctly installed.
5. If you encounter `cgo` related errors, make sure you have the necessary build tools installed (`sudo apt-get install build-essential`).
For more detailed information on using Kafka with Go, refer to the [confluent-kafka-go documentation](https://github.com/confluentinc/confluent-kafka-go).
file: ./content/docs/guides/databases/kafka/index.en.mdx
meta: {
"title": "Kafka",
"description": "Deploy and connect to Kafka clusters in Sealos DevBox"
}
Apache Kafka is a distributed event streaming platform that allows you to build real-time data pipelines and streaming applications. In Sealos DevBox, you can easily set up and connect to Kafka clusters for your development projects.
## Deploy Kafka in Sealos
Sealos makes it easy to deploy a Kafka cluster with just a few clicks. Follow these steps:
<div className="fd-steps [&_h5]:fd-step">
<h5>From the Sealos desktop, click on the "Database" icon to open the Database app.</h5>
<h5>Click on the "Create New Database" button. In the deployment form:</h5>
* Select "Kafka" as the database type.
* Choose the desired Kafka version (e.g., kafka-3.3.2).
* Enter a name for your Kafka cluster (use lowercase letters and numbers only).
* Adjust the CPU and Memory sliders to set the resources for your Kafka brokers.
* Set the number of brokers (1 for single-node development and testing, 3 or more for production).
* Specify the storage size for each broker (e.g., 3 Gi).
<h5>Review the projected cost on the left sidebar. Click the "Deploy" button in the top right corner to create your Kafka cluster.</h5>
</div>
Once deployed, Sealos will provide you with the necessary connection details.
## Connect to Kafka in DevBox
Here are examples of how to connect to your Kafka cluster using different programming languages and frameworks within your DevBox environment:
<Cards>
<Card title="Connect to Kafka with Go in Sealos DevBox" href="./kafka/go" />
<Card title="Connect to Kafka with Java in Sealos DevBox" href="./kafka/java" />
<Card title="Connect to Kafka with Node.js in Sealos DevBox" href="./kafka/nodejs" />
<Card title="Connect to Kafka with PHP in Sealos DevBox" href="./kafka/php" />
<Card title="Connect to Kafka with Python in Sealos DevBox" href="./kafka/python" />
<Card title="Connect to Kafka with Rust in Sealos DevBox" href="./kafka/rust" />
</Cards>
file: ./content/docs/guides/databases/kafka/java.en.mdx
meta: {
"title": "Java",
"description": "Learn how to connect to Kafka in Sealos DevBox using Java"
}
This guide will walk you through the process of connecting to Kafka using Java within your Sealos DevBox project.
## Prerequisites
* [A Sealos DevBox project](/docs/guides/devbox/create-a-project) with Java environment
* [A Kafka cluster created using the Database app in Sealos](./)
## Project Setup
<div className="fd-steps [&_h4]:fd-step">
#### Create a new Maven project
In your Sealos DevBox terminal, initialize a new Maven project:
```bash
mvn archetype:generate -DgroupId=com.example -DartifactId=kafka-java-example -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false
mv kafka-java-example/* .
rm -rf kafka-java-example
rm -rf test
```
#### Update pom.xml
Replace the content of your `pom.xml` file with the following:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.example</groupId>
<artifactId>kafka-java-example</artifactId>
<version>1.0-SNAPSHOT</version>
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<maven.compiler.source>11</maven.compiler.source>
<maven.compiler.target>11</maven.compiler.target>
</properties>
<dependencies>
<dependency>
<groupId>org.apache.kafka</groupId>
<artifactId>kafka-clients</artifactId>
<version>3.4.0</version>
</dependency>
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-simple</artifactId>
<version>2.0.5</version>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.8.1</version>
<configuration>
<source>11</source>
<target>11</target>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-shade-plugin</artifactId>
<version>3.2.4</version>
<executions>
<execution>
<phase>package</phase>
<goals>
<goal>shade</goal>
</goals>
<configuration>
<transformers>
<transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
<mainClass>com.example.App</mainClass>
</transformer>
</transformers>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>
```
This `pom.xml` file includes the necessary dependencies (Kafka client and SLF4J for logging) and configures the Maven Shade plugin to create an executable JAR.
#### Create a configuration file
Create a file named `kafka.properties` in the `src/main/resources` directory:
```ini
bootstrap.servers=your_kafka_bootstrap_servers:9092
topic=your_topic_name
group.id=your_consumer_group_id
```
Replace the placeholders with your actual Kafka credentials from the Database app in Sealos.
#### Create Java classes
Create the following Java classes in the `src/main/java/com/example` directory:
1. `KafkaProducerExample.java`:
```java
package com.example;
import org.apache.kafka.clients.producer.*;
import org.apache.kafka.common.serialization.StringSerializer;
import java.io.FileInputStream;
import java.io.IOException;
import java.util.Properties;
public class KafkaProducerExample {
public static void main(String[] args) {
Properties props = loadConfig();
props.put(ProducerConfig.KEY_SERIALIZER_CLASS_CONFIG, StringSerializer.class.getName());
props.put(ProducerConfig.VALUE_SERIALIZER_CLASS_CONFIG, StringSerializer.class.getName());
Producer<String, String> producer = new KafkaProducer<>(props);
String topic = props.getProperty("topic");
String message = "Hello from Sealos DevBox!";
ProducerRecord<String, String> record = new ProducerRecord<>(topic, message);
producer.send(record, (metadata, exception) -> {
if (exception == null) {
System.out.println("Message sent successfully. Topic: " + metadata.topic() +
", Partition: " + metadata.partition() +
", Offset: " + metadata.offset());
} else {
System.err.println("Error sending message: " + exception.getMessage());
}
});
producer.flush();
producer.close();
}
private static Properties loadConfig() {
Properties props = new Properties();
try (FileInputStream fis = new FileInputStream("src/main/resources/kafka.properties")) {
props.load(fis);
} catch (IOException e) {
throw new RuntimeException("Error loading Kafka configuration", e);
}
return props;
}
}
```
This class demonstrates how to create a Kafka producer, send a message, and handle the result asynchronously.
2. `KafkaConsumerExample.java`:
```java
package com.example;
import org.apache.kafka.clients.consumer.*;
import org.apache.kafka.common.serialization.StringDeserializer;
import java.time.Duration;
import java.util.Collections;
import java.util.Properties;
public class KafkaConsumerExample {
public static void main(String[] args) {
Properties props = loadConfig();
props.put(ConsumerConfig.KEY_DESERIALIZER_CLASS_CONFIG, StringDeserializer.class.getName());
props.put(ConsumerConfig.VALUE_DESERIALIZER_CLASS_CONFIG, StringDeserializer.class.getName());
props.put(ConsumerConfig.AUTO_OFFSET_RESET_CONFIG, "earliest");
Consumer<String, String> consumer = new KafkaConsumer<>(props);
String topic = props.getProperty("topic");
consumer.subscribe(Collections.singletonList(topic));
try {
while (true) {
ConsumerRecords<String, String> records = consumer.poll(Duration.ofMillis(100));
for (ConsumerRecord<String, String> record : records) {
System.out.println("Received message: " + record.value() +
" from topic: " + record.topic() +
", partition: " + record.partition() +
", offset: " + record.offset());
}
}
} finally {
consumer.close();
}
}
private static Properties loadConfig() {
Properties props = new Properties();
try (FileInputStream fis = new FileInputStream("src/main/resources/kafka.properties")) {
props.load(fis);
} catch (IOException e) {
throw new RuntimeException("Error loading Kafka configuration", e);
}
return props;
}
}
```
This class shows how to create a Kafka consumer, subscribe to a topic, and continuously poll for new messages.
</div>
Both classes use a loadConfig() method to read the Kafka properties from the kafka.properties file, allowing for easy configuration changes without modifying the code.
## Build and Run
To build and run the project, use the following commands in your terminal:
```bash
mvn clean package
java -cp target/kafka-java-example-1.0-SNAPSHOT.jar com.example.KafkaProducerExample
java -cp target/kafka-java-example-1.0-SNAPSHOT.jar com.example.KafkaConsumerExample
```
Run the producer and consumer in separate terminal windows to see the message being sent and received.
## Best Practices
1. Use a properties file to store Kafka configuration details.
2. Implement proper error handling and logging.
3. Use the try-with-resources statement to ensure that Kafka producers and consumers are properly closed.
4. Consider using Kafka's AdminClient for managing topics and other Kafka resources.
5. Implement proper serialization and deserialization for your message keys and values.
## Troubleshooting
If you encounter connection issues:
1. Verify your Kafka credentials in the `kafka.properties` file.
2. Ensure your Kafka cluster is running and accessible from your DevBox environment.
3. Check for any network restrictions in your DevBox environment.
4. Confirm that all required dependencies are correctly specified in your `pom.xml` file.
For more detailed information on using Kafka with Java, refer to the [Apache Kafka documentation](https://kafka.apache.org/documentation/).
file: ./content/docs/guides/databases/kafka/nodejs.en.mdx
meta: {
"title": "Node.js",
"description": "Learn how to connect to Kafka in Sealos DevBox using Node.js"
}
This guide will walk you through the process of connecting to Kafka using Node.js within your Sealos DevBox project.
## Prerequisites
* [A Sealos DevBox project](/docs/guides/devbox/create-a-project) with Node.js environment
* [A Kafka cluster created using the Database app in Sealos](./)
## Install Required Packages
In your Cursor terminal, install the necessary packages:
```bash
npm install kafkajs dotenv
```
This command installs:
* `kafkajs`: A modern Apache Kafka client for Node.js
* `dotenv`: A zero-dependency module that loads environment variables from a `.env` file
## Connection Setup
<div className="fd-steps [&_h4]:fd-step">
#### Set up the environment variables
First, let's set up the environment variables for our Kafka connection. Create a `.env` file in your project root with the following content:
```ini title=".env"
KAFKA_BROKERS=your_kafka_host:9092
KAFKA_CLIENT_ID=my-app
KAFKA_TOPIC=my-topic
```
Replace the placeholders with your actual Kafka broker address, client ID, and topic name from the Database app in Sealos.
#### Create a Kafka client
Create a new file named `kafkaClient.js` with the following content:
```javascript
const { Kafka } = require('kafkajs');
require('dotenv').config();
const kafka = new Kafka({
clientId: process.env.KAFKA_CLIENT_ID,
brokers: process.env.KAFKA_BROKERS.split(','),
});
const producer = kafka.producer();
const consumer = kafka.consumer({ groupId: 'test-group' });
module.exports = { kafka, producer, consumer };
```
This file creates a Kafka client and exports it along with a producer and consumer.
#### Create a producer script
Now, let's create a file named `producer.js` to demonstrate how to produce messages:
```javascript
const { kafka, producer } = require('./kafkaClient');
require('dotenv').config();
async function produceMessage() {
try {
await producer.connect();
// Check if the topic exists
const admin = kafka.admin();
await admin.connect();
const topics = await admin.listTopics();
if (!topics.includes(process.env.KAFKA_TOPIC)) {
console.log(`Topic ${process.env.KAFKA_TOPIC} does not exist. Creating it...`);
await admin.createTopics({
topics: [{ topic: process.env.KAFKA_TOPIC, numPartitions: 1, replicationFactor: 1 }]
});
console.log(`Topic ${process.env.KAFKA_TOPIC} created successfully.`);
}
await admin.disconnect();
// Send the message
const result = await producer.send({
topic: process.env.KAFKA_TOPIC,
messages: [
{ value: 'Hello from Sealos DevBox!' },
],
});
console.log('Message sent successfully', result);
} catch (error) {
console.error('Error producing message:', error);
if (error.name === 'KafkaJSNumberOfRetriesExceeded') {
console.error('Connection details:', {
clientId: process.env.KAFKA_CLIENT_ID,
brokers: process.env.KAFKA_BROKERS,
});
}
} finally {
await producer.disconnect();
}
}
produceMessage();
```
This script does the following:
1. Connects to Kafka using the producer.
2. Checks if the specified topic exists, creating it if necessary.
3. Sends a message to the topic.
4. Handles errors, including connection issues.
5. Disconnects from Kafka after the operation.
This approach ensures the topic exists before sending messages and provides detailed error information if the connection fails.
#### Create a consumer script
Create another file named `consumer.js` to demonstrate how to consume messages:
```javascript
const { consumer } = require('./kafkaClient');
require('dotenv').config();
async function consumeMessages() {
try {
await consumer.connect();
await consumer.subscribe({ topic: process.env.KAFKA_TOPIC, fromBeginning: true });
await consumer.run({
eachMessage: async ({ topic, partition, message }) => {
console.log({
topic,
partition,
offset: message.offset,
value: message.value.toString(),
});
},
});
} catch (error) {
console.error('Error consuming messages:', error);
}
}
consumeMessages();
```
This consumer script:
1. Connects to Kafka using the consumer instance.
2. Subscribes to the specified topic, starting from the beginning of the log.
3. Continuously runs and processes each incoming message.
4. Logs the topic, partition, offset, and message value for each received message.
5. Handles any errors that occur during the consumption process.
This setup allows for real-time processing of messages as they arrive in the Kafka topic.
</div>
## Usage
To run the producer script, use the following command in your Cursor terminal:
```bash
node producer.js
```
To run the consumer script, open another terminal and use:
```bash
node consumer.js
```
The consumer will start listening for messages. When you run the producer script, you should see the message being received by the consumer.
## Best Practices
1. Use environment variables for Kafka configuration details.
2. Implement proper error handling and logging.
3. Use the `kafkajs` built-in retry mechanism for better reliability.
4. Consider implementing a graceful shutdown mechanism for your consumer.
5. Use compression for better performance when dealing with large messages or high throughput.
## Troubleshooting
If you encounter connection issues:
1. Verify your Kafka broker address in the `.env` file.
2. Ensure your Kafka cluster is running and accessible.
3. Check for any network restrictions in your DevBox environment.
4. Confirm that the required packages are correctly installed.
For more detailed information on using Kafka with Node.js, refer to the [KafkaJS documentation](https://kafka.js.org/).
file: ./content/docs/guides/databases/kafka/php.en.mdx
meta: {
"title": "PHP",
"description": "Learn how to connect to Kafka in Sealos DevBox using PHP"
}
This guide will walk you through the process of connecting to Kafka using PHP within your Sealos DevBox project.
## Prerequisites
* [A Sealos DevBox project](/docs/guides/devbox/create-a-project) with PHP environment
* [A Kafka cluster created using the Database app in Sealos](./)
## Install Required Extensions
In your Cursor terminal, first install the necessary system dependencies:
```bash
sudo apt-get update
sudo apt-get install -y librdkafka-dev
```
Then, install the Kafka extension for PHP:
```bash
sudo pecl install rdkafka
sudo sh -c 'echo "extension=rdkafka.so" > /etc/php/*/mods-available/rdkafka.ini'
sudo phpenmod rdkafka
```
## Connection Setup
<div className="fd-steps [&_h4]:fd-step">
#### Create a Configuration File
First, let's create a configuration file to store our Kafka connection parameters. Create a file named `config.php` in your project directory with the following content:
```php
<?php
return [
'brokers' => 'your_kafka_broker:9092',
'topic' => 'your_topic_name',
'group_id' => 'your_consumer_group_id'
];
```
Replace the placeholders with your actual Kafka credentials from the Database app in Sealos.
#### Create a Kafka Producer
Create a file named `kafka_producer.php` with the following content:
```php
<?php
$config = include 'config.php';
$conf = new RdKafka\Conf();
$conf->set('metadata.broker.list', $config['brokers']);
$producer = new RdKafka\Producer($conf);
$topic = $producer->newTopic($config['topic']);
$message = "Hello from Sealos DevBox!";
$topic->produce(RD_KAFKA_PARTITION_UA, 0, $message);
$producer->flush(10000);
echo "Message sent: $message\n";
```
This script creates a Kafka producer and sends a message to the specified topic.
#### Create a Kafka Consumer
Create another file named `kafka_consumer.php` with the following content:
```php
<?php
$config = include 'config.php';
$conf = new RdKafka\Conf();
$conf->set('group.id', $config['group_id']);
$conf->set('metadata.broker.list', $config['brokers']);
$conf->set('auto.offset.reset', 'earliest');
$consumer = new RdKafka\KafkaConsumer($conf);
$consumer->subscribe([$config['topic']]);
echo "Waiting for messages...\n";
while (true) {
$message = $consumer->consume(120*1000);
switch ($message->err) {
case RD_KAFKA_RESP_ERR_NO_ERROR:
echo "Received message: " . $message->payload . "\n";
break;
case RD_KAFKA_RESP_ERR__PARTITION_EOF:
echo "No more messages; will wait for more\n";
break;
case RD_KAFKA_RESP_ERR__TIMED_OUT:
echo "Timed out\n";
break;
default:
throw new \Exception($message->errstr(), $message->err);
break;
}
}
```
This script creates a Kafka consumer that listens for messages on the specified topic.
</div>
## Usage
To run the producer script, use the following command in your Cursor terminal:
```bash
php kafka_producer.php
```
To run the consumer script, open another terminal and use:
```bash
php kafka_consumer.php
```
The consumer will start listening for messages. When you run the producer script, you should see the message being received by the consumer.
## Best Practices
1. Use environment variables for Kafka configuration details.
2. Implement proper error handling and logging.
3. Consider using a library like `monolog` for better logging capabilities.
4. Implement a graceful shutdown mechanism for your consumer.
5. Use compression for better performance when dealing with large messages or high throughput.
## Troubleshooting
If you encounter connection issues:
1. Verify your Kafka broker address in the `config.php` file.
2. Ensure your Kafka cluster is running and accessible.
3. Check for any network restrictions in your DevBox environment.
4. Confirm that the `rdkafka` extension is correctly installed and enabled.
For more detailed information on using Kafka with PHP, refer to the [php-rdkafka documentation](https://github.com/arnaud-lb/php-rdkafka).
file: ./content/docs/guides/databases/kafka/python.en.mdx
meta: {
"title": "Python",
"description": "Learn how to connect to Kafka in Sealos DevBox using Python"
}
This guide will walk you through the process of connecting to Kafka using Python within your Sealos DevBox project.
## Prerequisites
* [A Sealos DevBox project](/docs/guides/devbox/create-a-project) with Python environment
* [A Kafka cluster created using the Database app in Sealos](./)
## Activating the Python Environment
Before you start, you need to activate the Python virtual environment in your DevBox. Open the terminal within Cursor IDE and run:
```bash
source ./bin/activate
```
You should see your prompt change, indicating that the virtual environment is now active.
## Installing Required Packages
In your Cursor terminal, install the necessary packages:
```bash
pip install kafka-python python-dotenv
```
This command installs:
* `kafka-python`: The Apache Kafka client for Python
* `python-dotenv`: A Python package that allows you to load environment variables from a .env file
## Connection Setup
<div className="fd-steps [&_h4]:fd-step">
#### Set up the environment variables
First, let's set up the environment variables for our Kafka connection. Create a `.env` file in your project root with the following content:
```ini title=".env"
KAFKA_BOOTSTRAP_SERVERS=your_kafka_bootstrap_servers:9092
KAFKA_TOPIC=your_topic_name
KAFKA_CONSUMER_GROUP=your_consumer_group_id
```
Replace the placeholders with your actual Kafka credentials from the Database app in Sealos.
#### Create a Kafka client module
Create a new file named `kafka_client.py` with the following content:
```python title="kafka_client.py"
import os
from dotenv import load_dotenv
from kafka import KafkaProducer, KafkaConsumer
# Load environment variables
load_dotenv()
def get_kafka_producer():
try:
producer = KafkaProducer(bootstrap_servers=os.getenv('KAFKA_BOOTSTRAP_SERVERS'))
print("Successfully connected to Kafka producer")
return producer
except Exception as e:
print(f"Error connecting to Kafka producer: {e}")
return None
def get_kafka_consumer(topic, group_id=None):
try:
consumer = KafkaConsumer(
topic,
bootstrap_servers=os.getenv('KAFKA_BOOTSTRAP_SERVERS'),
auto_offset_reset='earliest',
enable_auto_commit=True,
group_id=group_id or 'my-default-group'
)
print(f"Successfully connected to Kafka consumer for topic: {topic}")
return consumer
except Exception as e:
print(f"Error connecting to Kafka consumer: {e}")
return None
```
This module provides two main functions:
1. `get_kafka_producer()`: This function creates a Kafka producer using the bootstrap servers specified in the environment variables.
2. `get_kafka_consumer(topic)`: This function creates a Kafka consumer for a specified topic.
#### Create a test script
Now, let's create a test script to verify our connection and perform some basic Kafka operations. Create a file named `test_kafka.py` with the following content:
```python title="test_kafka.py"
import os
from dotenv import load_dotenv
from kafka_client import get_kafka_producer, get_kafka_consumer
# Load environment variables
load_dotenv()
def test_kafka_producer():
producer = get_kafka_producer()
if producer:
topic = os.getenv('KAFKA_TOPIC')
message = "Hello from Sealos DevBox!"
producer.send(topic, message.encode('utf-8'))
producer.flush()
print(f"Message sent to topic {topic}: {message}")
producer.close()
def test_kafka_consumer():
topic = os.getenv('KAFKA_TOPIC')
group_id = os.getenv('KAFKA_CONSUMER_GROUP')
consumer = get_kafka_consumer(topic, group_id)
if consumer:
print(f"Waiting for messages on topic {topic}...")
for message in consumer:
print(f"Received message: {message.value.decode('utf-8')}")
break # Exit after receiving one message
consumer.close()
if __name__ == "__main__":
test_kafka_producer()
test_kafka_consumer()
```
This script demonstrates how to:
1. Create a Kafka producer and send a message to a topic.
2. Create a Kafka consumer and read a message from a topic.
</div>
## Running the Test Script
To run the test script, make sure your virtual environment is activated, then execute:
```bash
python test_kafka.py
```
If everything is set up correctly, you should see output indicating successful connection to Kafka, message sending, and message receiving.
## Best Practices
1. Always activate the virtual environment before running your Python scripts or installing packages.
2. Use environment variables to store sensitive information like Kafka bootstrap servers.
3. Handle exceptions appropriately to manage potential errors.
4. Consider using asynchronous Kafka clients for better performance in production environments.
5. Implement proper logging instead of print statements in production code.
## Troubleshooting
If you encounter connection issues:
1. Ensure you've activated the virtual environment with `source ./bin/activate`.
2. Verify that your Kafka cluster is running and accessible.
3. Double-check your Kafka credentials in the `.env` file.
4. Check the Kafka logs in the Database app for any error messages.
5. Make sure your DevBox environment has network access to the Kafka bootstrap servers.
For more detailed information on using Kafka with Python, refer to the [kafka-python documentation](https://kafka-python.readthedocs.io/).
file: ./content/docs/guides/databases/kafka/rust.en.mdx
meta: {
"title": "Rust",
"description": "Learn how to connect to Kafka in Sealos DevBox using Rust"
}
This guide will walk you through the process of connecting to Kafka using Rust within your Sealos DevBox project.
## Prerequisites
* [A Sealos DevBox project](/docs/guides/devbox/create-a-project) with Rust environment
* [A Kafka cluster created using the Database app in Sealos](./)
## Install Required Dependencies
In your Cursor terminal, add the necessary dependencies to your `Cargo.toml` file:
```toml
[dependencies]
rdkafka = "0.28"
tokio = { version = "1.28", features = ["full"] }
dotenv = "0.15"
```
These dependencies include:
* `rdkafka`: A high-level Apache Kafka client library for Rust
* `tokio`: An asynchronous runtime for Rust
* `dotenv`: A library for loading environment variables from a file
## Connection Setup
<div className="fd-steps [&_h4]:fd-step">
#### Set up the environment variables
First, let's set up the environment variables for our Kafka connection. Create a `.env` file in your project root with the following content:
```ini title=".env"
KAFKA_BROKERS=your_kafka_bootstrap_servers:9092
KAFKA_TOPIC=your_topic_name
KAFKA_GROUP_ID=rust-consumer-group
```
Replace the placeholders with your actual Kafka credentials from the Database app in Sealos.
#### Create the main.rs file
Create a new file named `src/main.rs` with the following content:
```rust
use rdkafka::config::ClientConfig;
use rdkafka::producer::{FutureProducer, FutureRecord};
use rdkafka::consumer::{StreamConsumer, Consumer};
use rdkafka::message::Message;
use std::time::Duration;
use dotenv::dotenv;
use std::env;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
dotenv().ok();
let brokers = env::var("KAFKA_BROKERS").expect("KAFKA_BROKERS must be set");
let topic = env::var("KAFKA_TOPIC").expect("KAFKA_TOPIC must be set");
let group_id = env::var("KAFKA_GROUP_ID").expect("KAFKA_GROUP_ID must be set");
// Producer setup
let producer: FutureProducer = ClientConfig::new()
.set("group.id", &group_id)
.set("bootstrap.servers", &brokers)
.set("message.timeout.ms", "5000")
.create()?;
// Produce a message
let delivery_status = producer
.send(
FutureRecord::to(&topic)
.payload("Hello from Sealos DevBox!")
.key("key"),
Duration::from_secs(0),
)
.await;
println!("Delivery status: {:?}", delivery_status);
// Add a delay to ensure the message is processed
tokio::time::sleep(Duration::from_secs(1)).await;
// Consumer setup
let consumer: StreamConsumer = ClientConfig::new()
.set("group.id", "rust-consumer-group")
.set("bootstrap.servers", &brokers)
.set("enable.partition.eof", "false")
.set("session.timeout.ms", "6000")
.set("enable.auto.commit", "true")
.set("auto.offset.reset", "earliest") // Add this line
.create()?;
consumer.subscribe(&[&topic])?;
// Consume messages
println!("Waiting for messages...");
let mut message_count = 0;
let max_messages = 5; // Set the maximum number of messages to receive
while message_count < max_messages {
match tokio::time::timeout(Duration::from_secs(5), consumer.recv()).await {
Ok(Ok(msg)) => {
println!("Received message: {:?}", msg.payload_view::<str>());
message_count += 1;
}
Ok(Err(e)) => println!("Error while receiving message: {:?}", e),
Err(_) => {
println!("No more messages received after {} seconds. Exiting.", 5);
break;
}
}
}
println!("Received {} messages in total.", message_count);
Ok(())
}
```
This script demonstrates how to:
1. Set up a Kafka producer and send a message to a topic.
2. Set up a Kafka consumer and read messages from a topic.
</div>
## Usage
To run the application, use the following command in your Cursor terminal:
```bash
cargo run
```
This will compile and execute the `main` function, demonstrating the connection to Kafka, message production, and consumption.
## Best Practices
1. Use environment variables for Kafka configuration details.
2. Implement proper error handling using Rust's `Result` type.
3. Use asynchronous programming with Tokio for better performance.
4. Consider implementing more robust consumer logic for production use, including proper error handling and graceful shutdown.
## Troubleshooting
If you encounter connection issues:
1. Verify your Kafka broker addresses in the `.env` file.
2. Ensure your Kafka cluster is running and accessible from your DevBox environment.
3. Check for any network restrictions in your DevBox environment.
4. Confirm that all required dependencies are correctly specified in your `Cargo.toml` file.
For more detailed information on using Kafka with Rust, refer to the [rdkafka documentation](https://docs.rs/rdkafka).
file: ./content/docs/guides/databases/milvus/go.en.mdx
meta: {
"title": "Go",
"description": "Learn how to connect to Milvus databases in Sealos DevBox using Go"
}
This guide will walk you through the process of connecting to a Milvus database using Go within your Sealos DevBox project.
## Prerequisites
* [A Sealos DevBox project](/docs/guides/devbox/create-a-project) with Go environment
* [A Milvus database created using the Database app in Sealos](./)
## Install Required Packages
In your Cursor terminal, install the necessary packages:
```bash
go get github.com/milvus-io/milvus-sdk-go/v2
go get github.com/joho/godotenv
```
These commands install the Milvus Go SDK and the godotenv package for loading environment variables.
## Connection Setup
<div className="fd-steps [&_h4]:fd-step">
#### Set up the environment variables
Create a `.env` file in your project root with the following content:
```ini title=".env"
MILVUS_ADDR=your_milvus_host:19530
COLLECTION_NAME=your_collection_name
DIMENSION=128
ID_COLUMN=id
EMBEDDING_COLUMN=embedding
```
Replace the placeholders with your actual Milvus credentials and desired configuration.
#### Create the main.go file
Create a new file named `main.go` with the following content:
```go title="main.go"
package main
import (
"context"
"log"
"os"
"strconv"
"time"
"github.com/joho/godotenv"
"github.com/milvus-io/milvus-sdk-go/v2/client"
"github.com/milvus-io/milvus-sdk-go/v2/entity"
)
func main() {
// Load environment variables from .env file
err := godotenv.Load()
if err != nil {
log.Fatal("Error loading .env file")
}
// Get configuration from environment variables
milvusAddr := os.Getenv("MILVUS_ADDR")
collectionName := os.Getenv("COLLECTION_NAME")
dimStr := os.Getenv("DIMENSION")
idCol := os.Getenv("ID_COLUMN")
embeddingCol := os.Getenv("EMBEDDING_COLUMN")
// Convert dimension to int64
dim, err := strconv.ParseInt(dimStr, 10, 64)
if err != nil {
log.Fatalf("Failed to parse DIMENSION: %v", err)
}
// Setup context for client creation, use 10 seconds here
ctx := context.Background()
ctx, cancel := context.WithTimeout(ctx, 10*time.Second)
defer cancel()
// Create a new Milvus client
c, err := client.NewClient(ctx, client.Config{
Address: milvusAddr,
})
if err != nil {
log.Fatal("failed to connect to milvus:", err.Error())
}
// Check if the collection exists
collExists, err := c.HasCollection(ctx, collectionName)
if err != nil {
log.Fatal("failed to check collection exists:", err.Error())
}
if collExists {
// Drop the old collection if it exists
_ = c.DropCollection(ctx, collectionName)
}
// Define collection schema
schema := entity.NewSchema().WithName(collectionName).WithDescription("this is the basic example collection").
WithField(entity.NewField().WithName(idCol).WithDataType(entity.FieldTypeInt64).WithIsPrimaryKey(true).WithIsAutoID(false)).
WithField(entity.NewField().WithName(embeddingCol).WithDataType(entity.FieldTypeFloatVector).WithDim(dim))
// Create the collection
err = c.CreateCollection(ctx, schema, entity.DefaultShardNumber)
if err != nil {
log.Fatal("failed to create collection:", err.Error())
}
// List all collections
collections, err := c.ListCollections(ctx)
if err != nil {
log.Fatal("failed to list collections:", err.Error())
}
for _, collection := range collections {
log.Printf("Collection id: %d, name: %s\n", collection.ID, collection.Name)
}
// Show collection partitions
partitions, err := c.ShowPartitions(ctx, collectionName)
if err != nil {
log.Fatal("failed to show partitions:", err.Error())
}
for _, partition := range partitions {
log.Printf("partition id: %d, name: %s\n", partition.ID, partition.Name)
}
// Create a new partition
partitionName := "new_partition"
err = c.CreatePartition(ctx, collectionName, partitionName)
if err != nil {
log.Fatal("failed to create partition:", err.Error())
}
log.Println("After create partition")
// Show collection partitions again to check creation
partitions, err = c.ShowPartitions(ctx, collectionName)
if err != nil {
log.Fatal("failed to show partitions:", err.Error())
}
for _, partition := range partitions {
log.Printf("partition id: %d, name: %s\n", partition.ID, partition.Name)
}
// Clean up by dropping the collection
_ = c.DropCollection(ctx, collectionName)
c.Close()
}
```
This code demonstrates how to connect to Milvus, create a collection, list collections, show and create partitions, and clean up by dropping the collection.
</div>
## Usage
To run the application, use the following command in your Cursor terminal:
```bash
go run main.go
```
This will execute the `main` function, demonstrating the connection to Milvus and basic operations with collections and partitions.
## Best Practices
1. Use environment variables for Milvus connection details and configuration.
2. Always handle potential errors using proper error checking.
3. Use contexts with timeouts for operations to prevent hanging in case of network issues.
4. Close the Milvus client connection after operations are complete.
5. Clean up resources (like dropping test collections) after you're done with them.
## Troubleshooting
If you encounter connection issues:
1. Verify your Milvus credentials in the `.env` file.
2. Ensure your Milvus database is running and accessible.
3. Check for any network restrictions in your DevBox environment.
4. Confirm that the required packages are correctly installed.
For more detailed information on using Milvus with Go, refer to the [Milvus Go SDK documentation](https://github.com/milvus-io/milvus-sdk-go).
file: ./content/docs/guides/databases/milvus/index.en.mdx
meta: {
"title": "Milvus",
"description": "在 Sealos DevBox 中部署和连接 Milvus 集群"
}
file: ./content/docs/guides/databases/milvus/nodejs.en.mdx
meta: {
"title": "Node.js",
"description": "Learn how to connect to Milvus databases in Sealos DevBox using Node.js"
}
This guide will walk you through the process of connecting to a Milvus database using Node.js within your Sealos DevBox project.
## Prerequisites
* [A Sealos DevBox project](/docs/guides/devbox/create-a-project) with Node.js environment
* [A Milvus database created using the Database app in Sealos](./)
## Install Required Packages
In your Cursor terminal, install the necessary packages:
```bash
npm install @zilliz/milvus2-sdk-node dotenv
```
This command installs:
* `@zilliz/milvus2-sdk-node`: The official Milvus Node.js SDK
* `dotenv`: A zero-dependency module that loads environment variables from a `.env` file
## Connection Setup
<div className="fd-steps [&_h4]:fd-step">
#### Set up the environment variables
First, let's set up the environment variables for our Milvus connection. Create a `.env` file in your project root with the following content:
```ini title=".env"
MILVUS_HOST=your_milvus_host
MILVUS_PORT=19530
COLLECTION_NAME=test_collection
DIMENSION=128
```
Replace the placeholders with your actual Milvus credentials from the Database app in Sealos.
#### Create a connection file
Create a new file named `milvusClient.js` with the following content:
```javascript title="milvusClient.js"
const { MilvusClient } = require('@zilliz/milvus2-sdk-node');
require('dotenv').config();
const client = new MilvusClient({
address: `${process.env.MILVUS_HOST}:${process.env.MILVUS_PORT}`,
});
module.exports = client;
```
#### Create database operations
Now, let's create a file named `milvusOperations.js` to handle our database operations:
```javascript title="milvusOperations.js"
const client = require('./milvusClient');
require('dotenv').config();
async function createCollection() {
try {
const collectionName = process.env.COLLECTION_NAME;
const dimension = parseInt(process.env.DIMENSION);
// Define collection schema
const collectionSchema = {
collection_name: collectionName,
fields: [
{
name: 'id',
data_type: 'Int64',
is_primary_key: true,
auto_id: true
},
{
name: 'vector',
data_type: 'FloatVector',
dim: dimension
},
{
name: 'metadata',
data_type: 'VarChar',
max_length: 255
}
]
};
// Create collection
await client.createCollection(collectionSchema);
console.log(`Collection ${collectionName} created successfully`);
// Create index
const indexParams = {
collection_name: collectionName,
field_name: 'vector',
extra_params: {
index_type: 'IVF_FLAT',
metric_type: 'L2',
params: JSON.stringify({ nlist: 1024 })
}
};
await client.createIndex(indexParams);
console.log('Index created successfully');
} catch (error) {
console.error('Error creating collection:', error);
throw error;
}
}
async function insertData(vectors, metadata) {
try {
const collectionName = process.env.COLLECTION_NAME;
const data = {
collection_name: collectionName,
fields_data: vectors.map((vector, index) => ({
id: [],
vector,
metadata: metadata[index]
}))
};
const result = await client.insert(data);
console.log('Data inserted successfully:', result);
return result;
} catch (error) {
console.error('Error inserting data:', error);
throw error;
}
}
async function search(queryVector, topK = 5) {
try {
const collectionName = process.env.COLLECTION_NAME;
// Load collection
await client.loadCollection({
collection_name: collectionName
});
const searchParams = {
collection_name: collectionName,
vector: queryVector,
output_fields: ['metadata'],
limit: topK,
params: { nprobe: 10 }
};
const result = await client.search(searchParams);
console.log('Search results:', result);
return result;
} catch (error) {
console.error('Error searching:', error);
throw error;
}
}
module.exports = {
createCollection,
insertData,
search
};
```
#### Create a main script
Finally, let's create a `main.js` file to demonstrate all the operations:
```javascript title="main.js"
const { createCollection, insertData, search } = require('./milvusOperations');
async function main() {
try {
// Create collection
await createCollection();
// Generate sample vectors and metadata
const sampleVectors = [
new Array(128).fill(0).map(() => Math.random()),
new Array(128).fill(0).map(() => Math.random())
];
const sampleMetadata = ['Sample 1', 'Sample 2'];
// Insert data
await insertData(sampleVectors, sampleMetadata);
// Perform search
const queryVector = new Array(128).fill(0).map(() => Math.random());
await search(queryVector, 2);
} catch (error) {
console.error('An error occurred:', error);
}
}
main();
```
</div>
## Usage
To run the script, use the following command in your Cursor terminal:
```bash
node main.js
```
This will execute all the operations defined in the `main` function, demonstrating the connection to Milvus, collection creation, data insertion, and vector search.
## Best Practices
1. Use environment variables for Milvus connection details.
2. Create indexes for better search performance.
3. Load collections before performing search operations.
4. Implement proper error handling.
5. Use batch operations for inserting multiple vectors.
6. Release resources by releasing collections when they're no longer needed.
## Troubleshooting
If you encounter connection issues:
1. Verify your Milvus credentials in the `.env` file.
2. Ensure your Milvus database is running and accessible.
3. Check for any network restrictions in your DevBox environment.
4. Confirm that the required packages are correctly installed.
5. Verify that the vector dimensions match your collection schema.
For more detailed information on using Milvus with Node.js, refer to the [Milvus Node.js SDK documentation](https://github.com/milvus-io/milvus-sdk-node).
file: ./content/docs/guides/databases/mongodb/go.en.mdx
meta: {
"title": "Go",
"description": "Learn how to connect to MongoDB databases in Sealos DevBox using Go"
}
This guide will walk you through the process of connecting to a MongoDB database using Go within your Sealos DevBox project.
## Prerequisites
* [A Sealos DevBox project](/docs/guides/devbox/create-a-project) with Go environment
* [A MongoDB database created using the Database app in Sealos](./)
## Install Required Packages
In your Cursor terminal, install the necessary packages:
```bash
go get go.mongodb.org/mongo-driver/mongo
go get github.com/joho/godotenv
```
These commands install:
* `go.mongodb.org/mongo-driver/mongo`: The official MongoDB driver for Go
* `github.com/joho/godotenv`: A Go port of the Ruby dotenv library
## Connection Setup
<div className="fd-steps [&_h4]:fd-step">
#### Set up the environment variables
First, let's set up the environment variables for our database connection. Create a `.env` file in your project root with the following content:
```ini title=".env"
MONGO_URI=mongodb://your_username:your_password@your_database_host:27017
DB_NAME=your_database_name
```
Replace the placeholders with your actual MongoDB credentials from the Database app in Sealos. Note that we're not including the database name in the URI, as we'll create it programmatically if it doesn't exist.
#### Create the main.go file
Create a new file named `main.go` with the following content:
```go title="main.go"
package main
import (
"context"
"fmt"
"log"
"os"
"time"
"github.com/joho/godotenv"
"go.mongodb.org/mongo-driver/bson"
"go.mongodb.org/mongo-driver/mongo"
"go.mongodb.org/mongo-driver/mongo/options"
)
// Employee struct represents the structure of our data
type Employee struct {
Name string
Position string
}
func main() {
// Load environment variables from .env file
err := godotenv.Load()
if err != nil {
log.Fatal("Error loading .env file")
}
// Get MongoDB connection URI and database name from environment variables
mongoURI := os.Getenv("MONGO_URI")
dbName := os.Getenv("DB_NAME")
// Create a new client and connect to the server
client, err := mongo.NewClient(options.Client().ApplyURI(mongoURI))
if err != nil {
log.Fatal(err)
}
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
err = client.Connect(ctx)
if err != nil {
log.Fatal(err)
}
defer client.Disconnect(ctx)
// Check if the database exists, if not create it
err = createDatabaseIfNotExists(client, ctx, dbName)
if err != nil {
log.Fatal(err)
}
// Get a handle for your collection
collection := client.Database(dbName).Collection("employees")
// Insert a document
employee := Employee{"John Doe", "Developer"}
insertResult, err := collection.InsertOne(ctx, employee)
if err != nil {
log.Fatal(err)
}
fmt.Println("Inserted a single document: ", insertResult.InsertedID)
// Find a document
var result Employee
err = collection.FindOne(ctx, bson.M{"name": "John Doe"}).Decode(&result)
if err != nil {
log.Fatal(err)
}
fmt.Printf("Found a single document: %+v\n", result)
}
func createDatabaseIfNotExists(client *mongo.Client, ctx context.Context, dbName string) error {
// List all database names
databases, err := client.ListDatabaseNames(ctx, bson.M{})
if err != nil {
return err
}
// Check if our database exists
for _, db := range databases {
if db == dbName {
fmt.Printf("Database '%s' already exists\n", dbName)
return nil
}
}
// If the database doesn't exist, create it by inserting a document
fmt.Printf("Creating database '%s'\n", dbName)
err = client.Database(dbName).RunCommand(ctx, bson.D{{"create", "employees"}}).Err()
if err != nil {
return err
}
fmt.Printf("Database '%s' created successfully\n", dbName)
return nil
}
```
This code demonstrates how to connect to MongoDB, create a database if it doesn't exist, insert a document, and find a document. It uses environment variables for the MongoDB URI and database name.
</div>
## Usage
To run the application, use the following command in your Cursor terminal:
```bash
go run main.go
```
This will execute the `main` function, demonstrating the connection to MongoDB, database creation (if necessary), and performing basic operations.
## Best Practices
1. Use environment variables for database credentials and configuration.
2. Always handle potential errors using proper error checking.
3. Use contexts for operations that might need to be cancelled or timed out.
4. Close the database connection after operations are complete.
5. Use indexes for frequently queried fields to improve performance.
## Troubleshooting
If you encounter connection issues:
1. Verify your MongoDB credentials in the `.env` file.
2. Ensure your MongoDB database is running and accessible.
3. Check for any network restrictions in your DevBox environment.
4. Confirm that the required packages are correctly installed.
For more detailed information on using MongoDB with Go, refer to the [official MongoDB Go driver documentation](https://pkg.go.dev/go.mongodb.org/mongo-driver/mongo).
file: ./content/docs/guides/databases/mongodb/index.en.mdx
meta: {
"title": "MongoDB",
"description": "Deploy and connect to MongoDB databases in Sealos DevBox"
}
MongoDB is a popular, open-source document-oriented database system. In Sealos DevBox, you can easily set up and connect to MongoDB databases for your development projects.
## Deploy MongoDB in Sealos
Sealos makes it easy to deploy a MongoDB database with just a few clicks. Follow these steps:
<div className="fd-steps [&_h5]:fd-step">
<h5>From the Sealos desktop, click on the "Database" icon to open the Database app.</h5>
<h5>Click on the "Create New Database" button. In the deployment form:</h5>
* Select "MongoDB" as the database type.
* Choose the desired MongoDB version (e.g., mongodb-6.0).
* Enter a name for your database (use lowercase letters and numbers only).
* Adjust the CPU and Memory sliders to set the resources for your database.
* Set the number of replicas (1 for single-node development and testing).
* Specify the storage size (e.g., 3 Gi).
<h5>Review the projected cost on the left sidebar. Click the "Deploy" button in the top right corner to create your MongoDB database.</h5>
</div>
Once deployed, Sealos will provide you with the necessary connection details.
## Connect to MongoDB in DevBox
Here are examples of how to connect to your MongoDB database using different programming languages and frameworks within your DevBox environment:
<Cards>
<Card title="Connect to MongoDB with Go in Sealos DevBox" href="./mongodb/go" />
<Card title="Connect to MongoDB with Java in Sealos DevBox" href="./mongodb/java" />
<Card title="Connect to MongoDB with Node.js in Sealos DevBox" href="./mongodb/nodejs" />
<Card title="Connect to MongoDB with PHP in Sealos DevBox" href="./mongodb/php" />
<Card title="Connect to MongoDB with Python in Sealos DevBox" href="./mongodb/python" />
<Card title="Connect to MongoDB with Rust in Sealos DevBox" href="./mongodb/rust" />
</Cards>
file: ./content/docs/guides/databases/mongodb/java.en.mdx
meta: {
"title": "Java",
"description": "Learn how to connect to MongoDB databases in Sealos DevBox using Java"
}
This guide will walk you through the process of connecting to a MongoDB database using Java within your Sealos DevBox project.
## Prerequisites
* [A Sealos DevBox project](/docs/guides/devbox/create-a-project) with Java environment
* [A MongoDB database created using the Database app in Sealos](./)
## Project Setup
<div className="fd-steps [&_h4]:fd-step">
#### Create a new Maven project
In your Sealos DevBox terminal, initialize a new Maven project:
```bash
mvn archetype:generate -DgroupId=com.example -DartifactId=mongodb-java-example -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false
mv mongodb-java-example/* .
rm -rf mongodb-java-example/
```
#### Project Structure
After setting up, your project structure should look like this:
```
/
├── pom.xml
├── src
│ ├── main
│ │ ├── java
│ │ │ └── com
│ │ │ └── example
│ │ │ ├── App.java
│ │ │ ├── MongoConfig.java
│ │ │ └── Employee.java
│ │ └── resources
│ │ └── mongodb.properties
│ └── test
│ └── java
│ └── com
│ └── example
│ └── AppTest.java
```
#### Update pom.xml
Replace the content of your `pom.xml` file with the following:
```xml title="pom.xml"
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.example</groupId>
<artifactId>mongodb-java-example</artifactId>
<version>1.0-SNAPSHOT</version>
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<maven.compiler.source>11</maven.compiler.source>
<maven.compiler.target>11</maven.compiler.target>
</properties>
<dependencies>
<dependency>
<groupId>org.mongodb</groupId>
<artifactId>mongodb-driver-sync</artifactId>
<version>5.2.0</version>
</dependency>
<dependency>
<groupId>ch.qos.logback</groupId>
<artifactId>logback-classic</artifactId>
<version>1.5.3</version>
</dependency>
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<version>4.13.2</version>
<scope>test</scope>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.8.1</version>
<configuration>
<source>11</source>
<target>11</target>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-shade-plugin</artifactId>
<version>3.2.4</version>
<executions>
<execution>
<phase>package</phase>
<goals>
<goal>shade</goal>
</goals>
<configuration>
<transformers>
<transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
<mainClass>com.example.App</mainClass>
</transformer>
</transformers>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>
```
This `pom.xml` file includes the necessary dependencies (MongoDB Java driver and Logback for logging) and configures the Maven Shade plugin to create an executable JAR.
#### Create a configuration file
Create a file named `mongodb.properties` in the `src/main/resources` directory:
```ini title="mongodb.properties"
mongodb.uri=mongodb://your_mongodb_host:27017
mongodb.database=your_database_name
```
Replace the placeholders with your actual MongoDB credentials from the Database app in Sealos.
#### Create Java classes
Create the following Java classes in the `src/main/java/com/example` directory:
1. `MongoConfig.java`:
```java title="MongoConfig.java"
package com.example;
import java.io.IOException;
import java.io.InputStream;
import java.util.Properties;
public class MongoConfig {
private static final Properties properties = new Properties();
static {
try (InputStream input = MongoConfig.class.getClassLoader().getResourceAsStream("mongodb.properties")) {
if (input == null) {
System.out.println("Sorry, unable to find mongodb.properties");
System.exit(1);
}
properties.load(input);
} catch (IOException e) {
e.printStackTrace();
}
}
public static String getMongoUri() {
return properties.getProperty("mongodb.uri");
}
public static String getDatabase() {
return properties.getProperty("mongodb.database");
}
}
```
This class loads the MongoDB connection details from the `mongodb.properties` file.
2. `Employee.java`:
```java title="Employee.java"
package com.example;
import org.bson.Document;
public class Employee {
private String id;
private String name;
private String position;
public Employee(String name, String position) {
this.name = name;
this.position = position;
}
public Employee(Document doc) {
this.id = doc.getObjectId("_id").toString();
this.name = doc.getString("name");
this.position = doc.getString("position");
}
public Document toDocument() {
return new Document("name", name)
.append("position", position);
}
@Override
public String toString() {
return "Employee{" +
"id='" + id + '\'' +
", name='" + name + '\'' +
", position='" + position + '\'' +
'}';
}
}
```
This class represents an Employee document in MongoDB.
3. `App.java`:
```java title="App.java"
package com.example;
import com.mongodb.client.*;
import org.bson.Document;
public class App {
public static void main(String[] args) {
try (MongoClient mongoClient = MongoClients.create(MongoConfig.getMongoUri())) {
MongoDatabase database = mongoClient.getDatabase(MongoConfig.getDatabase());
MongoCollection<Document> collection = database.getCollection("employees");
System.out.println("Connected to MongoDB");
// Insert a document
Employee newEmployee = new Employee("John Doe", "Developer");
collection.insertOne(newEmployee.toDocument());
System.out.println("Inserted a new employee");
// Find all documents
System.out.println("All employees:");
try (MongoCursor<Document> cursor = collection.find().iterator()) {
while (cursor.hasNext()) {
Employee employee = new Employee(cursor.next());
System.out.println(employee);
}
}
// Update a document
Document query = new Document("name", "John Doe");
Document update = new Document("$set", new Document("position", "Senior Developer"));
collection.updateOne(query, update);
System.out.println("Updated John Doe's position");
// Delete a document
Document deleteQuery = new Document("name", "John Doe");
collection.deleteOne(deleteQuery);
System.out.println("Deleted John Doe from the database");
} catch (Exception e) {
System.err.println("Error connecting to MongoDB: " + e.getMessage());
}
}
}
```
This is the main class that demonstrates basic MongoDB operations using the Java driver:
* It connects to the MongoDB database.
* It inserts a new employee document.
* It finds and prints all employee documents.
* It updates an employee's position.
* It deletes an employee document.
</div>
## Build and Run
To build and run the project, use the following commands in your terminal:
```bash
mvn clean package
java -jar target/mongodb-java-example-1.0-SNAPSHOT.jar
```
If everything is set up correctly, you should see output demonstrating the MongoDB operations.
## Best Practices
1. Use a properties file to store MongoDB connection details.
2. Implement a configuration class to load and provide access to MongoDB properties.
3. Use the try-with-resources statement to ensure that the MongoClient is properly closed.
4. Handle exceptions appropriately and provide meaningful error messages.
5. Use Maven for dependency management and build automation.
## Troubleshooting
If you encounter connection issues:
1. Verify your MongoDB credentials in the `mongodb.properties` file.
2. Ensure your MongoDB database is running and accessible from your DevBox environment.
3. Check for any network restrictions in your DevBox environment.
4. Confirm that the MongoDB Java driver dependency is correctly specified in your `pom.xml` file.
5. Make sure you're using the correct version of Java (11 in this example).
For more detailed information on using MongoDB with Java, refer to the [MongoDB Java Driver documentation](https://mongodb.github.io/mongo-java-driver/).
file: ./content/docs/guides/databases/mongodb/nodejs.en.mdx
meta: {
"title": "Node.js",
"description": "Learn how to connect to MongoDB databases in Sealos DevBox using Node.js"
}
This guide will walk you through the process of connecting to a MongoDB database using Node.js within your Sealos DevBox project.
## Prerequisites
* [A Sealos DevBox project](/docs/guides/devbox/create-a-project) with Node.js environment
* [A MongoDB database created using the Database app in Sealos](./)
## Install Required Packages
In your Cursor terminal, install the necessary packages:
```bash
npm install mongodb dotenv
```
This command installs:
* `mongodb`: The official MongoDB driver for Node.js
* `dotenv`: A zero-dependency module that loads environment variables from a `.env` file
## Connection Setup
<div className="fd-steps [&_h4]:fd-step">
#### Set up the environment variables
First, let's set up the environment variables for our database connection. Create a `.env` file in your project root with the following content:
```ini title=".env"
MONGO_URI=mongodb://your_username:your_password@your_database_host:27017/your_database_name?authSource=admin
```
Replace the placeholders with your actual MongoDB credentials from the Database app in Sealos.
#### Create a connection file
Next, create a file named `db.js` with the following content:
```javascript title="db.js"
const { MongoClient } = require('mongodb');
require('dotenv').config();
const uri = process.env.MONGO_URI;
const client = new MongoClient(uri);
async function connectToDatabase() {
try {
await client.connect();
console.log('Connected to MongoDB');
return client.db();
} catch (error) {
console.error('Error connecting to MongoDB:', error);
process.exit(1);
}
}
module.exports = { connectToDatabase, client };
```
This file creates a MongoDB client and exports a function to connect to the database.
#### Create database operations
Now, let's create a file named `dbOperations.js` to handle our database operations:
```javascript title="dbOperations.js"
const { connectToDatabase, client } = require('./db');
async function createDocument(collection, document) {
const db = await connectToDatabase();
const result = await db.collection(collection).insertOne(document);
console.log(`Document inserted with _id: ${result.insertedId}`);
return result.insertedId;
}
async function readDocuments(collection, query = {}) {
const db = await connectToDatabase();
const documents = await db.collection(collection).find(query).toArray();
console.log('Documents found:', documents);
return documents;
}
async function updateDocument(collection, filter, update) {
const db = await connectToDatabase();
const result = await db.collection(collection).updateOne(filter, { $set: update });
console.log(`${result.modifiedCount} document(s) updated`);
return result.modifiedCount;
}
async function deleteDocument(collection, filter) {
const db = await connectToDatabase();
const result = await db.collection(collection).deleteOne(filter);
console.log(`${result.deletedCount} document(s) deleted`);
return result.deletedCount;
}
module.exports = {
createDocument,
readDocuments,
updateDocument,
deleteDocument
};
```
#### Create a main script
Finally, let's create a `main.js` file to demonstrate all the operations:
```javascript title="main.js"
const {
createDocument,
readDocuments,
updateDocument,
deleteDocument
} = require('./dbOperations');
const { client } = require('./db');
async function main() {
try {
// Create a document
const newEmployeeId = await createDocument('employees', { name: 'John Doe', position: 'Developer' });
// Read all documents
await readDocuments('employees');
// Update a document
await updateDocument('employees', { _id: newEmployeeId }, { position: 'Senior Developer' });
// Read the updated document
await readDocuments('employees', { _id: newEmployeeId });
// Delete the document
await deleteDocument('employees', { _id: newEmployeeId });
// Confirm deletion
await readDocuments('employees');
} catch (error) {
console.error('An error occurred:', error);
} finally {
await client.close();
}
}
main();
```
</div>
## Usage
To run the script, use the following command in your Cursor terminal:
```bash
node main.js
```
This will execute all the operations defined in the `main` function, demonstrating the connection to the database, document creation, reading, updating, and deletion.
## Best Practices
1. Use environment variables for database credentials.
2. Use connection pooling for better performance (MongoDB driver handles this automatically).
3. Always handle potential errors using try-catch blocks.
4. Close the database connection after operations are complete.
5. Use indexes for frequently queried fields to improve performance.
## Troubleshooting
If you encounter connection issues:
1. Verify your MongoDB credentials in the `.env` file.
2. Ensure your MongoDB database is running and accessible.
3. Check for any network restrictions in your DevBox environment.
4. Confirm that the `mongodb` package is correctly installed.
For more detailed information on using MongoDB with Node.js, refer to the [official MongoDB Node.js driver documentation](https://docs.mongodb.com/drivers/node/).
file: ./content/docs/guides/databases/mongodb/php.en.mdx
meta: {
"title": "PHP",
"description": "Learn how to connect to MongoDB databases in Sealos DevBox using PHP"
}
This guide will walk you through the process of connecting to a MongoDB database using PHP within your Sealos DevBox project.
## Prerequisites
* [A Sealos DevBox project](/docs/guides/devbox/create-a-project) with PHP environment
* [A MongoDB database created using the Database app in Sealos](./)
## Install Required Extensions
In your Cursor terminal, ensure that the MongoDB extension for PHP is installed:
```bash
sudo pecl install mongodb
```
## Install the MongoDB PHP Library
To install the MongoDB PHP Library, run the following command in your php-quickstart directory:
```bash
composer require mongodb/mongodb
```
## Connection Setup
<div className="fd-steps [&_h4]:fd-step">
#### Create a Configuration File
First, let's create a configuration file to store our database connection parameters. Create a file named `config.php` in your project directory with the following content:
```php title="config.php"
<?php
return [
'host' => 'your_mongodb_host',
'port' => '27017',
'database' => 'your_database_name',
'username' => 'your_username',
'password' => 'your_password'
];
```
Replace the placeholders with your actual MongoDB credentials from the Database app in Sealos.
#### Create a Database Connection Function
Next, let's create a PHP file that will handle the database connection. Create a file named `db_connect.php` with the following content:
```php title="db_connect.php"
<?php
require_once __DIR__ . '/vendor/autoload.php'; // Ensure you have the MongoDB PHP library installed
function getMongoDBConnection() {
$config = include 'config.php';
try {
$client = new MongoDB\Client(
"mongodb://{$config['username']}:{$config['password']}@{$config['host']}:{$config['port']}/{$config['database']}?authSource=admin"
);
echo "Connected successfully to MongoDB.\n";
return $client->selectDatabase($config['database']);
} catch (Exception $e) {
die("Connection failed: " . $e->getMessage());
}
}
```
This function reads the configuration from `config.php` and establishes a connection to the MongoDB database.
#### Create a Test Script
Now, let's create a test script to verify our connection and perform some basic database operations. Create a file named `test_mongodb.php` with the following content:
```php title="test_mongodb.php"
<?php
require_once 'db_connect.php';
$db = getMongoDBConnection();
// Insert a document
$collection = $db->employees;
$insertResult = $collection->insertOne([
'name' => 'John Doe',
'position' => 'Developer'
]);
echo "Inserted document with ID: " . $insertResult->getInsertedId() . "\n";
// Find documents
$cursor = $collection->find();
echo "Employees:\n";
foreach ($cursor as $document) {
echo "ID: " . $document['_id'] . ", Name: " . $document['name'] . ", Position: " . $document['position'] . "\n";
}
// Update a document
$updateResult = $collection->updateOne(
['name' => 'John Doe'],
['$set' => ['position' => 'Senior Developer']]
);
echo "Modified " . $updateResult->getModifiedCount() . " document(s)\n";
// Delete a document
$deleteResult = $collection->deleteOne(['name' => 'John Doe']);
echo "Deleted " . $deleteResult->getDeletedCount() . " document(s)\n";
```
</div>
## Usage
To run the test script, use the following command in your Cursor terminal:
```bash
php test_mongodb.php
```
This will execute the script, demonstrating the connection to the database, document insertion, querying, updating, and deletion.
## Best Practices
1. Use environment variables or a separate configuration file for database credentials.
2. Always handle potential errors using try-catch blocks.
3. Use the MongoDB PHP library for better performance and features.
4. Close the database connection after operations are complete (in this case, it's handled automatically).
5. Use appropriate indexing for frequently queried fields to improve performance.
## Troubleshooting
If you encounter connection issues:
1. Verify your database credentials in the `config.php` file.
2. Ensure your MongoDB database is running and accessible.
3. Check for any network restrictions in your DevBox environment.
4. Confirm that the MongoDB PHP extension is correctly installed.
For more detailed information on using MongoDB with PHP, refer to the [official MongoDB PHP library documentation](https://docs.mongodb.com/drivers/php/).
file: ./content/docs/guides/databases/mongodb/python.en.mdx
meta: {
"title": "Python",
"description": "Learn how to connect to MongoDB databases in Sealos DevBox using Python"
}
This guide will walk you through the process of connecting to a MongoDB database using Python within your Sealos DevBox project.
## Prerequisites
* [A Sealos DevBox project](/docs/guides/devbox/create-a-project) with Python environment
* [A MongoDB database created using the Database app in Sealos](./)
## Activating the Python Environment
Before you start, you need to activate the Python virtual environment in your DevBox. Open the terminal within Cursor IDE and run:
```bash
source ./bin/activate
```
You should see your prompt change, indicating that the virtual environment is now active.
## Installing Required Packages
In your Cursor terminal, install the necessary packages:
```bash
pip install pymongo python-dotenv
```
This command installs:
* `pymongo`: The official MongoDB driver for Python
* `python-dotenv`: A Python package that allows you to load environment variables from a .env file
## Connection Setup
<div className="fd-steps [&_h4]:fd-step">
#### Set up the environment variables
First, let's set up the environment variables for our database connection. Create a `.env` file in your project root with the following content:
```ini title=".env"
MONGO_URI=mongodb://your_username:your_password@your_database_host:27017/your_database_name?authSource=admin
```
Replace the placeholders with your actual MongoDB credentials from the Database app in Sealos.
#### Create a database connection module
Create a new file named `db_connection.py` with the following content:
```python title="db_connection.py"
import os
from dotenv import load_dotenv
from pymongo import MongoClient
from pymongo.errors import ConnectionFailure
# Load environment variables
load_dotenv()
def get_db_connection():
try:
client = MongoClient(os.getenv('MONGO_URI'))
# The ismaster command is cheap and does not require auth.
client.admin.command('ismaster')
print("Successfully connected to MongoDB")
return client
except ConnectionFailure:
print("Server not available")
return None
def close_connection(client):
if client:
client.close()
print("MongoDB connection closed")
```
This module provides two main functions:
1. `get_db_connection()`: This function establishes a connection to the MongoDB database using the credentials stored in the environment variables. It returns the client object if successful, or None if an error occurs.
2. `close_connection(client)`: This function closes the database connection when it's no longer needed.
#### Create a test script
Now, let's create a test script to verify our connection and perform some basic database operations. Create a file named `test_mongodb.py` with the following content:
```python title="test_mongodb.py"
from db_connection import get_db_connection, close_connection
def insert_document(collection, document):
result = collection.insert_one(document)
print(f"Inserted document with ID: {result.inserted_id}")
def find_documents(collection, query={}):
documents = collection.find(query)
for doc in documents:
print(doc)
def update_document(collection, query, update):
result = collection.update_one(query, {'$set': update})
print(f"Modified {result.modified_count} document(s)")
def delete_document(collection, query):
result = collection.delete_one(query)
print(f"Deleted {result.deleted_count} document(s)")
def main():
client = get_db_connection()
if client:
try:
db = client.get_database()
collection = db['test_collection']
# Insert a document
insert_document(collection, {'name': 'John Doe', 'age': 30})
# Find all documents
print("\nAll documents:")
find_documents(collection)
# Update a document
update_document(collection, {'name': 'John Doe'}, {'age': 31})
# Find the updated document
print("\nUpdated document:")
find_documents(collection, {'name': 'John Doe'})
# Delete the document
delete_document(collection, {'name': 'John Doe'})
# Verify deletion
print("\nAfter deletion:")
find_documents(collection)
finally:
close_connection(client)
if __name__ == "__main__":
main()
```
This script demonstrates basic CRUD operations:
1. Inserting a document
2. Finding documents
3. Updating a document
4. Deleting a document
</div>
## Running the Test Script
To run the test script, make sure your virtual environment is activated, then execute:
```bash
python test_mongodb.py
```
If everything is set up correctly, you should see output indicating successful connection, document insertion, retrieval, update, and deletion.
## Best Practices
1. Always activate the virtual environment before running your Python scripts or installing packages.
2. Use environment variables to store sensitive information like database credentials.
3. Close database connections after use to free up resources.
4. Use try-except blocks to handle potential errors gracefully.
5. Use PyMongo's built-in methods for database operations to ensure proper handling of MongoDB-specific data types.
## Troubleshooting
If you encounter connection issues:
1. Ensure you've activated the virtual environment with `source ./bin/activate`.
2. Verify that your MongoDB database is running and accessible.
3. Double-check your database credentials in the `.env` file.
4. Check the MongoDB logs in the Database app for any error messages.
For more detailed information on using MongoDB with Python, refer to the [official PyMongo documentation](https://pymongo.readthedocs.io/).
file: ./content/docs/guides/databases/mongodb/rust.en.mdx
meta: {
"title": "Rust",
"description": "Learn how to connect to MongoDB databases in Sealos DevBox using Rust"
}
This guide will walk you through the process of connecting to a MongoDB database using Rust within your Sealos DevBox project.
## Prerequisites
* [A Sealos DevBox project](/docs/guides/devbox/create-a-project) with Rust environment
* [A MongoDB database created using the Database app in Sealos](./)
## Install Required Dependencies
In your Cursor terminal, add the necessary dependencies to your `Cargo.toml` file:
```toml title="Cargo.toml"
[dependencies]
mongodb = "3.1.0"
tokio = { version = "1.28", features = ["full"] }
dotenv = "0.15"
serde = { version = "1.0", features = ["derive"] }
futures-util = "0.3"
```
These dependencies include:
* `mongodb`: The official MongoDB driver for Rust
* `tokio`: An asynchronous runtime for Rust
* `dotenv`: A library for loading environment variables from a file
* `serde`: A framework for serializing and deserializing Rust data structures
* `futures-util`: Provides utility types for working with futures, including `StreamExt` which we'll use for cursor iteration
## Connection Setup
<div className="fd-steps [&_h4]:fd-step">
#### Set up the environment variables
First, let's set up the environment variables for our database connection. Create a `.env` file in your project root with the following content:
```ini title=".env"
MONGODB_URI=mongodb://your_username:your_password@your_database_host:27017/your_database_name?authSource=admin
```
Replace the placeholders with your actual MongoDB credentials from the Database app in Sealos.
#### Create the main.rs file
Create a new file named `src/main.rs` with the following content:
```rust title="src/main.rs"
use mongodb::{Client, options::ClientOptions};
use mongodb::bson::doc;
use dotenv::dotenv;
use std::env;
use serde::{Serialize, Deserialize};
use futures_util::stream::TryStreamExt;
#[derive(Debug, Serialize, Deserialize)]
struct Employee {
name: String,
position: String,
}
#[tokio::main]
async fn main() -> mongodb::error::Result<()> {
// Load environment variables from .env file
dotenv().ok();
// Get the MongoDB URI from the environment
let mongodb_uri = env::var("MONGODB_URI").expect("MONGODB_URI must be set");
// Parse a connection string into an options struct
let mut client_options = ClientOptions::parse(mongodb_uri).await?;
// Manually set an option
client_options.app_name = Some("Sealos DevBox Rust App".to_string());
// Get a handle to the deployment
let client = Client::with_options(client_options)?;
// Get a handle to the database specified in the connection string
let db = client.default_database()
.expect("No default database found in the connection string");
// Get a handle to a collection in the database
let collection = db.collection::<Employee>("employees");
// Insert a document
let new_employee = Employee {
name: "John Doe".to_string(),
position: "Developer".to_string(),
};
let insert_result = collection.insert_one(new_employee).await?;
println!("Inserted document with ID: {:?}", insert_result.inserted_id);
// Query the documents in the collection
let mut cursor = collection.find(doc! {}).await?;
// Iterate over the results of the cursor
while let Some(employee) = cursor.try_next().await? {
println!("Found employee: {:?}", employee);
}
Ok(())
}
```
Let's break down the main components of this code:
1. **Imports**: We import necessary modules from `mongodb`, `dotenv`, `std::env`, and `serde`.
2. **Employee struct**: We define a struct to represent our data, using Serde for serialization and deserialization.
3. **Main function**: The `main` function is marked with `#[tokio::main]` to use Tokio's async runtime.
4. **Environment setup**: We load environment variables from the `.env` file and retrieve the MongoDB URI.
5. **Connection**: We create a MongoDB client using the URI and connect to the database.
6. **Data insertion**: We insert a sample employee into the database.
7. **Data querying**: We query and display all employees in the database.
</div>
## Usage
To run the application, use the following command in your Cursor terminal:
```bash
cargo run
```
This will compile and execute the `main` function, demonstrating the connection to the database, document insertion, and querying.
## Best Practices
1. Use environment variables for database credentials.
2. Use the `dotenv` crate to manage environment variables in development.
3. Implement proper error handling using Rust's `Result` type.
4. Use Serde for serializing and deserializing data structures.
5. Use async/await for efficient database operations.
## Troubleshooting
If you encounter connection issues:
1. Verify your MongoDB credentials in the `.env` file.
2. Ensure your MongoDB database is running and accessible.
3. Check for any network restrictions in your DevBox environment.
4. Confirm that all required dependencies are correctly specified in your `Cargo.toml` file.
For more detailed information on using MongoDB with Rust, refer to the [MongoDB Rust driver documentation](https://docs.rs/mongodb/latest/mongodb/).
file: ./content/docs/guides/databases/mysql/go.en.mdx
meta: {
"title": "Go",
"description": "Learn how to connect to MySQL databases in Sealos DevBox using Go"
}
This guide will walk you through the process of connecting to a MySQL database using Go within your Sealos DevBox project.
## Prerequisites
* [A Sealos DevBox project](/docs/guides/devbox/create-a-project) with Go environment
* [A MySQL database created using the Database app in Sealos](./)
## Install Required Packages
In your Cursor terminal, install the necessary packages:
```bash
go get github.com/go-sql-driver/mysql
go get github.com/joho/godotenv
```
These commands install:
* `github.com/go-sql-driver/mysql`: A MySQL driver for Go's database/sql package
* `github.com/joho/godotenv`: A Go port of the Ruby dotenv library
## Connection Setup
<div className="fd-steps [&_h4]:fd-step">
#### Set up the environment variables
First, let's set up the environment variables for our database connection. Create a `.env` file in your project root with the following content:
```ini title=".env"
DB_HOST=your_database_host
DB_PORT=3306
DB_USER=your_username
DB_PASSWORD=your_password
DB_NAME=your_database_name
```
Replace the placeholders with your actual MySQL credentials from the Database app in Sealos.
#### Create the main.go file
Create a new file named `main.go` with the following content:
```go title="main.go"
package main
import (
"database/sql"
"fmt"
"log"
"os"
_ "github.com/go-sql-driver/mysql"
"github.com/joho/godotenv"
)
// Employee struct represents the structure of our data
type Employee struct {
ID int
Name string
Position string
}
// connectDB establishes a connection to the MySQL database
func connectDB() (*sql.DB, error) {
// Load environment variables from .env file
err := godotenv.Load()
if err != nil {
log.Fatal("Error loading .env file")
}
// Retrieve database connection details from environment variables
dbHost := os.Getenv("DB_HOST")
dbPort := os.Getenv("DB_PORT")
dbUser := os.Getenv("DB_USER")
dbPassword := os.Getenv("DB_PASSWORD")
dbName := os.Getenv("DB_NAME")
// First, connect without specifying the database
dsnWithoutDB := fmt.Sprintf("%s:%s@tcp(%s:%s)/", dbUser, dbPassword, dbHost, dbPort)
db, err := sql.Open("mysql", dsnWithoutDB)
if err != nil {
return nil, err
}
// Create the database if it doesn't exist
_, err = db.Exec("CREATE DATABASE IF NOT EXISTS " + dbName)
if err != nil {
return nil, err
}
// Close the connection and reconnect with the database specified
db.Close()
dsn := fmt.Sprintf("%s:%s@tcp(%s:%s)/%s", dbUser, dbPassword, dbHost, dbPort, dbName)
db, err = sql.Open("mysql", dsn)
if err != nil {
return nil, err
}
// Verify the connection
err = db.Ping()
if err != nil {
return nil, err
}
fmt.Println("Successfully connected to the database")
return db, nil
}
// createTable creates the employees table if it doesn't exist
func createTable(db *sql.DB) error {
_, err := db.Exec(`
CREATE TABLE IF NOT EXISTS employees (
id INT AUTO_INCREMENT PRIMARY KEY,
name VARCHAR(100) NOT NULL,
position VARCHAR(100) NOT NULL
)
`)
return err
}
// insertEmployee inserts a new employee into the database
func insertEmployee(db *sql.DB, name, position string) error {
_, err := db.Exec("INSERT INTO employees (name, position) VALUES (?, ?)", name, position)
return err
}
// getEmployees retrieves all employees from the database
func getEmployees(db *sql.DB) ([]Employee, error) {
rows, err := db.Query("SELECT id, name, position FROM employees")
if err != nil {
return nil, err
}
defer rows.Close()
var employees []Employee
for rows.Next() {
var emp Employee
err := rows.Scan(&emp.ID, &emp.Name, &emp.Position)
if err != nil {
return nil, err
}
employees = append(employees, emp)
}
return employees, nil
}
func main() {
// Connect to the database
db, err := connectDB()
if err != nil {
log.Fatal(err)
}
// Ensure the database connection is closed when the function exits
defer func() {
if err := db.Close(); err != nil {
log.Printf("Error closing database connection: %v", err)
} else {
fmt.Println("Database connection closed successfully")
}
}()
// Create the employees table
err = createTable(db)
if err != nil {
log.Fatal(err)
}
// Insert sample employees
err = insertEmployee(db, "John Doe", "Developer")
if err != nil {
log.Fatal(err)
}
err = insertEmployee(db, "Jane Smith", "Designer")
if err != nil {
log.Fatal(err)
}
// Retrieve and display all employees
employees, err := getEmployees(db)
if err != nil {
log.Fatal(err)
}
fmt.Println("Employees:")
for _, emp := range employees {
fmt.Printf("ID: %d, Name: %s, Position: %s\n", emp.ID, emp.Name, emp.Position)
}
// The database connection will be closed automatically when main() exits
// due to the defer statement at the beginning of the function
}
```
Let's break down the main components of this code:
1. **Imports**: We import necessary packages, including `database/sql` for database operations and `github.com/go-sql-driver/mysql` as the MySQL driver.
2. **Employee struct**: Defines the structure for our employee data.
3. **connectDB function**: Loads environment variables, constructs the connection string, and establishes a connection to the database.
4. **createTable function**: Creates the `employees` table if it doesn't exist.
5. **insertEmployee function**: Inserts a new employee into the database.
6. **getEmployees function**: Retrieves all employees from the database.
7. **main function**: Orchestrates the program flow, demonstrating database connection, table creation, data insertion, and retrieval.
</div>
## Usage
To run the application, use the following command in your Cursor terminal:
```bash
go run main.go
```
This will execute the `main` function, demonstrating the connection to the database, table creation, data insertion, and querying.
## Best Practices
1. Use environment variables for database credentials.
2. Always handle potential errors using proper error checking.
3. Close the database connection after operations are complete.
4. Use prepared statements for queries to prevent SQL injection.
5. Consider using a connection pool for better performance in production environments.
## Troubleshooting
If you encounter connection issues:
1. Verify your database credentials in the `.env` file.
2. Ensure your MySQL database is running and accessible.
3. Check for any network restrictions in your DevBox environment.
4. Confirm that the required packages are correctly installed.
For more detailed information on using MySQL with Go, refer to the [go-sql-driver/mysql documentation](https://github.com/go-sql-driver/mysql).
file: ./content/docs/guides/databases/mysql/index.en.mdx
meta: {
"title": "MySQL",
"description": "Deploy and connect to MySQL databases in Sealos DevBox"
}
MySQL is a popular, open-source relational database management system. In Sealos DevBox, you can easily set up and connect to MySQL databases for your development projects.
## Deploy MySQL in Sealos
Sealos makes it easy to deploy a MySQL database with just a few clicks. Follow these steps:
<div className="fd-steps [&_h5]:fd-step">
<h5>From the Sealos desktop, click on the "Database" icon to open the Database app.</h5>
<h5>Click on the "Create New Database" button. In the deployment form:</h5>
* Select "MySQL" as the database type.
* Choose the desired MySQL version (e.g., ac-mysql-8.0.30).
* Enter a name for your database (use lowercase letters and numbers only).
* Adjust the CPU and Memory sliders to set the resources for your database.
* Set the number of replicas (1 for single-node development and testing).
* Specify the storage size (e.g., 3 Gi).
<h5>Review the projected cost on the left sidebar. Click the "Deploy" button in the top right corner to create your MySQL database.</h5>
</div>
Once deployed, Sealos will provide you with the necessary connection details.
## Connect to MySQL in DevBox
Here are examples of how to connect to your MySQL database using different programming languages and frameworks within your DevBox environment:
<Cards>
<Card title="Connect to MySQL with Go in Sealos DevBox" href="./mysql/go" />
<Card title="Connect to MySQL with Java in Sealos DevBox" href="./mysql/java" />
<Card title="Connect to MySQL with Node.js in Sealos DevBox" href="./mysql/nodejs" />
<Card title="Connect to MySQL with PHP in Sealos DevBox" href="./mysql/php" />
<Card title="Connect to MySQL with Python in Sealos DevBox" href="./mysql/python" />
<Card title="Connect to MySQL with Rust in Sealos DevBox" href="./mysql/rust" />
</Cards>
file: ./content/docs/guides/databases/mysql/java.en.mdx
meta: {
"title": "Java",
"description": "Learn how to connect to MySQL databases in Sealos DevBox using Java"
}
This guide will walk you through the process of connecting to a MySQL database using Java within your Sealos DevBox project, including basic CRUD (Create, Read, Update, Delete) operations.
## Prerequisites
* [A Sealos DevBox project](/docs/guides/devbox/create-a-project) with Java environment
* [A MySQL database created using the Database app in Sealos](./)
## Setup
<div className="fd-steps [&_h4]:fd-step">
#### Download MySQL JDBC Driver
To connect to the MySQL server from a Java program, you need a MySQL JDBC driver.
You can download the latest version of the driver from the [MySQL Connector/J download page](https://dev.mysql.com/downloads/connector/j/). The downloaded file is a JAR file, e.g., mysql-connector-j-9.0.0.jar.
#### Create a database configuration file
Create a file named `db.properties` in your project directory with the following content:
```ini title="db.properties"
db.url=jdbc:mysql://your_database_host:3306/your_database_name
db.username=your_username
db.password=your_password
```
Replace the placeholders with your actual MySQL credentials from the Database app in Sealos.
#### Create a DatabaseConfig class
Create a new file named `DatabaseConfig.java` with the following content:
```java title="DatabaseConfig.java"
import java.io.IOException;
import java.io.InputStream;
import java.util.Properties;
public class DatabaseConfig {
private static final Properties properties = new Properties();
static {
try (InputStream input = DatabaseConfig.class.getClassLoader().getResourceAsStream("db.properties")) {
if (input == null) {
System.out.println("Sorry, unable to find db.properties");
System.exit(1);
}
properties.load(input);
} catch (IOException e) {
e.printStackTrace();
}
}
public static String getDbUrl() {
return properties.getProperty("db.url");
}
public static String getDbUsername() {
return properties.getProperty("db.username");
}
public static String getDbPassword() {
return properties.getProperty("db.password");
}
}
```
The `DatabaseConfig` class is responsible for loading database configuration from the `db.properties` file. It has three static methods that expose the database configuration:
* `getDbUrl()` – Returns the database URL.
* `getDbUsername()` – Returns the username.
* `getDbPassword()` – Returns the password.
This class ensures that sensitive database credentials are not hardcoded in the application.
#### Create an Employee class
Create a new file named `Employee.java` with the following content:
```java title="Employee.java"
public class Employee {
private int id;
private String name;
private String position;
public Employee(int id, String name, String position) {
this.id = id;
this.name = name;
this.position = position;
}
// Getters and setters
public int getId() { return id; }
public void setId(int id) { this.id = id; }
public String getName() { return name; }
public void setName(String name) { this.name = name; }
public String getPosition() { return position; }
public void setPosition(String position) { this.position = position; }
@Override
public String toString() {
return "Employee{" +
"id=" + id +
", name='" + name + '\'' +
", position='" + position + '\'' +
'}';
}
}
```
The `Employee` class represents the data model for an employee. It includes fields for id, name, and position, along with a constructor, getters, setters, and a `toString` method for easy printing of employee information.
#### Create a DB class
Create a new file named `DB.java` with the following content:
```java title="DB.java"
import java.sql.*;
import java.util.ArrayList;
import java.util.List;
public class DB {
public static Connection getConnection() throws SQLException {
String jdbcUrl = DatabaseConfig.getDbUrl();
String user = DatabaseConfig.getDbUsername();
String password = DatabaseConfig.getDbPassword();
return DriverManager.getConnection(jdbcUrl, user, password);
}
public static void createTable() throws SQLException {
String sql = "CREATE TABLE IF NOT EXISTS employees (" +
"id INT AUTO_INCREMENT PRIMARY KEY," +
"name VARCHAR(100) NOT NULL," +
"position VARCHAR(100) NOT NULL)";
try (Connection conn = getConnection();
Statement stmt = conn.createStatement()) {
stmt.execute(sql);
}
}
public static void insertEmployee(String name, String position) throws SQLException {
String sql = "INSERT INTO employees (name, position) VALUES (?, ?)";
try (Connection conn = getConnection();
PreparedStatement pstmt = conn.prepareStatement(sql)) {
pstmt.setString(1, name);
pstmt.setString(2, position);
pstmt.executeUpdate();
}
}
public static List<Employee> getEmployees() throws SQLException {
List<Employee> employees = new ArrayList<>();
String sql = "SELECT id, name, position FROM employees";
try (Connection conn = getConnection();
Statement stmt = conn.createStatement();
ResultSet rs = stmt.executeQuery(sql)) {
while (rs.next()) {
employees.add(new Employee(
rs.getInt("id"),
rs.getString("name"),
rs.getString("position")
));
}
}
return employees;
}
public static void updateEmployee(int id, String name, String position) throws SQLException {
String sql = "UPDATE employees SET name = ?, position = ? WHERE id = ?";
try (Connection conn = getConnection();
PreparedStatement pstmt = conn.prepareStatement(sql)) {
pstmt.setString(1, name);
pstmt.setString(2, position);
pstmt.setInt(3, id);
pstmt.executeUpdate();
}
}
public static void deleteEmployee(int id) throws SQLException {
String sql = "DELETE FROM employees WHERE id = ?";
try (Connection conn = getConnection();
PreparedStatement pstmt = conn.prepareStatement(sql)) {
pstmt.setInt(1, id);
pstmt.executeUpdate();
}
}
}
```
The `DB` class is responsible for database operations:
* The `getConnection()` method connects to the MySQL database using the connection parameters from `DatabaseConfig`.
* It returns a `Connection` object if successful, or throws a `SQLException` if there's an error.
* Other methods (`createTable`, `insertEmployee`, etc.) use this connection to perform CRUD operations.
* Each method opens a new connection, performs its operation, and then closes the connection using try-with-resources, ensuring proper resource management.
#### Create the main Java program
Create a new file named `Main.java` with the following content:
```java title="Main.java"
import java.sql.SQLException;
import java.util.List;
public class Main {
public static void main(String[] args) {
try {
System.out.println("Connecting to the MySQL database...");
// Create the employees table
DB.createTable();
System.out.println("Employees table created (if not exists).");
// Insert sample employees
DB.insertEmployee("John Doe", "Developer");
DB.insertEmployee("Jane Smith", "Designer");
System.out.println("Sample employees inserted.");
// Retrieve and display all employees
List<Employee> employees = DB.getEmployees();
System.out.println("Employees:");
for (Employee emp : employees) {
System.out.println(emp);
}
// Update an employee
DB.updateEmployee(1, "John Doe", "Senior Developer");
System.out.println("Employee updated.");
// Delete an employee
DB.deleteEmployee(2);
System.out.println("Employee deleted.");
// Display updated employee list
employees = DB.getEmployees();
System.out.println("\nUpdated Employees:");
for (Employee emp : employees) {
System.out.println(emp);
}
} catch (SQLException e) {
System.err.println("Database operation error: " + e.getMessage());
}
}
}
```
The `Main` class demonstrates the usage of the `DB` class to perform various database operations:
* It creates a table, inserts sample data, retrieves and displays employees, updates an employee, deletes an employee, and displays the updated list.
* Each operation is wrapped in a try-catch block to handle potential `SQLException`s.
* The program uses the methods from the `DB` class, which manage their own connections, ensuring that connections are properly opened and closed for each operation.
</div>
## Compile and Run
To compile and run the example, use the following commands in your terminal:
```bash
javac -cp .:mysql-connector-j-9.0.0.jar *.java
java -cp .:mysql-connector-j-9.0.0.jar Main
```
Make sure to replace `mysql-connector-j-9.0.0.jar` with the actual name of your MySQL JDBC driver JAR file.
If everything is set up correctly, you should see output demonstrating the CRUD operations on the employees table.
## Best Practices
1. Use a properties file to store database connection details.
2. Implement a configuration class to load and provide access to database properties.
3. Create a separate class for database connection management and operations.
4. Use try-with-resources to ensure proper closure of database connections.
5. Use prepared statements to prevent SQL injection.
6. Handle exceptions appropriately and provide meaningful error messages.
## Troubleshooting
If you encounter connection issues:
1. Verify your database credentials in the `db.properties` file.
2. Ensure your MySQL database is running and accessible from your DevBox environment.
3. Check for any network restrictions in your DevBox environment.
4. Confirm that the MySQL JDBC driver JAR file is in the same directory as your Java files.
For more detailed information on using MySQL with Java, refer to the [official MySQL Connector/J documentation](https://dev.mysql.com/doc/connector-j/en/).
file: ./content/docs/guides/databases/mysql/nodejs.en.mdx
meta: {
"title": "Node.js",
"description": "Learn how to connect to MySQL databases in Sealos DevBox using Node.js"
}
This guide will walk you through the process of connecting to a MySQL database using Node.js within your Sealos DevBox project.
## Prerequisites
* [A Sealos DevBox project](/docs/guides/devbox/create-a-project) with Node.js environment
* [A MySQL database created using the Database app in Sealos](./)
## Install Required Packages
In your Cursor terminal, install the necessary packages:
```bash
npm install mysql2 dotenv
```
This command installs:
* `mysql2`: A MySQL client for Node.js with focus on performance
* `dotenv`: A zero-dependency module that loads environment variables from a `.env` file
## Connection Setup
<div className="fd-steps [&_h4]:fd-step">
#### Set up the environment and create a client
First, we'll create a `.env` file to store our database credentials and a configuration file to load them:
```ini title=".env"
DB_HOST=your_database_host
DB_USER=your_username
DB_PASSWORD=your_password
DB_NAME=your_database_name
DB_PORT=3306
```
Replace the placeholders with your actual MySQL credentials from the Database app in Sealos.
Next, create a file named `db.js` with the following content:
```javascript title="db.js"
const mysql = require('mysql2/promise');
require('dotenv').config();
const pool = mysql.createPool({
host: process.env.DB_HOST,
user: process.env.DB_USER,
password: process.env.DB_PASSWORD,
database: process.env.DB_NAME,
port: process.env.DB_PORT,
waitForConnections: true,
connectionLimit: 10,
queueLimit: 0
});
module.exports = pool;
```
This creates a connection pool, which is more efficient for handling multiple database operations.
#### Create database operations
Now, let's create a file named `dbOperations.js` to handle our database operations:
```javascript title="dbOperations.js"
const pool = require('./db');
async function createTable() {
const createTableQuery = `
CREATE TABLE IF NOT EXISTS employees (
id INT AUTO_INCREMENT PRIMARY KEY,
name VARCHAR(100) NOT NULL,
position VARCHAR(100) NOT NULL
)
`;
await pool.query(createTableQuery);
console.log('Table created successfully');
}
async function insertEmployee(name, position) {
const insertQuery = 'INSERT INTO employees (name, position) VALUES (?, ?)';
const [result] = await pool.query(insertQuery, [name, position]);
console.log('Employee inserted:', result.insertId);
return result.insertId;
}
async function updateEmployee(id, name, position) {
const updateQuery = 'UPDATE employees SET name = ?, position = ? WHERE id = ?';
const [result] = await pool.query(updateQuery, [name, position, id]);
console.log('Employee updated:', result.affectedRows > 0);
return result.affectedRows > 0;
}
async function getAllEmployees() {
const selectQuery = 'SELECT * FROM employees';
const [rows] = await pool.query(selectQuery);
console.log('All employees:', rows);
return rows;
}
async function deleteEmployee(id) {
const deleteQuery = 'DELETE FROM employees WHERE id = ?';
const [result] = await pool.query(deleteQuery, [id]);
console.log('Employee deleted:', result.affectedRows > 0);
return result.affectedRows > 0;
}
module.exports = {
createTable,
insertEmployee,
updateEmployee,
getAllEmployees,
deleteEmployee
};
```
#### Create a main script
Finally, let's create a `main.js` file to demonstrate all the operations:
```javascript title="main.js"
const {
createTable,
insertEmployee,
updateEmployee,
getAllEmployees,
deleteEmployee
} = require('./dbOperations');
async function main() {
try {
await createTable();
const johnId = await insertEmployee('John Doe', 'Developer');
await insertEmployee('Jane Smith', 'Designer');
await updateEmployee(johnId, 'John Updated', 'Senior Developer');
const employees = await getAllEmployees();
console.log('Current employees:', employees);
await deleteEmployee(johnId);
const remainingEmployees = await getAllEmployees();
console.log('Remaining employees:', remainingEmployees);
} catch (error) {
console.error('An error occurred:', error);
} finally {
process.exit();
}
}
main();
```
</div>
## Usage
To run the script, use the following command in your Cursor terminal:
```bash
node main.js
```
This will execute all the operations defined in the `main` function, demonstrating the connection to the database, table creation, data insertion, updating, querying, and deletion.
## Best Practices
1. Use environment variables for database credentials.
2. Use connection pooling for better performance.
3. Use prepared statements to prevent SQL injection.
4. Always handle potential errors using try-catch blocks.
5. Close the database connection after operations are complete (in this case, the pool handles this automatically).
## Troubleshooting
If you encounter connection issues:
1. Verify your database credentials in the `.env` file.
2. Ensure your MySQL database is running and accessible.
3. Check for any network restrictions in your DevBox environment.
4. Confirm that the `mysql2` package is correctly installed.
For more detailed information on using MySQL with Node.js, refer to the [mysql2 documentation](https://github.com/sidorares/node-mysql2#readme).
file: ./content/docs/guides/databases/mysql/php.en.mdx
meta: {
"title": "PHP",
"description": "Learn how to connect to MySQL databases in Sealos DevBox using PHP"
}
This guide will walk you through the process of connecting to a MySQL database using PHP within your Sealos DevBox project.
## Prerequisites
* [A Sealos DevBox project](/docs/guides/devbox/create-a-project) with PHP environment
* [A MySQL database created using the Database app in Sealos](./)
## Install Required Extensions
In your Cursor terminal, ensure that the MySQL extension for PHP is installed:
```bash
sudo apt-get update
sudo apt-get install php-mysql -y
```
## Connection Setup
<div className="fd-steps [&_h4]:fd-step">
#### Create a Configuration File
First, let's create a configuration file to store our database connection parameters. Create a file named `config.php` in your project directory with the following content:
```php title="config.php"
<?php
return [
'host' => 'your_database_host',
'port' => '3306',
'dbname' => 'your_database_name',
'user' => 'your_username',
'password' => 'your_password'
];
```
Replace the placeholders with your actual MySQL credentials from the Database app in Sealos.
#### Create a Database Connection Function
Next, let's create a PHP file that will handle the database connection. Create a file named `db_connect.php` with the following content:
```php title="db_connect.php"
<?php
function getDbConnection() {
$config = include 'config.php';
$dsn = "mysql:host={$config['host']};port={$config['port']};dbname={$config['dbname']};charset=utf8mb4";
try {
$pdo = new PDO($dsn, $config['user'], $config['password'], [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION]);
echo "Connected successfully to the database.\n";
return $pdo;
} catch (PDOException $e) {
die("Connection failed: " . $e->getMessage());
}
}
```
This function reads the configuration from `config.php` and establishes a connection to the MySQL database using PDO (PHP Data Objects).
#### Create a Test Script
Now, let's create a test script to verify our connection and perform some basic database operations. Create a file named `test_db.php` with the following content:
```php title="test_db.php"
<?php
require_once 'db_connect.php';
$pdo = getDbConnection();
// Create a table
$pdo->exec("CREATE TABLE IF NOT EXISTS employees (
id INT AUTO_INCREMENT PRIMARY KEY,
name VARCHAR(100) NOT NULL,
position VARCHAR(100) NOT NULL
)");
echo "Table created successfully.\n";
// Insert a record
$stmt = $pdo->prepare("INSERT INTO employees (name, position) VALUES (?, ?)");
$stmt->execute(['John Doe', 'Developer']);
echo "Record inserted successfully.\n";
// Query the table
$stmt = $pdo->query("SELECT * FROM employees");
echo "Employees:\n";
while ($row = $stmt->fetch(PDO::FETCH_ASSOC)) {
echo "ID: {$row['id']}, Name: {$row['name']}, Position: {$row['position']}\n";
}
// Close the connection
$pdo = null;
```
This script demonstrates creating a table, inserting a record, and querying the table.
</div>
## Usage
To run the test script, use the following command in your Cursor terminal:
```bash
php test_db.php
```
This will execute the script, demonstrating the connection to the database, table creation, data insertion, and querying.
## Best Practices
1. Use environment variables or a separate configuration file for database credentials.
2. Always use prepared statements to prevent SQL injection.
3. Handle potential errors using try-catch blocks.
4. Close the database connection after operations are complete.
5. Use connection pooling for better performance in production environments.
## Troubleshooting
If you encounter connection issues:
1. Verify your database credentials in the `config.php` file.
2. Ensure your MySQL database is running and accessible.
3. Check for any network restrictions in your DevBox environment.
4. Confirm that the `php-mysql` extension is correctly installed.
For more detailed information on using MySQL with PHP, refer to the [official PHP MySQL documentation](https://www.php.net/manual/en/book.mysql.php).
file: ./content/docs/guides/databases/mysql/python.en.mdx
meta: {
"title": "Python",
"description": "Learn how to connect to MySQL databases in Sealos DevBox using Python"
}
This guide will walk you through the process of connecting to a MySQL database using Python within your Sealos DevBox project.
## Prerequisites
* [A Sealos DevBox project](/docs/guides/devbox/create-a-project) with Python environment
* [A MySQL database created using the Database app in Sealos](./)
## Activating the Python Environment
Before you start, you need to activate the Python virtual environment in your DevBox. Open the terminal within Cursor IDE and run:
```bash
source ./bin/activate
```
You should see your prompt change, indicating that the virtual environment is now active.
## Installing Required Packages
In your Cursor terminal, install the necessary packages:
```bash
pip install mysql-connector-python python-dotenv
```
This command installs:
* `mysql-connector-python`: The official MySQL driver for Python
* `python-dotenv`: A Python package that allows you to load environment variables from a .env file
## Connection Setup
<div className="fd-steps [&_h4]:fd-step">
#### Set up the environment variables
First, let's set up the environment variables for our database connection. Create a `.env` file in your project root with the following content:
```ini title=".env"
DB_HOST=your_database_host
DB_USER=your_username
DB_PASSWORD=your_password
DB_NAME=your_database_name
DB_PORT=3306
```
Replace the placeholders with your actual MySQL credentials from the Database app in Sealos.
#### Create a database connection module
Create a new file named `db_connection.py` with the following content:
```python title="db_connection.py"
import os
from dotenv import load_dotenv
import mysql.connector
from mysql.connector import Error
# Load environment variables
load_dotenv()
def get_db_connection():
try:
# First, connect without specifying a database
connection = mysql.connector.connect(
host=os.getenv('DB_HOST'),
user=os.getenv('DB_USER'),
password=os.getenv('DB_PASSWORD'),
port=os.getenv('DB_PORT')
)
if connection.is_connected():
cursor = connection.cursor()
# Create the database if it doesn't exist
db_name = os.getenv('DB_NAME')
cursor.execute(f"CREATE DATABASE IF NOT EXISTS {db_name}")
# Close the initial connection
cursor.close()
connection.close()
# Reconnect with the database specified
connection = mysql.connector.connect(
host=os.getenv('DB_HOST'),
user=os.getenv('DB_USER'),
password=os.getenv('DB_PASSWORD'),
database=db_name,
port=os.getenv('DB_PORT')
)
if connection.is_connected():
print(f"Successfully connected to MySQL database '{db_name}'")
return connection
except Error as e:
print(f"Error connecting to MySQL database: {e}")
return None
def close_connection(connection):
if connection:
connection.close()
print("MySQL connection closed")
```
This module provides two main functions:
1. `get_db_connection()`: This function establishes a connection to the MySQL database using the credentials stored in the environment variables. It returns the connection object if successful, or None if an error occurs.
2. `close_connection(connection)`: This function closes the database connection when it's no longer needed.
#### Create a test script
Now, let's create a test script to verify our connection and perform some basic database operations. Create a file named `test_mysql.py` with the following content:
```python title="test_mysql.py"
from mysql.connector import Error
from db_connection import get_db_connection, close_connection
def create_table(cursor):
create_table_query = """
CREATE TABLE IF NOT EXISTS employees (
id INT AUTO_INCREMENT PRIMARY KEY,
name VARCHAR(100),
email VARCHAR(100)
)
"""
cursor.execute(create_table_query)
print("Table 'employees' created successfully")
def insert_employee(cursor, name, email):
insert_query = "INSERT INTO employees (name, email) VALUES (%s, %s)"
cursor.execute(insert_query, (name, email))
print(f"Employee {name} inserted successfully")
def get_all_employees(cursor):
select_query = "SELECT * FROM employees"
cursor.execute(select_query)
employees = cursor.fetchall()
for employee in employees:
print(f"ID: {employee[0]}, Name: {employee[1]}, Email: {employee[2]}")
def main():
connection = get_db_connection()
if connection:
try:
cursor = connection.cursor()
create_table(cursor)
insert_employee(cursor, "John Doe", "john@example.com")
insert_employee(cursor, "Jane Smith", "jane@example.com")
print("\nAll Employees:")
get_all_employees(cursor)
connection.commit()
except Error as e:
print(f"Error: {e}")
finally:
if cursor:
cursor.close()
close_connection(connection)
if __name__ == "__main__":
main()
```
Let's break down the main components of this script:
1. `create_table(cursor)`: This function creates a table named 'employees' if it doesn't already exist. It demonstrates how to execute a CREATE TABLE SQL statement.
2. `insert_employee(cursor, name, email)`: This function inserts a new employee record into the 'employees' table. It shows how to use parameterized queries to safely insert data.
3. `get_all_employees(cursor)`: This function retrieves all records from the 'employees' table and prints them. It demonstrates how to execute a SELECT query and fetch results.
4. `main()`: This is the main function that ties everything together. It:
* Establishes a database connection
* Creates the 'employees' table
* Inserts two sample employees
* Retrieves and prints all employees
* Handles any exceptions that might occur
* Ensures that the cursor and connection are properly closed
</div>
## Running the Test Script
To run the test script, make sure your virtual environment is activated, then execute:
```bash
python test_mysql.py
```
If everything is set up correctly, you should see output indicating successful connection, table creation, data insertion, and retrieval.
## Best Practices
1. Always activate the virtual environment before running your Python scripts or installing packages.
2. Use environment variables to store sensitive information like database credentials.
3. Close database connections and cursors after use to free up resources.
4. Use parameterized queries to prevent SQL injection.
5. Handle exceptions appropriately to manage potential errors.
## Troubleshooting
If you encounter connection issues:
1. Ensure you've activated the virtual environment with `source ./bin/activate`.
2. Verify that your MySQL database is running and accessible.
3. Double-check your database credentials in the `.env` file.
4. Check the MySQL logs in the Database app for any error messages.
For more detailed information on using MySQL with Python, refer to the [official MySQL Connector/Python documentation](https://dev.mysql.com/doc/connector-python/en/).
file: ./content/docs/guides/databases/mysql/rust.en.mdx
meta: {
"title": "Rust",
"description": "Learn how to connect to MySQL databases in Sealos DevBox using Rust"
}
This guide will walk you through the process of connecting to a MySQL database using Rust within your Sealos DevBox project.
## Prerequisites
* [A Sealos DevBox project](/docs/guides/devbox/create-a-project) with Rust environment
* [A MySQL database created using the Database app in Sealos](./)
## Install Required Dependencies
In your Cursor terminal, add the necessary dependencies to your `Cargo.toml` file:
```toml
[dependencies]
tokio = { version = "1.28", features = ["full"] }
sqlx = { version = "0.6", features = ["runtime-tokio-rustls", "mysql"] }
dotenv = "0.15"
```
These dependencies include:
* `tokio`: An asynchronous runtime for Rust
* `sqlx`: A database toolkit for Rust with async support
* `dotenv`: A library for loading environment variables from a file
## Connection Setup
<div className="fd-steps [&_h4]:fd-step">
#### Set up the environment variables
First, let's set up the environment variables for our database connection. Create a `.env` file in your project root with the following content:
```ini title=".env"
DATABASE_URL=mysql://your_username:your_password@your_database_host:3306/your_database_name
```
Replace the placeholders with your actual MySQL credentials from the Database app in Sealos.
#### Create the main.rs file
Create a new file named `src/main.rs` with the following content:
```rust title="src/main.rs"
use sqlx::mysql::MySqlPoolOptions;
use sqlx::Row;
use dotenv::dotenv;
use std::env;
#[tokio::main]
async fn main() -> Result<(), sqlx::Error> {
// Load environment variables from .env file
dotenv().ok();
// Get the database URL from the environment
let database_url = env::var("DATABASE_URL").expect("DATABASE_URL must be set");
// Create a connection pool
let pool = MySqlPoolOptions::new()
.max_connections(5)
.connect(&database_url)
.await?;
// Create the employees table if it doesn't exist
sqlx::query(
r#"
CREATE TABLE IF NOT EXISTS employees (
id INT AUTO_INCREMENT PRIMARY KEY,
name VARCHAR(100) NOT NULL,
position VARCHAR(100) NOT NULL
)
"#,
)
.execute(&pool)
.await?;
println!("Table created successfully");
// Insert a sample employee
let new_employee = sqlx::query(
r#"
INSERT INTO employees (name, position)
VALUES (?, ?)
"#,
)
.bind("John Doe")
.bind("Developer")
.execute(&pool)
.await?;
println!(
"Inserted employee: ID: {}",
new_employee.last_insert_id()
);
// Query all employees
let employees = sqlx::query("SELECT id, name, position FROM employees")
.fetch_all(&pool)
.await?;
println!("All employees:");
for employee in employees {
println!(
"ID: {}, Name: {}, Position: {}",
employee.get::<i32, _>("id"),
employee.get::<String, _>("name"),
employee.get::<String, _>("position")
);
}
Ok(())
}
```
Let's break down the main components of this code:
1. **Imports**: We import necessary modules from `sqlx`, `dotenv`, and `std::env`.
2. **Main function**: The `main` function is marked with `#[tokio::main]` to use Tokio's async runtime.
3. **Environment setup**: We load environment variables from the `.env` file and retrieve the database URL.
4. **Connection pool**: We create a connection pool using `MySqlPoolOptions`.
5. **Table creation**: We create the `employees` table if it doesn't exist.
6. **Data insertion**: We insert a sample employee into the database.
7. **Data querying**: We query and display all employees in the database.
</div>
## Usage
To run the application, use the following command in your Cursor terminal:
```bash
cargo run
```
This will compile and execute the `main` function, demonstrating the connection to the database, table creation, data insertion, and querying.
## Best Practices
1. Use environment variables for database credentials.
2. Use connection pooling for better performance and resource management.
3. Use prepared statements (as demonstrated with `sqlx::query`) to prevent SQL injection.
4. Handle errors appropriately using Rust's `Result` type.
5. Use async/await for efficient database operations.
## Troubleshooting
If you encounter connection issues:
1. Verify your database credentials in the `.env` file.
2. Ensure your MySQL database is running and accessible.
3. Check for any network restrictions in your DevBox environment.
4. Confirm that all required dependencies are correctly specified in your `Cargo.toml` file.
For more detailed information on using MySQL with Rust, refer to the [sqlx documentation](https://github.com/launchbadge/sqlx).
file: ./content/docs/guides/databases/postgresql/go.en.mdx
meta: {
"title": "Go",
"description": "Learn how to connect to PostgreSQL databases in Sealos DevBox using Go"
}
This guide will walk you through the process of connecting to a PostgreSQL database using Go within your Sealos DevBox project.
## Prerequisites
* [A Sealos DevBox project](/docs/guides/devbox/create-a-project) with Go environment
* [A PostgreSQL database created using the Database app in Sealos](./)
## Install Required Packages
In your Cursor terminal, install the necessary packages:
```bash
go get github.com/lib/pq
go get github.com/joho/godotenv
```
These commands install:
* `github.com/lib/pq`: A pure Go PostgreSQL driver for the database/sql package
* `github.com/joho/godotenv`: A Go port of the Ruby dotenv library
## Connection Setup
<div className="fd-steps [&_h4]:fd-step">
#### Set up the environment variables
First, let's set up the environment variables for our database connection. Create a `.env` file in your project root with the following content:
```ini title=".env"
DB_HOST=your_database_host
DB_PORT=5432
DB_USER=your_username
DB_PASSWORD=your_password
DB_NAME=your_database_name
```
Replace the placeholders with your actual PostgreSQL credentials from the Database app in Sealos.
#### Create the main.go file
Create a new file named `main.go` with the following content:
```go title="main.go"
package main
import (
"database/sql"
"fmt"
"log"
"os"
"github.com/joho/godotenv"
_ "github.com/lib/pq"
)
// Employee struct represents the structure of our data
type Employee struct {
ID int
Name string
Position string
}
// connectDB establishes a connection to the PostgreSQL database
func connectDB() (*sql.DB, error) {
// Load environment variables from .env file
err := godotenv.Load()
if err != nil {
log.Fatal("Error loading .env file")
}
// Retrieve database connection details from environment variables
dbHost := os.Getenv("DB_HOST")
dbPort := os.Getenv("DB_PORT")
dbUser := os.Getenv("DB_USER")
dbPassword := os.Getenv("DB_PASSWORD")
dbName := os.Getenv("DB_NAME")
// Construct the connection string
connStr := fmt.Sprintf("host=%s port=%s user=%s password=%s dbname=%s sslmode=disable",
dbHost, dbPort, dbUser, dbPassword, dbName)
// Open a connection to the database
db, err := sql.Open("postgres", connStr)
if err != nil {
return nil, err
}
// Verify the connection
err = db.Ping()
if err != nil {
return nil, err
}
fmt.Println("Successfully connected to the database")
return db, nil
}
// createTable creates the employees table if it doesn't exist
func createTable(db *sql.DB) error {
_, err := db.Exec(`
CREATE TABLE IF NOT EXISTS employees (
id SERIAL PRIMARY KEY,
name VARCHAR(100) NOT NULL,
position VARCHAR(100) NOT NULL
)
`)
return err
}
// insertEmployee inserts a new employee into the database
func insertEmployee(db *sql.DB, name, position string) error {
_, err := db.Exec("INSERT INTO employees (name, position) VALUES ($1, $2)", name, position)
return err
}
// getEmployees retrieves all employees from the database
func getEmployees(db *sql.DB) ([]Employee, error) {
rows, err := db.Query("SELECT id, name, position FROM employees")
if err != nil {
return nil, err
}
defer rows.Close()
var employees []Employee
for rows.Next() {
var emp Employee
err := rows.Scan(&emp.ID, &emp.Name, &emp.Position)
if err != nil {
return nil, err
}
employees = append(employees, emp)
}
return employees, nil
}
func main() {
// Connect to the database
db, err := connectDB()
if err != nil {
log.Fatal(err)
}
// Ensure the database connection is closed when the function exits
defer func() {
if err := db.Close(); err != nil {
log.Printf("Error closing database connection: %v", err)
} else {
fmt.Println("Database connection closed successfully")
}
}()
// Create the employees table
err = createTable(db)
if err != nil {
log.Fatal(err)
}
// Insert sample employees
err = insertEmployee(db, "John Doe", "Developer")
if err != nil {
log.Fatal(err)
}
err = insertEmployee(db, "Jane Smith", "Designer")
if err != nil {
log.Fatal(err)
}
// Retrieve and display all employees
employees, err := getEmployees(db)
if err != nil {
log.Fatal(err)
}
fmt.Println("Employees:")
for _, emp := range employees {
fmt.Printf("ID: %d, Name: %s, Position: %s\n", emp.ID, emp.Name, emp.Position)
}
// The database connection will be closed automatically when main() exits
// due to the defer statement at the beginning of the function
}
```
Let's break down the main components of this code:
1. **Imports**: We import necessary packages, including `database/sql` for database operations and `github.com/lib/pq` as the PostgreSQL driver.
2. **Employee struct**: Defines the structure for our employee data.
3. **connectDB function**: Loads environment variables, constructs the connection string, and establishes a connection to the database.
4. **createTable function**: Creates the `employees` table if it doesn't exist.
5. **insertEmployee function**: Inserts a new employee into the database.
6. **getEmployees function**: Retrieves all employees from the database.
7. **main function**: Orchestrates the program flow, demonstrating database connection, table creation, data insertion, and retrieval.
</div>
## Usage
To run the application, use the following command in your Cursor terminal:
```bash
go run main.go
```
This will execute the `main` function, demonstrating the connection to the database, table creation, data insertion, and querying.
## Best Practices
1. Use environment variables for database credentials.
2. Always handle potential errors using proper error checking.
3. Close the database connection after operations are complete.
4. Use prepared statements for queries to prevent SQL injection.
5. Consider using a connection pool for better performance in production environments.
## Troubleshooting
If you encounter connection issues:
1. Verify your database credentials in the `.env` file.
2. Ensure your PostgreSQL database is running and accessible.
3. Check for any network restrictions in your DevBox environment.
4. Confirm that the required packages are correctly installed.
For more detailed information on using PostgreSQL with Go, refer to the [lib/pq documentation](https://pkg.go.dev/github.com/lib/pq).
file: ./content/docs/guides/databases/postgresql/index.en.mdx
meta: {
"title": "PostgreSQL",
"description": "Deploy and connect to PostgreSQL databases in Sealos DevBox"
}
PostgreSQL is a powerful, open-source object-relational database system. In Sealos DevBox, you can easily set up and connect to PostgreSQL databases for your development projects.
## Deploy PostgreSQL in Sealos
Sealos makes it easy to deploy a PostgreSQL database with just a few clicks. follow these steps:
<div className="fd-steps [&_h5]:fd-step">
<h5>From the Sealos desktop, click on the "Database" icon to open the Database app.</h5>
<h5>Click on the "Create New Database" button. In the deployment form:</h5>
* Select "Postgres" as the database type.
* Choose the desired PostgreSQL version (e.g., postgresql-14.8.0).
* Enter a name for your database (use lowercase letters and numbers only).
* Adjust the CPU and Memory sliders to set the resources for your database.
* Set the number of replicas (1 for single-node development and testing).
* Specify the storage size (e.g., 3 Gi).
<h5>Review the projected cost on the left sidebar. Click the "Deploy" button in the top right corner to create your PostgreSQL database.</h5>
</div>
Once deployed, Sealos will provide you with the necessary connection details.
## Connect to PostgreSQL in DevBox
Here are examples of how to connect to your PostgreSQL database using different programming languages and frameworks within your DevBox environment:
<Cards>
<Card title="Connect to PostgreSQL with Go in Sealos DevBox" href="./postgresql/go" />
<Card title="Connect to PostgreSQL with Java in Sealos DevBox" href="./postgresql/java" />
<Card title="Connect to PostgreSQL with Node.js in Sealos DevBox" href="./postgresql/nodejs" />
<Card title="Connect to PostgreSQL with PHP in Sealos DevBox" href="./postgresql/php" />
<Card title="Connect to PostgreSQL with Python in Sealos DevBox" href="./postgresql/python" />
<Card title="Connect to PostgreSQL with Rust in Sealos DevBox" href="./postgresql/rust" />
</Cards>
file: ./content/docs/guides/databases/postgresql/java.en.mdx
meta: {
"title": "Java",
"description": "Learn how to connect to PostgreSQL databases in Sealos DevBox using Java"
}
This guide will walk you through the process of connecting to a PostgreSQL database using Java within your Sealos DevBox project, including basic CRUD (Create, Read, Update, Delete) operations.
## Prerequisites
* [A Sealos DevBox project](/docs/guides/devbox/create-a-project) with Java environment
* [A PostgreSQL database created using the Database app in Sealos](./)
## Setup
<div className="fd-steps [&_h4]:fd-step">
#### Download PostgreSQL JDBC Driver
To connect to the PostgreSQL server from a Java program, you need a PostgreSQL JDBC driver.
You can download the latest version of the driver on the [jdbc.postgresql.org download page](https://jdbc.postgresql.org/download/). The downloaded file is a jar file e.g., postgresql-42.7.1.jar.
#### Create a database configuration file
Create a file named `db.properties` in your project directory with the following content:
```ini title="db.properties"
db.url=jdbc:postgresql://your_database_host:5432/your_database_name
db.username=your_username
db.password=your_password
```
Replace the placeholders with your actual PostgreSQL credentials from the Database app in Sealos.
#### Create a DatabaseConfig class
Create a new file named `DatabaseConfig.java` with the following content:
```java title="DatabaseConfig.java"
import java.io.IOException;
import java.io.InputStream;
import java.util.Properties;
public class DatabaseConfig {
private static final Properties properties = new Properties();
static {
try (InputStream input = DatabaseConfig.class.getClassLoader().getResourceAsStream("db.properties")) {
if (input == null) {
System.out.println("Sorry, unable to find db.properties");
System.exit(1);
}
properties.load(input);
} catch (IOException e) {
e.printStackTrace();
}
}
public static String getDbUrl() {
return properties.getProperty("db.url");
}
public static String getDbUsername() {
return properties.getProperty("db.username");
}
public static String getDbPassword() {
return properties.getProperty("db.password");
}
}
```
The `DatabaseConfig` class is responsible for loading database configuration from the `db.properties` file. It has three static methods that expose the database configuration:
* `getDbUrl()` – Returns the database URL.
* `getDbUsername()` – Returns the username.
* `getDbPassword()` – Returns the password.
This class ensures that sensitive database credentials are not hardcoded in the application.
#### Create an Employee class
Create a new file named `Employee.java` with the following content:
```java title="Employee.java"
public class Employee {
private int id;
private String name;
private String position;
public Employee(int id, String name, String position) {
this.id = id;
this.name = name;
this.position = position;
}
// Getters and setters
public int getId() { return id; }
public void setId(int id) { this.id = id; }
public String getName() { return name; }
public void setName(String name) { this.name = name; }
public String getPosition() { return position; }
public void setPosition(String position) { this.position = position; }
@Override
public String toString() {
return "Employee{" +
"id=" + id +
", name='" + name + '\'' +
", position='" + position + '\'' +
'}';
}
}
```
The `Employee` class represents the data model for an employee. It includes fields for id, name, and position, along with a constructor, getters, setters, and a `toString` method for easy printing of employee information.
#### Create a DB class
Create a new file named `DB.java` with the following content:
```java title="DB.java"
import java.sql.*;
import java.util.ArrayList;
import java.util.List;
public class DB {
public static Connection getConnection() throws SQLException {
String jdbcUrl = DatabaseConfig.getDbUrl();
String user = DatabaseConfig.getDbUsername();
String password = DatabaseConfig.getDbPassword();
return DriverManager.getConnection(jdbcUrl, user, password);
}
public static void createTable() throws SQLException {
String sql = "CREATE TABLE IF NOT EXISTS employees (" +
"id SERIAL PRIMARY KEY," +
"name VARCHAR(100) NOT NULL," +
"position VARCHAR(100) NOT NULL)";
try (Connection conn = getConnection();
Statement stmt = conn.createStatement()) {
stmt.execute(sql);
}
}
public static void insertEmployee(String name, String position) throws SQLException {
String sql = "INSERT INTO employees (name, position) VALUES (?, ?)";
try (Connection conn = getConnection();
PreparedStatement pstmt = conn.prepareStatement(sql)) {
pstmt.setString(1, name);
pstmt.setString(2, position);
pstmt.executeUpdate();
}
}
public static List<Employee> getEmployees() throws SQLException {
List<Employee> employees = new ArrayList<>();
String sql = "SELECT id, name, position FROM employees";
try (Connection conn = getConnection();
Statement stmt = conn.createStatement();
ResultSet rs = stmt.executeQuery(sql)) {
while (rs.next()) {
employees.add(new Employee(
rs.getInt("id"),
rs.getString("name"),
rs.getString("position")
));
}
}
return employees;
}
public static void updateEmployee(int id, String name, String position) throws SQLException {
String sql = "UPDATE employees SET name = ?, position = ? WHERE id = ?";
try (Connection conn = getConnection();
PreparedStatement pstmt = conn.prepareStatement(sql)) {
pstmt.setString(1, name);
pstmt.setString(2, position);
pstmt.setInt(3, id);
pstmt.executeUpdate();
}
}
public static void deleteEmployee(int id) throws SQLException {
String sql = "DELETE FROM employees WHERE id = ?";
try (Connection conn = getConnection();
PreparedStatement pstmt = conn.prepareStatement(sql)) {
pstmt.setInt(1, id);
pstmt.executeUpdate();
}
}
}
```
The `DB` class is responsible for database operations:
* The `getConnection()` method connects to the PostgreSQL database using the connection parameters from `DatabaseConfig`.
* It returns a `Connection` object if successful, or throws a `SQLException` if there's an error.
* Other methods (`createTable`, `insertEmployee`, etc.) use this connection to perform CRUD operations.
* Each method opens a new connection, performs its operation, and then closes the connection using try-with-resources, ensuring proper resource management.
#### Create the main Java program
Create a new file named `Main.java` with the following content:
```java title="Main.java"
import java.sql.SQLException;
import java.util.List;
public class Main {
public static void main(String[] args) {
try {
System.out.println("Connecting to the PostgreSQL database...");
// Create the employees table
DB.createTable();
System.out.println("Employees table created (if not exists).");
// Insert sample employees
DB.insertEmployee("John Doe", "Developer");
DB.insertEmployee("Jane Smith", "Designer");
System.out.println("Sample employees inserted.");
// Retrieve and display all employees
List<Employee> employees = DB.getEmployees();
System.out.println("Employees:");
for (Employee emp : employees) {
System.out.println(emp);
}
// Update an employee
DB.updateEmployee(1, "John Doe", "Senior Developer");
System.out.println("Employee updated.");
// Delete an employee
DB.deleteEmployee(2);
System.out.println("Employee deleted.");
// Display updated employee list
employees = DB.getEmployees();
System.out.println("\nUpdated Employees:");
for (Employee emp : employees) {
System.out.println(emp);
}
} catch (SQLException e) {
System.err.println("Database operation error: " + e.getMessage());
}
}
}
```
The `Main` class demonstrates the usage of the `DB` class to perform various database operations:
* It creates a table, inserts sample data, retrieves and displays employees, updates an employee, deletes an employee, and displays the updated list.
* Each operation is wrapped in a try-catch block to handle potential `SQLException`s.
* The program uses the methods from the `DB` class, which manage their own connections, ensuring that connections are properly opened and closed for each operation.
</div>
## Compile and Run
To compile and run the example, use the following commands in your terminal:
```bash
javac -cp .:postgresql-42.6.0.jar *.java
java -cp .:postgresql-42.6.0.jar Main
```
If everything is set up correctly, you should see output demonstrating the CRUD operations on the employees table.
## Best Practices
1. Use a properties file to store database connection details.
2. Implement a configuration class to load and provide access to database properties.
3. Create a separate class for database connection management and operations.
4. Use try-with-resources to ensure proper closure of database connections.
5. Use prepared statements to prevent SQL injection.
6. Handle exceptions appropriately and provide meaningful error messages.
## Troubleshooting
If you encounter connection issues:
1. Verify your database credentials in the `db.properties` file.
2. Ensure your PostgreSQL database is running and accessible from your DevBox environment.
3. Check for any network restrictions in your DevBox environment.
4. Confirm that the PostgreSQL JDBC driver JAR file is in the same directory as your Java files.
For more detailed information on using PostgreSQL with Java, refer to the [official PostgreSQL JDBC driver documentation](https://jdbc.postgresql.org/documentation/head/index.html).
file: ./content/docs/guides/databases/postgresql/nodejs.en.mdx
meta: {
"title": "Node.js",
"description": "Learn how to connect to PostgreSQL databases in Sealos DevBox using Node.js"
}
This guide will walk you through the process of connecting to a PostgreSQL database using Node.js within your Sealos DevBox project.
## Prerequisites
* [A Sealos DevBox project](/docs/guides/devbox/create-a-project) with Node.js environment
* [A PostgreSQL database created using the Database app in Sealos](./)
## Install Required Packages
In your Cursor terminal, install the necessary packages:
```bash
npm install pg dotenv
```
This command installs:
* `pg`: The PostgreSQL client for Node.js
* `dotenv`: A zero-dependency module that loads environment variables from a `.env` file
## Connection Setup
<div className="fd-steps [&_h4]:fd-step">
#### Set up the environment and create a client
First, we'll import the required modules and set up the database configuration:
```javascript
const { Client } = require('pg');
require('dotenv').config();
const dbConfig = {
user: process.env.DB_USER,
password: process.env.DB_PASSWORD,
host: process.env.DB_HOST,
port: process.env.DB_PORT,
database: process.env.DB_NAME,
};
const client = new Client(dbConfig);
```
#### Create connection and query functions
Next, we'll create functions to handle database connection and query execution:
```javascript
async function connectToDatabase() {
try {
await client.connect();
console.log('Connected to PostgreSQL database');
} catch (err) {
console.error('Error connecting to PostgreSQL database', err);
throw err;
}
}
async function executeQuery(query, values = []) {
try {
const result = await client.query(query, values);
return result.rows;
} catch (err) {
console.error('Error executing query', err);
throw err;
}
}
async function closeDatabaseConnection() {
try {
await client.end();
console.log('Connection to PostgreSQL closed');
} catch (err) {
console.error('Error closing connection', err);
}
}
```
#### Implement database operations
Now, let's implement functions for various database operations:
```javascript
async function createTable() {
const createTableQuery = `
CREATE TABLE IF NOT EXISTS employees (
id SERIAL PRIMARY KEY,
name VARCHAR(100) NOT NULL,
position VARCHAR(100) NOT NULL
);
`;
await executeQuery(createTableQuery);
console.log('Table created successfully');
}
async function insertEmployee(name, position) {
const insertQuery = 'INSERT INTO employees(name, position) VALUES ($1, $2) RETURNING *';
const values = [name, position];
const result = await executeQuery(insertQuery, values);
console.log('Employee inserted:', result[0]);
}
async function updateEmployee(id, name, position) {
const updateQuery = 'UPDATE employees SET name = $1, position = $2 WHERE id = $3 RETURNING *';
const values = [name, position, id];
const result = await executeQuery(updateQuery, values);
console.log('Employee updated:', result[0]);
}
async function getAllEmployees() {
const selectQuery = 'SELECT * FROM employees';
const employees = await executeQuery(selectQuery);
console.log('All employees:', employees);
}
```
#### Create a main function to run operations
Finally, let's create a main function to demonstrate all the operations:
```javascript
async function main() {
try {
await connectToDatabase();
await createTable();
await insertEmployee('John Doe', 'Developer');
await insertEmployee('Jane Smith', 'Designer');
await updateEmployee(1, 'John Updated', 'Senior Developer');
await getAllEmployees();
} catch (err) {
console.error('An error occurred:', err);
} finally {
await closeDatabaseConnection();
}
}
main();
```
</div>
Here’s the complete code to connect to the Postgres database with Node.js:
```javascript title="test-connection.js"
const { Client } = require('pg');
require('dotenv').config();
const dbConfig = {
user: process.env.DB_USER,
password: process.env.DB_PASSWORD,
host: process.env.DB_HOST,
port: process.env.DB_PORT,
database: process.env.DB_NAME,
};
const client = new Client(dbConfig);
async function connectToDatabase() {
try {
await client.connect();
console.log('Connected to PostgreSQL database');
} catch (err) {
console.error('Error connecting to PostgreSQL database', err);
throw err;
}
}
async function executeQuery(query, values = []) {
try {
const result = await client.query(query, values);
return result.rows;
} catch (err) {
console.error('Error executing query', err);
throw err;
}
}
async function closeDatabaseConnection() {
try {
await client.end();
console.log('Connection to PostgreSQL closed');
} catch (err) {
console.error('Error closing connection', err);
}
}
async function createTable() {
const createTableQuery = `
CREATE TABLE IF NOT EXISTS employees (
id SERIAL PRIMARY KEY,
name VARCHAR(100) NOT NULL,
position VARCHAR(100) NOT NULL
);
`;
await executeQuery(createTableQuery);
console.log('Table created successfully');
}
async function insertEmployee(name, position) {
const insertQuery = 'INSERT INTO employees(name, position) VALUES ($1, $2) RETURNING *';
const values = [name, position];
const result = await executeQuery(insertQuery, values);
console.log('Employee inserted:', result[0]);
}
async function updateEmployee(id, name, position) {
const updateQuery = 'UPDATE employees SET name = $1, position = $2 WHERE id = $3 RETURNING *';
const values = [name, position, id];
const result = await executeQuery(updateQuery, values);
console.log('Employee updated:', result[0]);
}
async function getAllEmployees() {
const selectQuery = 'SELECT * FROM employees';
const employees = await executeQuery(selectQuery);
console.log('All employees:', employees);
}
async function main() {
try {
await connectToDatabase();
await createTable();
await insertEmployee('John Doe', 'Developer');
await insertEmployee('Jane Smith', 'Designer');
await updateEmployee(1, 'John Updated', 'Senior Developer');
await getAllEmployees();
} catch (err) {
console.error('An error occurred:', err);
} finally {
await closeDatabaseConnection();
}
}
main();
```
## Usage
Before running the script, create a `.env` file in the same directory with the following content:
```ini title=".env"
DB_USER=your_username
DB_PASSWORD=your_password
DB_HOST=your_database_host
DB_PORT=5432
DB_NAME=your_database_name
```
Replace the placeholders with your actual PostgreSQL credentials from the Database app in Sealos.
To test the connection, run the test script:
```bash
node test-connection.js
```
This will execute all the operations defined in the `main` function, demonstrating the connection to the database, table creation, data insertion, updating, and querying.
## Best Practices
1. Use environment variables for database credentials.
2. Always handle potential errors using try-catch blocks.
3. Close the database connection after operations are complete.
4. Use parameterized queries to prevent SQL injection.
5. Consider using connection pooling for better performance in production environments.
## Troubleshooting
If you encounter connection issues:
1. Verify your database credentials in the `.env` file.
2. Ensure your PostgreSQL database is running and accessible.
3. Check for any network restrictions in your DevBox environment.
4. Confirm that the `pg` package is correctly installed.
For more detailed information on using PostgreSQL with Node.js, refer to the [node-postgres documentation](https://node-postgres.com/).
file: ./content/docs/guides/databases/postgresql/php.en.mdx
meta: {
"title": "PHP",
"description": "Learn how to connect to PostgreSQL databases in Sealos DevBox using PHP"
}
This guide will walk you through the process of connecting to a PostgreSQL database using PHP within your Sealos DevBox project.
## Prerequisites
* [A Sealos DevBox project](/docs/guides/devbox/create-a-project) with PHP environment
* [A PostgreSQL database created using the Database app in Sealos](./)
## Install Required Extensions
In your Cursor terminal, ensure that the PostgreSQL extension for PHP is installed:
```bash
sudo apt-get update
sudo apt-get install php-pgsql
```
## Connection Setup
<div className="fd-steps [&_h4]:fd-step">
#### Create a Configuration File
First, let's create a configuration file to store our database connection parameters. Create a file named `config.php` in your project directory with the following content:
```php title="config.php"
<?php
return [
'host' => 'your_database_host',
'port' => '5432',
'dbname' => 'your_database_name',
'user' => 'your_username',
'password' => 'your_password'
];
```
Replace the placeholders with your actual PostgreSQL credentials from the Database app in Sealos.
#### Create a Database Connection Function
Next, let's create a PHP file that will handle the database connection. Create a file named `db_connect.php` with the following content:
```php title="db_connect.php"
<?php
function getDbConnection() {
$config = include 'config.php';
$dsn = "pgsql:host={$config['host']};port={$config['port']};dbname={$config['dbname']};";
try {
$pdo = new PDO($dsn, $config['user'], $config['password'], [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION]);
echo "Connected successfully to the database.\n";
return $pdo;
} catch (PDOException $e) {
die("Connection failed: " . $e->getMessage());
}
}
```
This function reads the configuration from `config.php` and establishes a connection to the PostgreSQL database using PDO (PHP Data Objects).
#### Create a Test Script
Now, let's create a test script to verify our connection and perform some basic database operations. Create a file named `test_db.php` with the following content:
```php title="test_db.php"
<?php
require_once 'db_connect.php';
$pdo = getDbConnection();
// Create a table
$pdo->exec("CREATE TABLE IF NOT EXISTS employees (
id SERIAL PRIMARY KEY,
name VARCHAR(100) NOT NULL,
position VARCHAR(100) NOT NULL
)");
echo "Table created successfully.\n";
// Insert a record
$stmt = $pdo->prepare("INSERT INTO employees (name, position) VALUES (?, ?)");
$stmt->execute(['John Doe', 'Developer']);
echo "Record inserted successfully.\n";
// Query the table
$stmt = $pdo->query("SELECT * FROM employees");
echo "Employees:\n";
while ($row = $stmt->fetch(PDO::FETCH_ASSOC)) {
echo "ID: {$row['id']}, Name: {$row['name']}, Position: {$row['position']}\n";
}
// Close the connection
$pdo = null;
```
This script demonstrates creating a table, inserting a record, and querying the table.
</div>
## Usage
To run the test script, use the following command in your Cursor terminal:
```bash
php test_db.php
```
This will execute the script, demonstrating the connection to the database, table creation, data insertion, and querying.
## Best Practices
1. Use environment variables or a separate configuration file for database credentials.
2. Always use prepared statements to prevent SQL injection.
3. Handle potential errors using try-catch blocks.
4. Close the database connection after operations are complete.
5. Use connection pooling for better performance in production environments.
## Troubleshooting
If you encounter connection issues:
1. Verify your database credentials in the `config.php` file.
2. Ensure your PostgreSQL database is running and accessible.
3. Check for any network restrictions in your DevBox environment.
4. Confirm that the `php-pgsql` extension is correctly installed.
For more detailed information on using PostgreSQL with PHP, refer to the [official PHP PostgreSQL documentation](https://www.php.net/manual/en/book.pgsql.php).
file: ./content/docs/guides/databases/postgresql/python.en.mdx
meta: {
"title": "Python",
"description": "Learn how to connect to PostgreSQL databases in Sealos DevBox using Python"
}
This guide will walk you through the process of connecting to a PostgreSQL database using Python within your Sealos DevBox project.
## Prerequisites
* [A Sealos DevBox project](/docs/guides/devbox/create-a-project) with Python environment
* [A PostgreSQL database created using the Database app in Sealos](./)
## Activating the Python Environment
Before you start, you need to activate the Python virtual environment in your DevBox. Open the terminal within Cursor IDE and run:
```bash
source ./bin/activate
```
You should see your prompt change, indicating that the virtual environment is now active.
## Installing psycopg2-binary
In your Cursor terminal, install `psycopg2-binary` using pip:
```bash
pip install psycopg2-binary
```
## Connection Setup
<div className="fd-steps [&_h4]:fd-step">
#### Create a Configuration File
First, we'll create a configuration file to store our database connection parameters. This approach allows us to easily change settings without modifying our code.
Create a file named `database.ini` in your project directory with the following content:
```ini title="database.ini"
[postgresql]
host=your_database_host
database=your_database_name
user=your_username
password=your_password
port=5432
```
Replace `your_database_name`, `your_username`, and `your_password` with your actual PostgreSQL credentials from the Database app in Sealos.
#### Create a Configuration Loader
Next, we'll create a Python module to load the configuration from our `database.ini` file. This module will use the built-in `configparser` to read the configuration data.
Create a file named `config.py` with the following content:
```python title="config.py"
from configparser import ConfigParser
def load_config(filename='database.ini', section='postgresql'):
parser = ConfigParser()
parser.read(filename)
# get section, default to postgresql
config = {}
if parser.has_section(section):
params = parser.items(section)
for param in params:
config[param[0]] = param[1]
else:
raise Exception('Section {0} not found in the {1} file'.format(section, filename))
return config
if __name__ == '__main__':
config = load_config()
print(config)
```
This `load_config()` function reads the `database.ini` file and returns a dictionary with the connection parameters. If you run this script directly, it will print out the configuration, which can be useful for debugging.
#### Create a Connection Function
Now, we'll create a module that uses our configuration loader to connect to the PostgreSQL database.
Create a file named `connect.py` with the following content:
```python title="connect.py"
import psycopg2
from config import load_config
def connect(config):
""" Connect to the PostgreSQL database server """
try:
# connecting to the PostgreSQL server
conn = psycopg2.connect(**config)
print('Connected to the PostgreSQL server.')
return conn
except (psycopg2.DatabaseError, Exception) as error:
print(f"Error: {error}")
return None
def execute_query(conn, query):
""" Execute a SQL query and return the results """
try:
with conn.cursor() as cur:
cur.execute(query)
return cur.fetchall()
except (psycopg2.DatabaseError, Exception) as error:
print(f"Error executing query: {error}")
return None
if __name__ == '__main__':
config = load_config()
conn = connect(config)
if conn:
# Execute SELECT version() query
version_query = "SELECT version();"
result = execute_query(conn, version_query)
if result:
print(f"PostgreSQL version: {result[0][0]}")
# Don't forget to close the connection
conn.close()
print("Connection closed.")
```
This module does several things:
1. The `connect()` function uses `psycopg2.connect()` to establish a connection to the database using the configuration we loaded.
2. The `execute_query()` function demonstrates how to execute a SQL query and fetch the results.
3. In the `if __name__ == '__main__':` block, we test the connection by connecting to the database and querying its version.
</div>
## Usage
To test the connection, make sure your virtual environment is activated, then run the `connect.py` script:
```bash
python connect.py
```
If successful, you should see output similar to:
```bash
Connected to the PostgreSQL server.
PostgreSQL version: PostgreSQL 14.10 (Ubuntu 14.10-1.pgdg22.04+1) on x86_64-pc-linux-gnu, compiled by gcc (Ubuntu 11.4.0-1ubuntu1~22.04) 11.4.0, 64-bit
Connection closed.
```
## Best Practices
1. Always activate the virtual environment before running your Python scripts or installing packages.
2. Use a configuration file (`database.ini`) to store database credentials. This makes it easier to change settings without modifying your code.
3. If using version control (e.g., git), add `database.ini` to your `.gitignore` file to avoid committing sensitive information.
4. Use connection pooling for better performance in production environments.
5. Always close database connections properly to avoid resource leaks.
6. Use try-except blocks to handle potential database errors gracefully.
## Troubleshooting
If you encounter connection issues:
1. Ensure you've activated the virtual environment with `source ./bin/activate`.
2. Verify that your PostgreSQL database is running.
3. Double-check your database credentials in the `database.ini` file.
4. Check the PostgreSQL logs in the Database app for any error messages.
For more detailed information on using PostgreSQL with Python, refer to the [official psycopg2 documentation](https://www.psycopg.org/docs/).
file: ./content/docs/guides/databases/postgresql/rust.en.mdx
meta: {
"title": "Rust",
"description": "Learn how to connect to PostgreSQL databases in Sealos DevBox using Rust"
}
This guide will walk you through the process of connecting to a PostgreSQL database using Rust within your Sealos DevBox project.
## Prerequisites
* [A Sealos DevBox project](/docs/guides/devbox/create-a-project) with Rust environment
* [A PostgreSQL database created using the Database app in Sealos](./)
## Install Required Dependencies
In your Cursor terminal, add the necessary dependencies to your `Cargo.toml` file:
```toml
[dependencies]
tokio = { version = "1.28", features = ["full"] }
sqlx = { version = "0.6", features = ["runtime-tokio-rustls", "postgres"] }
dotenv = "0.15"
```
These dependencies include:
* `tokio`: An asynchronous runtime for Rust
* `sqlx`: A database toolkit for Rust with async support
* `dotenv`: A library for loading environment variables from a file
## Connection Setup
<div className="fd-steps [&_h4]:fd-step">
#### Set up the environment variables
First, let's set up the environment variables for our database connection. Create a `.env` file in your project root with the following content:
```ini title=".env"
DATABASE_URL=postgres://your_username:your_password@your_database_host:5432/your_database_name
```
Replace the placeholders with your actual PostgreSQL credentials from the Database app in Sealos.
#### Create the main.rs file
Create a new file named `src/main.rs` with the following content:
```rust title="src/main.rs"
use sqlx::postgres::PgPoolOptions;
use sqlx::Row;
use dotenv::dotenv;
use std::env;
#[tokio::main]
async fn main() -> Result<(), sqlx::Error> {
// Load environment variables from .env file
dotenv().ok();
// Get the database URL from the environment
let database_url = env::var("DATABASE_URL").expect("DATABASE_URL must be set");
// Create a connection pool
let pool = PgPoolOptions::new()
.max_connections(5)
.connect(&database_url)
.await?;
// Create the employees table if it doesn't exist
sqlx::query(
r#"
CREATE TABLE IF NOT EXISTS employees (
id SERIAL PRIMARY KEY,
name VARCHAR(100) NOT NULL,
position VARCHAR(100) NOT NULL
)
"#,
)
.execute(&pool)
.await?;
println!("Table created successfully");
// Insert a sample employee
let new_employee = sqlx::query(
r#"
INSERT INTO employees (name, position)
VALUES ($1, $2)
RETURNING id, name, position
"#,
)
.bind("John Doe")
.bind("Developer")
.fetch_one(&pool)
.await?;
println!(
"Inserted employee: ID: {}, Name: {}, Position: {}",
new_employee.get::<i32, _>("id"),
new_employee.get::<String, _>("name"),
new_employee.get::<String, _>("position")
);
// Query all employees
let employees = sqlx::query("SELECT id, name, position FROM employees")
.fetch_all(&pool)
.await?;
println!("All employees:");
for employee in employees {
println!(
"ID: {}, Name: {}, Position: {}",
employee.get::<i32, _>("id"),
employee.get::<String, _>("name"),
employee.get::<String, _>("position")
);
}
Ok(())
}
```
Let's break down the main components of this code:
1. **Imports**: We import necessary modules from `sqlx`, `dotenv`, and `std::env`.
2. **Main function**: The `main` function is marked with `#[tokio::main]` to use Tokio's async runtime.
3. **Environment setup**: We load environment variables from the `.env` file and retrieve the database URL.
4. **Connection pool**: We create a connection pool using `PgPoolOptions`.
5. **Table creation**: We create the `employees` table if it doesn't exist.
6. **Data insertion**: We insert a sample employee into the database.
7. **Data querying**: We query and display all employees in the database.
</div>
## Usage
To run the application, use the following command in your Cursor terminal:
```bash
cargo run
```
This will compile and execute the `main` function, demonstrating the connection to the database, table creation, data insertion, and querying.
## Best Practices
1. Use environment variables for database credentials.
2. Use connection pooling for better performance and resource management.
3. Use prepared statements (as demonstrated with `sqlx::query`) to prevent SQL injection.
4. Handle errors appropriately using Rust's `Result` type.
5. Use async/await for efficient database operations.
## Troubleshooting
If you encounter connection issues:
1. Verify your database credentials in the `.env` file.
2. Ensure your PostgreSQL database is running and accessible.
3. Check for any network restrictions in your DevBox environment.
4. Confirm that all required dependencies are correctly specified in your `Cargo.toml` file.
For more detailed information on using PostgreSQL with Rust, refer to the [sqlx documentation](https://github.com/launchbadge/sqlx).
file: ./content/docs/guides/databases/redis/go.en.mdx
meta: {
"title": "Go",
"description": "Learn how to connect to Redis databases in Sealos DevBox using Go"
}
This guide will walk you through the process of connecting to a Redis database using Go within your Sealos DevBox project.
## Prerequisites
* [A Sealos DevBox project](/docs/guides/devbox/create-a-project) with Go environment
* [A Redis database created using the Database app in Sealos](./)
## Install Required Packages
In your Cursor terminal, install the necessary packages:
```bash
go get github.com/go-redis/redis
go get github.com/joho/godotenv
```
These commands install:
* `github.com/go-redis/redis`: A Redis client for Go
* `github.com/joho/godotenv`: A Go port of the Ruby dotenv library
## Connection Setup
<div className="fd-steps [&_h4]:fd-step">
#### Set up the environment variables
First, let's set up the environment variables for our database connection. Create a `.env` file in your project root with the following content:
```ini title=".env"
REDIS_HOST=your_redis_host
REDIS_PORT=6379
REDIS_PASSWORD=your_redis_password
```
Replace the placeholders with your actual Redis credentials from the Database app in Sealos.
#### Create the main.go file
Create a new file named `main.go` with the following content:
```go title="main.go"
package main
import (
"fmt"
"log"
"os"
"github.com/go-redis/redis"
"github.com/joho/godotenv"
)
func main() {
// Load environment variables from .env file
err := godotenv.Load()
if err != nil {
log.Fatal("Error loading .env file")
}
// Create a new Redis client
client := redis.NewClient(&redis.Options{
Addr: fmt.Sprintf("%s:%s", os.Getenv("REDIS_HOST"), os.Getenv("REDIS_PORT")),
Password: os.Getenv("REDIS_PASSWORD"),
DB: 0, // use default DB
})
// Test the connection
pong, err := client.Ping().Result()
if err != nil {
log.Fatal("Could not connect to Redis: ", err)
}
fmt.Println("Connected to Redis: ", pong)
// Set a key
err = client.Set("mykey", "Hello from Sealos DevBox!", 0).Err()
if err != nil {
log.Fatal("Could not set key: ", err)
}
// Get a key
val, err := client.Get("mykey").Result()
if err != nil {
log.Fatal("Could not get key: ", err)
}
fmt.Println("mykey:", val)
// Close the connection
err = client.Close()
if err != nil {
log.Fatal("Error closing Redis connection: ", err)
}
fmt.Println("Redis connection closed successfully")
}
```
This code demonstrates how to connect to Redis, set a key, get a key, and close the connection.
</div>
## Usage
To run the application, use the following command in your Cursor terminal:
```bash
go run main.go
```
This will execute the `main` function, demonstrating the connection to Redis, setting and getting a key, and closing the connection.
## Best Practices
1. Use environment variables for Redis credentials.
2. Always handle potential errors using proper error checking.
3. Use a context for operations that might need to be cancelled or timed out.
4. Close the Redis connection after operations are complete.
5. Consider using connection pooling for better performance in production environments.
## Troubleshooting
If you encounter connection issues:
1. Verify your Redis credentials in the `.env` file.
2. Ensure your Redis database is running and accessible.
3. Check for any network restrictions in your DevBox environment.
4. Confirm that the required packages are correctly installed.
For more detailed information on using Redis with Go, refer to the [go-redis documentation](https://github.com/go-redis/redis).
file: ./content/docs/guides/databases/redis/index.en.mdx
meta: {
"title": "Redis",
"description": "Deploy and connect to Redis databases in Sealos DevBox"
}
Redis is a popular, open-source in-memory data structure store that can be used as a database, cache, message broker, and queue. In Sealos DevBox, you can easily set up and connect to Redis databases for your development projects.
## Deploy Redis in Sealos
Sealos makes it easy to deploy a Redis database with just a few clicks. Follow these steps:
<div className="fd-steps [&_h5]:fd-step">
<h5>From the Sealos desktop, click on the "Database" icon to open the Database app.</h5>
<h5>Click on the "Create New Database" button. In the deployment form:</h5>
* Select "Redis" as the database type.
* Choose the desired Redis version (e.g., redis-7.0.6).
* Enter a name for your database (use lowercase letters and numbers only).
* Adjust the CPU and Memory sliders to set the resources for your database.
* Set the number of replicas (1 for single-node development and testing).
* Specify the storage size (e.g., 1 Gi).
<h5>Review the projected cost on the left sidebar. Click the "Deploy" button in the top right corner to create your Redis database.</h5>
</div>
Once deployed, Sealos will provide you with the necessary connection details.
## Connect to Redis in DevBox
Here are examples of how to connect to your Redis database using different programming languages and frameworks within your DevBox environment:
<Cards>
<Card title="Connect to Redis with Go in Sealos DevBox" href="./redis/go" />
<Card title="Connect to Redis with Java in Sealos DevBox" href="./redis/java" />
<Card title="Connect to Redis with Node.js in Sealos DevBox" href="./redis/nodejs" />
<Card title="Connect to Redis with PHP in Sealos DevBox" href="./redis/php" />
<Card title="Connect to Redis with Python in Sealos DevBox" href="./redis/python" />
<Card title="Connect to Redis with Rust in Sealos DevBox" href="./redis/rust" />
</Cards>
file: ./content/docs/guides/databases/redis/java.en.mdx
meta: {
"title": "Java",
"description": "Learn how to connect to Redis databases in Sealos DevBox using Java"
}
This guide will walk you through the process of connecting to a Redis database using Java within your Sealos DevBox project.
## Prerequisites
* [A Sealos DevBox project](/docs/guides/devbox/create-a-project) with Java environment
* [A Redis database created using the Database app in Sealos](./)
## Project Setup
<div className="fd-steps [&_h4]:fd-step">
#### Create a new Maven project
In your Sealos DevBox terminal, initialize a new Maven project:
```bash
mvn archetype:generate -DgroupId=com.example -DartifactId=redis-java-example -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false
mv redis-java-example/* .
rm -rf redis-java-example/
```
#### Project Structure
After setting up, your project structure should look like this:
```
/
├── pom.xml
├── src
│ ├── main
│ │ ├── java
│ │ │ └── com
│ │ │ └── example
│ │ │ ├── App.java
│ │ │ ├── RedisConfig.java
│ │ │ └── RedisConnection.java
│ │ └── resources
│ │ └── redis.properties
│ └── test
│ └── java
│ └── com
│ └── example
│ └── AppTest.java
```
#### Update pom.xml
Replace the content of your `pom.xml` file with the following:
```xml title="pom.xml"
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.example</groupId>
<artifactId>redis-java-example</artifactId>
<version>1.0-SNAPSHOT</version>
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<maven.compiler.source>11</maven.compiler.source>
<maven.compiler.target>11</maven.compiler.target>
</properties>
<dependencies>
<dependency>
<groupId>redis.clients</groupId>
<artifactId>jedis</artifactId>
<version>4.3.1</version>
</dependency>
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-api</artifactId>
<version>2.0.5</version>
</dependency>
<dependency>
<groupId>ch.qos.logback</groupId>
<artifactId>logback-classic</artifactId>
<version>1.4.12</version>
</dependency>
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<version>4.13.2</version>
<scope>test</scope>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.8.1</version>
<configuration>
<source>11</source>
<target>11</target>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-shade-plugin</artifactId>
<version>3.2.4</version>
<executions>
<execution>
<phase>package</phase>
<goals>
<goal>shade</goal>
</goals>
<configuration>
<transformers>
<transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
<mainClass>com.example.App</mainClass>
</transformer>
</transformers>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>
```
This `pom.xml` file includes the necessary dependencies (Jedis for Redis connectivity, SLF4J for logging) and configures the Maven Shade plugin to create an executable JAR.
#### Create a configuration file
Create a file named `redis.properties` in the `src/main/resources` directory:
```ini title="redis.properties"
redis.host=your_redis_host
redis.port=6379
redis.password=your_redis_password
```
Replace the placeholders with your actual Redis credentials from the Database app in Sealos.
#### Create Java classes
Create the following Java classes in the `src/main/java/com/example` directory:
1. `App.java`:
```java title="App.java"
package com.example;
import redis.clients.jedis.Jedis;
public class App {
public static void main(String[] args) {
try (Jedis jedis = RedisConnection.getConnection()) {
System.out.println("Connected to Redis");
// String operations
jedis.set("mykey", "Hello from Sealos DevBox!");
String value = jedis.get("mykey");
System.out.println("Retrieved value: " + value);
// List operations
jedis.lpush("mylist", "element1", "element2", "element3");
String listElement = jedis.lpop("mylist");
System.out.println("Popped element from list: " + listElement);
// Hash operations
jedis.hset("myhash", "field1", "value1");
jedis.hset("myhash", "field2", "value2");
String hashValue = jedis.hget("myhash", "field1");
System.out.println("Retrieved hash value: " + hashValue);
} catch (Exception e) {
System.err.println("Error connecting to Redis: " + e.getMessage());
} finally {
RedisConnection.closePool();
}
}
}
```
This is the main class that demonstrates basic Redis operations using Jedis:
* It sets and gets a string value.
* It pushes elements to a list and pops an element.
* It sets and gets hash values.
2. `RedisConfig.java`:
```java title="RedisConfig.java"
package com.example;
import java.io.IOException;
import java.io.InputStream;
import java.util.Properties;
public class RedisConfig {
private static final Properties properties = new Properties();
static {
try (InputStream input = RedisConfig.class.getClassLoader().getResourceAsStream("redis.properties")) {
if (input == null) {
System.out.println("Sorry, unable to find redis.properties");
System.exit(1);
}
properties.load(input);
} catch (IOException e) {
e.printStackTrace();
}
}
public static String getHost() {
return properties.getProperty("redis.host");
}
public static int getPort() {
return Integer.parseInt(properties.getProperty("redis.port"));
}
public static String getPassword() {
return properties.getProperty("redis.password");
}
}
```
This class loads the Redis connection details from the `redis.properties` file.
3. `RedisConnection.java`:
```java title="RedisConnection.java"
package com.example;
import redis.clients.jedis.Jedis;
import redis.clients.jedis.JedisPool;
import redis.clients.jedis.JedisPoolConfig;
public class RedisConnection {
private static final JedisPool pool = new JedisPool(new JedisPoolConfig(),
RedisConfig.getHost(),
RedisConfig.getPort(),
2000,
RedisConfig.getPassword());
public static Jedis getConnection() {
return pool.getResource();
}
public static void closePool() {
pool.close();
}
}
```
This class manages the Redis connection pool using Jedis.
4. `AppTest.java` (in `src/test/java/com/example`):
```java title="AppTest.java"
package com.example;
import static org.junit.Assert.assertTrue;
import org.junit.Test;
public class AppTest
{
@Test
public void shouldAnswerWithTrue()
{
assertTrue( true );
}
}
```
</div>
## Build and Run
To build and run the project, use the following commands in your terminal:
```bash
mvn clean package
java -jar target/redis-java-example-1.0-SNAPSHOT.jar
```
If everything is set up correctly, you should see output demonstrating the Redis operations.
## Best Practices
1. Use a properties file to store Redis connection details.
2. Implement a configuration class to load and provide access to Redis properties.
3. Use a connection pool for better performance and resource management.
4. Always close Redis connections after use (or use try-with-resources as shown in the example).
5. Handle exceptions appropriately and provide meaningful error messages.
6. Use Maven for dependency management and build automation.
## Troubleshooting
If you encounter connection issues:
1. Verify your Redis credentials in the `redis.properties` file.
2. Ensure your Redis database is running and accessible from your DevBox environment.
3. Check for any network restrictions in your DevBox environment.
4. Confirm that the Jedis dependency is correctly specified in your `pom.xml` file.
5. Make sure you're using the correct version of Java (11 in this example).
## Conclusion
This guide provided a complete example of how to set up a Java project with Maven to connect to a Redis database in the Sealos DevBox environment. It includes all the necessary steps, from project creation to running the application, along with best practices and troubleshooting tips.
For more detailed information on using Redis with Java, refer to the [Jedis GitHub repository](https://github.com/redis/jedis).
file: ./content/docs/guides/databases/redis/nodejs.en.mdx
meta: {
"title": "Node.js",
"description": "Comprehensive guide for using Redis with Node.js in Sealos - from basics to production deployment"
}
import { File, Folder, Files } from 'fumadocs-ui/components/files';
This comprehensive guide covers everything you need to know about using Redis with Node.js in Sealos DevBox, from basic operations to production-ready implementations.
## Prerequisites
* [A Sealos DevBox project](/docs/guides/devbox/create-a-project) with Node.js environment
* [A Redis database created using the Database app in Sealos](./)
* Basic understanding of JavaScript and Node.js
## Project Setup & Structure
Let's start by setting up a complete project structure that we'll build upon throughout this guide.
### Initialize Your Project
In your Cursor terminal, install the necessary packages:
```bash
npm install redis dotenv @redis/json @redis/search @redis/time-series msgpack5
```
### Project Structure
Create the following directory structure:
```bash
# Create directories
mkdir src examples tests
# Create main files
touch .env package.json
touch src/redisClient.js
touch examples/basic-operations.js
touch tests/connection-test.js
```
Your project should look like this:
<Files>
<Folder name="redis-nodejs-guide" defaultOpen>
<File name=".env" />
<File name="package.json" />
<Folder name="src" defaultOpen>
<File name="redisClient.js" />
</Folder>
<Folder name="examples">
<File name="basic-operations.js" />
</Folder>
<Folder name="tests">
<File name="connection-test.js" />
</Folder>
</Folder>
</Files>
### Environment Configuration
<div className="fd-steps [&_h4]:fd-step">
#### Set up environment variables
Create your `.env` file with your Sealos Redis credentials:
```ini title=".env"
# Basic Redis connection
REDIS_HOST=your_redis_host
REDIS_PORT=6379
REDIS_PASSWORD=your_redis_password
REDIS_DB=0
# Advanced settings (we'll use these later)
REDIS_TLS=false
REDIS_USERNAME=default
REDIS_CONNECT_TIMEOUT=10000
REDIS_COMMAND_TIMEOUT=5000
```
#### Create the main Redis client
Create `src/redisClient.js` - this will be our single source of truth for Redis connections:
```javascript title="src/redisClient.js"
const { createClient } = require('redis');
require('dotenv').config();
class RedisManager {
constructor() {
this.client = null;
this.isConnected = false;
}
createClient() {
const config = {
url: `redis://${process.env.REDIS_HOST}:${process.env.REDIS_PORT}`,
password: process.env.REDIS_PASSWORD,
database: parseInt(process.env.REDIS_DB) || 0,
socket: {
connectTimeout: parseInt(process.env.REDIS_CONNECT_TIMEOUT) || 60000,
commandTimeout: parseInt(process.env.REDIS_COMMAND_TIMEOUT) || 5000,
reconnectStrategy: (retries) => {
if (retries > 20) {
console.error('Too many reconnection attempts, giving up');
return false;
}
// Exponential backoff with jitter (latest best practice)
const jitter = Math.floor(Math.random() * 200);
const delay = Math.min(Math.pow(2, retries) * 50, 2000);
console.log(`Reconnecting in ${delay + jitter}ms...`);
return delay + jitter;
},
keepAlive: 30000,
noDelay: true
}
};
// Add TLS if enabled
if (process.env.REDIS_TLS === 'true') {
config.socket.tls = true;
config.socket.rejectUnauthorized = process.env.NODE_ENV === 'production';
}
this.client = createClient(config);
this.setupEventHandlers();
return this.client;
}
setupEventHandlers() {
this.client.on('connect', () => {
console.log('✅ Redis client connected');
});
this.client.on('ready', () => {
console.log('✅ Redis client ready');
this.isConnected = true;
});
this.client.on('error', (err) => {
console.error('❌ Redis client error:', err.message);
this.isConnected = false;
});
this.client.on('end', () => {
console.log('🔌 Redis client disconnected');
this.isConnected = false;
});
this.client.on('reconnecting', () => {
console.log('🔄 Redis client reconnecting...');
this.isConnected = false;
});
}
async connect() {
if (!this.client) {
this.createClient();
}
if (!this.isConnected) {
await this.client.connect();
}
return this.client;
}
async disconnect() {
if (this.client && this.isConnected) {
// Use destroy() instead of quit() for latest node-redis
this.client.destroy();
}
}
getClient() {
if (!this.isConnected) {
throw new Error('Redis client not connected. Call connect() first.');
}
return this.client;
}
async ping() {
try {
const result = await this.client.ping();
return result === 'PONG';
} catch (error) {
console.error('Redis ping failed:', error);
return false;
}
}
}
// Export singleton instance
const redisManager = new RedisManager();
module.exports = redisManager;
```
#### Test your connection
Create `tests/connection-test.js`:
```javascript title="tests/connection-test.js"
const redisManager = require('../src/redisClient');
async function testConnection() {
try {
console.log('🔍 Testing Redis connection...');
// Connect to Redis
await redisManager.connect();
// Test ping
const pingResult = await redisManager.ping();
console.log('📡 Ping result:', pingResult ? 'SUCCESS' : 'FAILED');
// Test basic operations
const client = redisManager.getClient();
await client.set('test:connection', 'Hello from Sealos!');
const value = await client.get('test:connection');
console.log('💾 Test value:', value);
// Clean up test key
await client.del('test:connection');
console.log('✅ Connection test completed successfully!');
} catch (error) {
console.error('❌ Connection test failed:', error.message);
} finally {
await redisManager.disconnect();
}
}
// Run the test
testConnection();
```
#### Run your first test
```bash
node tests/connection-test.js
```
You should see output like:
```
🔍 Testing Redis connection...
✅ Redis client connected
✅ Redis client ready
📡 Ping result: SUCCESS
💾 Test value: Hello from Sealos!
✅ Connection test completed successfully!
🔌 Redis client disconnected
```
</div>
## Basic Operations & Data Types
Now let's explore Redis data types with practical examples. Create `examples/basic-operations.js`:
```javascript title="examples/basic-operations.js"
const redisManager = require('../src/redisClient');
async function demonstrateBasicOperations() {
try {
await redisManager.connect();
const client = redisManager.getClient();
console.log('🚀 Starting basic operations demo...\n');
// 1. Strings
console.log('📝 STRING OPERATIONS:');
await client.set('user:name', 'John Doe');
await client.setEx('session:abc123', 3600, 'active'); // With TTL
const name = await client.get('user:name');
const session = await client.get('session:abc123');
console.log(`Name: ${name}`);
console.log(`Session: ${session}`);
// Increment counter
await client.incr('page:views');
await client.incrBy('page:views', 5);
const views = await client.get('page:views');
console.log(`Page views: ${views}\n`);
// 2. Hashes
console.log('🗂️ HASH OPERATIONS:');
await client.hSet('user:1001', {
name: 'Alice Smith',
email: 'alice@example.com',
age: '28',
city: 'New York'
});
const user = await client.hGetAll('user:1001');
const userAge = await client.hGet('user:1001', 'age');
console.log('User data:', user);
console.log(`User age: ${userAge}\n`);
// 3. Lists
console.log('📋 LIST OPERATIONS:');
await client.lPush('tasks', 'Task 1', 'Task 2', 'Task 3');
await client.rPush('tasks', 'Task 4'); // Add to end
const tasks = await client.lRange('tasks', 0, -1);
const firstTask = await client.lPop('tasks');
console.log('All tasks:', tasks);
console.log(`Completed task: ${firstTask}\n`);
// 4. Sets
console.log('🎯 SET OPERATIONS:');
await client.sAdd('tags:user:1001', 'developer', 'nodejs', 'redis');
await client.sAdd('tags:user:1002', 'designer', 'css', 'nodejs');
const userTags = await client.sMembers('tags:user:1001');
const commonTags = await client.sInter('tags:user:1001', 'tags:user:1002');
console.log('User 1001 tags:', userTags);
console.log('Common tags:', commonTags);
console.log('\n✅ Basic operations demo completed!');
} catch (error) {
console.error('❌ Error in basic operations:', error.message);
} finally {
await redisManager.disconnect();
}
}
// Run the demo
demonstrateBasicOperations();
```
### Test Basic Operations
```bash
node examples/basic-operations.js
```
Expected output:
```
🚀 Starting basic operations demo...
📝 STRING OPERATIONS:
Name: John Doe
Session: active
Page views: 6
🗂️ HASH OPERATIONS:
User data: { name: 'Alice Smith', email: 'alice@example.com', age: '28', city: 'New York' }
User age: 28
📋 LIST OPERATIONS:
All tasks: [ 'Task 3', 'Task 2', 'Task 1', 'Task 4' ]
Completed task: Task 3
🎯 SET OPERATIONS:
User 1001 tags: [ 'nodejs', 'redis', 'developer' ]
Common tags: [ 'nodejs' ]
✅ Basic operations demo completed!
```
## Advanced Data Structures & Real-World Use Cases
Now let's build practical applications using Redis's advanced data structures. We'll create several examples that demonstrate real-world scenarios.
### Working with Sorted Sets - Leaderboard System
Create `examples/leaderboard.js`:
```javascript title="examples/leaderboard.js"
const redisManager = require('../src/redisClient');
class Leaderboard {
constructor(name) {
this.leaderboardKey = `leaderboard:${name}`;
}
async updateScore(userId, score, userData = {}) {
const client = redisManager.getClient();
// Update score in sorted set
await client.zAdd(this.leaderboardKey, { score, value: userId });
// Store additional user data if provided
if (Object.keys(userData).length > 0) {
await client.hSet(`user:${userId}`, userData);
}
console.log(`✅ Updated score for user ${userId}: ${score}`);
}
async getTopPlayers(count = 10) {
const client = redisManager.getClient();
const players = await client.zRevRange(this.leaderboardKey, 0, count - 1, {
withScores: true
});
// Enrich with user data
const enrichedPlayers = [];
for (let i = 0; i < players.length; i++) {
const { value: userId, score } = players[i];
const userData = await client.hGetAll(`user:${userId}`);
enrichedPlayers.push({
rank: i + 1,
userId,
score,
name: userData.name || `User ${userId}`,
...userData
});
}
return enrichedPlayers;
}
async getUserRank(userId) {
const client = redisManager.getClient();
const rank = await client.zRevRank(this.leaderboardKey, userId);
const score = await client.zScore(this.leaderboardKey, userId);
return rank !== null ? { rank: rank + 1, score } : null;
}
}
async function demonstrateLeaderboard() {
try {
await redisManager.connect();
console.log('🏆 Starting leaderboard demo...\n');
const gameLeaderboard = new Leaderboard('game_scores');
// Add some players with scores
await gameLeaderboard.updateScore('player1', 1500, { name: 'Alice', level: 25 });
await gameLeaderboard.updateScore('player2', 2300, { name: 'Bob', level: 32 });
await gameLeaderboard.updateScore('player3', 1800, { name: 'Charlie', level: 28 });
await gameLeaderboard.updateScore('player4', 2100, { name: 'Diana', level: 30 });
await gameLeaderboard.updateScore('player5', 1200, { name: 'Eve', level: 22 });
console.log('\n🥇 Top 3 Players:');
const topPlayers = await gameLeaderboard.getTopPlayers(3);
topPlayers.forEach(player => {
console.log(`${player.rank}. ${player.name} - Score: ${player.score} (Level ${player.level})`);
});
// Check specific player rank
const aliceRank = await gameLeaderboard.getUserRank('player1');
console.log(`\n📊 Alice's rank: #${aliceRank.rank} with score ${aliceRank.score}`);
console.log('\n✅ Leaderboard demo completed!');
} catch (error) {
console.error('❌ Error in leaderboard demo:', error.message);
} finally {
await redisManager.disconnect();
}
}
// Export for use in other examples
module.exports = Leaderboard;
// Run demo if called directly
if (require.main === module) {
demonstrateLeaderboard();
}
```
### Working with Lists - Task Queue System
Create `examples/task-queue.js`:
```javascript title="examples/task-queue.js"
const redisManager = require('../src/redisClient');
class TaskQueue {
constructor(queueName = 'default_queue') {
this.queueName = queueName;
this.processingQueue = `${queueName}:processing`;
}
async addTask(taskData, priority = 'normal') {
const client = redisManager.getClient();
const task = {
id: `task_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`,
data: taskData,
createdAt: new Date().toISOString(),
priority,
attempts: 0
};
const queueKey = priority === 'high' ? `${this.queueName}:high` : this.queueName;
await client.lPush(queueKey, JSON.stringify(task));
console.log(`📝 Added ${priority} priority task: ${task.id}`);
return task.id;
}
async processTask(timeout = 5) {
const client = redisManager.getClient();
// Check high priority queue first
let result = await client.brPop(`${this.queueName}:high`, 0.1);
if (!result) {
// Then check normal priority queue
result = await client.brPop(this.queueName, timeout);
}
if (result) {
const task = JSON.parse(result.element);
// Move to processing queue for reliability
await client.lPush(this.processingQueue, JSON.stringify(task));
console.log(`⚡ Processing task: ${task.id}`);
return task;
}
return null;
}
async completeTask(taskId) {
const client = redisManager.getClient();
// Remove from processing queue
const processingTasks = await client.lRange(this.processingQueue, 0, -1);
for (let i = 0; i < processingTasks.length; i++) {
const task = JSON.parse(processingTasks[i]);
if (task.id === taskId) {
await client.lRem(this.processingQueue, 1, processingTasks[i]);
console.log(`✅ Completed task: ${taskId}`);
break;
}
}
}
async getQueueStats() {
const client = redisManager.getClient();
return {
pending: await client.lLen(this.queueName),
highPriority: await client.lLen(`${this.queueName}:high`),
processing: await client.lLen(this.processingQueue)
};
}
}
async function demonstrateTaskQueue() {
try {
await redisManager.connect();
console.log('📋 Starting task queue demo...\n');
const emailQueue = new TaskQueue('email_queue');
// Add various tasks
await emailQueue.addTask({
type: 'welcome_email',
recipient: 'user@example.com',
template: 'welcome'
});
await emailQueue.addTask({
type: 'password_reset',
recipient: 'admin@example.com',
token: 'abc123'
}, 'high');
await emailQueue.addTask({
type: 'newsletter',
recipients: ['user1@example.com', 'user2@example.com']
});
// Check queue stats
let stats = await emailQueue.getQueueStats();
console.log('📊 Queue stats:', stats);
// Process some tasks
console.log('\n🔄 Processing tasks...');
for (let i = 0; i < 3; i++) {
const task = await emailQueue.processTask();
if (task) {
// Simulate task processing
await new Promise(resolve => setTimeout(resolve, 1000));
await emailQueue.completeTask(task.id);
}
}
// Final stats
stats = await emailQueue.getQueueStats();
console.log('\n📊 Final queue stats:', stats);
console.log('\n✅ Task queue demo completed!');
} catch (error) {
console.error('❌ Error in task queue demo:', error.message);
} finally {
await redisManager.disconnect();
}
}
// Export for use in other examples
module.exports = TaskQueue;
// Run demo if called directly
if (require.main === module) {
demonstrateTaskQueue();
}
```
### Test Advanced Data Structures
Run the leaderboard example:
```bash
node examples/leaderboard.js
```
Run the task queue example:
```bash
node examples/task-queue.js
```
Expected output for leaderboard:
```
🏆 Starting leaderboard demo...
✅ Updated score for user player1: 1500
✅ Updated score for user player2: 2300
✅ Updated score for user player3: 1800
✅ Updated score for user player4: 2100
✅ Updated score for user player5: 1200
🥇 Top 3 Players:
1. Bob - Score: 2300 (Level 32)
2. Diana - Score: 2100 (Level 30)
3. Charlie - Score: 1800 (Level 28)
📊 Alice's rank: #4 with score 1500
✅ Leaderboard demo completed!
```
## Advanced Caching Strategies
Let's implement different caching patterns that you can use in production applications.
### Cache-Aside Pattern (Lazy Loading)
Create `examples/cache-patterns.js`:
```javascript title="examples/cache-patterns.js"
const redisManager = require('../src/redisClient');
class CacheAsideService {
constructor(ttl = 3600) {
this.ttl = ttl; // Time to live in seconds
}
async get(key, fetchFunction) {
try {
const client = redisManager.getClient();
// Try to get from cache first
const cached = await client.get(key);
if (cached) {
console.log(`🎯 Cache HIT for key: ${key}`);
return JSON.parse(cached);
}
console.log(`❌ Cache MISS for key: ${key}`);
// Cache miss - fetch from source
const data = await fetchFunction();
// Store in cache with TTL
await client.setEx(key, this.ttl, JSON.stringify(data));
console.log(`💾 Cached data for key: ${key}`);
return data;
} catch (error) {
console.error('Cache-aside error:', error);
// Fallback to direct fetch if cache fails
return await fetchFunction();
}
}
async invalidate(key) {
const client = redisManager.getClient();
await client.del(key);
console.log(`🗑️ Invalidated cache for key: ${key}`);
}
async invalidatePattern(pattern) {
const client = redisManager.getClient();
const keys = await client.keys(pattern);
if (keys.length > 0) {
await client.del(keys);
console.log(`🗑️ Invalidated ${keys.length} keys matching pattern: ${pattern}`);
}
}
}
// Simulate database operations
const mockDatabase = {
async getUserById(userId) {
console.log(`🔍 Fetching user ${userId} from database...`);
// Simulate database delay
await new Promise(resolve => setTimeout(resolve, 500));
return {
id: userId,
name: `User ${userId}`,
email: `user${userId}@example.com`,
createdAt: new Date().toISOString()
};
},
async getProductById(productId) {
console.log(`🔍 Fetching product ${productId} from database...`);
await new Promise(resolve => setTimeout(resolve, 300));
return {
id: productId,
name: `Product ${productId}`,
price: Math.floor(Math.random() * 1000) + 10,
category: 'Electronics'
};
}
};
async function demonstrateCacheAside() {
try {
await redisManager.connect();
console.log('🚀 Starting Cache-Aside pattern demo...\n');
const cache = new CacheAsideService(1800); // 30 minutes TTL
// Function to get user with caching
async function getUserProfile(userId) {
return await cache.get(`user:${userId}`, async () => {
return await mockDatabase.getUserById(userId);
});
}
// First call - cache miss
console.log('📞 First call to getUserProfile(1001):');
let user = await getUserProfile('1001');
console.log('👤 User data:', user);
console.log('\n📞 Second call to getUserProfile(1001):');
// Second call - cache hit
user = await getUserProfile('1001');
console.log('👤 User data:', user);
// Invalidate and try again
console.log('\n🗑️ Invalidating user cache...');
await cache.invalidate('user:1001');
console.log('\n📞 Third call after invalidation:');
user = await getUserProfile('1001');
console.log('👤 User data:', user);
console.log('\n✅ Cache-Aside demo completed!');
} catch (error) {
console.error('❌ Error in cache-aside demo:', error.message);
} finally {
await redisManager.disconnect();
}
}
// Export for use in other examples
module.exports = { CacheAsideService, mockDatabase };
// Run demo if called directly
if (require.main === module) {
demonstrateCacheAside();
}
```
### Write-Through Pattern
Add this to `examples/cache-patterns.js` (append to the file):
```javascript title="examples/cache-patterns.js (continued)"
class WriteThroughCache {
constructor(ttl = 3600) {
this.ttl = ttl;
}
async set(key, data, saveFunction) {
try {
const client = redisManager.getClient();
// Write to database first
await saveFunction(data);
console.log(`💾 Saved data to database for key: ${key}`);
// Then update cache
await client.setEx(key, this.ttl, JSON.stringify(data));
console.log(`🎯 Updated cache for key: ${key}`);
return data;
} catch (error) {
console.error('Write-through error:', error);
throw error; // Re-throw to maintain transaction integrity
}
}
async get(key) {
const client = redisManager.getClient();
const cached = await client.get(key);
return cached ? JSON.parse(cached) : null;
}
async update(key, updates, updateFunction) {
try {
const client = redisManager.getClient();
// Update database first
const updatedData = await updateFunction(updates);
console.log(`🔄 Updated database for key: ${key}`);
// Update cache
await client.setEx(key, this.ttl, JSON.stringify(updatedData));
console.log(`🎯 Updated cache for key: ${key}`);
return updatedData;
} catch (error) {
console.error('Write-through update error:', error);
throw error;
}
}
}
async function demonstrateWriteThrough() {
try {
await redisManager.connect();
console.log('🚀 Starting Write-Through pattern demo...\n');
const writeCache = new WriteThroughCache(3600);
// Create new user
const newUser = {
id: '2001',
name: 'John Smith',
email: 'john.smith@example.com',
role: 'admin'
};
console.log('📝 Creating new user with write-through:');
await writeCache.set('user:2001', newUser, async (userData) => {
// Simulate database save
console.log('💾 Saving to database:', userData.name);
await new Promise(resolve => setTimeout(resolve, 200));
});
// Read from cache
console.log('\n📖 Reading user from cache:');
const cachedUser = await writeCache.get('user:2001');
console.log('👤 Cached user:', cachedUser);
// Update user
console.log('\n🔄 Updating user with write-through:');
await writeCache.update('user:2001', { role: 'super_admin' }, async (updates) => {
// Simulate database update
console.log('🔄 Updating database with:', updates);
await new Promise(resolve => setTimeout(resolve, 200));
return { ...cachedUser, ...updates };
});
// Read updated data
const updatedUser = await writeCache.get('user:2001');
console.log('👤 Updated user:', updatedUser);
console.log('\n✅ Write-Through demo completed!');
} catch (error) {
console.error('❌ Error in write-through demo:', error.message);
} finally {
await redisManager.disconnect();
}
}
// Add to exports
module.exports = { CacheAsideService, WriteThroughCache, mockDatabase };
```
### Test Caching Patterns
```bash
node examples/cache-patterns.js
```
Expected output:
```
🚀 Starting Cache-Aside pattern demo...
📞 First call to getUserProfile(1001):
❌ Cache MISS for key: user:1001
🔍 Fetching user 1001 from database...
💾 Cached data for key: user:1001
👤 User data: { id: '1001', name: 'User 1001', email: 'user1001@example.com', createdAt: '...' }
📞 Second call to getUserProfile(1001):
🎯 Cache HIT for key: user:1001
👤 User data: { id: '1001', name: 'User 1001', email: 'user1001@example.com', createdAt: '...' }
🗑️ Invalidating user cache...
🗑️ Invalidated cache for key: user:1001
📞 Third call after invalidation:
❌ Cache MISS for key: user:1001
🔍 Fetching user 1001 from database...
💾 Cached data for key: user:1001
✅ Cache-Aside demo completed!
```
## Redis Stack Integration
Redis Stack provides powerful modules for JSON, Search, and TimeSeries. Let's explore how to use them with our Node.js application.
### Working with RedisJSON
Create `examples/redis-json.js`:
```javascript title="examples/redis-json.js"
const redisManager = require('../src/redisClient');
class RedisJSONService {
async setDocument(key, document) {
const client = redisManager.getClient();
// Use the native JSON.SET command (latest node-redis supports JSON module)
await client.json.set(key, '$', document);
console.log(`📄 Stored JSON document: ${key}`);
}
async getDocument(key) {
const client = redisManager.getClient();
return await client.json.get(key);
}
async updateField(key, path, value) {
const client = redisManager.getClient();
await client.json.set(key, path, value);
console.log(`🔄 Updated field ${path} in document: ${key}`);
}
async getField(key, path) {
const client = redisManager.getClient();
return await client.json.get(key, { path });
}
async appendToArray(key, path, ...values) {
const client = redisManager.getClient();
return await client.json.arrAppend(key, path, ...values);
}
async incrementNumber(key, path, increment = 1) {
const client = redisManager.getClient();
return await client.json.numIncrBy(key, path, increment);
}
}
async function demonstrateRedisJSON() {
try {
await redisManager.connect();
console.log('📄 Starting RedisJSON demo...\n');
const jsonService = new RedisJSONService();
// Store user profile as JSON document
const userProfile = {
id: 1001,
name: 'John Doe',
email: 'john@example.com',
preferences: {
theme: 'dark',
notifications: true,
language: 'en'
},
tags: ['premium', 'early-adopter'],
level: 25,
metadata: {
createdAt: new Date().toISOString(),
lastLogin: new Date().toISOString()
}
};
await jsonService.setDocument('user:1001', userProfile);
// Get entire document
console.log('📖 Retrieved user profile:');
const retrievedProfile = await jsonService.getDocument('user:1001');
console.log(JSON.stringify(retrievedProfile, null, 2));
// Update nested field
console.log('\n🔄 Updating theme preference...');
await jsonService.updateField('user:1001', '$.preferences.theme', 'light');
// Get specific field
const theme = await jsonService.getField('user:1001', '$.preferences.theme');
console.log(`🎨 Current theme: ${theme}`);
// Add new tag to array
console.log('\n🏷️ Adding new tag...');
await jsonService.appendToArray('user:1001', '$.tags', 'beta-tester');
// Get updated tags
const tags = await jsonService.getField('user:1001', '$.tags');
console.log('🏷️ Updated tags:', tags);
// Increment a numeric field
console.log('\n🔢 Incrementing user level...');
await jsonService.incrementNumber('user:1001', '$.level', 1);
const level = await jsonService.getField('user:1001', '$.level');
console.log('📈 New level:', level);
console.log('\n✅ RedisJSON demo completed!');
} catch (error) {
console.error('❌ Error in RedisJSON demo:', error.message);
} finally {
await redisManager.disconnect();
}
}
// Export for use in other examples
module.exports = RedisJSONService;
// Run demo if called directly
if (require.main === module) {
demonstrateRedisJSON();
}
```
### Working with RediSearch
Create `examples/redis-search.js`:
```javascript title="examples/redis-search.js"
const redisManager = require('../src/redisClient');
const { SchemaFieldTypes } = require('@redis/search');
class RedisSearchService {
async createIndex(indexName, schema, options = {}) {
const client = redisManager.getClient();
try {
// Use the native ft.create method (latest node-redis supports Search module)
await client.ft.create(indexName, schema, {
ON: 'JSON',
PREFIX: 'product:',
...options
});
console.log(`🔍 Created search index: ${indexName}`);
} catch (error) {
if (!error.message.includes('Index already exists')) {
throw error;
}
console.log(`🔍 Index ${indexName} already exists`);
}
}
async indexDocument(key, document) {
const client = redisManager.getClient();
await client.json.set(key, '$', document);
console.log(`📄 Indexed document: ${key}`);
}
async search(indexName, query, options = {}) {
const client = redisManager.getClient();
return await client.ft.search(indexName, query, options);
}
async aggregate(indexName, query, options = {}) {
const client = redisManager.getClient();
return await client.ft.aggregate(indexName, query, options);
}
}
async function demonstrateRediSearch() {
try {
await redisManager.connect();
console.log('🔍 Starting RediSearch demo...\n');
const searchService = new RedisSearchService();
// Create product search index using latest schema format
await searchService.createIndex('idx:products', {
'$.name': {
type: SchemaFieldTypes.TEXT,
AS: 'name',
SORTABLE: true
},
'$.description': {
type: SchemaFieldTypes.TEXT,
AS: 'description'
},
'$.price': {
type: SchemaFieldTypes.NUMERIC,
AS: 'price'
},
'$.category': {
type: SchemaFieldTypes.TAG,
AS: 'category'
},
'$.rating': {
type: SchemaFieldTypes.NUMERIC,
AS: 'rating'
}
});
// Index some products
const products = [
{
id: 1,
name: 'Wireless Headphones',
description: 'High-quality wireless headphones with noise cancellation',
price: 199.99,
category: 'electronics',
rating: 4.5
},
{
id: 2,
name: 'Smart Watch',
description: 'Feature-rich smartwatch with health monitoring',
price: 299.99,
category: 'electronics',
rating: 4.2
},
{
id: 3,
name: 'Coffee Maker',
description: 'Automatic coffee maker with programmable timer',
price: 89.99,
category: 'appliances',
rating: 4.0
}
];
for (const product of products) {
await searchService.indexDocument(`product:${product.id}`, product);
}
console.log('\n🔍 Searching for "wireless":');
let results = await searchService.search('idx:products', 'wireless');
console.log(`Found ${results.total} results:`);
results.documents.forEach((doc) => {
console.log(`- ${doc.value.name}: $${doc.value.price}`);
});
console.log('\n🔍 Searching electronics under $250:');
results = await searchService.search('idx:products', '@category:{electronics} @price:[0 250]');
console.log(`Found ${results.total} results:`);
results.documents.forEach((doc) => {
console.log(`- ${doc.value.name}: $${doc.value.price} (${doc.value.category})`);
});
console.log('\n✅ RediSearch demo completed!');
} catch (error) {
console.error('❌ Error in RediSearch demo:', error.message);
} finally {
await redisManager.disconnect();
}
}
// Export for use in other examples
module.exports = RedisSearchService;
// Run demo if called directly
if (require.main === module) {
demonstrateRediSearch();
}
```
### Test Redis Stack Features
Run the RedisJSON example:
```bash
node examples/redis-json.js
```
Run the RediSearch example:
```bash
node examples/redis-search.js
```
**Note**: Redis Stack features require a Redis Stack installation. If you're using standard Redis, these examples will show how the commands work, but you'll need Redis Stack for full functionality.
### Working with Connection Pooling (Latest v5+ Features)
For high-performance applications, use the latest connection pooling features:
```javascript title="examples/connection-pool.js"
const { createClientPool } = require('redis');
require('dotenv').config();
async function demonstrateConnectionPool() {
try {
console.log('🏊 Starting connection pool demo...\n');
// Create a connection pool (v5+ feature)
const pool = await createClientPool({
url: `redis://${process.env.REDIS_HOST}:${process.env.REDIS_PORT}`,
password: process.env.REDIS_PASSWORD,
database: parseInt(process.env.REDIS_DB) || 0
})
.on('error', err => console.error('Redis Client Pool Error', err))
.connect();
console.log('✅ Connection pool created and connected');
// Execute commands directly on the pool
await pool.ping();
console.log('📡 Pool ping successful');
// Use pool for multiple operations
const operations = [];
for (let i = 0; i < 10; i++) {
operations.push(pool.set(`pool:test:${i}`, `value-${i}`));
}
await Promise.all(operations);
console.log('💾 Stored 10 keys using pool');
// Read back the values
const values = [];
for (let i = 0; i < 10; i++) {
values.push(await pool.get(`pool:test:${i}`));
}
console.log('📖 Retrieved values:', values.slice(0, 3), '...');
// Clean up
for (let i = 0; i < 10; i++) {
await pool.del(`pool:test:${i}`);
}
await pool.destroy();
console.log('🧹 Pool destroyed');
console.log('\n✅ Connection pool demo completed!');
} catch (error) {
console.error('❌ Error in connection pool demo:', error.message);
}
}
// Export for use in other examples
module.exports = { demonstrateConnectionPool };
// Run demo if called directly
if (require.main === module) {
demonstrateConnectionPool();
}
```
### Test Connection Pool
```bash
node examples/connection-pool.js
```
## Comprehensive Troubleshooting Guide
### Common Connection Issues
#### Issue: "ECONNREFUSED" Error
**Symptoms:**
```
Error: connect ECONNREFUSED 127.0.0.1:6379
```
**Solutions:**
1. **Check Redis server status:**
```bash
# In Sealos terminal
redis-cli ping
```
2. **Verify connection parameters:**
```javascript
// Debug connection
const client = redis.createClient({
url: `redis://${process.env.REDIS_HOST}:${process.env.REDIS_PORT}`,
password: process.env.REDIS_PASSWORD,
socket: {
connectTimeout: 60000,
lazyConnect: true
}
});
client.on('error', (err) => {
console.error('Detailed error:', err);
});
```
3. **Check environment variables:**
```javascript
console.log('Redis config:', {
host: process.env.REDIS_HOST,
port: process.env.REDIS_PORT,
hasPassword: !!process.env.REDIS_PASSWORD
});
```
#### Issue: "WRONGPASS" Authentication Error
**Symptoms:**
```
ReplyError: WRONGPASS invalid username-password pair
```
**Solutions:**
1. **Verify password in environment:**
```bash
echo $REDIS_PASSWORD
```
2. **Test authentication manually:**
```bash
redis-cli -h your_host -p 6379 -a your_password ping
```
3. **Handle authentication in code:**
```javascript
const client = redis.createClient({
url: `redis://${process.env.REDIS_HOST}:${process.env.REDIS_PORT}`,
password: process.env.REDIS_PASSWORD,
// For Redis with ACL users
username: process.env.REDIS_USERNAME || 'default'
});
```
#### Issue: "Socket closed unexpectedly"
**Symptoms:**
```
Error: Socket closed unexpectedly
```
**Solutions:**
1. **Implement robust reconnection:**
```javascript
const client = redis.createClient({
socket: {
reconnectStrategy: (retries) => {
if (retries > 20) return false;
return Math.min(retries * 50, 500);
},
connectTimeout: 60000,
lazyConnect: true
}
});
```
2. **Handle connection events:**
```javascript
client.on('end', () => {
console.log('Connection ended, attempting to reconnect...');
});
client.on('reconnecting', () => {
console.log('Reconnecting to Redis...');
});
```
### Performance Issues
#### Issue: Slow Response Times
**Diagnosis:**
```javascript
// Monitor command execution time
const originalSend = client.sendCommand;
client.sendCommand = function(...args) {
const start = Date.now();
const result = originalSend.apply(this, args);
result.then(() => {
const duration = Date.now() - start;
if (duration > 100) { // Log slow commands
console.warn(`Slow Redis command: ${args[0]} took ${duration}ms`);
}
});
return result;
};
```
**Solutions:**
1. **Use pipelining for bulk operations:**
```javascript
// Instead of multiple individual commands
const pipeline = client.multi();
for (let i = 0; i < 1000; i++) {
pipeline.set(`key:${i}`, `value:${i}`);
}
await pipeline.exec();
```
2. **Optimize data structures:**
```javascript
// Use appropriate data types
// For counters: use INCR instead of GET/SET
await client.incr('page_views');
// For bulk data: use HMSET instead of multiple SET
await client.hSet('user:1001', {
name: 'John',
email: 'john@example.com',
age: '30'
});
```
#### Issue: Memory Usage Problems
**Diagnosis:**
```javascript
async function diagnoseMemory() {
const info = await client.info('memory');
const stats = await client.info('stats');
console.log('Memory info:', info);
console.log('Stats:', stats);
// Check for memory leaks
const keyCount = await client.dbSize();
console.log('Total keys:', keyCount);
}
```
**Solutions:**
1. **Set appropriate TTL:**
```javascript
// Always set expiration for cache data
await client.setEx('cache:user:1001', 3600, userData);
// Use EXPIRE for existing keys
await client.expire('session:abc123', 1800);
```
2. **Clean up unused keys:**
```javascript
async function cleanupOldKeys() {
const cursor = '0';
let scanCursor = cursor;
do {
const result = await client.scan(scanCursor, {
MATCH: 'temp:*',
COUNT: 100
});
if (result.keys.length > 0) {
await client.del(result.keys);
}
scanCursor = result.cursor;
} while (scanCursor !== '0');
}
```
### Data Consistency Issues
#### Issue: Race Conditions
**Problem:** Multiple clients modifying the same data simultaneously.
**Solution - Optimistic Locking:**
```javascript
async function updateUserBalance(userId, amount) {
const key = `user:${userId}:balance`;
while (true) {
// Watch the key for changes
await client.watch(key);
const currentBalance = parseFloat(await client.get(key) || '0');
const newBalance = currentBalance + amount;
// Start transaction
const multi = client.multi();
multi.set(key, newBalance.toString());
try {
const results = await multi.exec();
if (results) {
// Transaction succeeded
return newBalance;
}
// Transaction failed due to key modification, retry
} catch (error) {
throw error;
}
}
}
```
**Solution - Lua Scripts for Atomicity:**
```javascript
const updateBalanceScript = `
local key = KEYS[1]
local amount = tonumber(ARGV[1])
local current = tonumber(redis.call('GET', key) or 0)
local new_balance = current + amount
if new_balance >= 0 then
redis.call('SET', key, new_balance)
return new_balance
else
return -1
end
`;
async function updateBalanceAtomic(userId, amount) {
const result = await client.eval(
updateBalanceScript,
1,
`user:${userId}:balance`,
amount.toString()
);
if (result === -1) {
throw new Error('Insufficient balance');
}
return result;
}
```
## Best Practices Summary
### Development Best Practices
1. **Always use environment variables** for configuration
2. **Implement proper error handling** with specific error types
3. **Use connection pooling** for high-traffic applications
4. **Set appropriate TTL** for all cached data
5. **Use pipelining** for bulk operations
6. **Implement health checks** for production deployments
### Security Best Practices
1. **Enable TLS/SSL** in production
2. **Use strong passwords** and consider ACL users
3. **Restrict network access** to Redis instances
4. **Regularly update** Redis and client libraries
5. **Monitor for suspicious activity**
### Performance Best Practices
1. **Choose appropriate data structures** for your use case
2. **Use Lua scripts** for complex atomic operations
3. **Monitor memory usage** and implement cleanup strategies
4. **Optimize serialization** for large objects
5. **Use Redis Stack modules** when appropriate
### Production Best Practices
1. **Implement comprehensive monitoring**
2. **Set up proper logging** and alerting
3. **Use container orchestration** for scalability
4. **Plan for disaster recovery**
5. **Regular performance testing** and optimization
## Complete Application Example
Let's create a comprehensive example that combines multiple Redis features. Create `examples/complete-app.js`:
```javascript title="examples/complete-app.js"
const redisManager = require('../src/redisClient');
const TaskQueue = require('./task-queue');
const Leaderboard = require('./leaderboard');
const { CacheAsideService } = require('./cache-patterns');
class RedisApplication {
constructor() {
this.taskQueue = new TaskQueue('app_tasks');
this.leaderboard = new Leaderboard('user_scores');
this.cache = new CacheAsideService(3600);
}
async initialize() {
await redisManager.connect();
console.log('🚀 Redis Application initialized');
}
async simulateUserActivity() {
console.log('\n👥 Simulating user activity...');
// Add some users to leaderboard
const users = [
{ id: 'user1', name: 'Alice', score: 1500 },
{ id: 'user2', name: 'Bob', score: 2300 },
{ id: 'user3', name: 'Charlie', score: 1800 },
{ id: 'user4', name: 'Diana', score: 2100 }
];
for (const user of users) {
await this.leaderboard.updateScore(user.id, user.score, { name: user.name });
// Add task to send welcome email
await this.taskQueue.addTask({
type: 'welcome_email',
userId: user.id,
email: `${user.name.toLowerCase()}@example.com`
});
}
}
async processBackgroundTasks() {
console.log('\n⚡ Processing background tasks...');
for (let i = 0; i < 4; i++) {
const task = await this.taskQueue.processTask(1);
if (task) {
console.log(`📧 Sending ${task.data.type} to ${task.data.email}`);
// Simulate email sending
await new Promise(resolve => setTimeout(resolve, 500));
await this.taskQueue.completeTask(task.id);
}
}
}
async showLeaderboard() {
console.log('\n🏆 Current Leaderboard:');
const topPlayers = await this.leaderboard.getTopPlayers(5);
topPlayers.forEach(player => {
console.log(`${player.rank}. ${player.name} - ${player.score} points`);
});
}
async demonstrateCache() {
console.log('\n💾 Cache demonstration:');
// Simulate expensive operation
const expensiveOperation = async (id) => {
console.log(`🔄 Performing expensive calculation for ${id}...`);
await new Promise(resolve => setTimeout(resolve, 1000));
return { id, result: Math.random() * 1000, timestamp: new Date().toISOString() };
};
// First call - cache miss
console.log('First call (cache miss):');
const result1 = await this.cache.get('calculation:1', () => expensiveOperation('calc1'));
console.log('Result:', result1);
// Second call - cache hit
console.log('\nSecond call (cache hit):');
const result2 = await this.cache.get('calculation:1', () => expensiveOperation('calc1'));
console.log('Result:', result2);
}
async getApplicationStats() {
const client = redisManager.getClient();
const stats = {
queueStats: await this.taskQueue.getQueueStats(),
totalKeys: await client.dbSize(),
memoryUsage: await client.info('memory'),
topPlayer: await this.leaderboard.getTopPlayers(1)
};
return stats;
}
async cleanup() {
await redisManager.disconnect();
console.log('🧹 Application cleanup completed');
}
}
async function runCompleteExample() {
const app = new RedisApplication();
try {
await app.initialize();
await app.simulateUserActivity();
await app.processBackgroundTasks();
await app.showLeaderboard();
await app.demonstrateCache();
console.log('\n📊 Application Statistics:');
const stats = await app.getApplicationStats();
console.log('Queue stats:', stats.queueStats);
console.log('Total Redis keys:', stats.totalKeys);
console.log('Top player:', stats.topPlayer[0]);
console.log('\n✅ Complete application example finished!');
} catch (error) {
console.error('❌ Application error:', error.message);
} finally {
await app.cleanup();
}
}
// Run the complete example
if (require.main === module) {
runCompleteExample();
}
module.exports = RedisApplication;
```
### Run All Examples
Now you can test all the examples we've built:
```bash
# Test connection
node tests/connection-test.js
# Basic operations
node examples/basic-operations.js
# Advanced data structures
node examples/leaderboard.js
node examples/task-queue.js
# Caching patterns
node examples/cache-patterns.js
# Redis Stack features (if available)
node examples/redis-json.js
node examples/redis-search.js
# Connection pooling (v5+ features)
node examples/connection-pool.js
# Complete application
node examples/complete-app.js
```
### Project Structure Summary
Your final project structure should look like this:
<Files>
<Folder name="redis-nodejs-guide" defaultOpen>
<File name=".env" />
<File name="package.json" />
<Folder name="src" defaultOpen>
<File name="redisClient.js" />
</Folder>
<Folder name="examples">
<File name="basic-operations.js" />
<File name="leaderboard.js" />
<File name="task-queue.js" />
<File name="cache-patterns.js" />
<File name="redis-json.js" />
<File name="redis-search.js" />
<File name="connection-pool.js" />
<File name="complete-app.js" />
</Folder>
<Folder name="tests">
<File name="connection-test.js" />
</Folder>
</Folder>
</Files>
## Next Steps
Now that you have a solid foundation with Redis and Node.js, consider exploring:
1. **Production Deployment**: Implement monitoring, logging, and error handling
2. **Performance Optimization**: Use pipelining, connection pooling, and memory optimization
3. **Security**: Enable TLS, implement proper authentication, and secure your Redis instance
4. **Scaling**: Explore Redis Cluster, Sentinel, and horizontal scaling strategies
5. **Integration**: Connect with your favorite Node.js frameworks (Express, NestJS, Fastify)
For more detailed information and updates, refer to the [official node-redis documentation](https://github.com/redis/node-redis) and [Redis Stack documentation](https://redis.io/docs/stack/).
file: ./content/docs/guides/databases/redis/php.en.mdx
meta: {
"title": "PHP",
"description": "Learn how to connect to Redis databases in Sealos DevBox using PHP"
}
This guide will walk you through the process of connecting to a Redis database using PHP within your Sealos DevBox project.
## Prerequisites
* [A Sealos DevBox project](/docs/guides/devbox/create-a-project) with PHP environment
* [A Redis database created using the Database app in Sealos](./)
## Install Required Extensions
In your Cursor terminal, ensure that the Redis extension for PHP is installed:
```bash
sudo apt-get update
sudo apt-get install php-redis -y
```
## Connection Setup
<div className="fd-steps [&_h4]:fd-step">
#### Create a Configuration File
First, let's create a configuration file to store our Redis connection parameters. Create a file named `config.php` in your project directory with the following content:
```php
<?php
return [
'host' => 'your_redis_host',
'port' => 6379,
'password' => 'your_redis_password'
];
```
Replace the placeholders with your actual Redis credentials from the Database app in Sealos.
#### Create a Redis Connection Function
Next, let's create a PHP file that will handle the Redis connection. Create a file named `redis_connect.php` with the following content:
```php
<?php
function getRedisConnection() {
$config = include 'config.php';
try {
$redis = new Redis();
$redis->connect($config['host'], $config['port']);
if (isset($config['password']) && !empty($config['password'])) {
$redis->auth($config['password']);
}
echo "Connected successfully to Redis.\n";
return $redis;
} catch (Exception $e) {
die("Connection failed: " . $e->getMessage());
}
}
```
This function reads the configuration from `config.php` and establishes a connection to the Redis database.
#### Create a Test Script
Now, let's create a test script to verify our connection and perform some basic Redis operations. Create a file named `test_redis.php` with the following content:
```php
<?php
require_once 'redis_connect.php';
$redis = getRedisConnection();
// Set a key
$redis->set('mykey', 'Hello from Sealos DevBox!');
echo "Key set successfully.\n";
// Get a key
$value = $redis->get('mykey');
echo "Retrieved value: " . $value . "\n";
// Set a hash
$redis->hSet('myhash', 'field1', 'value1');
$redis->hSet('myhash', 'field2', 'value2');
echo "Hash set successfully.\n";
// Get hash fields
$hashValue = $redis->hGetAll('myhash');
echo "Retrieved hash: " . print_r($hashValue, true) . "\n";
// Close the connection
$redis->close();
echo "Redis connection closed.\n";
```
This script demonstrates setting and getting a key, as well as working with Redis hashes.
</div>
## Usage
To run the test script, use the following command in your Cursor terminal:
```bash
php test_redis.php
```
This will execute the script, demonstrating the connection to Redis and basic operations.
## Best Practices
1. Use environment variables or a separate configuration file for Redis credentials.
2. Handle potential errors using try-catch blocks.
3. Close the Redis connection after operations are complete.
4. Use Redis transactions for operations that need to be atomic.
5. Consider using a connection pool for better performance in production environments.
## Troubleshooting
If you encounter connection issues:
1. Verify your Redis credentials in the `config.php` file.
2. Ensure your Redis database is running and accessible.
3. Check for any network restrictions in your DevBox environment.
4. Confirm that the `php-redis` extension is correctly installed.
For more detailed information on using Redis with PHP, refer to the [official PHP Redis documentation](https://github.com/phpredis/phpredis).
file: ./content/docs/guides/databases/redis/python.en.mdx
meta: {
"title": "Python",
"description": "Learn how to connect to Redis databases in Sealos DevBox using Python"
}
This guide will walk you through the process of connecting to a Redis database using Python within your Sealos DevBox project.
## Prerequisites
* [A Sealos DevBox project](/docs/guides/devbox/create-a-project) with Python environment
* [A Redis database created using the Database app in Sealos](./)
## Activating the Python Environment
Before you start, you need to activate the Python virtual environment in your DevBox. Open the terminal within Cursor IDE and run:
```bash
source ./bin/activate
```
You should see your prompt change, indicating that the virtual environment is now active.
## Installing Required Packages
In your Cursor terminal, install the necessary packages:
```bash
pip install redis python-dotenv
```
This command installs:
* `redis`: The Redis client for Python
* `python-dotenv`: A Python package that allows you to load environment variables from a .env file
## Connection Setup
<div className="fd-steps [&_h4]:fd-step">
#### Set up the environment variables
First, let's set up the environment variables for our database connection. Create a `.env` file in your project root with the following content:
```ini title=".env"
REDIS_HOST=your_redis_host
REDIS_PORT=6379
REDIS_PASSWORD=your_redis_password
```
Replace the placeholders with your actual Redis credentials from the Database app in Sealos.
#### Create a Redis connection module
Create a new file named `redis_connection.py` with the following content:
```python title="redis_connection.py"
import os
from dotenv import load_dotenv
import redis
# Load environment variables
load_dotenv()
def get_redis_connection():
try:
r = redis.Redis(
host=os.getenv('REDIS_HOST'),
port=os.getenv('REDIS_PORT'),
password=os.getenv('REDIS_PASSWORD'),
decode_responses=True
)
r.ping() # Test the connection
print("Successfully connected to Redis")
return r
except redis.ConnectionError as e:
print(f"Error connecting to Redis: {e}")
return None
def close_connection(connection):
if connection:
connection.close()
print("Redis connection closed")
```
This module provides two main functions:
1. `get_redis_connection()`: This function establishes a connection to the Redis database using the credentials stored in the environment variables. It returns the connection object if successful, or None if an error occurs.
2. `close_connection(connection)`: This function closes the Redis connection when it's no longer needed.
#### Create a test script
Now, let's create a test script to verify our connection and perform some basic Redis operations. Create a file named `test_redis.py` with the following content:
```python title="test_redis.py"
from redis_connection import get_redis_connection, close_connection
def set_value(r, key, value):
r.set(key, value)
print(f"Set {key}: {value}")
def get_value(r, key):
value = r.get(key)
print(f"Get {key}: {value}")
return value
def main():
redis_conn = get_redis_connection()
if redis_conn:
try:
# String operations
set_value(redis_conn, "mykey", "Hello from Sealos DevBox!")
get_value(redis_conn, "mykey")
# List operations
redis_conn.lpush("mylist", "element1", "element2", "element3")
print("List after push:", redis_conn.lrange("mylist", 0, -1))
print("Popped element:", redis_conn.lpop("mylist"))
print("List after pop:", redis_conn.lrange("mylist", 0, -1))
# Hash operations
redis_conn.hset("myhash", "field1", "value1")
redis_conn.hset("myhash", "field2", "value2")
print("Hash value for field1:", redis_conn.hget("myhash", "field1"))
print("All hash fields:", redis_conn.hgetall("myhash"))
except Exception as e:
print(f"An error occurred: {e}")
finally:
close_connection(redis_conn)
if __name__ == "__main__":
main()
```
This script demonstrates various Redis operations:
* Setting and getting string values
* Working with lists (push, pop, and range)
* Using hash structures (set, get, and get all)
</div>
## Running the Test Script
To run the test script, make sure your virtual environment is activated, then execute:
```bash
python test_redis.py
```
If everything is set up correctly, you should see output indicating successful connection and the results of various Redis operations.
## Best Practices
1. Always activate the virtual environment before running your Python scripts or installing packages.
2. Use environment variables to store sensitive information like database credentials.
3. Close Redis connections after use to free up resources.
4. Handle exceptions appropriately to manage potential errors.
5. Consider using connection pooling for better performance in production environments.
## Troubleshooting
If you encounter connection issues:
1. Ensure you've activated the virtual environment with `source ./bin/activate`.
2. Verify that your Redis database is running and accessible.
3. Double-check your Redis credentials in the `.env` file.
4. Check the Redis logs in the Database app for any error messages.
For more detailed information on using Redis with Python, refer to the [official Redis-py documentation](https://redis-py.readthedocs.io/en/stable/).
file: ./content/docs/guides/databases/redis/rust.en.mdx
meta: {
"title": "Rust",
"description": "Learn how to connect to Redis databases in Sealos DevBox using Rust"
}
This guide will walk you through the process of connecting to a Redis database using Rust within your Sealos DevBox project.
## Prerequisites
* [A Sealos DevBox project](/docs/guides/devbox/create-a-project) with Rust environment
* [A Redis database created using the Database app in Sealos](./)
## Install Required Dependencies
In your Cursor terminal, add the necessary dependencies to your `Cargo.toml` file:
```toml
[dependencies]
redis = "0.22.0"
dotenv = "0.15.0"
```
These dependencies include:
* `redis`: The Redis client for Rust
* `dotenv`: A library for loading environment variables from a file
## Connection Setup
<div className="fd-steps [&_h4]:fd-step">
#### Set up the environment variables
First, let's set up the environment variables for our database connection. Create a `.env` file in your project root with the following content:
```ini title=".env"
REDIS_HOST=your_redis_host
REDIS_PORT=6379
REDIS_PASSWORD=your_redis_password
```
Replace the placeholders with your actual Redis credentials from the Database app in Sealos.
#### Create the main.rs file
Create a new file named `src/main.rs` with the following content:
```rust title="src/main.rs"
use redis::Commands;
use dotenv::dotenv;
use std::env;
fn main() -> redis::RedisResult<()> {
// Load environment variables from .env file
dotenv().ok();
// Get Redis connection details from environment variables
let redis_host = env::var("REDIS_HOST").expect("REDIS_HOST must be set");
let redis_port = env::var("REDIS_PORT").expect("REDIS_PORT must be set");
let redis_password = env::var("REDIS_PASSWORD").expect("REDIS_PASSWORD must be set");
// Create the Redis connection URL
let redis_url = format!("redis://:{}@{}:{}", redis_password, redis_host, redis_port);
// Create a client
let client = redis::Client::open(redis_url)?;
// Connect to Redis
let mut con = client.get_connection()?;
// Set a key
let _: () = con.set("my_key", "Hello from Sealos DevBox!")?;
// Get a key
let value: String = con.get("my_key")?;
println!("Retrieved value: {}", value);
// Set a hash
let _: () = redis::cmd("HSET")
.arg("my_hash")
.arg("field1")
.arg("value1")
.arg("field2")
.arg("value2")
.query(&mut con)?;
// Get hash fields
let hash_value: std::collections::HashMap<String, String> = con.hgetall("my_hash")?;
println!("Retrieved hash: {:?}", hash_value);
Ok(())
}
```
Let's break down the main components of this code:
1. **Imports**: We import necessary modules from `redis` and `dotenv` crates.
2. **Main function**: The `main` function is where we perform our Redis operations.
3. **Environment setup**: We load environment variables from the `.env` file and retrieve the Redis connection details.
4. **Connection**: We create a Redis client and establish a connection.
5. **Basic operations**: We demonstrate setting and getting a key, as well as working with Redis hashes.
</div>
## Usage
To run the application, use the following command in your Cursor terminal:
```bash
cargo run
```
This will compile and execute the `main` function, demonstrating the connection to Redis and basic operations.
## Best Practices
1. Use environment variables for Redis credentials.
2. Handle errors appropriately using Rust's `Result` type.
3. Use the `redis::Commands` trait for a more idiomatic way of interacting with Redis.
4. Close the Redis connection when it's no longer needed (in this case, it's handled automatically when `con` goes out of scope).
5. Consider using connection pooling for better performance in production environments.
## Troubleshooting
If you encounter connection issues:
1. Verify your Redis credentials in the `.env` file.
2. Ensure your Redis database is running and accessible.
3. Check for any network restrictions in your DevBox environment.
4. Confirm that all required dependencies are correctly specified in your `Cargo.toml` file.
For more detailed information on using Redis with Rust, refer to the [redis-rs documentation](https://docs.rs/redis/latest/redis/).
file: ./content/docs/k8s/operations/build-image/build-image-binary.en.mdx
meta: {
"title": "构建基于二进制文件的集群镜像",
"keywords": [
"集群镜像构建",
"二进制文件打包",
"sealos工具",
"helm安装",
"镜像推送"
],
"description": "学习如何使用sealos工具将二进制文件（如helm）打包为集群镜像，并通过主节点部署实现安装。包含详细步骤和命令示例。"
}
file: ./content/docs/k8s/operations/build-image/build-image-go_template.en.mdx
meta: {
"title": "构建基于 go-template 的集群镜像",
"keywords": [
"集群镜像构建",
"go-template",
"Kubefile",
"环境变量",
"sealos",
"yaml模板",
"服务类型自定义",
"镜像运行",
"kubectl",
"helm"
],
"description": "学习如何使用go-template构建集群镜像，通过Kubefile和yaml模板利用环境变量自定义服务配置，掌握sealos运行镜像的高级技巧。"
}
file: ./content/docs/k8s/operations/build-image/build-image-helm_charts.en.mdx
meta: {
"title": "构建基于 Helm Charts 的集群镜像",
"keywords": [
"Helm Charts",
"集群镜像",
"Sealos",
"Kubernetes",
"nginx",
"镜像构建",
"容器化",
"云原生",
"DevOps",
"CI/CD"
],
"description": "学习如何使用Sealos和Helm Charts构建基于nginx的Kubernetes集群镜像。本教程涵盖准备工作、Charts配置、Kubefile创建、镜像构建和安装等步骤。"
}
file: ./content/docs/k8s/operations/build-image/build-image-image-list.en.mdx
meta: {
"title": "构建基于镜像清单的集群镜像",
"keywords": [
"集群镜像构建",
"镜像列表",
"Kubefile",
"容器镜像",
"kubectl apply",
"Calico",
"镜像tar包",
"docker-archive",
"oci-archive",
"Sealos"
],
"description": "学习如何使用镜像列表或docker存储的tar包构建Sealos集群镜像。本指南涵盖了Kubefile配置、镜像列表格式和tar包构建方法，助您轻松管理容器化应用。"
}
file: ./content/docs/k8s/operations/build-image/build-image-manifests.en.mdx
meta: {
"title": "构建基于部署清单的集群镜像",
"keywords": [
"集群镜像构建",
"Sealos",
"Kubernetes",
"部署清单",
"Kubefile",
"Docker镜像",
"nginx应用",
"镜像推送",
"私有镜像仓库"
],
"description": "学习如何使用Sealos构建基于部署清单的Kubernetes集群镜像。本教程涵盖从准备工作到镜像推送的完整流程，包括创建Kubefile和验证镜像等关键步骤。"
}
file: ./content/docs/k8s/operations/build-image/build-image-scp_exec.en.mdx
meta: {
"title": "使用 exec 和 scp 命令构建集群镜像",
"keywords": [
"sealos构建集群镜像",
"sealos exec",
"sealos scp",
"集群镜像构建",
"Kubefile",
"openebs mayastor",
"flannel部署"
],
"description": "学习如何使用sealos exec和scp命令构建自定义集群镜像。本文详细介绍了openebs mayastor和flannel的部署过程，帮助开发者轻松创建高效的Kubernetes集群。"
}
file: ./content/docs/k8s/operations/build-image/build-image-with-kubeadm-run-cluster.en.mdx
meta: {
"title": "使用构建镜像自定义 Kubernetes 集群",
"keywords": [
"自定义Kubernetes集群",
"kubeadm config",
"构建自定义镜像",
"Clusterfile配置",
"sealos",
"Calico网络配置",
"Pod CIDR",
"集群安装"
],
"description": "学习如何使用kubeadm config构建自定义镜像来定制Kubernetes集群。包括构建镜像、配置Clusterfile和安装集群的详细步骤，助您轻松实现个性化部署。"
}
file: ./content/docs/k8s/operations/build-image/build-multi-arch-image.en.mdx
meta: {
"title": "构建支持多架构的集群镜像",
"keywords": [
"多架构集群镜像",
"sealos构建",
"amd64和arm64",
"容器镜像仓库",
"镜像清单",
"Kubefile",
"多平台支持",
"Docker优化",
"Kubernetes部署",
"镜像推送"
],
"description": "学习如何使用sealos工具构建支持amd64和arm64架构的集群镜像，并将其推送到容器镜像仓库。掌握多架构镜像构建、推送和清单创建的完整流程。"
}
file: ./content/docs/k8s/operations/build-image/build_run_application_private_registry.en.mdx
meta: {
"title": "使用私有镜像构建一个完整应用服务",
"keywords": [
"私有镜像",
"Helm Chart",
"Kubernetes应用",
"Sealos",
"容器化部署",
"镜像构建",
"服务暴露",
"集群管理",
"应用服务",
"DevOps"
],
"description": "本文详细介绍如何使用私有镜像和Helm Chart构建完整的Kubernetes应用服务。包括镜像构建、服务配置、部署测试等关键步骤，助您轻松实现容器化应用管理。"
}
file: ./content/docs/k8s/operations/build-image/index.en.mdx
meta: {
"title": "Sealos 集群镜像构建",
"keywords": [
"Sealos集群镜像",
"镜像构建",
"基础构建",
"高级构建",
"sealos build",
"多阶段构建",
"集群镜像优化"
],
"description": "探索Sealos集群镜像构建的多种方法，从基础到高级技术。学习如何优化镜像大小，使用sealos build命令进行定制构建，提升您的Sealos使用体验。"
}
file: ./content/docs/k8s/operations/registry/index.en.mdx
meta: {
"title": "Sealos 镜像仓库",
"keywords": [
"Sealos镜像仓库",
"Docker Registry",
"容器镜像管理",
"镜像同步备份",
"安全管理",
"镜像仓库故障排除"
],
"description": "探索Sealos镜像仓库管理指南，涵盖安全设置、镜像管理、同步备份及故障排除，助您高效管理Docker Registry，确保容器镜像的安全性和可靠性。"
}
file: ./content/docs/k8s/operations/registry/sealos_sync_backup_solution.en.mdx
meta: {
"title": "高效的Sealos集群镜像同步和备份策略",
"keywords": [
"Sealos集群镜像同步",
"容器镜像备份",
"镜像仓库同步",
"sealos registry",
"增量镜像同步",
"高效镜像管理",
"容器镜像优化",
"Kubernetes镜像同步"
],
"description": "探索Sealos高效的集群镜像同步和备份策略，学习如何创建临时仓库、同步镜像，实现增量同步，优化容器镜像管理，提高Kubernetes集群效率。"
}
file: ./content/docs/k8s/operations/registry/using_sealoshub_private_registry.en.mdx
meta: {
"title": "如何使用 sealos作为私有容器仓库",
"keywords": [
"sealos私有容器仓库",
"image-cri-shim",
"sealos login",
"Docker客户端配置",
"推送与拉取镜像"
],
"description": "了解如何使用sealos作为私有容器仓库，包括image-cri-shim守护进程、sealos登录、Docker客户端配置及镜像推送与拉取的详细步骤。"
}
file: ./content/docs/k8s/operations/run-cluster/config-customize-app_images-config-rootfs_mage.en.mdx
meta: {
"title": "配置和自定义应用镜像及其运行时环境",
"keywords": [
"Sealos",
"Config对象",
"应用镜像",
"Clusterfile",
"node-local-dns"
],
"description": "了解如何使用Sealos的Config对象在运行时对应用镜像进行补丁操作，创建和自定义node-local-dns应用镜像及其运行时环境。"
}
file: ./content/docs/k8s/operations/run-cluster/gen-apply-cluster.en.mdx
meta: {
"title": "自定义配置安装",
"keywords": [
"sealos",
"Clusterfile",
"Kubernetes集群",
"自定义配置",
"集群管理"
],
"description": "了解如何使用sealos生成和应用Clusterfile，自定义配置Kubernetes集群，实现高效的集群管理。"
}
file: ./content/docs/k8s/operations/run-cluster/index.en.mdx
meta: {
"title": "Sealos 集群镜像运行",
"keywords": [
"Sealos集群",
"集群初始化",
"节点管理",
"服务管理",
"实战示例"
],
"description": "了解如何有效运行和管理Sealos集群，包括集群初始化、节点管理、服务管理和实战示例的详细教程和资源。"
}
file: ./content/docs/k8s/operations/run-cluster/template-apply-cluster.en.mdx
meta: {
"title": "模板配置安装",
"keywords": [
"Go模板语法",
"Clusterfile",
"Kubernetes集群部署",
"sealos",
"自定义values文件"
],
"description": "了解如何使用Go模板语法编写Clusterfile并通过sealos部署Kubernetes集群，包含自定义values文件示例和详细步骤。"
}
file: ./content/docs/k8s/operations/run-cluster/upgrade-cluster.en.mdx
meta: {
"title": "如何升级集群",
"keywords": [
"Kubernetes升级",
"sealos",
"集群管理",
"Kubernetes版本",
"Kubernetes集群"
],
"description": "了解如何使用sealos命令轻松升级Kubernetes集群，确保集群稳定运行并保持最新版本。"
}
file: ./content/docs/k8s/reference/sealctl/cert.en.mdx
meta: {
"title": "cert 证书管理",
"keywords": [
"Kubernetes证书管理",
"sealctl cert命令",
"Kubernetes集群安全",
"TLS加密",
"Kubernetes证书生成"
],
"description": "了解如何使用sealctl cert命令生成Kubernetes集群所需的证书，确保组件之间的安全通信和数据加密。"
}
file: ./content/docs/k8s/reference/sealctl/cri.en.mdx
meta: {
"title": "CRI 容器管理",
"keywords": [
"Kubernetes",
"CRI",
"容器管理",
"sealctl",
"cgroup驱动"
],
"description": "了解如何使用sealctl命令管理和检查Kubernetes集群中的CRI容器运行时环境，确保其正确配置和正常运行。"
}
file: ./content/docs/k8s/reference/sealctl/hostname.en.mdx
meta: {
"title": "hostname 获取主机名",
"keywords": [
"sealctl",
"主机名",
"获取主机名",
"操作系统",
"命令行工具"
],
"description": "使用sealctl命令行工具获取操作系统的主机名，无需传递任何参数，简单高效。"
}
file: ./content/docs/k8s/reference/sealctl/hosts.en.mdx
meta: {
"title": "hosts 管理",
"keywords": [
"hosts管理",
"sealctl命令",
"hosts文件",
"域名解析",
"IP地址映射"
],
"description": "了解如何使用sealctl命令管理操作系统的hosts文件，包括列出、添加和删除域名与IP地址映射的详细步骤。"
}
file: ./content/docs/k8s/reference/sealctl/index.en.mdx
meta: {
"title": "Sealctl 使用指南",
"keywords": [
"Sealos",
"sealctl",
"集群管理",
"容器管理",
"证书管理",
"IPVS负载均衡",
"静态Pod",
"Kubernetes",
"镜像仓库",
"CRI配置"
],
"description": "了解如何使用Sealos的sealctl命令行工具进行集群管理、容器管理、证书管理、IPVS负载均衡、静态Pod部署等操作，全面掌控Kubernetes集群。"
}
file: ./content/docs/k8s/reference/sealctl/ipvs.en.mdx
meta: {
"title": "ipvs 管理",
"keywords": [
"IPVS负载均衡",
"sealctl命令",
"虚拟服务器",
"真实服务器",
"健康检查",
"代理模式",
"调度算法",
"清理功能"
],
"description": "了解如何使用sealctl ipvs命令创建和管理本地IPVS负载均衡，包括虚拟服务器和真实服务器的映射、健康检查、代理模式和调度算法配置。"
}
file: ./content/docs/k8s/reference/sealctl/registry.en.mdx
meta: {
"title": "registry 镜像仓库",
"keywords": [
"Sealos",
"sealctl",
"registry serve",
"Docker 镜像仓库",
"文件系统模式",
"内存模式",
"镜像管理",
"Docker 分发",
"镜像同步"
],
"description": "了解如何使用Sealos的sealctl registry serve命令启动和管理Docker镜像仓库，支持文件系统和内存模式，轻松实现镜像同步和分发。"
}
file: ./content/docs/k8s/reference/sealctl/static-pod.en.mdx
meta: {
"title": "static-pod 配置",
"keywords": [
"static-pod",
"sealctl",
"lvscare",
"Kubernetes",
"静态Pod配置",
"kubelet",
"IPVS",
"Kubernetes集群"
],
"description": "了解如何使用sealctl命令生成Kubernetes静态Pod配置，特别是lvscare静态Pod，简化集群管理。"
}
file: ./content/docs/k8s/reference/sealctl/tar-and-untar.en.mdx
meta: {
"title": "tar 与 untar 详解",
"keywords": [
"Sealos",
"sealctl tar",
"sealctl untar",
"文件压缩",
"文件解压"
],
"description": "了解如何使用Sealos的sealctl tar和sealctl untar命令进行文件和文件夹的压缩与解压，简化备份和迁移操作。"
}
file: ./content/docs/k8s/reference/sealctl/token.en.mdx
meta: {
"title": "token 管理",
"keywords": [
"sealctl token",
"Kubernetes 集群",
"token 管理",
"节点身份验证",
"配置文件",
"证书密钥",
"工作节点",
"主节点",
"安全性",
"节点加入"
],
"description": "了解如何使用 sealctl token 命令生成用于 Kubernetes 集群节点身份验证的 token，确保工作节点安全加入集群，简化管理过程。"
}
file: ./content/docs/k8s/reference/sealos/app-cluster-image.en.mdx
meta: {
"title": "应用集群镜像使用指南",
"keywords": [
"Sealos",
"cluster-image",
"Kubernetes集群",
"应用镜像",
"Docker镜像",
"GitHub Action",
"镜像构建",
"Helm chart",
"Kubernetes yaml",
"镜像配置"
],
"description": "Sealos 提供 cluster-image 仓库，用于构建和发布 Kubernetes 集群的应用镜像，支持 Docker 和应用集群镜像构建，使用 GitHub Action。"
}
file: ./content/docs/k8s/reference/sealos/index.en.mdx
meta: {
"title": "Sealos 使用指南",
"keywords": [
"Sealos",
"云操作系统",
"Kubernetes管理",
"集群镜像",
"命令行工具"
],
"description": "了解Sealos使用指南，掌握云操作系统管理Kubernetes集群的命令行工具和集群镜像的详细信息。"
}
file: ./content/docs/k8s/reference/sealos/kubernetes-cluster-image.en.mdx
meta: {
"title": "Kubernetes 集群镜像说明文档",
"keywords": [
"Sealos",
"Kubernetes集群镜像",
"rootfs类型",
"容器运行时",
"Kubernetes镜像版本"
],
"description": "了解Sealos官方提供的Kubernetes集群镜像，包括镜像名称、类型和版本，选择适合您的Kubernetes容器运行时解决方案。"
}
file: ./content/docs/k8s/reference/sealos/commands/add.en.mdx
meta: {
"title": "add 集群节点添加",
"keywords": [
"Sealos",
"集群节点添加",
"Sealos add",
"控制节点",
"节点添加"
],
"description": "了解如何使用Sealos add命令向集群中添加节点和控制节点，确保etcd正常选举，掌握基本用法和选项。"
}
file: ./content/docs/k8s/reference/sealos/commands/apply.en.mdx
meta: {
"title": "apply 启动集群",
"keywords": [
"sealos apply",
"Kubernetes 集群",
"集群镜像",
"Clusterfile",
"sealos 命令"
],
"description": "了解如何使用 sealos apply 命令在 Kubernetes 集群中运行集群镜像，详细介绍基本用法和选项设置。"
}
file: ./content/docs/k8s/reference/sealos/commands/build.en.mdx
meta: {
"title": "build 构建镜像",
"keywords": [
"Sealos build命令",
"构建OCI镜像",
"Dockerfile构建",
"镜像构建选项",
"Sealos使用指南"
],
"description": "了解如何使用Sealos的build命令构建OCI镜像，包括主要选项和示例，提升构建效率和便捷性。"
}
file: ./content/docs/k8s/reference/sealos/commands/cert.en.mdx
meta: {
"title": "cert 更新集群证书",
"keywords": [
"sealos cert",
"集群证书更新",
"API服务器证书",
"sealos命令行工具",
"Kubernetes证书"
],
"description": "了解如何使用sealos cert命令更新Kubernetes集群的API服务器证书，添加域名和IP，确保集群安全。"
}
file: ./content/docs/k8s/reference/sealos/commands/create.en.mdx
meta: {
"title": "create 创建工作目录",
"keywords": [
"Sealos create",
"集群工作目录",
"Kubernetes",
"镜像审查",
"Sealos 命令行"
],
"description": "了解如何使用 Sealos create 命令创建集群工作目录，审查 Kubernetes 镜像，支持调试和测试，确保镜像内容符合预期。"
}
file: ./content/docs/k8s/reference/sealos/commands/delete.en.mdx
meta: {
"title": "delete 集群节点删除",
"keywords": [
"sealos delete",
"集群节点删除",
"sealos 命令",
"删除控制节点",
"sealos 使用指南"
],
"description": "了解如何使用 sealos delete 命令从集群中删除节点和控制节点，确保集群正常运行。详细指南和选项说明。"
}
file: ./content/docs/k8s/reference/sealos/commands/env.en.mdx
meta: {
"title": "env 环境变量",
"keywords": [
"sealos",
"环境变量",
"sealos env",
"命令行工具",
"sealos build"
],
"description": "了解如何使用Sealos命令行工具查看和设置环境变量，掌握sealos env命令的基本用法和详细说明。"
}
file: ./content/docs/k8s/reference/sealos/commands/exec.en.mdx
meta: {
"title": "exec 执行命令",
"keywords": [
"sealos exec",
"Sealos 命令行工具",
"集群节点",
"Shell 命令",
"执行脚本",
"集群管理",
"Sealos 使用指南",
"Sealos 选项",
"Sealos 示例"
],
"description": "了解如何使用 Sealos exec 命令在集群节点上执行 Shell 命令或脚本，掌握基本用法、选项和示例，提升集群管理效率。"
}
file: ./content/docs/k8s/reference/sealos/commands/gen.en.mdx
meta: {
"title": "gen 生成集群配置",
"keywords": [
"Sealos",
"Kubernetes集群",
"gen命令",
"Clusterfile",
"sealos apply"
],
"description": "了解如何使用Sealos的gen命令生成Kubernetes集群配置文件，快速创建和管理集群，提升运维效率。"
}
file: ./content/docs/k8s/reference/sealos/commands/images.en.mdx
meta: {
"title": "image 镜像列表",
"keywords": [
"Sealos",
"镜像管理",
"Sealos images 命令",
"镜像参数",
"镜像过滤"
],
"description": "了解如何使用Sealos的images命令查看和管理本地存储的镜像，包括显示所有镜像、特定镜像和使用多种参数进行过滤。"
}
file: ./content/docs/k8s/reference/sealos/commands/index.en.mdx
meta: {
"title": "Sealos 命令说明",
"keywords": [
"Sealos命令",
"Kubernetes集群管理",
"节点管理",
"容器镜像",
"Sealos调试模式"
],
"description": "了解Sealos命令，包括Kubernetes集群管理、节点管理、容器镜像操作等，开启调试模式获取详细系统运行信息。"
}
file: ./content/docs/k8s/reference/sealos/commands/inspect.en.mdx
meta: {
"title": "inspect 详细信息",
"keywords": [
"Sealos命令",
"inspect命令",
"容器配置",
"镜像配置",
"Go模板格式",
"远程镜像仓库",
"本地OCI归档",
"Docker归档文件"
],
"description": "了解如何使用Sealos的inspect命令查看容器和镜像的详细配置信息，包括元数据、环境变量和启动命令等。"
}
file: ./content/docs/k8s/reference/sealos/commands/load.en.mdx
meta: {
"title": "load 加载镜像",
"keywords": [
"sealos load",
"加载镜像",
"存档文件",
"无网络环境",
"镜像导入"
],
"description": "了解如何使用sealos load命令从存档文件中加载镜像，特别适用于无网络环境下的镜像导入。"
}
file: ./content/docs/k8s/reference/sealos/commands/login.en.mdx
meta: {
"title": "login 登录仓库",
"keywords": [
"sealos login",
"容器注册表登录",
"sealos命令",
"镜像推送",
"镜像拉取"
],
"description": "了解如何使用sealos login命令登录容器注册表，进行镜像的拉取和推送，确保提供正确的用户名和密码。"
}
file: ./content/docs/k8s/reference/sealos/commands/logout.en.mdx
meta: {
"title": "logout 登出仓库",
"keywords": [
"sealos logout",
"镜像仓库",
"认证信息",
"身份验证文件",
"quay.io"
],
"description": "了解如何使用sealos logout命令移除本地缓存的镜像仓库账号和密码，包括参数和示例，帮助你轻松管理认证信息。"
}
file: ./content/docs/k8s/reference/sealos/commands/manifest.en.mdx
meta: {
"title": "manifest 镜像清单",
"keywords": [
"Sealos",
"manifest命令",
"多架构支持",
"Docker镜像",
"OCI镜像"
],
"description": "了解Sealos的manifest命令，轻松创建、修改和推送多架构支持的Docker和OCI镜像清单，提升部署效率。"
}
file: ./content/docs/k8s/reference/sealos/commands/merge.en.mdx
meta: {
"title": "merge 合并镜像",
"keywords": [
"Sealos merge",
"合并镜像",
"Dockerfile",
"镜像优化",
"应用部署"
],
"description": "了解如何使用Sealos的merge命令将多个镜像合并为一个，优化镜像大小，简化应用部署，节省存储空间。"
}
file: ./content/docs/k8s/reference/sealos/commands/pull.en.mdx
meta: {
"title": "pull 拉取镜像",
"keywords": [
"sealos pull",
"拉取镜像",
"容器镜像仓库",
"镜像下载",
"sealos命令"
],
"description": "了解如何使用sealos pull命令从容器镜像仓库下载镜像并存储在本地，提高工作效率。获取详细参数和使用示例。"
}
file: ./content/docs/k8s/reference/sealos/commands/push.en.mdx
meta: {
"title": "push 上传镜像",
"keywords": [
"Sealos push",
"上传镜像",
"Docker 镜像",
"镜像仓库",
"OCI 布局",
"Docker 注册表",
"镜像传输",
"镜像推送",
"镜像管理"
],
"description": "Sealos push 命令指南，详细介绍如何将本地 Docker 镜像推送到远程镜像仓库，支持多种传输方式和可选参数，轻松管理镜像。"
}
file: ./content/docs/k8s/reference/sealos/commands/registry.en.mdx
meta: {
"title": "registry 镜像仓库命令",
"keywords": [
"Sealos",
"registry 命令",
"Docker 镜像",
"镜像仓库",
"镜像同步",
"镜像复制",
"镜像管理",
"Docker 分发",
"镜像保存",
"镜像服务器"
],
"description": "了解Sealos registry命令的使用指南，包括save、serve、passwd、sync和copy命令，帮助您高效管理Docker镜像仓库。"
}
file: ./content/docs/k8s/reference/sealos/commands/reset.en.mdx
meta: {
"title": "reset 重置集群",
"keywords": [
"Sealos reset",
"重置集群",
"Sealos 命令",
"集群管理",
"Kubernetes 重置"
],
"description": "了解如何使用 Sealos reset 命令重置集群，包括基本用法、示例和可选参数，确保集群管理更高效。"
}
file: ./content/docs/k8s/reference/sealos/commands/rmi.en.mdx
meta: {
"title": "rmi 删除本地镜像",
"keywords": [
"sealos rmi",
"删除本地镜像",
"sealos命令行工具",
"镜像管理",
"sealos教程"
],
"description": "了解如何使用Sealos rmi命令删除本地镜像，清理无用或过时的镜像，节省存储空间。阅读详细指南获取更多信息。"
}
file: ./content/docs/k8s/reference/sealos/commands/run.en.mdx
meta: {
"title": "run 运行集群镜像",
"keywords": [
"Sealos",
"集群镜像",
"Kubernetes",
"run命令",
"多镜像执行",
"集群初始化",
"应用安装"
],
"description": "了解如何使用Sealos的run命令进行集群初始化、应用安装和多镜像执行，掌握Kubernetes集群管理的最佳实践。"
}
file: ./content/docs/k8s/reference/sealos/commands/save.en.mdx
meta: {
"title": "save 保存镜像",
"keywords": [
"sealos save",
"保存镜像",
"Sealos 命令行工具",
"镜像备份",
"镜像迁移"
],
"description": "了解如何使用 Sealos save 命令保存镜像到归档文件中，轻松备份和迁移你的镜像，支持多种格式和参数。"
}
file: ./content/docs/k8s/reference/sealos/commands/scp.en.mdx
meta: {
"title": "scp 拷贝文件",
"keywords": [
"sealos scp",
"拷贝文件",
"集群节点",
"远程节点",
"命令行工具"
],
"description": "了解如何使用 Sealos scp 命令将文件复制到指定的集群节点，详细介绍基本用法和选项，助您轻松管理文件传输。"
}
file: ./content/docs/k8s/reference/sealos/commands/tag.en.mdx
meta: {
"title": "tag 添加镜像名称",
"keywords": [
"Sealos tag",
"镜像管理",
"命令行工具",
"添加镜像名称",
"Sealos 使用指南"
],
"description": "了解如何使用 Sealos tag 命令为本地存储的镜像添加一个或多个附加名称，提升镜像管理效率。"
}
Поделиться результатами
Обсудить с ИИ
Добавлен 19.07.2026