4. Service startup modes

When installing and deploying the open-source version of Coze Loop, stable mode is used by default. In this mode, the Coze Loop service retrieves the Docker public image and starts it directly.

Service startup modes

Stable mode (stable)

• Feature: Retrieve the Coze Loop image from the docker.io public repository.
• Scenarios: demonstration, experience, and use in stable mode
• Usage: After cloning the repository with git, you can deploy and start it directly.

Deployment and startup commands:

make compose-up

Development mode (dev)

• Features: Builds the Coze Loop image locally. Images are automatically built after code changes, which involves compiling both frontend and backend code.
• Scenarios: development, customization, and verification
• Usage: Code changes -> Build a temporary image locally -> Deploy using the local temporary image

Deployment startup commands:

make compose-up-dev

Note: This command will automatically perform the following steps:

1. Compile and build the image to the local Docker image repository cozedev/coze-loop:dev.
2. Start the service using the locally built image.

The Dockerfile logic includes cache acceleration functionality:

• If only the server code is modified, then only the server is recompiled (go mod also provides caching acceleration).
• If only the frontend code is changed, then only recompile the frontend.
• If both are modified at the same time, both will be recompiled.

The single-step debug mode (debug)

• Feature: In addition to development mode, step-by-step debugging with breakpoints is also supported.
• Scenarios: development, customization, and validation
• Usage: make code changes -> build a temporary image locally -> deploy using the local temporary image -> hit a breakpoint -> debug

Startup command:

make compose-up-debug

Preliminary configurations:

1. Configure the Debug port. If there is no port conflict issue, you can skip this step. Configure COZE_LOOP_APP_DEBUG_PORT in release/deployment/docker-compose/.env; the default value is 40000.
2. For example, in GoLand, create a new Debug configuration in the IDE, and select Run -> Edit Configurations... -> Add Go Remote configurations.
3. Enter the relevant information based on your environment, and click app. The host refers to the IP address used to start the service; the server port defaults to 40000.
4. Develop and modify code as usual.
5. Run the make compose-up-debug command. Once executed, the backend service will automatically perform the following steps:
   1. Compile and build the image locally cozedev/coze-loop:debug.
   2. Start the service using the locally built image.
6. Single-step debugging. If you see the following information output in the startup log and the process is interrupted, click the Debug button in the upper right corner of GoLand to perform step-by-step debugging.

   coze-loop-app              | API server listening at: [::]:40000
   coze-loop-app              | 2025-08-12T10:20:33Z warn layer=rpc Listening for remote connections (connections are not authenticated nor encrypted)
   coze-loop-app              | 2025-08-12T10:20:33Z info layer=debugger launching process with args: [/coze-loop/bin/main]
   coze-loop-app              | 2025-08-12T10:20:34Z debug layer=debugger Adding target 27 "/coze-loop/bin/main"
   

Start and stop services

Mode	Operation	Commands
stable	Start all services	make compose-up
stable	Restart individual services	make compose-restart-<svc>
stable	Close all services	make compose-down
stable	Shut down all services and delete mounted scrolls	make compose-down-v
dev	Start all services	make compose-up-dev
dev	Restart individual services	make compose-restart-dev-<svc>
dev	Close all services	make compose-down-dev
dev	Shut down all services and delete mounted scrolls	make compose-down-v-dev
debug	Start all services	make compose-up-debug
debug	Restart individual services	make compose-restart-debug-<svc>
debug	Turn off all services	make compose-down-debug
debug	Close all services and delete mounted scrolls	make compose-down-v-debug