Publishing a project to Osyrin

Summary#

A project is on Osyrin once a publish of it has succeeded: osy deploy --env <slug> --server <url> builds it on this computer, hands it to Osyrin, and Osyrin builds it again and serves it. That deploy writes the link into the project's own osyrin.json: the server, the app, the environment, and the version and source it published. osy link reads the link back and asks the server about it. Studio's Publish does the whole thing from a sheet, through exactly these commands.

Signature#

osy link [path] [--server <url>] [--offline] [--json]
osy apps [--server <url>] [--json]
osy migration explain <file> [--json]
osy deploy --env <slug> --server <url> [--app <slug>] [--migration <file>] [--json]
osyrin login --server <url> · osyrin whoami --server <url> [--json] · osyrin logout --server <url>
osyrin app create <name> --server <url> [--org <slug>] [--json]

Description#

Signing in is Osyrin's own. osyrin login --server https://osyrin.app opens your browser on Osyrin's own sign-in page (Signing in to Osyrin; --no-browser types it in the terminal instead) and keeps the sign-in in ~/.osyrin/credentials.json, under the server's apex address (admin.osyrin.app and osyrin.app are the same sign-in). Every other verb uses that sign-in and none of them asks for a password: osyrin app create included. osyrin whoami --json answers {"signedIn": false, …} when nobody is signed in, and a tool asking with --json is never prompted.

The link lives in the project. After a publish succeeds, osyrin.json beside app.osy reads:

It is an ordinary file of the project, so the link goes wherever the project goes and a teammate's copy sees the same one. A deploy that is refused or fails writes nothing. The link is not in osyrin.lock, because the lock is part of what a deploy builds.

osy link says where the project stands. It never changes anything and never prompts:

• signed in — who is signed in to the server, or that nobody is, with the command that signs in;
• the app — the linked one. found says the server has it; address is where people open it. An app the server holds under the project's name is never taken to be this project — a copy of a project has the same name — so it is given apart, as sameName, and becomes the project's app only when a publish from here goes to it (--app);
• served — the version people get in the linked environment;
• changed — whether the project's source now differs from what was last published from here. It compares the same source hash a deploy is identified by, so a change to any source file, test, the lock, an asset or a package is a change, and nothing else is;
• declared secrets — the names the source declares. Values are never read: give them on Osyrin, in the app's Secrets;
• where a first publish can go — your organizations, and their environments in rank order. For each organization, cannotAdd says when the project cannot be added there: its first version needs a newer platform (its minPlatform, as the next deploy would carry it) than the newest release the organization can run.

--offline answers from this computer alone: the link and whether the source changed. Without --server it asks the server the link names.

Adding a project is two commands: osyrin app create "<name>" --server <url> makes the app (in your organization; --org when you belong to several) and prints its address name, then osy deploy --env <slug> --server <url> --app <that name> publishes the first version. An update is the deploy alone, because a successful deploy records the app in the project's osyrin.json. A deploy to a remote Osyrin never picks an app by the project's name: a project with no link to that server and no --app is refused, the refusal naming --app <slug> and, as "did you mean", the apps you can see whose names are the project's or close to it. Under --json, osy deploy prints one line of result on standard output — succeeded, message, application, version, address — and its progress on standard error. A change to stored data that needs a migration is refused by Osyrin before the new version is served, with the reason; people keep the version they have. See Deploying your app to an environment for everything a deploy does.

In Studio, every project has Publish. The sheet runs osy link and says, before anything is pressed: who is signed in; whether the project is on Osyrin and as which app; the version people get; what was asked of the builder since the last publish; and what will happen — a new app in which organization and environment, or the next version of the linked one, the data line above, and the secrets it still needs. Add to Osyrin runs osyrin app create and then osy deploy; Publish update runs osy deploy. While it runs the sheet shows the deploy's newest line; after, the version people get and the address, or the reason it was refused in Osyrin's words. Under the project's name a line says "On Osyrin as … · published … · changed since" whenever the project has a link.

Your organizations' apps. osy apps --server <url> lists every app of the organizations you belong to on that Osyrin — its organization, its address and the version people get — and each organization's app slots: how many it uses and how many its plan gives (2 of 3 app slots used), counted exactly as Osyrin counts when an app's first version starts running. An app that runs anywhere takes a slot; one that was only made takes none yet. It asks only: it never fetches or syncs source. An app's source lives on the computers it was written on; Osyrin keeps the built app, not the project. Studio's On Osyrin page draws this list and puts each app beside the project on this computer whose osyrin.json links it — "On this computer as Greeter", with Open — or says Not on this machine. Updating an app is opening its project and publishing.

App slots before an Add. osy link gives each organization's slots too, and Studio's Add says them before anything is sent. With none free, Studio does not make the app — its first version would be refused when it started — and says so: "Acme uses all 3 of its app slots, so another app would not start. A pro slot gives it one more." A pro slot is one more app for an organization; it cannot be bought yet, so Studio shows it as coming soon. In the same way, an organization that cannot yet run the platform the project needs is said before anything is sent, in the deploy's own words, and Add makes nothing — rather than an app whose first version is refused.

An app of the same name. When the project is linked to nothing and Osyrin has an app of its name, the sheet says so and offers both: Publish to that app, if this project is it, or Add to Osyrin as a new app. It never offers "Publish update" over an app it only matched by name.

A publish that needs a migration. A change that removes something holding data — a field renamed, an entity dropped — is refused before anything changes, and the refusal carries the migration Osyrin wrote from the change it saw. Under --json, osy deploy prints it apart from the sentence, as migration. osy migration explain <file> reads a migration with the same parser the deploy uses and says what each statement does: a rename keeps every value under the new name; a drop retires the values for good (with the safer way: keep the field one more version, copy its values, drop it in the next publish); a line the deploy only guessed — an inferred rename — is marked to check; and a file that no longer parses is refused with its line. In Studio the refused sheet keeps the migration in the project as migrations/next.migration, shows it in a field you can edit, explains it line by line (Check what it does), and Publish with this migration runs osy deploy --migration migrations/next.migration with the file exactly as you left it. It is the same .migration file as everywhere else (see Renaming and removing things that hold data and Running a function when a version deploys for run F;).

Settings has Your Osyrin account: who is signed in to the Osyrin Studio publishes to (https://osyrin.app unless you name another), Sign in to Osyrin, which runs osyrin login in the background with no window of its own: your browser opens on Osyrin's sign-in, you sign in there, and Studio never sees your password. If no browser opened, Studio shows the address to open. And Sign out. Studio keeps only which Osyrin it publishes to, in .studio/publishing.json in your projects folder; the sign-in is the CLI's.

Examples#

osyrin login --server https://osyrin.app        # once: Osyrin's own sign-in
osy link --server https://osyrin.app            # not on Osyrin yet — your organizations and environments
osyrin app create "Greeter" --server https://osyrin.app      # prints its address name, e.g. greeter-acme
osy deploy --env production --server https://osyrin.app --app greeter-acme   # the first version; osyrin.json now links it
osy link                                        # on Osyrin as greeter-acme · serves 1.0.0 · nothing has changed since
osy deploy --env production --server https://osyrin.app       # an update, to the app osyrin.json links
osy apps --server https://osyrin.app            # Acme — 1 of 3 app slots used · greeter-acme 1.0.0
osy deploy --env production --server https://osyrin.app --json   # refused: a field was renamed — the result carries `migration`
osy migration explain migrations/next.migration # what each statement does, and what to check
osy deploy --env production --server https://osyrin.app --migration migrations/next.migration

See also#

Signing in to Osyrin — osyrin login: in the browser, or typed with --no-browser; how long it lasts.

Deploying your app to an environment — what a deploy does, step by step, and how a failed one is put back.

Opening Studio — Studio, where Publish lives.

Giving a secret its value — secrets on this computer; on Osyrin they are given in the app's Secrets.