Update a server from its git repository

A server that runs your own code from a git repository, such as a Node.js or Python server with a Git address, is updated by a release. A release puts one commit of the repository on the server. We fetch the commit and check it before the server is touched, and we keep the version it ran before until the new one has started and stayed up. If the new one does not start, the previous version is put back and started again.

Use a release whenever you have pushed new code. You do not need Reinstall server… to update: a reinstall deletes every file on the server, and a release keeps the files that are not in your repository.

A web service built from git has releases of another kind, built for it and started beside the live one (Deploy, promote and roll back releases). A game server or a database has none.

• The server runs software that clones a git repository: one of the Node.js or Python runtimes.
• Its GIT_ADDRESS startup variable names a repository on GitHub or GitLab, as a web address (https://github.com/example/api) or as example/api for GitHub. GIT_BRANCH names the branch, and main is used when it is empty. Both are on the server's Settings tab, on the Startup variables card (Server settings).
• For a private repository, a repository token that can read it (Set the repository token).
• You own the server, or you are a subuser with the software.update permission. software.read is enough to read the releases (Share a server with other users).

A server with a Git address on another host has no Releases tab. It clones the repository when it installs, and the tab's address says so.

A release replaces the files your repository holds, and removes a file the last release held that this commit no longer has. Everything else on the server stays where it is: a .env file, installed dependencies such as node_modules, uploads, a database file.

Two things to know:

• A change you made on the server to a file the repository holds is replaced by the repository's version. Commit a change you want to keep.
• A file of your own that a release replaces is not deleted. This happens when the repository holds a file with the same name as one you made on the server, and on the first release of a server that already had files. The release moves each such file into .coritan/kept/, in a folder named after the release, and its log names the folder.

The server stops while its files are replaced, and starts again if it was running. A server that was stopped stays stopped.

1. In the dashboard, go to App Deployment, open the server, then the Releases tab.
2. Select Deploy…. A page opens, titled Deploy a release.
3. Under Branch, tag or commit, leave the server's branch to deploy its newest commit, or type another branch, a tag or a commit.
4. Select Deploy.

A message says Deploy started. and the release's page opens. It shows what the release is doing: Fetching the commit, Copying the files to the server, Replacing the files, Starting the server, then Watching the server after the start. While it reads Fetching the commit, nothing on the server has changed, and Cancel release… stops the release. Once it copies files it finishes on its own, or puts the previous version back.

When the server already runs the newest commit of the branch, the release ends as Cancelled with Nothing to deploy, and the server is not restarted. Use Rebuild… or Redeploy… to put its files back.

Both are under Run again on the Releases tab, once the server has a live release.

Each asks first, and you confirm with Rebuild or Redeploy. The Repository card names the folders a rebuild clears, beside Cleared by a rebuild.

1. On the Releases tab, find the release you want to return to. One you can return to reads Replaced.
2. Open its menu and select Roll back to this…, or open the release and select the same button.
3. Select Roll back.

A rollback is a new release that runs the stored files of the earlier one. Nothing is fetched, so it works while the git host is down or your token has expired. If the server does not stay up on those files either, the version it ran before the rollback is put back.

We keep the files of a server's newest releases and of its live release. A release whose files are no longer kept has no Roll back to this…. Deploy its commit instead: type the commit under Branch, tag or commit.

The Releases tab lists every release, newest first, with its commit, what started it and how long it took. Select one to open it.

A release's page has its Log, each step it took with the time, and its Details: the repository, the commit, who started it and whether its files are kept for a rollback. A release that failed to start shows the server's last lines of output in the log, which is where a missing module or a syntax error shows.

A private repository needs a token that can read it. We store it sealed and use it only to fetch the repository. It is never shown again, sent to the server or written to a log.

1. On the Releases tab, find the Repository card and select Set token…, or Replace token… when one is set.
2. Paste the token under Repository token. On GitHub, use a fine-grained personal access token with read access to Contents for this repository.
3. Select Save token.

The token applies from the next release. To remove it, open the same page and select Remove token…, then Remove token. Changing the token needs the startup.update permission.

Reinstall server… on the Settings tab still deletes every file on the server. For a server with releases it does two things first and one after:

1. It fetches the repository. When the repository does not answer, or refuses the token, the reinstall does not start and no file is deleted. The message says why.
2. It deletes every file and installs the software again.
3. It puts the commit it fetched back on the server, as a release that reads Install under Started by.

Files the repository does not hold are gone after a reinstall. Take a snapshot first to keep them, or deploy a release instead.

The Releases card reads, for example, 4 releases, newest first. Live: 3b9d7f1. and the release you started reads Live. Your server runs the new commit, and its other files are as they were.

Every path starts with https://api.coritan.com/api/v1/client/servers/{uuid}, with the server's ID. Send your access token as Authorization: Bearer $CORITAN_TOKEN.

Deploy the newest commit of the server's branch, or name a branch, tag or commit in git_ref:

curl -X POST https://api.coritan.com/api/v1/client/servers/$SERVER/releases \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"git_ref": "v1.4.0"}'

The answer is 201 with the queued release. Read it again with GET /releases/{release_uuid} until its status is ready or failed:

{
  "release": {
    "uuid": "8a4c2e6f-1d7b-4c3a-9e5f-2b8d4a6c1e37",
    "status": "ready",
    "stage": "done",
    "trigger": "manual",
    "source": "git",
    "git_ref": "v1.4.0",
    "git_sha": "3b9d7f1a5c2e8b4d6f0a9c3e7b1d5f2a8c4e6b10",
    "is_current": true,
    "can_rollback": false,
    "restored": false,
    "error": null,
    "log": "[11:05:22] Downloading example/api at v1.4.0 from GitHub.\n[11:06:14] The release is live.\n"
  }
}

status is queued, building, deploying, ready, failed, canceled or superseded. The dashboard shows building as Fetching, superseded as Replaced, and ready as Live while is_current is true. A failed release has error, error_code and restored, which is true when it had changed files and the previous version was put back.

A refusal answers {"detail": {"error": "...", "message": "..."}}:

The server's own read, GET /api/v1/client/servers/{uuid}, has the same git block. It is null for a server that clones nothing, and git.releases is false for a repository on another host.

GitHub refused the repository token for example/api (HTTP 401). It may have expired or been revoked.

The token no longer works. Replace the repository token, then deploy again. The server kept running its current version.

GitHub found nothing for example/api at main (HTTP 404).

The branch, tag or commit does not exist, or the repository is private and no token is set, or the token cannot read it. GitHub answers 404 for a private repository it will not show. Check GIT_BRANCH, then the token.

The server stopped 4 seconds after it started. The previous version is back and running.

The new commit does not start. Open the release and read the end of its Log for the server's last output. Fix the code, push, and deploy again.

The server's disk has 12 MB free and the release needs about 40 MB while it is put in place.

A release needs room for the new files beside the old ones until it is live. Free some space on the Files tab, then deploy again.

The reinstall was not started and no file was deleted.

A reinstall fetches the repository before it deletes anything, and the fetch failed. The rest of the message says why. Fix it, then reinstall again.

The server was installed, and its directory is empty

The repository could not be fetched when the server was installed. The Releases tab shows the failed release with the reason. Fix it, then select Deploy…. There is no need to reinstall.

Deploy… is missing, and the page says A release cannot start right now

The message under it names what the server is busy with. Wait for it to finish.

• Server settings to change GIT_ADDRESS, GIT_BRANCH and your app's own variables.
• Take a snapshot to keep a copy of the whole server, including the files a release does not touch.
• Use the console and power controls to read your app's output while it runs.