Update package instructions

[benloh]

Addresses #84

---

Preparing an Electron Build

Overview

IMPORTANT: Read Reference Build Differences first to understand the different ways of building the app!!!

General Goals

• Start meme.app for the first time should start with a blank template if nothing has been defined.
• Researchers and teachers should be able to start meme.app with a default set of data (e.g. classroom/teacher/students/projects/resources etc) that can be defined easily via copying and pasting the whole MEME macOS distribution folder.
• Technical users should be able to define a starting project database by editing template *.db.js files.

Generally when preparing an Electron package to deliver to another site, you need to define three things:

I. Prepare Resources
II. Prepare Default Template
III. Prepare Distribution Files

Repo paths

Where to find files (for clarity, we are assuming / is the root repo directory, e.g. /src/ refers to /<repodir>/src/):

Folder ()	Source Code	Template Data	Local Runtime Data	Electron Runtime Data
/src/	X
/docs/	X
/node_modules/	from package.json
/templates/		X
/templates/_blank/		X
/built/			built from /src/
/data/			copied from /templates/
/resources/			references /resources/ directly
/dist/				built from /src/ via electron compile
/dist/MEME macOS/				X
/dist/MEME macOS/data/				copied from /data/
/dist/MEME macOS/resources/				copied from /templates/_blank/ and manual override
/dist/MEME macOS/templates/				copied from /templates/ and manual override

Where do I find my current running project database (loki) files?

The current running project database files are saved in different paths depending on how you start the server.

Run Mode	Command	Sources	Runtime Path*
Development	npm run dev	/meme/templates/test/*.db.js or if not exist, /meme/templates/_blank/*.db.js	/meme/data/db/test.loki
Electron Debug from Command Line -- with live reload (does not build dist)	npm run electron	meme.loki or if not exist, /meme/templates/meme/*.db.js or if not exist, /meme/templates/_blank_/*.db.js	/meme/data/db/meme.loki
"App" Mode -- Production from Command Line -- with console output	npm run app	same as electron	/meme/dist/MEME macOS/data/db/meme.loki
"App" Mode -- Production from Electron App	Double-click meme.app	same as electron	/meme/dist/MEME macOS/data/db/meme.loki

• The default project database name is always:

  • test.loki -- when running a Local Server via npm run dev, or
  • meme.loki -- when running an Electron app via npm run electron, npm run app, or double clicking the Electron meme.app.

• The two names (test.loki and meme.loki) are "burned in" and cannot be changed for loading. (But you can replace one meme.loki with another meme.lokifile in the same folder to swap out databases.

• Since the project database is just a single file, you can copy, archive, and replace test.loki and meme.loki files at will to manage versions over time.

• Generally, you only change the name (e.g. test.loki vs meme.loki) if you need to manually create a backup for archival purposes. e.g. you want to save your pilot study as meme_2023-0930.loki. If you want to load a different db file, you'd either use the Electron MKZIP export/import, or rename the db file from meme_2023-0930.loki to meme.loki.

• NOTE that the initial _blank template project is created from *.db.js files, that are then compiled and saved as *.loki when the app loads.

• The default runtime folder is <repo_folder>/data/test.loki, typically /meme/data/test.loki.

---

I. Prepare Resources

How do I add resources and their corresponding URLs in the Resource Editor?

Projects rely on references to "resources". Resources might be files (e.g. pdfs of articles, graphics), or simply links (e.g. url to a website, url to a simulation). File resources must be prepared for a project in advance. Link resources can be set up with the project.

Adding File Resources

There are two ways to add resources:

1. Use the "resources" defined in the main template to automatically copy resources for running during runtime, usually stored at /<repodir>/templates/_blank/resources/*.*, or
2. Add resources as you develop materials for the project directly to the corresponding runtime path, usually stored at /<repodir>/resources/*.* for local dev or at /<repodir>/dist/MEME macOS/resources/*.* when using Electron.

Resources are saved either to the local server or to the Electron app, depending on how you start the app.

Local Server Resources

For Local Servers, during compile the resources are copied from the /<repodir>/templates/_blank/resources to the /<repodir>/resources folder. You can then add additional resources as needed.

Electron App Resources

For the Electron App, during compile the resources are copied from the /<repodir>/templates/_blank/resources to the /<repodir>/dist/MEME macOS/resources folder. You can then add additional resources as needed.

Here's a table summarizing the sources and paths of resources

Run Mode	Command	Sources	Runtime Path*
Development	npm run dev	/<repodir>/templates/_blank/resources/*.*	/<repodir>/resources/*.*
Electron Debug from Command Line -- with live reload (does not build dist)	npm run electron	/<repodir>/templates/_blank/resources/*.*	/<repodir>/resources/*.*
"App" Mode -- Production from Command Line -- with console output	npm run app	/<repodir>/templates/_blank/resources/*.*	/<repodir>/dist/MEME macOS/resources/*.*
"App" Mode -- Production from Electron App	Double-click meme.app	/<repodir>/templates/_blank/resources/*.*	/<repodir>/dist/MEME macOS/resources/*.*

*Runtime Path -- You can add additional non-templated resources in the Runtime path folder.

URL Reference

All references should use .../static/dlc/*.* as the URL for resources.

You can use subfolders as well, e.g. resources in the disk path /<repodir>/dist/MEME macOS/resources/subfolder/helloworld.pdf would use a URL of ``.../static/dlc/subfolder/helloworld.pdf.

II. Prepare Default Template

New projects are always started from a template. By default, the _blank template is used. But existing projects (database files and resources) can be used to override the defaults.

How are projects created by default and where are they stored?

MEME tries to provide a graceful way to fall back to usable projects and templates. Here's the order in which MEME will attempt to create projects:

... for Local Development (npm run dev )

For local development, the test.loki database will always be generated from the *.db.js files with every run.

1. Using the files in...
   • <repodir>/templates/_blank/*.db.js and
   • <repodir>/templates/_blank/resources/*...
2. ...generate and load <repodir>/data/db/test.loki

...for Electron ( npm run electron, npm run app, or double-clicking meme.app)

For Electron Mode, we try these in order:

1. Use meme.loki

   • If meme.loki has been created...
   • ...copy <repodir>/data/db/meme.loki ...
   • ...to <repodir>/dist/MEME macOS/data/db/meme.loki

2. Use templates/meme/*.db.js

   • If meme.loki has not been created yet, but there is a <repodir>/templates/meme/ folder...
   • ...use <repodir>/templates/meme/*.db.js files to...
   • ...construct <repodir>/dist/MEME macOS/data/db/meme.loki

3. Fall back to /templates/_blank:

   • ...use <repodir>/templates/_blank/*.db.js to...

   • ...construct a new <repodir>/dist/MEME macOS/data/db/meme.loki

How do I create a template for new projects?

If you want to create a starting template for projects, e.g. you want to create water quality projects that share resources to use for a few different sites, you have two options:

A. Duplicate the dist meme.loki

The easiest method is to run the distributed electron version and update the files in the <repodir>/dist/MEME macOS/ folder:

1. Build, package, and run the electron app

   npm run electron
   npm run package
   npm run appsign
   

2. Start Electron via npm run app or double clicking the meme.app to load and run the files in <repodir>/dist/MEME macOS/
3. Edit any resources, add any teachers, classrooms, and other settings
4. Build and run the electron app to make sure the data is correct

   npm run package
   npm run appsign
   

5. Once you've confirmed everything is to your liking
6. Duplicate the whole <repodir>/dist/MEME macOS/ folder

The copied app will start with the same project data.

This is somewhat fragile in that you'd need to lock down the meme.loki and associated files to make sure you don't inadvertently change something. The eaiset method is probably to simply zip the <repodir>/dist/MEME macOS/ folder.

B. Clone the meme.loki

If you've already been refining the running meme.loki file you can also just run the packager to build the distribution files.

1. npm run electron
2. Edit any resources, add any teachers, classrooms, and other settings
3. Build and run the electron app to make sure the data is correct

   npm run package
   npm run appsign
   

4. Duplicate the whole <repodir>/dist/MEME macOS/ folder

C. Edit <repodir>/templates/meme/*.db.js files

For advanced coders, you can edit the *.db.js files directly. The easiest way here is to:

1. Copy <repodir>/templates/_blank/*.db.js to <repodir>/templates/meme/*.db.js
2. Edit the files in <repodir>/templates/meme/*.db.js
3. Build and run the electron app to make sure the data is correct
4. Duplicate the whole<repodir>/dist/MEME macOS/ folder

The copied app will then start with fresh *.db.js files on the initial build.

NOTE that any changes you make to the Electron app will then be saved in the current meme.loki file, and you can just copy those. Any changes to meme.loki will NOT be reflected in the <repodir>/templates/meme/*.db.jsfiles though -- you'll have to duplicate those changes by hand editing the *.db.js files.

---

III. Prepare Distribution Files

Here's what you need to do to prepare the combined package of the Electron app and project data for sharing to other sites.

Overview

1. Decide on a template
2. Prepare resources
3. Customize starting project
4. Package and Sign
5. Fix Quarantine Flag
6. Test Other Computers
7. Zip, Copy, and Distribute

1. Decide on a Template

Generally you would start with the __blank template. If you want to use another template, see II. Prepare Default Template for more information.

2. Prepare Resources

If you start with the _blank template, any resources already defined in /<repodir>/templates/_blank/resources/*.* will be copied over.

If you want to add additional resources add them to ``//resources/.`. During packaging, the resources will be copied over.

3. Customize Starting Project

Do an initial compile to build the meme.loki file to review the starting setup.

npm run electron
http://localhost/#/admin

Add any classrooms, teachers, student groups, and students you want to share across all copies.

Add any ratings definitions, criteria for a good model, sentence starters, and resource definitions.

If you want to add a starting demo project, login and create a model.

4. Package and Sign

npm run electron   # build the `meme.loki` file from `*.db.js` files and run Electron locally
npm run package    # build the the distribution files for `meme.app` Electron app
npm run appsign    # code sign the `meme.app`
npm run app        # or double click on `meme.app`

Run the app to make sure it looks right.

5. Fix Quarantine Flag (macOS)

In addition to codesigning, if you want to copy the Electron app to another machine, you need to run a install.sh script.

1. Build the electron app (npm run package) and copy the /dist/MEME macOS folder to your new computer/new location, e.g. to ~/Desktop/MEME macOS.
2. Open a terminal.
3. cd ~/Desktop/MEME macOS
4. ./install.sh
5. The quarantine flag should now be fixed.
6. Double click the meme.app Electron application to start the server to make sure it works.
7. If you see javascript error, then the quarantine flag was probably not removed successfully. Try typing xattr meme.app -- you should NOT see the line com.apple.quarantine
   If you copy the app to another computer you may have to run ./install.sh again.

6. Test Other Computers

Make sure everything works. Make sure you test:

• Intel Macs
• Apple Silicon Macs (M1, M2)
• Older macOS versions that you might be running on

7. Zip, Copy, and Distribute

Once everything is set you can zip the <repodir>/dist/MEME macoS/ folder and copy the zip file to another computer.

Unzip it to run it.

---

---

---

---

PR Test Instructions

Test basic paths

1. nvm use
2. npm run clean:all -- note the dist and built folders have been removed
3. npm ci
4. npm run dev -- compile to make sure it runs
5. Check http://localhost:3000 and http://localhost:3000/#/admin to make sure app loads
6. Make sure you prepped the files using the "Preparing for Electron" instructions above.
7. npm run package
8. Check boilerplate/dist/MEME macOS to make sure the electron app has been built correctly:
   • data/ -- should be empty
   • resources/ -- should be empty
   • templates/ -- should have a _blank template folder
   • LICENSE
   • LICENSE.chromium.html
   • meme.app
   • version
9. If you haven't already set up code signing, see Signing
10. Verify that you can run meme.app locally on your machine -- start the Electron app, and load http://localhost:3000/#/admin
11. npm run appsign

Test create a blank database with /templates/_blank

Try different methods of starting a new project from scratch. You should always be able to create a new blank project without any errors.

1. Test npm run dev with blank

1. Delete <repodir>/data and dist
2. Run npm run dev
3. A new test.loki file should be created in <repodir>/data/db/test.loki
4. Going to http://localhost:3000/#/admin you should see a blank project

2. Test npm run electron with blank

1. Delete <repodir>/data and dist
2. Run npm run electron
3. A new meme.loki file should be created in <repodir>/data/db/meme.loki
4. An electron app should be built and started
5. Going to http://localhost:3000/#/admin you should see a blank project

3. Test npm run app with blank

1. Delete <repodir>/data and dist

2. Run npm run app => npm should complain

   ./dist/meme-darwin-x64/meme.app: No such file or directory
   MEME EXEC    - ERROR from codesign check
   MEME EXEC    - macos will not run this app until it is signed
   

3. Run npm run package

4. Run npm run app => npm should complain

   ./dist/meme-darwin-x64/meme.app: No such file or directory
   MEME EXEC    - ERROR from codesign check
   MEME EXEC    - macos will not run this app until it is signed
   

5. Run npm run electron to build the meme.loki file.

6. Run npm run package to build with the necessary depdencies.

7. Run npm run appsign (NOTE you need to have set up code signing -- see Signing)

8. A new meme.loki file should be created in <repodir>/data/db/meme.loki

9. An electron app should be built and started

10. Going to http://localhost:3000/#/admin you should see a blank project

Test with default /templates/test template folder

Make sure that npm run dev will generate test.loki based on a starting template and that it'll fall back to templates/_blank if templates/test is not defined.

Test Blank

1. Delete <repodir>/data and dist
2. Delete /<repodir>/templates/test (if it exists)
3. npm run dev
4. The app should run with a blank project

Test test

1. Delete <repodir>/data and dist
2. Add /<repodir>/templates/test -- use the zip file attached.
3. npm run dev
4. The app should run with a test project that has three teachers added.

Test with default /templates/meme template folder

Make sure the various ways of setting a starting non-blank template work.

Test Blank

1. Delete <repodir>/data and dist
2. Delete /<repodir>/templates/meme (if it exists)
3. npm run dev
4. The app should run with a blank project

Test npm run electron with meme

1. Delete <repodir>/data and dist
2. Add /<repodir>/templates/meme -- use the zip file attached.
3. npm run electron
4. The app should run with a test project that has three teachers added.

Test npm run app with meme

1. Delete <repodir>/data and dist
2. Add /<repodir>/templates/meme -- use the zip file attached.
3. npm run electron
4. npm run package
5. npm run appsign
6. npm run app
7. The app should run with a test project that has three teachers added.

Test meme.app with meme

1. Delete <repodir>/data and dist
2. Add /<repodir>/templates/meme -- use the zip file attached.
3. npm run electron
4. npm run package
5. npm run appsign
6. Double-click meme.app to start Electron
7. The app should run with a test project that has three teachers added.

Test copy distribution

Make sure it's possible to copy the distribution files to another computer.

1. Build the electron app (npm run package) and copy the /dist/MEME macOS folder to your new computer/new location, e.g. to ~/Desktop/MEME macOS.

2. Open a terminal.

3. cd ~/Desktop/MEME macOS

4. ./install.sh

5. The quarantine flag should now be fixed.

6. Double click the meme.app Electron application to start the server.

7. If you see javascript error, then the quarantine flag was probably not removed successfully. Try typing xattr meme.app -- you should NOT see the line com.apple.quarantine
   If you copy the app to another computer you may have to run ./install.sh again.

[benloh]

Implemented with #135