Updating Job Lab

A new version of Job Lab is new code. Your data is in the database and the file storage, and your settings are in one small file, so an update means replacing the code round them and then bringing the database tables in line with it. This guide covers your own computer and a server, then what to carry when you move a board.

Which version you have#

The version is the "version" line near the top of package.json, and the newest entry in CHANGELOG.md. It is not shown anywhere in the admin.

grep '"version"' /opt/joblab/package.json

What is yours#

Everything else in the folder is the kit's code. If you changed any of it, note which files: you repeat the change in the new copy.

Before you update#

• Read CHANGELOG.md in the new version. It lists what changed, newest first, and says under Upgrading whether the database changes.

• Take a backup. On a server, run the backup script below: see Backups, scheduled tasks and health.

• Leave APP_SECRET as it is. Why is below.

/opt/joblab/scripts/prod/backup.sh daily

On your own computer#

1. 1

   Step 1: Stop the site

   Press Ctrl and C in the terminal where pnpm dev is running. Leave the Docker services running.

2. 2

   Step 2: Replace the code

   With a git copy, run git pull in the Job Lab folder. Your .env is not in the repository, so the pull leaves it alone.

   With a zip, unzip the new version beside the old one. Copy .env from the old folder into the new one. Then rename the old folder, for example to job-lab-old, and give the new folder the name the old one had.

3. 3

   Step 3: Install and bring the tables in line

   bashCopy

   pnpm install
   pnpm db:push

   pnpm install adds any packages the new version needs. pnpm db:push compares the tables with the new code and changes them to match. If the change would remove a column or a table, it lists what would be lost and asks "Do you still want to push changes?" before it does anything.

4. 4

   Step 4: Start the site

   bashCopy

   pnpm dev

   Check your jobs and your settings are there before you delete the old folder.

On a server, from a repository#

cd /opt/joblab
./scripts/prod/backup.sh daily
./scripts/prod/deploy.sh update

update does these things, in this order:

1. Pulls the new code: git pull --ff-only origin main.

2. For each board in turn, builds its image, removes its container and starts a new one, then builds the joblab-tools image and runs pnpm db:push --force in it against that board's database.

3. Removes unused images and trims Docker's build cache to 3 GB. If the disk is more than 75% full it clears the build cache altogether.

4. Runs scripts/prod/setup-crons.sh, so the nightly backup stays installed.

5. Prints a health line for each board.

To update one board, name it: ./scripts/prod/deploy.sh update myboard. A board does not answer for a few seconds while its container is swapped, and between the swap and the end of db:push it runs new code on the old tables. If any step fails the script stops there, and the boards after it in the list are not touched. Read the error, fix it and run update again.

Afterwards, open System Health under Overview in the admin sidebar and check that the banner reads "All systems go".

On a server, from a zip#

update begins with git pull, and an unzipped copy is not a git repository: it stops with "fatal: not a git repository". Replace the files by hand and tell update to skip the pull.

1. 1

   Step 1: Back up, upload and unpack

   On your computerCopy

   scp job-lab-X.Y.Z.zip root@YOUR-SERVER-IP:/opt/

   On the serverCopy

   /opt/joblab/scripts/prod/backup.sh daily
   cd /opt
   unzip job-lab-X.Y.Z.zip

2. 2

   Step 2: Move what is yours into the new folder

   bashCopy

   mv joblab/sites joblab/backups job-lab-X.Y.Z/
   cp -p joblab/.env job-lab-X.Y.Z/

   Copy joblab/.backup.env too if you made one, and repeat any change you made to scripts/prod/nginx-site.conf.template.

3. 3

   Step 3: Swap the folders

   bashCopy

   mv joblab joblab-old
   mv job-lab-X.Y.Z joblab

   The code must end up at /opt/joblab: the backup script and its schedule have that path written into them.

4. 4

   Step 4: Build and restart every board

   bashCopy

   cd /opt/joblab
   SKIP_PULL=1 ./scripts/prod/deploy.sh update

   This is the same update as above without its first step. A board that started seconds ago can show "health 000": run ./scripts/prod/deploy.sh status a minute later. When every board shows "health 200" and you have looked at each one, delete /opt/joblab-old.

Keep the same APP_SECRET#

APP_SECRET is a line in .env on your computer and in sites/NAME/.env on a server. Job Lab encrypts every key you save in the admin with it: the Stripe keys, the email password, the AI keys, the Google client secret and the rest of Integrations & Secrets under Settings. The Telegram bot token is encrypted with it too.

No update needs a new one. If it changes:

• The saved keys can no longer be read, and each feature behaves as if it had never been set up. Each such field on the Integrations page says "A key was saved here but can no longer be read, because the app secret changed since. Paste the key again to store it under the current one."

• One-click unsubscribe links in job alert emails already sent stop working.

• A value shorter than 16 characters stops the site from starting at all.

AUTH_SECRET is different. Changing it signs everyone out and loses nothing.

Move a board to another server#

A board is one database, one storage bucket and one settings file. Whatever else changes, the new copy must run with the old APP_SECRET.

Every board on a server at once: restore the newest backup on the new server, with the old .env and sites/ folder. Restore a backup has the steps. The settings files carry each APP_SECRET across.

One board, from your computer or from another server:

1. 1

   Step 1: Make an empty board on the new server

   bashCopy

   ./scripts/prod/new-site.sh myboard example.com --no-start

   --no-start makes the database, the bucket, the settings file and the nginx file, and does not build or start the board. Set the server up first as in Deploy to a server.

2. 2

   Step 2: Carry the secret across

   Open sites/myboard/.env on the new server and replace the value of APP_SECRET with the one from the old copy.

3. 3

   Step 3: Copy the database

   On the old machine, write the database to a file. On your own computer the database is called joblab:

   On your computerCopy

   docker compose exec -T postgres pg_dump -U joblab --no-owner --no-acl joblab | gzip > board.sql.gz

   On a server it is joblab_ and the board's name:

   On the old serverCopy

   docker exec joblab-postgres pg_dump -U joblab --no-owner --no-acl joblab_myboard | gzip > board.sql.gz

   Copy the file to the new server and load it as the board's own database user, so that the board owns its tables:

   On the new serverCopy

   gunzip -c board.sql.gz | docker exec -i joblab-postgres psql -U joblab_myboard -d joblab_myboard

4. 4

   Step 4: Build and start the board

   bashCopy

   SKIP_PULL=1 ./scripts/prod/deploy.sh update myboard

   Then open Search Index under Tools and click Full Reindex: the search index is not copied, it is rebuilt.

Going back to a copy older than 1.0.0#

Copies from before 1.0.0 kept saved keys as plain text and cannot read encrypted ones. Before you put such a copy back, write the keys back as plain text with the script made for it. It needs the same APP_SECRET and database address the site runs with:

pnpm tsx --env-file=.env scripts/encrypt-integration-secrets.ts --revert

docker run --rm --network joblab-net --env-file sites/myboard/.env joblab-tools pnpm tsx scripts/encrypt-integration-secrets.ts --revert

It prints a line for each key it changed, then a summary that starts with how many were "written back as plain text". Nobody who started on 1.0.0 or later needs this.

What 1.1.0 changed#