Deploying your app on 6.1040 Apps

Check the Bun version, then skip the Vue checks. Leave .db("conceptbox") unchanged. It names only the local in-memory database; with the platform's MongoDB, ConceptBox calls client.db() with no name.

When you reach Try it and push, first run bun run storage:setup once if you haven't run ConceptBox locally before, as its README describes. Then run bun run storage in a second terminal and leave it running for the local preview. Add this preview script to the root package.json:

    "preview": "bun run build && NODE_ENV=production PORT=3000 PUBLIC_ORIGIN=http://localhost:3000 bun run start",

Use localhost in the addresses you open; local file storage accepts uploads only from localhost. In step 4, add MongoDB and S3 storage, and keep the suggested variable names for both.

The local guide's app runs two servers and has no separate build step. Bun builds the page when the frontend server first serves it. Run bun --version; if it's older than 1.3.9, run bun upgrade so you can use bun run --parallel to start both servers.

Check the Bun version. If your app uses cookie-based sign-in, also follow If you use cookie-based sign-in, with http://127.0.0.1:8080 as the default address. You can skip the other Vue checks and keep your existing scripts. In step 3, use . alone for Package directories and leave Build script empty.

The start script runs both servers with bun run --parallel. The frontend listens on PORT at 0.0.0.0, and the backend stays on 127.0.0.1:4000, so don't pick 4000 for Port. The frontend passes /health to the backend, so the health check covers the frontend, backend, and database.

For Try it and push, add this preview script to the root package.json:

    "preview": "bun run db:up && NODE_ENV=production PORT=3000 PUBLIC_ORIGIN=http://127.0.0.1:3000 bun run start",

If Windows asks whether to let Bun through the firewall, click Cancel; the app still works on your computer.

With NODE_ENV=production, Bun builds the page once, as it will on the platform, instead of rebuilding it for every change.

Run bun --version and set packageManager in the root package.json to that version. For example, if it prints 1.4.0:

  "packageManager": "bun@1.4.0",

The platform installs and runs your app with this exact version of Bun. sync-engine setup wrote bun@1.3.4, and Bun 1.3.4 can't read a lockfile written by Bun 1.4 or later.

The lockfile records the package versions to install. The platform uses bun.lock in each folder. If you installed with npm, as create-vue suggests, run bun install in frontend to copy the versions from package-lock.json into bun.lock. Then delete frontend/package-lock.json and commit frontend/bun.lock. Use bun add for new packages so the Bun lockfile stays up to date.

In the root package.json, add this build script under scripts:

    "build": "bun run --cwd frontend build",

In frontend/package.json, replace the build script that create-vue writes for TypeScript projects, run-p type-check "build-only {@}" --, with:

    "build": "vite build",

With TypeScript, the build script from create-vue also runs vue-tsc to check for type errors. That command requires Node.js, which isn't included in the platform's Bun runtime. Run npm run type-check in frontend on your computer before pushing instead; npm run runs the script without changing your lockfiles. If your frontend imports the typed client, type-check also needs your design files. In frontend/tsconfig.app.json, add "@design/*": ["../design/*"] under paths and "../src/text.d.ts" under include.

Vite's development server doesn't run on the platform, so your backend sends the pages. Set the root start script to run only your backend:

    "start": "bun src/main.ts",

Add a fetch function to the existing Bun.serve call in src/main.ts, keeping the hostname, port, and routes settings:

const dist = `${import.meta.dir}/../frontend/dist`;

const server = Bun.serve({
  // hostname, port, and routes stay as they are
  async fetch(request) {
    const file = Bun.file(dist + new URL(request.url).pathname);
    return new Response((await file.exists()) ? file : Bun.file(`${dist}/index.html`));
  },
});

Bun checks routes first, so /api/... and /health still reach your backend. For other paths, the backend sends a file from frontend/dist if one exists, or index.html so Vue Router can display the page. This also lets a visitor reload an inner page, such as /reservations. You can leave the local guide's other scripts and the web folder in place; the platform doesn't use them.

Use /api/... instead of http://localhost:3000/api/... or an address from a VITE_ variable. In a visitor's browser, localhost refers to their computer, not your deployed app. With the typed client, set baseUrl: "/api". For local development, add a proxy for /api inside defineConfig in frontend/vite.config.ts (or .js), merging it with any existing server settings. Vite will forward those requests to your backend:

  server: { proxy: { "/api": "http://127.0.0.1:3000" } },

Vite puts VITE_ values into the frontend during the build. The environment variables you enter on the platform are supplied when the app runs, after the build, so they won't be available to Vite. Replace API addresses with /api/..., as in API calls. Put fixed values, such as a title, directly in the code. For a public value that changes between deployments, read it on the backend and return it through an API endpoint. Keep API keys and other secrets on the server; don't return them to the browser. Move variables still used by the backend to the root .env, then delete frontend/.env.

For connections to the platform's MongoDB, call client.db() with no name. This selects the database specified in the connection string, rather than a name you used locally.

If your app uses a cookie to remember who is signed in, the backend accepts sign-in requests and requests using that cookie only from the publicOrigin address. Find this setting in the HTTP policy (src/http.ts in the local guide). Read it from PUBLIC_ORIGIN, which you'll set to the deployed address in step 4. When the variable isn't set, use the address you open while developing. With Vite's development server, that's http://localhost:5173:

  publicOrigin: process.env.PUBLIC_ORIGIN ?? "http://localhost:5173",

localhost and 127.0.0.1 count as different addresses, so use the one in your browser's address bar. If the policy also has a browser setting, remove it; on the platform, pages and the API share one address.

To deploy from a private repository, add a deploy key to it on GitHub. The key lets the platform read that one repository. Someone with admin access to the repository must add it.

1. Save the repository URL in Settings. Under Private repository, click Create deploy key and copy the key.
2. On GitHub, open the repository's Settings, then Deploy keys, then Add deploy key. Paste the key and leave Allow write access off.
3. Return to your app's Settings tab and click Check access. You should see GitHub accepts the key., followed by the commit your branch is on.

You can let people sign in with their class account, with a password, or both. ConceptBox includes code for each option that you can copy into a sync-engine app. Copy parts into your app in the README lists the files and how to connect them.

• With a class account, classmates and course staff sign in through Commons, as you did in step 1. This works at https://<name>.mit-sdg.dev, and at localhost or 127.0.0.1 while you develop. To write sign-in yourself, Commons' deployment guide lists the requests your server makes.
• With a password, anyone can sign up. Copy the sign-in code from ConceptBox rather than writing your own. It stores an argon2id hash for checking the password, not the password itself. Even so, you're responsible for other people's account information. Ask only for the information your app needs, and avoid collecting sensitive details.

Either way, read PUBLIC_ORIGIN as in If you use cookie-based sign-in, and set it in step 4.

Your app's folders are read-only, and each deployment starts on a fresh machine, so keep uploaded files in S3 storage. Under Databases and storage, click Add S3 storage and confirm, then click Save variables in the next dialog, and deploy again to set them. ConceptBox reads the names the dialog suggests, so a copy of its storage needs no changes.

Bun's S3 client reads all of these except S3_PUBLIC_ENDPOINT by itself, so you only pass in the public address:

import { S3Client } from "bun";

// For your server's own reads and writes.
export const s3 = new S3Client();

// Only for signing URLs that browsers will use.
export const publicS3 = new S3Client({ endpoint: process.env.S3_PUBLIC_ENDPOINT });

Use s3 on the server to read and write files, as in await s3.write("notes/hello.txt", "Hello!") and await s3.file("notes/hello.txt").text().

For a browser upload, your server can create a signed URL that grants temporary permission to upload one file. The browser sends the file to that URL without receiving your storage credentials:

// On the server
const key = `uploads/${crypto.randomUUID()}`;
const url = publicS3.presign(key, { method: "PUT", expiresIn: 600 });

// In the browser, with the url from the server
await fetch(url, { method: "PUT", body: file });

Save key in your database so you can fetch the file later. For downloads, use publicS3.presign(key, { expiresIn: 300 }).

• Check the person's permission to use a file before signing its URL. Anyone with that URL can use it until it expires.
• Always set expiresIn. Bun's default is a whole day.
• Browsers can upload only from https pages on mit-sdg.dev, so try browser uploads on your deployed app, not on localhost. Other tools can still use a signed URL from anywhere.
• Each upload can be up to about 100 MB, and your app's storage holds up to 5 GB and 100,000 files.

S3 storage added before October 14 keeps the older names: Edit variables next to the storage shows names starting with AWS_, such as AWS_ACCESS_KEY_ID. Code written for those names keeps working, but the code above and ConceptBox read the S3_ names. To switch, click Edit variables, then Reset to defaults and Save variables, update your code if it reads the old names, and deploy again.

Apps. Each student can create two apps, and a stopped app still counts. Names can't be changed, and only the course staff can delete an app or a database. Each app can have one MongoDB database, one PostgreSQL database, and one S3 bucket.

Running. Your app has a fixed memory limit, and going over it stops the app. The platform restarts an app that crashes, up to three times within five minutes.

Changes. The platform makes one change at a time, across all your apps. Changes to settings and to database and S3 variables take effect on the next deployment. Saving an environment variable restarts the app right away.

Health checks. Visitors reach a new deployment only after its health check returns HTTP 2xx, with a body of at most 4 KB and no redirect. The platform waits up to 10 minutes for that before the deployment fails. A failed deployment leaves the previous one running.

MongoDB. Your database runs on a separate server, with separate memory, CPU, and disk limits. It holds 2 GB and allows 10 connections at a time. The connection string already sets the connection limit, so create one MongoClient when your app starts and reuse it throughout your code. If the database grows past 2 GB, writes pause until at least 5% of the space is free. Reads and deletes still work. The course staff can raise the limit.

PostgreSQL. Your database holds 2 GB and allows 20 connections.

Files. S3 storage holds up to 5 GB and 100,000 files, with uploads of up to about 100 MB each.

Backups. Databases and S3 files go into encrypted backups every night.

Bun and Node.js versions. packageManager names an exact Bun version. To give a range instead, remove that line and use engines, such as "engines": { "bun": ">=1.3.9" } or "engines": { "node": ">=22" }. A range selects the newest release it allows; for Node.js, the newest long-term support one. Without either, the platform reads .bun-version, .nvmrc, or .node-version, and otherwise uses its default. Node.js before 20 and Bun before 1.1 aren't supported. The Deploy tab shows the version a commit specifies.

Node.js apps. Choose Node.js under Runtime and commit package-lock.json in each package directory. The platform installs with npm ci.

S3 from Node.js. Use @aws-sdk/client-s3 and @aws-sdk/s3-request-presigner. The AWS SDK doesn't read the S3_ variables, so pass them in, along with forcePathStyle:

import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
import { getSignedUrl } from "@aws-sdk/s3-request-presigner";

const options = {
  region: process.env.S3_REGION,
  credentials: {
    accessKeyId: process.env.S3_ACCESS_KEY_ID!,
    secretAccessKey: process.env.S3_SECRET_ACCESS_KEY!,
  },
  forcePathStyle: true,
};
const s3 = new S3Client({ ...options, endpoint: process.env.S3_ENDPOINT });
const publicS3 = new S3Client({ ...options, endpoint: process.env.S3_PUBLIC_ENDPOINT });

const key = `uploads/${crypto.randomUUID()}`;
const command = new PutObjectCommand({ Bucket: process.env.S3_BUCKET, Key: key });
const url = await getSignedUrl(publicS3, command, { expiresIn: 600 });

PostgreSQL. Click Add PostgreSQL instead of Add MongoDB. With the suggested variable names, your app gets DATABASE_URL, which includes the password, and the standard PG variables, such as PGHOST and PGUSER. Most PostgreSQL clients can connect with DATABASE_URL alone.

6.1040 Apps runs in a project on CSAIL's OpenStack cloud, run by TIG, CSAIL's infrastructure group. OpenStack is open-source software for running your own cloud of virtual machines, much like a private AWS.

Every machine runs NixOS. Its image is built from one commit of the platform repository and boot-tested before use. Machines aren't updated in place; an update replaces the machine.

There are five kinds of machines:

• The admin machine runs Nomad, which schedules app containers, and the controller that manages deployments.
• The ingress machine runs Traefik, which routes each app's address to the right app.
• The storage machine runs a separate PostgreSQL or MongoDB server for each app's database, each with separate memory, CPU, and disk limits. It also runs Garage, an S3-compatible file store shared by all apps with a separate bucket for each, and the private registry for app images.
• Each app gets its own worker machine, with no SSH and no persistent disk.
• Each build gets a single-use builder machine.

When you deploy, the platform fetches the exact commit, and a fresh builder uses BuildKit to build a container image from the official Bun or Node.js image. The builder pushes the image to the private registry and is then deleted. The platform starts a fresh worker for your app, and Nomad runs the image there. Traffic switches only after the app, the scheduler, and the public address all pass their health checks. Starting these virtual machines takes most of the deployment's time.

Public traffic reaches Cloudflare first, which handles HTTPS. Traefik then forwards it to the app.

Students don't get SSH, OpenStack, or database-admin access.

The code is public. You can read the platform repository and Commons, the class site whose accounts you use to sign in.