Skip to main content

​
Overview

Containers are Docker containers managed by Lightd with automatic lifecycle tracking and state management.

​
Container States

  • installing - Container is being created and installed
  • ready - Container is ready to start
  • starting - Container is starting up
  • running - Container is running (pattern matched)
  • stopping - Container is stopping
  • failed - Installation or operation failed

​
Create Container

Create a new container with optional install script and resource limits. 
curl -X POST http://localhost:8070/containers \
  -H "Authorization: Bearer lightd_token" \
  -H "Accept: Application/vnd.pkglatv1+json" \
  -H "Content-Type: application/json" \
  -d '{
    "internal_id": "my-server-001",
    "image": "ubuntu:22.04",
    "volume_id": "d6764075-c5f1-4045-9fb3-85315b85cb0f",
    "startup_command": "bash -c \"while true; do echo Hello; sleep 1; done\"",
    "start_pattern": "Hello",
    "ports": [
      {"container_port": 3000, "host_port": 25565, "protocol": "tcp"}
    ],
    "limits": {
      "memory": 536870912,
      "cpu": 1.0
    },
    "mount": {
      "/custom/path": "/host/path"
    },
    "install_script": "#!/bin/bash\napt-get update\napt-get install -y curl"
  }'
Request Body:
FieldTypeRequiredDescription
internal_idstringYesUnique identifier for the container
imagestringYesDocker image (e.g., ubuntu:22.04, node:18)
volume_idstringYesVolume UUID for persistent storage
startup_commandstringYesCommand to run when container starts
start_patternstringNoRegex pattern to detect when server is ready
portsarrayNoArray of port bindings
limitsobjectNoResource limits (memory in bytes, cpu in cores)
mountobjectNoCustom volume mounts
install_scriptstringNoBash script to run during installation
Response: 
{
  "message": "Container creation started",
  "internal_id": "my-server-001",
  "state": "installing"
}
Container creation is asynchronous. Monitor progress via WebSocket or poll the container state endpoint.

​
Get Container State

Retrieve detailed information about a container. 
curl -X GET http://localhost:8070/containers/my-server-001 \
  -H "Authorization: Bearer lightd_token" \
  -H "Accept: Application/vnd.pkglatv1+json"
Response: 
{
  "internal_id": "my-server-001",
  "container_id": "a1b2c3d4e5f6",
  "volume_id": "d6764075-c5f1-4045-9fb3-85315b85cb0f",
  "image": "ubuntu:22.04",
  "startup_command": "bash -c 'while true; do echo Hello; sleep 1; done'",
  "start_pattern": "Hello",
  "install_state": "ready",
  "ports": [
    {
      "container_port": 3000,
      "host_port": 25565,
      "protocol": "tcp"
    }
  ],
  "limits": {
    "memory": 536870912,
    "cpu": 1.0
  },
  "mount": {},
  "created_at": 1706450000,
  "updated_at": 1706450100
}

​
List All Containers

Get a list of all containers. 
curl -X GET http://localhost:8070/containers \
  -H "Authorization: Bearer lightd_token" \
  -H "Accept: Application/vnd.pkglatv1+json"
Response: 
{
  "containers": [
    {
      "internal_id": "my-server-001",
      "container_id": "a1b2c3d4e5f6",
      "install_state": "ready",
      "image": "ubuntu:22.04"
    }
  ]
}

​
Delete Container

Remove a container and its Docker instance. 
curl -X DELETE http://localhost:8070/containers/my-server-001 \
  -H "Authorization: Bearer lightd_token" \
  -H "Accept: Application/vnd.pkglatv1+json"
Response: 
{
  "message": "Container deleted successfully"
}
This removes the container from Docker and deletes the database entry. Volume data is preserved.

​
Power Actions

​
Start Container

Start a stopped container. 
curl -X POST http://localhost:8070/containers/my-server-001/start \
  -H "Authorization: Bearer lightd_token" \
  -H "Accept: Application/vnd.pkglatv1+json"
Response: 
{
  "message": "Container start initiated",
  "internal_id": "my-server-001"
}

​
Kill Container

Forcefully stop a running container (SIGKILL). 
curl -X POST http://localhost:8070/containers/my-server-001/kill \
  -H "Authorization: Bearer lightd_token" \
  -H "Accept: Application/vnd.pkglatv1+json"
Response: 
{
  "message": "Container kill initiated",
  "internal_id": "my-server-001"
}

​
Restart Container

Restart a running container. 
curl -X POST http://localhost:8070/containers/my-server-001/restart \
  -H "Authorization: Bearer lightd_token" \
  -H "Accept: Application/vnd.pkglatv1+json"
Response: 
{
  "message": "Container restart initiated",
  "internal_id": "my-server-001"
}

​
Reinstall Container

Recreate the container with a new image or install script. 
curl -X POST http://localhost:8070/containers/my-server-001/reinstall \
  -H "Authorization: Bearer lightd_token" \
  -H "Accept: Application/vnd.pkglatv1+json" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "ubuntu:22.04",
    "install_script": "#!/bin/bash\napt-get update"
  }'
Response: 
{
  "message": "Container reinstall started",
  "internal_id": "my-server-001"
}
Reinstall removes the old Docker container and creates a new one. Volume data is preserved.

​
Rebind Network

Change container port bindings without losing data. 
curl -X POST http://localhost:8070/containers/my-server-001/rebind-network \
  -H "Authorization: Bearer lightd_token" \
  -H "Accept: Application/vnd.pkglatv1+json" \
  -H "Content-Type: application/json" \
  -d '{
    "ports": [
      {"ip": "0.0.0.0", "port": 25566, "protocol": "tcp"}
    ]
  }'
Response: 
{
  "message": "Network rebinding started",
  "internal_id": "my-server-001"
}
Process:
  1. Validates new port bindings
  2. Removes old Docker container
  3. Creates new container with new ports
  4. Updates database
  5. Old ports marked as available, new ports marked as in use

​
Resource Limits

Memory:
  • Specified in bytes
  • Example: 536870912 = 512MB, 1073741824 = 1GB
CPU:
  • Specified as number of cores
  • Example: 1.0 = 1 core, 0.5 = half core, 2.0 = 2 cores

​
Startup Pattern Detection

The start_pattern field accepts regex patterns to detect when a server is ready: Example patterns:
  • "Server started" - Exact match
  • "Hello" - Simple substring
  • "Server.*ready" - Regex pattern
  • "Listening on port \\d+" - Port detection
When the pattern matches in console output, container state transitions from starting to running.

​
Volume Mounts

Every container has these mounts:
  • /home/container → Volume storage (persistent)
  • /app/data → Container data directory (entrypoint.sh, install.sh)
Custom mounts can be added via the mount field.

​
Error Responses

Container Not Found: 
{
  "error": "Container not found"
}
Container Installing: 
{
  "error": "Cannot rebind network while container is installing"
}
Invalid Port Binding: 
{
  "error": "Port not found in network pool"
}