Quick Links

Appsmith is a low code platform for assembling complex line-of-business software from pre-built UI components. It connects to your existing data sources such as SQL databases, spreadsheets, REST APIs and GraphQL endpoints. You can wire these information repositories up to rich widgets including tables, lists, and charts.

The Appsmith Community Edition is open-source and can be fully self-hosted. In this guide, we'll show how to deploy your own Appsmith instance as a Docker container. This is the recommended method which simplifies initial installation and ongoing maintenance. We'll assume you've already got Docker and Docker Compose installed on your system.

A First Deployment

You can start a basic Appsmith server for experimentation using docker run alone:

$ docker run -d --name appsmith -p 8080:80 -p 9001:9001 

-v $PWD/appsmith-stacks:/appsmith-stacks

appsmith/appsmith-ce

This starts a new container using the appsmith/appsmith-ce image and binds the appsmith-stacks directory in your working directory to /appsmith-stacks inside the container. You should always mount a volume to this location to avoid data loss after you update or restart the Appsmith container.

Appsmith's first initialization can take a while to complete. The container will generate config files, create your MongoDB database, and enable the initial set of application plugins. You can check when your instance is ready for connections by following the container logs:

$ docker logs appsmith --follow

Wait to see an Appsmith is Running! message in the log output.

Setting Up Appsmith

Now visit localhost:8080 in your browser. This port was bound to the container's port 80 in the docker run command above. Substitute in your own value if you changed the port number in the command.

Screenshot of the Appsmith landing page after a fresh installation

You should see the Appsmith web UI's landing page. Click "Get Started" and fill out the form to set up your Appsmith instance. You'll then be taken straight to a new application that's ready to connect to your data sources.

Using Supervisor

The Appsmith Docker image uses supervisord to run multiple processes inside a single container. The Supervisor web UI is exposed on port 9001; in the docker run command above, host port 9001 was bound to the container, so you can view your container's process list by visiting localhost:9001 in your browser.

Screenshot of the supervisord web interface for Appsmith

Visiting Supervisor can help you debug issues when one of the Appsmith components stops working. You can restart processes, view their logs, and shut them down without killing the Docker container. Keeping Supervisor exposed like this is a security risk though: don't bind port 9001 to a production Appsmith container unless you set up authentication first.

Using Docker Compose

It's recommended to use Docker Compose for long-term Appsmith deployments. Appsmith maintains its own docker-compose.yml that automatically configures a container with an appsmith-stack bind mount and HTTP, HTTPS, and Supervisor port binds.

This official Docker Compose stack comes with Watchtower integration. Watchtower will automatically replace your Appsmith container each time the image gets updated, ensuring you're using the newest available release.

Download the Docker Compose file to your Docker host:

$ curl -L https://bit.ly/32jBNin -o $PWD/docker-compose.yml

Now use Docker Compose to bring up the Appsmith stack:

$ docker-compose up -d

Wait for Appsmith is Running! to show up in the logs before you visit localhost in your browser.

Writing Your Own Compose File

Appsmith's Compose file doesn't provide environment variables to customize the port binds or image version. This alternative stack lets you use different ports and pin to a specific version of the Appsmith image.

version: "3"

services:

appsmith:

image: appsmith/appsmith-ce:${IMAGE_TAG:-latest}

ports:

- ${HTTP_PORT:-80}:80

- ${HTTPS_PORT:-443}:443

volumes:

- stacks:/appsmith_stacks

restart: unless-stopped

volumes:

stacks:

Now you can run docker-compose up -d to start a specific Appsmith version on a particular port.

$ IMAGE_TAG=v1.6.19 HTTP_PORT=8080 docker-compose up -d

This Compose file also uses a named Docker volume instead of the direct host bind mount.

Updating Your Installation

You can update to new Appsmith releases by pulling the latest image and restarting your stack:

$ docker-compose pull && docker-compose up -d --force-recreate appsmith

This is safe as all your persistent data is stored inside the stacks volume.

You don't need to manually update when you're using the Watchtower integration included with the official Compose file. You can add Watchtower to your own stack by including it as an extra service:

version: "3"

services:

appsmith:

image: appsmith/appsmith-ce:${IMAGE_TAG:-latest}

ports:

- ${HTTP_PORT:-80}:80

- ${HTTPS_PORT:-443}:443

volumes:

- stacks:/appsmith_stacks

labels:

com.centurylinklabs.watchtower.enable: "true"

restart: unless-stopped

watchtower:

image: containrrr/watchtower:latest

volumes:

- /var/run/docker.sock:/var/run/docker.sock

command: --interval 3600 --label-enable --cleanup

restart: unless-stopped

volumes:

stacks:

This runs Appsmith with a Watchtower container that checks for image updates every hour (3600 seconds). Only containers with the com.centurylinklabs.watchtower.enable label are checked so this is added to the appsmith service. Watchtower needs access to your host's Docker socket so it can pull new images and replace running containers.

Configuring Your Instance

Appsmith's config file is available at /appsmith-stacks/configuration/docker.env inside the container. If you've bind mounted a local directory to this path, you can edit the file on your host instead of connecting directly to the container.

# If you're bind mounting "stacks" to /appsmith-stacks

$ nano stacks/configuration/docker.env

# If you're using a Docker volume

$ docker cp appsmith:/appsmith-stacks/configuration/docker.env docker.env

$ nano docker.env

$ docker cp docker.env appsmith:/appsmith-stacks/configuration/docker.env

The config file sets up environment variables that will be made available to your Appsmith installation. The possible settings include credentials for different data sources, API keys for third-party integrations, and connection details for your mail server and MongoDB database. Required values are automatically populated during Appsmith's first run routine.

To change a setting, first update its value in the config file:

APPSMITH_MAIL_ENABLED=true

APPSMITH_MAIL_HOST=mail.example.com

APPSMITH_MAIL_PORT=465

APPSMITH_MAIL_USERNAME=appsmith

APPSMITH_MAIL_PASSWORD=$3cureP@ss

APPSMITH_MAIL_FROM=appsmith@example.com

Next restart your Appsmith container to apply the changes:

$ docker-compose restart appsmith

Appsmith will use the new configuration automatically next time it starts.

Exporting Your Data

Once you begin using Appsmith, you'll quickly assemble apps which could be difficult to replicate in the future. You should frequently back up your installation to guard against data loss.

The Docker image includes a command that can produce a complete archive on-demand:

$ docker-compose exec appsmith appsmithctl export_db

The backup will be stored to /appsmith-stacks/data/backup/appsmith-data.archive inside the container. Use docker cp to move the archive to your Docker host:

$ docker cp appsmith:/appsmith-stacks/data/backup/appsmith-data.archive appsmith-backup-$(date +%Y-%m-%d).archive

Next copy the /appsmith-stacks/configuration directory out of the container. Including these files in your final backup will avoid having to reconstruct your config file after a backup restoration. Now you can upload your backup to cloud storage or a dedicated server to protect your data if your Docker host suffers a failure.

To restore a backup archive in the future, copy it to /appsmith-stacks/data/restore in a new Appsmith container and run the import_db command:

$ docker cp appsmith-backup-2022-04-13.archive appsmith:/appsmith-stacks/data/restore

$ docker-compose exec appsmith appsmithctl import_db

Restart Appsmith to complete the restoration:

$ docker-compose restart appsmith

Using Appsmith

Appsmith applications have four fundamental components:

  • Pages - The screens in your app.
  • Widgets - The UI components on those screens.
  • Queries/JavaScript - Custom JavaScript snippets that add advanced functionality.
  • Datasources - Connections to your external databases.
Screenshot of an empty Appsmith app

Start a new app by clicking the "Add a Datasource" button on its landing page. You can quickly scaffold an example app using one of the built-in sample databases. Click the "users" option to add a PostgreSQL database populated with some user data.

Screenshot of creating a datasource in Appsmith

Next click the "New Query" button to add a query that surfaces information from the datastore.

Screenshot of creating a datasource in Appsmith
Screenshot of creating a datasource in Appsmith

Go back to your application's page by clicking "Page 1" in the left sidebar. Press "Add a Widget" and drag one of the widgets from the sidebar onto the canvas. We're using a List.

Screenshot of an empty page with an "Add a Widget" button in Appsmith

In the properties pane on the right, clear out the sample data and replace it with {{Query1.data}}. This executes the query created earlier to surface data from the users database. The live preview will update and show the user list.

Screenshot of configuring an Appsmith widget to work with a data source

 

You can keep adding widgets to build out your app's capabilities. Once you're done, click the "Deploy" button in the top-right to publish your app and launch it in Appsmith's viewing mode.

Screenshot of an Appsmith app showing the default users list in viewing mode

Summary

Appsmith is an open-source low code platform for rapidly developing new business apps. The official Docker image lets you quickly start your own Appsmith instance with minimal configuration.

Once your container's operational, you can use the included suite of connectors to query, edit, and visualize your organization's data stores. Then you can share your app with other team members or enable public access so external contractors, suppliers, and customers can join in.

A Dockerized Appsmith instance should require little long-term maintenance beyond regular updates and backups. Using Docker for deployment also makes it easy to wipe Appsmith from your system if you decide it's not for you. Run docker-compose down --volumes to completely tear down your stack, including the data stored inside your appsmith-stacks volume.