export APPSMITH_MONGODB_URI="mongodb://localhost:27017/appsmith"
export APPSMITH_REDIS_URL="redis://localhost:6379"
export APPSMITH_ENCRYPTION_PASSWORD="your-encryption-password"
export APPSMITH_ENCRYPTION_SALT="your-encryption-salt"
export APPSMITH_OAUTH2_GITHUB_CLIENT_ID=""
export APPSMITH_OAUTH2_GITHUB_CLIENT_SECRET=""
export APPSMITH_OAUTH2_GOOGLE_CLIENT_ID=""
export APPSMITH_OAUTH2_GOOGLE_CLIENT_SECRET=""
export APPSMITH_MAIL_ENABLED="false"
export APPSMITH_DISABLE_TELEMETRY="true"

3. Build all modules from source/:

cd source
./build.sh
# Or directly:
mvn clean package -DskipTests -pl appsmith-server -am

4. Run the server:

cd source/appsmith-server
mvn spring-boot:run
# Server starts on port 8080 by default

5. Seed MongoDB with default plugin records:

cd source/mongo-seed
# Follow the seed scripts inside this directory to populate default datasource plugin metadata

6. tsconfig / babel: Not applicable - this is a pure Java project. No TypeScript configuration is needed for the backend itself.

Public API

Because this is a Java Spring Boot backend (no TypeScript exports), the "public API" is the HTTP REST surface and the plugin interface. The following are the primary integration contracts visible from the source structure.

PluginExecutor (Plugin Interface)

// appsmith-plugins/<pluginName>/src/main/java/.../PluginExecutor.java
public interface PluginExecutor<C> {
    Mono<ActionExecutionResult> execute(
        C connection,
        DatasourceConfiguration datasourceConfiguration,
        ActionConfiguration actionConfiguration
    );

    Mono<C> datasourceCreate(DatasourceConfiguration datasourceConfiguration);

    void datasourceDestroy(C connection);

    Set<String> validateDatasource(DatasourceConfiguration datasourceConfiguration);
}

Implement this interface to create a new datasource plugin. execute is called on every query run; datasourceCreate establishes the connection; validateDatasource returns a set of error strings (empty = valid).

DatasourceConfiguration

// Core model used by all plugins
public class DatasourceConfiguration {
    private String url;
    private List<Property> properties;
    private DBAuth authentication;
    private List<Endpoint> endpoints;
    private SSLDetails sslDetails;
    // getters/setters ...
}

Passed into every PluginExecutor method. Holds connection URL, credentials, endpoints, and SSL settings. Populate this in tests to exercise a plugin directly without the full server stack.

ActionConfiguration

// Core model carrying the user's query body
public class ActionConfiguration {
    private String body;           // Raw query / command body
    private List<Property> pluginSpecifiedTemplates; // Plugin-specific options
    private PaginationField paginationField;
    private Integer timeoutInMillisecond;
    // getters/setters ...
}

Carries the query text and plugin-specific parameters into PluginExecutor.execute. pluginSpecifiedTemplates maps to the indexed fields defined in each plugin's editor/*.json form configuration.

Working examples

Scenario - Building and testing the Postgres plugin in isolation

Stand up the Postgres plugin module, run its unit tests, and verify a datasource connection without starting the full Appsmith server.

cd source/appsmith-plugins/postgresPlugin
mvn test -Dspring.profiles.active=test

// PostresPluginTest.java (within the plugin's test sources)
import com.appsmith.external.model.DatasourceConfiguration;
import com.appsmith.external.model.Endpoint;
import com.appsmith.external.model.DBAuth;

DatasourceConfiguration dsConfig = new DatasourceConfiguration();
Endpoint endpoint = new Endpoint();
endpoint.setHost("localhost");
endpoint.setPort(5432L);
dsConfig.setEndpoints(List.of(endpoint));

DBAuth auth = new DBAuth();
auth.setUsername("postgres");
auth.setPassword("password");
auth.setDatabaseName("testdb");
dsConfig.setAuthentication(auth);

// Validate - should return empty set for valid config
Set<String> errors = pluginExecutor.validateDatasource(dsConfig);
assert errors.isEmpty();

Scenario - Registering a custom plugin form

Each plugin defines its editor UI via JSON resources. To add a new command to an existing plugin, drop a JSON file into the plugin's editor/ directory matching the existing schema.

// source/appsmith-plugins/postgresPlugin/src/main/resources/editor/custom_command.json
{
  "controlType": "QUERY_DYNAMIC_TEXT",
  "label": "Custom SQL",
  "configProperty": "actionConfiguration.body",
  "isRequired": true,
  "placeholderText": "SELECT * FROM {{table_name}}",
  "subtitle": "Use {{ }} for dynamic bindings"
}

# After editing, rebuild the plugin module:
cd source/appsmith-plugins/postgresPlugin
mvn package -DskipTests
# The JAR in target/ is picked up by appsmith-server at startup

Scenario - Running the full server stack with Docker

cd source

# Build all images
docker build -t appsmith-server:local -f appsmith-server/Dockerfile .

# Run with required environment variables
docker run -d \
  -e APPSMITH_MONGODB_URI="mongodb://mongo:27017/appsmith" \
  -e APPSMITH_REDIS_URL="redis://redis:6379" \
  -e APPSMITH_ENCRYPTION_PASSWORD="changeme" \
  -e APPSMITH_ENCRYPTION_SALT="changeme-salt" \
  -e APPSMITH_DISABLE_TELEMETRY="true" \
  -p 8080:8080 \
  --name appsmith-server \
  appsmith-server:local

File walkthrough

• appsmith-server/ - The Spring Boot core. Contains controllers, services, repositories, security configuration, and the query execution pipeline that dispatches to plugins.
• appsmith-plugins/ - Each subdirectory is an independent Maven module implementing PluginExecutor for one datasource. Plugins are loaded by the server at startup via classpath scanning.
• appsmith-plugins/amazons3Plugin/ - S3 plugin with form definitions for create/read/list/delete/create-many/delete-many operations.
• appsmith-plugins/anthropicPlugin/ - Anthropic Claude plugin with chat and vision editor forms.
• appsmith-plugins/appsmithAiPlugin/ - Appsmith-native AI plugin supporting text generation, summarization, classification, entity extraction, image captioning, and classification.
• appsmith-plugins/arangoDBPlugin/ - ArangoDB plugin with AQL query editor and template metadata.
• appsmith-plugins/postgresPlugin/ - PostgreSQL plugin using JDBC.
• appsmith-plugins/mongoPlugin/ - MongoDB plugin using the reactive MongoDB driver.
• appsmith-plugins/openAiPlugin/ - OpenAI plugin.
• appsmith-git/ - Git integration module. The git.sh script is invoked by the server to perform git operations (commit, push, pull, merge) on exported application JSON files.
• mongo-seed/ - JavaScript/shell scripts to insert default MongoDB documents (plugin registry, default organizations) needed for first-run.
• scripts/ - Operational scripts: health checks, startup ordering, migration helpers.
• build.sh - Orchestrates the full Maven multi-module build; sets profiles and skips integration tests by default.
• buildpack-run.sh - Buildpack lifecycle script for Cloud Foundry / Paketo-style deployments.

Common pitfalls and fixes

• MongoDB URI missing auth source: If using MongoDB Atlas or authenticated Mongo, append ?authSource=admin to APPSMITH_MONGODB_URI or connections will silently fail.
• Java version mismatch: The server requires Java 17. Running with Java 11 or 21 causes compilation errors in sealed class and record usages; pin your JDK with JAVA_HOME.
• Plugin JARs not discovered: All plugin modules must be listed in the root pom.xml as <module> entries. A new plugin directory without a corresponding entry is silently ignored at runtime.
• git.sh not executable: After checkout on Linux/CI, appsmith-git/src/main/resources/git.sh loses the execute bit; fix with chmod +x appsmith-git/src/main/resources/git.sh.
• Redis connection refused on startup: The server performs a blocking Redis ping at startup; if Redis is not ready, the server exits. Use depends_on with health checks in Docker Compose.
• Encryption keys changed after seeding: APPSMITH_ENCRYPTION_PASSWORD and APPSMITH_ENCRYPTION_SALT are used to encrypt stored datasource credentials. Changing them after data exists renders all saved credentials unreadable; treat them as immutable after first run.

Vibe-coding prompt template

I have the Appsmith backend server source tree in the `source/` directory of my project.
I also have a `USAGE.md` file that describes the architecture, plugin interface, and setup steps.

Please help me integrate this into my project step by step:

1. Read `USAGE.md` fully before writing any code.
2. The upstream project is `appsmithorg/appsmith` (app/server subtree), a Java 17 Spring Boot application.
3. My goal is: [DESCRIBE YOUR GOAL - e.g., "add a new datasource plugin for ClickHouse" or "expose a new REST endpoint" or "modify the query execution pipeline"].
4. The plugin interface is `PluginExecutor<C>` in `appsmith-plugins/`. New plugins go in their own Maven module under `appsmith-plugins/`.
5. Editor UI for a plugin is defined in JSON files under `src/main/resources/editor/` and referenced by `form.json`.
6. All environment variables required are listed in `USAGE.md` under "Project setup".
7. Do not invent class names or package paths - only use what is visible in `source/` and documented in `USAGE.md`.
8. After generating code, show me the exact Maven commands to build and test the changes.

License and credit

Appsmith is released under the Apache License 2.0. See source/LICENSE if present, or refer to the upstream repository for the full license text.

Upstream project: https://github.com/appsmithorg/appsmith

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

ToolJet Open-Source Low-Code App Builder

Automation, Utilities & Developer Tools

Free