Hosting your application in CARTO

Build an application that CARTO hosts and serves behind your organization's login

Private Preview: Hosted Apps is available to selected accounts during its Private Preview. To request access, contact your CARTO representative.

Here you will learn how to build an application that CARTO hosts for you with Hosted Apps. Like a private application, it will only be accessible to users inside your CARTO organization, but CARTO serves the files and signs users in, so there is no OAuth client to create and no login code to write. If you only want to see a hosted application working first, follow Hosting your first application.

After completing this guide you will be familiar with the following concepts:

• Preparing your application to be hosted by CARTO.

• Reading the user's credentials at runtime.

• Deploying and sharing your application.

• Using Named Sources, so that no SQL reaches the browser.

• Publishing new versions and rolling back.

During this guide, we're using the CARTO Data Warehouse. The process explained here is also compatible with other Warehouses like BigQuery, Snowflake, Redshift, Databricks, Oracle, or Postgres. Instead of using connectionName: 'carto_dw', you need to use the name of your connection.

Before you start

• Install the CARTO CLI, version 0.12.0 or later, and log in with carto auth login. You will use the CLI to deploy the application, and its login to run the application on your computer.

• Make sure Hosted Apps is enabled for your account (see the note above).

Scaffolding your application

As in the other guides, we're going to start from the basic CARTO template in Vite, which already includes a basemap and deck.gl:

git clone https://github.com/CartoDB/carto-for-developers-guides.git
cp -r carto-for-developers-guides/template hosted-app
cd hosted-app
npm install

Then update the scripts in package.json. build produces the files you will deploy in the dist folder, and deploy builds and deploys them in one step:

"scripts": {
  "dev": "vite --https --open",
  "build": "tsc && vite build",
  "deploy": "npm run build && carto app deploy dist --name \"Retail stores\" --slug retail-stores",
  "preview": "vite preview",
  "lint": "eslint . --ext .ts"
}

The slug, retail-stores, identifies your application and is part of its URL.

Preparing the application for CARTO hosting

CARTO serves a hosted application under /app/<slug>/ instead of at the root of a domain, and gives it the user's credentials in a file named carto-info.json. Replace vite.config.js with the following, which does two things:

• base: './' makes every asset URL relative, so the files load correctly under /app/<slug>/.

• The cartoInfo plugin serves carto-info.json while you develop, using your CARTO CLI login. Once the application is deployed, CARTO serves this file instead, with the credentials of each user.

import basicSsl from '@vitejs/plugin-basic-ssl'
import eslint from 'vite-plugin-eslint'
import { readFileSync } from 'node:fs'
import { homedir } from 'node:os'
import { join } from 'node:path'

// Development only: serve carto-info.json from your CARTO CLI login, as CARTO
// serves it to each user once the app is deployed.
function cartoInfo() {
  return {
    name: 'carto-info',
    apply: 'serve',
    configureServer(server) {
      server.middlewares.use('/carto-info.json', (req, res) => {
        const credentials = JSON.parse(readFileSync(join(homedir(), '.carto_credentials.json'), 'utf-8'))
        const profile = credentials.profiles[process.env.CARTO_PROFILE || credentials.current_profile]
        res.setHeader('Content-Type', 'application/json')
        res.setHeader('Cache-Control', 'no-store')
        res.end(JSON.stringify({
          schemaVersion: 1,
          accessToken: profile.token,
          apiBaseUrl: process.env.CARTO_API_BASE_URL || `https://${profile.tenant_id}.api.carto.com`,
          user: { id: 'local', accountId: profile.organization_id, email: profile.user_email }
        }))
      })
    }
  }
}

export default {
  base: './',
  plugins: [basicSsl(), eslint(), cartoInfo()]
}

The plugin uses the API Base URL of your CARTO region. If the one shown in Workspace -> Developers is different, start the development server with CARTO_API_BASE_URL set to it.

Reading the user's credentials

A hosted application does not store any credential. When it starts, it fetches carto-info.json, relative to its own URL, and CARTO answers with the access token of the user who opened it and the API base URL to use. The runtime and authentication reference describes every field.

Create a file src/session.ts:

export interface CartoSession {
  accessToken: string;
  apiBaseUrl: string;
  expiresAt?: number;
  user: { id: string; accountId: string; email: string | null } | null;
}

export async function getSession(): Promise<CartoSession> {
  const response = await fetch('./carto-info.json', { cache: 'no-store' });
  if (response.status === 401) {
    renewSession();
  }
  if (!response.ok) {
    throw new Error(`carto-info.json returned HTTP ${response.status}`);
  }
  return response.json();
}

export function renewSession() {
  const slug = location.pathname.split('/')[2];
  location.assign(`/app/_session?slug=${slug}`);
}

CARTO keeps the user's session in the application for up to one hour. When it ends, carto-info.json returns 401, and renewSession takes the user through the CARTO login and back to the application. If they are still logged in to CARTO, this happens without asking them for anything. Call renewSession too if a CARTO API returns 401.

Visualizing a dataset

Now let's use those credentials to add a layer. Replace src/map.ts with:

import maplibregl from 'maplibre-gl';
import { Deck } from '@deck.gl/core';
import { BASEMAP, vectorTableSource, VectorTileLayer } from '@deck.gl/carto';
import type { CartoSession } from './session';

export function createMap({ apiBaseUrl, accessToken }: CartoSession) {
  const stores = vectorTableSource({
    apiBaseUrl,
    accessToken,
    connectionName: 'carto_dw',
    tableName: 'carto-demo-data.demo_tables.retail_stores'
  });

  const deck = new Deck({
    canvas: 'deck-canvas',
    initialViewState: { latitude: 39.8097343, longitude: -98.5556199, zoom: 4 },
    controller: true,
    layers: [
      new VectorTileLayer({
        id: 'stores',
        data: stores,
        pointRadiusMinPixels: 3,
        getFillColor: [200, 0, 80]
      })
    ]
  });

  // Add basemap
  const map = new maplibregl.Map({ container: 'map', style: BASEMAP.POSITRON, interactive: false });
  deck.setProps({
    onViewStateChange: ({ viewState }) => {
      const { longitude, latitude, ...rest } = viewState;
      map.jumpTo({ center: [longitude, latitude], ...rest });
    }
  });
}

And src/main.ts with:

import './style.css';
import 'maplibre-gl/dist/maplibre-gl.css';
import { createMap } from './map';
import { getSession } from './session';

document.querySelector<HTMLDivElement>('#app')!.innerHTML = `
  <div id="map"></div>
  <canvas id="deck-canvas"></canvas>
`;

getSession().then((session) => createMap(session));

The only difference with any other CARTO for Developers application is where the credentials come from. Run npm run dev and you should see the retail stores on the map at https://127.0.0.1:5173/, loaded with your own credentials.

Deploying and sharing your application

Deploy the application:

npm run deploy

The CLI uploads the contents of dist and prints the URL of your application, ending in /app/retail-stores/. Open it in your browser: CARTO asks you to log in if you aren't already, and the application loads with your credentials.

New applications are private. To share it with everyone in your organization, run:

carto app share retail-stores --org

You can also share it with specific groups or users with --group and --user. Users open the same URL and log in with their CARTO account. The application runs with their credentials, so each of them only sees the data they have access to.

Using Named Sources

Right now, the application tells CARTO which table to read, and a SQL query would travel from the browser in the same way. With Named Sources, the query is stored in CARTO and the application only references it by name, so no SQL reaches the browser.

A hosted application declares its Named Sources in a carto.json file at the root of the deployed files. Create public/carto.json (Vite copies the public folder to the root of dist):

{
  "connections": [
    {
      "name": "carto_dw",
      "provider": "bigquery",
      "sources": {
        "stores_in_state": {
          "sql": "SELECT cartodb_id, storetype, revenue, geom FROM `carto-demo-data`.demo_tables.retail_stores WHERE state = @state"
        }
      }
    }
  ]
}

When you deploy, CARTO registers each source under the name <slug>_<key>, here retail-stores_stores_in_state. The CLI does not upload carto.json, so it is never served to the browser.

Then, in src/map.ts, replace vectorTableSource with vectorQuerySource in the import, and the source with:

const stores = vectorQuerySource({
  apiBaseUrl,
  accessToken,
  connectionName: 'carto_dw',
  sqlQuery: 'retail-stores_stores_in_state',
  queryParameters: { state: 'CA' }
});

Deploy again with npm run deploy. The map now shows only the stores in California, and the network requests carry the name of the source and its parameters, never its SQL. Named Sources run with the credentials of the user, like any other request of the application. From this point, they also work with npm run dev.

Publishing new versions

Each npm run deploy publishes a new version of the application and makes it the active one. The URL and the sharing settings stay the same. To list the versions and go back to a previous one:

carto app versions retail-stores
carto app rollback retail-stores <version>

A rollback changes the files that are served. Named Sources stay as they were in the last deploy.

Congratulations! You now have an application that CARTO hosts and serves to the users you share it with, with their own credentials and without exposing any SQL.

What's next?

• Learn how hosting fits with the rest of your options in Hosted Apps, in Key concepts.

• The Hosted Apps reference describes the carto.json manifest, the runtime and authentication contract, and the bundle requirements and limits, including which external resources an application can load.

• The app command reference documents every command and flag, including carto app delete.