Skip to content

Step 0 — Set up

About 20 minutes. One install, one account, one environment.

What you need

  • Node 22.19 or newer — node --version. The CLI will refuse to install on anything older rather than misbehave later.
  • Git, and an account on GitLab or GitHub.
  • Optionally Docker, if you want to run Tally on your own machine as well as on the platform. Nothing in the tutorial requires it.

Install the CLI

npm install -g appmecca

That gives you a command called mecca. Check it:

mecca --version

The package is appmecca; the command is mecca

They differ because the package name is about the platform and the command is about your app. It trips people up exactly once.

Point it at an environment

mecca configure

It asks for an API URL and stores it in ~/.appmecca/mecca.conf. Your environment's URL comes from whoever runs it — it is not something you can guess, and there is no public default.

Check that it answers:

mecca status

Get an account

mecca signup

Then, on any machine afterwards:

mecca login
mecca whoami

whoami is worth running now and remembering, because it answers three questions at once: who you are, which group you are in, and which environment you are pointed at. Almost every confusing result later is one of those three being different from what you assumed.

Fork the tutorial app

The platform builds from a remote, not from your laptop — it clones your repository on a build host. So a branch that exists only locally is invisible to it, and you need somewhere of your own to push.

Your fork must be public

A public repository is cloned with the environment's deploy key and needs no setup at all. A private one additionally needs a linked Git account, which is more moving parts than a tutorial should ask for on page one.

Create an empty, public repository on GitLab or GitHub. Then:

git clone https://gitlab.com/appmecca-public/appmecca-tutorial-app.git tally
cd tally
git remote rename origin upstream
git remote add origin <your empty repository's URL>

Now make the one branch you will use for the whole tutorial:

git checkout -b tutorial upstream/step-1
git push -u origin tutorial

Why one branch, for the whole tutorial

This is the single most important thing on this page.

On AppMecca a branch is not a variant of an app — it is an app. Each branch gets its own database, its own URL, its own environment variables and its own history. Nothing is shared.

So if you deployed step-1, then step-2, then step-3, you would not be updating anything. You would be provisioning a new application each time, with a new empty database, and you would end up with seventeen of them. It would not error. It would just quietly cost you seventeen apps.

Working on one branch called tutorial avoids all of that. To move to a later step you overwrite your branch with that step's contents:

git fetch upstream
git reset --hard upstream/step-4
git push --force origin tutorial

No merge, no rebase, no conflicts.

You will see a warning about the default branch

mecca register says "Registering branch 'tutorial', but this repo's default branch is 'main'". That is expected and correct — you are deliberately working on a branch of your own. Carry on.

step-N holds the state at the end of step N

To do step 4, start from step-3 and make the edits the page describes. To skip to the finished state of step 4, reset to step-4.

Reset to step-4 intending to do step 4 and you will find the edits already made, and reasonably conclude you have done something wrong.

Next: Step 0.5 — See it work first, which proves all of the above before you spend an afternoon on it.