Migrate from Multi-Container setup

Let's say your current Appsmith instance is located in the folder ~/appsmith-old, and you'd like the new setup be at ~/appsmith-new. (This are just example folder names, please use what you prefer.)
Then we can see a rough folder structure like this for ~/appsmith-old:
1
~/appsmith-old
2
├── data
3
│   ├── certbot
4
│   │   ├── conf
5
│   │   └── www
6
│   ├── mongo
7
│   │   ├── db
8
│   │   └── init.js
9
│   └── nginx
10
│       └── app.conf.template
11
├── docker-compose.yml
12
├── docker.env
13
└── encryption.env
Copied!
And like this for ~/appsmith-new (after the steps in this document are done):
1
~/appsmith-new
2
├── docker-compose.yml
3
└── stacks
4
    ├── configuration
5
    │   ├── docker.env
6
    │   └── mongo-init.js
7
    ├── data
8
    │   ├── backup
9
    │   ├── certificate
10
    │   ├── mongodb
11
    │   └── restore
12
    └── letsencrypt
13
        ├── accounts
14
        ├── archive
15
        ├── conf
16
        ├── csr
17
        ├── keys
18
        ├── live
19
        ├── options-ssl-nginx.conf
20
        ├── renewal
21
        ├── renewal-hooks
22
        ├── ssl-dhparams.pem
23
        └── www
Copied!
Now let's go over the steps to be performed.
1. Shutdown old appsmith instance
🚨 Please ensure you are aware of the following facts before proceeding:
This whole migration should take under 25-30mins, usually less than that.
All users who are currently logged-in, will be logged out. They can just log back in, once the new instance is up and running just fine.
Depending on your configuration, any docker-compose and docker commands below might need to be run with a sudo at the start.
Please check the output of commands to see if there's any errors, after running a command, and before proceeding to next steps.
Let's first define a couple of variables that'll be useful during our migration. Please use the appropriate paths in place of ~/appsmith-old and ~/appsmith-new.
1
old_path=~/appsmith-old
2
new_path=~/appsmith-new
Copied!
Before we can start the migration, please stop the old server with the following command:
1
cd "$old_path"
2
docker-compose stop appsmith-internal-server
Copied!
2. Export database
To export data from the running MongoDB database, we use the mongodump command, which will create a gzip archive with all the data. This file will then be copied to the new setup and imported.
Create backup folder to store dump file:
1
cd "$old_path"
2
docker-compose exec mongo mkdir -pv /data/db/backup
Copied!
Dumping MongoDB data and compressed into a gzip file:
1
docker-compose exec mongo sh -c 'mongodump --uri="$APPSMITH_MONGODB_URI" --archive=/data/db/backup/appsmith-data.archive --gzip'
Copied!
3. Migrate Configuration
The new setup uses a single docker.env file for all environment variable configuration.
Let's create the folder structure needed:
1
mkdir -pv "$new_path"/stacks/configuration
Copied!
Migrate configuration from old location:
1
cat "$old_path"/docker.env "$old_path"/encryption.env >> "$new_path"/stacks/configuration/docker.env
Copied!
Now, in the file "$new_path"/stacks/configuration/docker.env:
Unless you are using an external MongoDB database, in APPSMITH_MONGODB_URI, please change the @mongo part to @localhost, and remove the query params (the ? and everything after it). For example, if the current value is mongodb://root:[email protected]/appsmith?retryWrites=true&authSource=admin, change it to be just mongodb://root:[email protected]/appsmith.
Unless you are using an external Redis instance, in APPSMITH_REDIS_URL, please change redis://redis:6379 to redis://localhost:6379. That is, change the host from redis to localhost.
At the end of this docker.env file, let's add the following new environment variables:
1
APPSMITH_MONGODB_USER=<Your MongoDB User>
2
APPSMITH_MONGODB_PASSWORD=<Your MongoDB Password>
3
APPSMITH_API_BASE_URL=http://localhost:8080
Copied!
Here, in place of <Your MongoDB User> and <Your MongoDB Password>, please use the same username and password that were given to APPSMITH_MONGODB_URI above. In the above example values, these would be root for user and rootpass for password.
4. Export https config & certificate (optional)
If you are not using a custom domain with your Appsmith instance, please skip this step.
If you don't have APPSMITH_CUSTOM_DOMAIN already configured in your docker.env, please add a line like below
1
echo APPSMITH_CUSTOM_DOMAIN=appsmith.mycustomdomain.com >> "$new_path"/stacks/configuration/docker.env
Copied!
You can also move your certificate to the new container by running following commands:
1
mkdir -pv "$new_path"/stacks/letsencrypt
2
sudo cp -rfv "$old_path"/data/certbot/conf/* "$new_path"/stacks/letsencrypt
Copied!
5. Setup new Appsmith with Fat container
Let's bring down the old instance in-full now:
1
docker-compose --file "$old_path"/docker-compose.yml down
Copied!
Follow the official guide to start with a new Appsmith deployment at https://docs.appsmith.com/setup/docker#docker-compose-configuration, also shown here in brief for reference:
1
cd "$new_path"
2
curl -L https://bit.ly/32jBNin -o docker-compose.yml
3
docker-compose up -d
Copied!
Please note that you must create a new docker-compose.yml in "$new_path" folder, like with the curl command above. Don't copy it from "$old_path".
6. Import database
After your new deployment comes up (usually takes ~30 seconds), we will import the data that was exported from the old instance:
Create the folder to copy the archive file:
1
mkdir -pv "$new_path"/stacks/data/restore
Copied!
Copy the archive file:
1
cp "$old_path"/data/mongo/db/backup/appsmith-data.archive "$new_path"/stacks/data/restore/
Copied!
Import data from this archive:
1
docker-compose exec appsmith appsmithctl import_db
Copied!
Note that this will ask you Importing this DB will erase this data. Are you sure you want to proceed, where you can respond with y. It is safe in this situation since the new database in the new setup only contains initial data and should be safe to be overwritten.
Once this is successful, we are ready to bring up our new instance!
7. Verify migration
Navigate to your Appsmith instance, the same way you used to with your old instance, whether using IP address, or custom domain, and verify that your Appsmith instance is working well, and all your data is intact.
After this, please designate a user as the superuser, to give them access to the Admin Settings page. You can follow the instructions at https://docs.appsmith.com/setup/instance-configuration/admin-settings#configuring-a-superuser to apply this change. diff --git a/setting-up/migrate.md b/setting-up/migrate.md

Instance Management

Tutorials

Last modified 1mo ago

Copy link

Edit on GitHub

Contents

1. Shutdown old appsmith instance

2. Export database

3. Migrate Configuration

4. Export https config & certificate (optional)

5. Setup new Appsmith with Fat container

6. Import database

7. Verify migration