Migrate a small app from one instance to another

It’s quite common to have multiple environments, e.g. preproduction and production, hence the need to have a release process between them.

We will call source instance the first environment and target instance the second environment. E.g., the source instance will look like https://my-toucan-preprod.com and the target instance like https://my-toucan-prod.com.

This procedure describes how to copy a small app from the source instance to the target one. It requires an administrator account on both instances.

1. Create the small app

On the target instance, create the small app using Create a projet button. Give it the same name than the small app you want to copy from the source instance.

Create a new small app

Create a new small app

2. Copy configuration files

On the source instance, go to staging mode, hit Edit, and open the Config files interface.

Access staging mode

Access staging mode

Access edition mode

Access edition mode

Access config files editor

Access config files editor

Download all the files there (in their production version):

  • front_config.cson
  • etl_config.cson
  • all reports templates
  • all dashboards templates
  • preprocess files
  • permissions
  • notifications
Download a config file

Download a config file

On the destination instance, open the same Config files interface and drop all the files you previously downloaded.

Drop a config file

Drop a config file

Create and/or remove reports and dashboards templates to have exactly the same names as in the source instance.

Create a new template Remove a template

3. Copy data source files

On the source instance, in staging mode, with Edit, open the Data sources interface. Access data sources

Download all the files there, in their production version. Download a data source

On the destination instance, open the same Data sources interface and drop all the files you previously downloaded. Drop a data source

4. Run the data pipeline

On the destination instance, still in the Data sources interface, select Operations, check all the boxes, and hit Start now.

Run the data pipeline

Run the data pipeline

Note

Depending on how much processing there is, this step can take a while. You can follow the status by looking at the logs or, alternatively (if your version doesn’t support log streaming), by hitting the Report button.

If this operation fails, contact the conceptor of the small app, and send him the logs and/or the report (containing the trace of the error).

Log the data pipeline Report of a successfull data pipeline

5. Copy assets

On the source instance, in staging mode, with Edit, open the Assets interface and download all the files there.

Download an asset file

Download an asset file

On the destination instance, open the same Assets interface and drop all the files you previously downloaded.

Drop an assset

Drop an assset

6. Copy the color scheme

On the source instance, in staging mode, with Edit, open the Color scheme interface.

Access color scheme

Access color scheme

On the destination instance, open the same Color scheme interface and check all the values are the same.

Color scheme values (appear when hovering)

Color scheme values (appear when hovering)

Copy/paste the content of the Specific stylesheet text area in the source instance to the one on the destination instance.

Specific stylesheet

Specific stylesheet

Hit save on the destination instance.

Save button for color scheme

Save button for color scheme

7. Have a look at the small app

Hit preview on the the small app to return to preview mode. Switch to preview mode

Check that the small app is identical, in staging mode, on the source and on the destination instance.

If everything is fine, advance to the last step.

8. Release the small app

Still on the destination instance, hit the Release to prod button (either from Config files or from the Data sources interfaces).

Release to prod button

Release to prod button

Release to prod successful

Release to prod successful

Note

This process is the one to copy all elements of the small app. It’s necessary to follow all the steps the first time, when the small app needs to be created.

On subsequent updates, if only the data sources need to be updated, only the steps 3, 4, 7 and 8 need to be executed.