Skip to main content

​
Prerequisites

  • Lightd daemon running
  • Docker installed and running
  • API token (see Authentication)

​
Common Workflow

This guide walks through creating a complete container setup from scratch.

​
1. Create a Volume

Volumes provide persistent storage for your containers. 
curl -X POST http://localhost:8070/volumes \
  -H "Authorization: Bearer lightd_token" \
  -H "Accept: Application/vnd.pkglatv1+json"
Response: 
{
  "volume_id": "d6764075-c5f1-4045-9fb3-85315b85cb0f",
  "path": "/storage/volumes/d6764075-c5f1-4045-9fb3-85315b85cb0f"
}

​
2. Write Files to Volume

Add configuration files or scripts to your volume. 
curl -X POST http://localhost:8070/volumes/d6764075/files \
  -H "Authorization: Bearer lightd_token" \
  -H "Accept: Application/vnd.pkglatv1+json" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "config.yml",
    "content": "server-port: 25565\nmax-players: 20"
  }'

​
3. Add Network Port (Optional)

If your container needs network access, add ports to the pool. 
curl -X POST http://localhost:8070/network/ports \
  -H "Authorization: Bearer lightd_token" \
  -H "Accept: Application/vnd.pkglatv1+json" \
  -H "Content-Type: application/json" \
  -d '{
    "ip": "0.0.0.0",
    "port": 25565,
    "protocol": "tcp"
  }'

​
4. Create Container

Create a container with your volume and configuration. 
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 Ready; sleep 1; done\"",
    "start_pattern": "Ready",
    "ports": [
      {"ip": "0.0.0.0", "port": 25565, "protocol": "tcp"}
    ],
    "limits": {
      "memory": 536870912,
      "cpu": 1.0
    }
  }'
Response: 
{
  "message": "Container creation started",
  "internal_id": "my-server-001",
  "state": "installing"
}

​
5. Monitor via WebSocket

Connect to the WebSocket to monitor installation progress and container output. 
const ws = new WebSocket('ws://localhost:8070/ws/my-server-001?token=lightd_token');

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  
  if (data.event === 'event') {
    console.log('State:', data.data);
  } else if (data.event === 'console') {
    console.log('Output:', data.data);
  }
};

ws.onopen = () => {
  console.log('Connected to container');
};

​
6. Start Container

Once the container state is ready, start it. 
curl -X POST http://localhost:8070/containers/my-server-001/start \
  -H "Authorization: Bearer lightd_token" \
  -H "Accept: Application/vnd.pkglatv1+json"

​
Complete Example Script

Here’s a complete bash script that sets up a Minecraft server: 
#!/bin/bash

TOKEN="lightd_your_token_here"
BASE_URL="http://localhost:8070"

# 1. Create volume
VOLUME=$(curl -s -X POST $BASE_URL/volumes \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: Application/vnd.pkglatv1+json" | jq -r '.volume_id')

echo "Created volume: $VOLUME"

# 2. Write server properties
curl -X POST $BASE_URL/volumes/$VOLUME/files \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: Application/vnd.pkglatv1+json" \
  -H "Content-Type: application/json" \
  -d '{"path": "server.properties", "content": "server-port=25565\nmax-players=20"}'

# 3. Add port to pool
curl -X POST $BASE_URL/network/ports \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: Application/vnd.pkglatv1+json" \
  -H "Content-Type: application/json" \
  -d '{"ip": "0.0.0.0", "port": 25565, "protocol": "tcp"}'

# 4. Create container
curl -X POST $BASE_URL/containers \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: Application/vnd.pkglatv1+json" \
  -H "Content-Type: application/json" \
  -d "{
    \"internal_id\": \"minecraft-001\",
    \"image\": \"openjdk:17-slim\",
    \"volume_id\": \"$VOLUME\",
    \"startup_command\": \"java -Xmx1G -jar server.jar nogui\",
    \"start_pattern\": \"Done\",
    \"ports\": [{\"ip\": \"0.0.0.0\", \"port\": 25565, \"protocol\": \"tcp\"}],
    \"limits\": {\"memory\": 1073741824, \"cpu\": 2.0},
    \"install_script\": \"#!/bin/bash\\nwget https://example.com/server.jar\\necho 'eula=true' > eula.txt\"
  }"

echo "Container created. Waiting for installation..."

# 5. Wait for ready state (poll every 2 seconds)
while true; do
  STATE=$(curl -s -X GET $BASE_URL/containers/minecraft-001 \
    -H "Authorization: Bearer $TOKEN" \
    -H "Accept: Application/vnd.pkglatv1+json" | jq -r '.install_state')
  
  echo "Current state: $STATE"
  
  if [ "$STATE" = "ready" ]; then
    break
  fi
  
  sleep 2
done

# 6. Start container
curl -X POST $BASE_URL/containers/minecraft-001/start \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: Application/vnd.pkglatv1+json"

echo "Container started!"

​
Next Steps

Volumes API

Learn about file operations and compression

Containers API

Explore container lifecycle management

WebSocket API

Real-time monitoring and control

Response Examples

See all API response formats