Conscript is a Go-based HTTP server that provides various read only endpoints to interact with Docker containers. It includes endpoints for health checks, listing containers, and retrieving container details based on query parameters.

• Health Check: Endpoint to check the health of the server.
• List Containers: Endpoint to list Docker containers.
• Get Container Details: Endpoint to get details of a specific Docker container based on query parameters.

Access the application: once deployed open your browser and navigate to http://localhost:3333.

Run the Docker container:

docker run -d \
  -p 3333:3333 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /etc/hostname:/etc/host_hostname \ # Optional, mount if you want machine_hostname to be available when running in docker environments
  ghcr.io/ultimaterex/conscript/conscript:latest

1. Create a docker-compose.yml file with the following content:

   services:
     conscript:
       command:
         - './conscript'
       container_name: 'conscript'
       hostname: 'conscript'
       image: 'ghcr.io/ultimaterex/conscript/conscript:latest'
       ports:
         - '3333:3333/tcp'
       restart: 'unless-stopped'
       volumes:
         - '/var/run/docker.sock:/var/run/docker.sock'
         - "/etc/hostname:/etc/host_hostname" # Optional, mount if you want machine_hostname to be available when running in docker environments
       working_dir: '/root'

2. Run the Docker Compose setup:

   docker-compose up -d

• Go 1.23.1 or later
• or Docker

1. Clone the repository:

   git clone https://github.com/yourusername/conscript.git
   cd conscript

2. Build the application:

   go build -o conscript .

3. Run the application:

   ./conscript

1. Build the Docker image:

   docker build -t conscript:latest .

2. Run the Docker container:

   docker run -p 3333:3333 -v /var/run/docker.sock:/var/run/docker.sock conscript:latest

• URL: /
• Method: GET
• Description: Returns a welcome message.
• Response:

  Conscript version 0.1.0

• URL: /health
• Method: GET
• Description: Returns the health status of the server.
• Response:

  OK

• URL: /containers
• Method: GET
• Description: Lists Docker containers. By default, it lists only running containers. If the "all" query parameter is set, it lists all containers.
• Query Parameters:
  • all: If set to true, lists all containers.
  • json: If set to true, returns the response in JSON format.
• Response: JSON array of container details if json=true is set, otherwise plain text.
  • Default (Plain Text):

    ID: 1234567890, Name: /my-container, Image: my-image:latest, Status: running
    ID: abcdef1234, Name: /another-container, Image: another-image:latest, Status: exited
    

  • JSON Format:

    [
      {
        "id": "1234567890",
        "names": ["/my-container"],
        "image": "my-image:latest",
        "status": "running"
      },
      {
        "id": "abcdef1234",
        "names": ["/another-container"],
        "image": "another-image:latest",
        "status": "exited"
      }
    ]

• URL: /container/{containerID}

• Method: GET

• Description: Retrieves details of a specific Docker container based on query parameters.

• Query Parameters:

  • status: Returns the status of the container.

  • running: Returns whether the container is running.

  • paused: Returns whether the container is paused.

  • restarting: Returns whether the container is restarting.

  • dead: Returns whether the container is dead.

  • error: Returns any error associated with the container.

  • exitcode: Returns the exit code of the container.

  • state: Returns the entire state object of the container.

  • Response:

    • Example Request:

      curl http://localhost:3333/container/1234567890?status=true&running=true

    • Example Response:

      {
        "Running": true,
        "Status": "running"
      }

• URL: /container/health/{containerID}

• Method: GET

• Description: Returns the health status of a specific Docker container.

• Response: Plain text message indicating the health status of the container.

  • Example Request:

    curl http://localhost:3333/container/health/1234567890

  • Example Response:

    "Container 1234567890 is healthy and running."
    

This project is licensed under the GNU General Public License. See the LICENSE file for details.

Contributions are welcome! Please open an issue or submit a pull request for any improvements or bug fixes.

For any questions or inquiries, please contact [email protected].