Install Atelier and run the local demo

Start the supplied application, Atelier, on your machine, create a fictional account, and save your first project. Email stays in a local mailbox and subscription billing is simulated: you do not need a mail provider, a Stripe account or a payment card.

Before you start

• Use Linux or macOS 13.5 or later.
• Accept the invitation to the private GitHub repository using the GitHub account designated for your purchase.
• Install Node.js 24.22.1 or later within version 24 and npm 11. Check with node --version and npm --version.
• Have a running PostgreSQL 18 server on your machine, an empty database dedicated to this demo, and a database user with a password and permission to create tables in that database. The kit does not install or start PostgreSQL.
• Have a browser and an internet connection for downloading dependencies.

If you already have PostgreSQL 18, use its host port, database name and credentials in step 2. Use 127.0.0.1 or localhost as the database host.

If you prefer Docker and have it installed and running, this example creates a dedicated PostgreSQL server and database. Replace YOUR_LOCAL_DB_PASSWORD before running it, and keep that password for step 2. A password made of letters and digits avoids URL-encoding issues in the connection string.

docker run --name atelier-demo-db \
  -e POSTGRES_USER=atelier \
  -e POSTGRES_PASSWORD=YOUR_LOCAL_DB_PASSWORD \
  -e POSTGRES_DB=atelier \
  -p 127.0.0.1:55439:5432 \
  -d postgres:18.6-bookworm
docker exec atelier-demo-db pg_isready -U atelier -d atelier

Wait until the second command reports accepting connections; run it again if the server is still starting. This example stores the database in Docker-managed storage. Keep the container to resume the demo later.

Get the sources

If you already have the acquired sources, confirm that they match the source commit in your offer, then continue with Install dependencies. If you cannot establish which revision you have, retrieve it below or contact Alto Brio for your delivery reference.

Copy the source commit shown in your offer after the repository name. Replace RECEIVED_SOURCE_COMMIT with that commit. If you no longer have the offer, contact Alto Brio for your delivery reference.

ATELIER_COMMIT='RECEIVED_SOURCE_COMMIT'
printf '%s\n' "$ATELIER_COMMIT" | grep -Eq '^[0-9a-f]{40}$' &&
git clone --origin atelier https://github.com/altobrio/atelier.git my-saas &&
cd my-saas &&
test "$(git rev-parse --verify "${ATELIER_COMMIT}^{commit}")" = "$ATELIER_COMMIT" &&
git switch -C main "$ATELIER_COMMIT" &&
git branch --unset-upstream &&
test "$(git rev-parse HEAD)" = "$ATELIER_COMMIT"

Run the commands as one block. If a command fails, stop and check the commit and the error before retrying. The clone needs an unused my-saas directory. If a later step fails after entering the new clone, return to its parent directory. Choose another unused directory or remove only the new, incomplete clone before retrying.

On success, main in this fresh clone starts at the exact source commit in your offer. The atelier remote retrieves kit updates; main holds your application changes. Before customizing or deploying, set up your own private repository.

Alternatively, while signed in to the designated GitHub account, replace RECEIVED_SOURCE_COMMIT in the following address with the full commit from your offer and open it in your browser to download that revision:

https://github.com/altobrio/atelier/archive/RECEIVED_SOURCE_COMMIT.zip

Extract the archive into a writable folder. Run the following commands from the source folder, alongside package.json.

1. Install dependencies

npm ci

Wait for the command to finish successfully before continuing.

2. Configure the local demo

If .env.local already exists, edit it instead of overwriting it: skip the cp command below. For a fresh installation, copy .env.example to .env.local, then generate a secret:

cp .env.example .env.local
node -e "console.log(require('node:crypto').randomBytes(32).toString('hex'))"

Open .env.local in your editor and set these two values:

DATABASE_URL=postgres://atelier:YOUR_LOCAL_DB_PASSWORD@127.0.0.1:55439/atelier
BILLING_WEBHOOK_SECRET=PASTE_THE_GENERATED_HEX_VALUE_HERE

The database URL must contain your actual username, password, port and database name. The example matches the Docker command above; other installations may use port 5432. URL-encode special characters in credentials, such as @ as %40. Paste the full generated value for BILLING_WEBHOOK_SECRET and keep it private. .env.local is ignored by Git.

Use the default demo mode. Leave APP_MODE and BILLING_MODE unset in your terminal and configuration; do not use the public hosting template runtime.env.example for this walkthrough. Existing environment variables can override .env.local.

3. Check the connection and prepare the database

npm run doctor -- --connection-only
npm run db:migrate
npm run doctor -- --database

The first check should report configurationValid: true, mode: 'demo' and databaseReachable: true. Migration creates the application tables in the database you selected and reports Applied migrations. The final check verifies the installed migrations. clientTlsVerified: false is expected for this local demo.

On a later run, db:migrate reports Database is up to date; no changes. when nothing needs applying. There are no preloaded demo accounts: you create one next.

4. Start the application

npm run dev

Keep this terminal running. Once it reports ready, open http://127.0.0.1:3000. The application is named Atelier. Use this same hostname throughout the walkthrough, including mailbox links.

If port 3000 is occupied, stop this command and choose another port:

npm run dev -- --port 3001

Then open http://127.0.0.1:3001. Use the actual port for all subsequent links.

5. Create and verify a fictional account

1. In Create account, enter alex@demo.test in Fictional email (.test), a demo-only password of 12–128 characters in Local password, and Demo studio in Team name. Use fictional data throughout this demo.
2. Click Create account. The confirmation asks you to open the local mailbox.
3. Follow the local mailbox link, which opens a new tab. Under Demo emails, find the Verify email message addressed to alex@demo.test and click its Verify email link.
4. On the page that opens, click Verify email to confirm. Wait for Email verified.
5. Select Sign in and enter the same email and password. Click Sign in.

You should now see your team's workspace. No message is delivered to an external email inbox. You can also open the local mailbox at /mailbox on the same server.

6. Save your first project

1. In Subscription, click Activate subscription. Its status becomes Active. This is a local simulation and does not charge anything.
2. Open Create a project. Enter My first project in Name and, optionally, a description. Click Create project.
3. Confirm that Project created. appears and your project is listed. Reload the page: the project should still be there.

Your account owns the new team. An active subscription is required to create or archive projects; the workspace shows the team's project quota.

Stop and return later

Press Ctrl+C in the terminal running npm run dev. Your account and project remain in PostgreSQL. To return, start your database if necessary, run npm run dev from the same folder and sign in with the account you created. If you chose port 3001, reuse npm run dev -- --port 3001 and http://127.0.0.1:3001.

For the Docker example, use docker stop atelier-demo-db to stop that demo database and docker start atelier-demo-db to start it again. Keep .env.local and the container to reuse the same configuration and data.

If a step fails

Restart npm run dev after changing configuration.

Continue with your application

Explore teams, permissions and subscriptions, then customize the application for your product. To try real email and Stripe test billing, prepare a public configuration and follow the staging deployment.