Skip to main content
This guide walks you through setting up the Runtime service on your local development environment.

​
Prerequisites

Before you begin, ensure you have the following installed:

Java

JDK 21 or higher

Maven

Apache Maven 3.6+

Docker

Docker Engine with TCP socket enabled

Git

For cloning the repository
Docker must be configured to listen on tcp://localhost:2375 for the service to communicate with Docker Engine.

​
Docker Configuration

The Runtime service connects to Docker via TCP socket. Configure Docker to expose the API:
Edit the Docker daemon configuration:
sudo nano /etc/docker/daemon.json
Add the following configuration:
{
  "hosts": ["unix:///var/run/docker.sock", "tcp://0.0.0.0:2375"]
}
Restart Docker:
sudo systemctl restart docker

​
Installation Steps

1

Clone the Repository

git clone <repository-url>
cd runtime
2

Navigate to Backend Directory

cd backend
3

Install Dependencies

Use Maven to download all required dependencies:
mvn clean install
This will install:
  • Spring Boot 4.0.2 (Web MVC)
  • Docker Java Client 3.3.6
  • Lombok for Java annotations
4

Pull Docker Images

Pre-pull the language runtime images to improve first execution performance:
docker pull eclipse-temurin:17
docker pull python:3.11
docker pull gcc:latest
docker pull node:18
5

Configure Application (Optional)

The default configuration in application.properties:
spring.application.name=backend
server.port=8081
You can modify the port by editing src/main/resources/application.properties.
6

Run the Application

Start the Spring Boot application:
mvn spring-boot:run
Or build and run the JAR:
mvn package
java -jar target/engine-0.0.1-SNAPSHOT.jar

​
Verify Installation

Once the service is running, you should see: 
Started BackendApplication in X.XXX seconds
Test the service with a simple request: 
curl -X POST http://localhost:8081/api/execute \
  -H "Content-Type: application/json" \
  -d '{
    "code": "print('Hello, Runtime!')",
    "language": "python"
  }'

{
  "success": true,
  "message": "Code Executed successfully",
  "data": {
    "output": "Hello, Runtime!\n",
    "exitCode": 0,
    "executionTime": 1523
  }
}

​
Project Structure

backend/
├── src/main/java/com/runtime/
│   ├── BackendApplication.java          # Main Spring Boot application
│   ├── controller/
│   │   └── ExecutionController.java     # REST API endpoint
│   ├── engine/
│   │   ├── CodeExecutor.java           # Language executor registry
│   │   ├── DockerExecutorUtil.java     # Docker container management
│   │   ├── LanguageExecutor.java       # Executor interface
│   │   └── executors/
│   │       ├── BaseExecutor.java
│   │       └── GeneralDockerExecutor.java
│   ├── model/
│   │   ├── ApiResponse.java            # Generic API response wrapper
│   │   ├── CodeExecutionRequest.java   # Request DTO
│   │   └── ExecutionResult.java        # Execution result DTO
│   └── service/
│       └── ExecutionService.java       # Business logic layer
├── src/main/resources/
│   └── application.properties          # Application configuration
└── pom.xml                            # Maven dependencies

​
Key Dependencies

From pom.xml: 
<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>4.0.2</version>
</parent>

<properties>
    <java.version>21</java.version>
</properties>

<dependencies>
    <!-- Spring Boot Web MVC -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-webmvc</artifactId>
    </dependency>
    
    <!-- Docker Java Client -->
    <dependency>
        <groupId>com.github.docker-java</groupId>
        <artifactId>docker-java</artifactId>
        <version>3.3.6</version>
    </dependency>
    
    <!-- HTTP Client for Docker -->
    <dependency>
        <groupId>com.github.docker-java</groupId>
        <artifactId>docker-java-transport-httpclient5</artifactId>
        <version>3.3.6</version>
    </dependency>
    
    <!-- Lombok -->
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <optional>true</optional>
    </dependency>
</dependencies>

​
Troubleshooting

Error: Connect to localhost:2375 [localhost/127.0.0.1] failedSolution: Ensure Docker is configured to listen on TCP port 2375. See Docker Configuration section.
Error: Port 8081 is already in useSolution: Either stop the process using port 8081 or change the port in application.properties:
server.port=8082
Error: Failed to execute goalSolution: Ensure you’re using Java 21 or higher:
java -version
If needed, set JAVA_HOME to point to JDK 21.
Error: Image not found: python:3.11Solution: Pull the required images manually:
docker pull python:3.11
docker pull eclipse-temurin:17
docker pull gcc:latest
docker pull node:18

​
Next Steps

Supported Languages

Learn about all supported programming languages

API Reference

Explore the code execution API

Deployment

Deploy Runtime to production

Security

Understand security features

Build docs developers (and LLMs) love

Get started for freeTalk to us