✨ Starting a new project

When you start a new project, there are a few one-time steps you must take. These include copying the current version of the 🫠 Smile project, adjusting the configuration settings for your project, and running a setup script.

Don't worry it is easy and most of it you only do once!

Customize this page!

To prevent typo errors you can enter the key details of your project here and the example commands below will be adapted for your situation allowing you to simply cut and paste without modifying the commands. This also give some recommendations. Things throughout this page will update as you type, nothing is stored.

GitHub username Enter your GitHub user name here.
Base Github repo If in gureckislab then default to `nyuccl/smile` otherwise, it is the base smile repo for your lab (e.g, `hartleylab/smile`).
Project name We highly recommend you use underscores for spaces and name your project based on the science (e.g., `question_asking`).
Description Provide a one sentence description of your experiment.

1. Copy over the basic project

Set your current working directory to where you would like to place your files. For example, on Mac this might be your desktop

cd ~/Desktop

Following the steps below, copy the Smile GitHub repo into a new project name and clone it locally.

In this example command, the new project will be named my_cool_project, using the NYU CCL Smile GitHub repo as a template.

Note: if your lab has already been set up, you will likely use your lab's copy of the Smile GitHub repo as a template (e.g., hartleylab/smile).

gh repo create my_cool_project --private --template nyuccl/smile

Then clone that project to a local folder with the same name:

gh repo clone ghuser/my_cool_project

Next, alter the Github description for your new repo:

gh repo edit ghuser/my_cool_project --description "my new research project"

After this you can visit GitHub and you should see a new repo in your personal repositories list: http://github.com/ghuser/my_cool_project

Finally change into the newly created project directory (assuming you called your project my_cool_project):

cd my_cool_project

2. Configure your project

If your lab has already been set up, then you simply need to decrypt the files provided in the repository. You can find more information on the configuration settings and options here, but this is optional.

Warning!

This will only work if you have first sent your lab coordinator your gpg key and waited for them to push a change to the 🫠 Smile repo. See instructions here.

To decrypt the organization files, simply type:

git secret reveal

This should create several .env.*.local files in your env/ directory.

Only on first setup: After all the necessary files are in the env folder run:

npm run upload_config

to configure your deployment process, remove some files you do not need, and create an initial deployment/commit. The npm run upload_config command only needs to be run once in your project the first time you create it. If you are collaborating with someone on an existing project you only need to run git secret reveal.

Error handling

In case of error, retry the process of adding a new user.

3. Setup the project

Next run the npm run setup_project command:

npm run setup_project

This will install the required node packages for local development and testing.

4. Verify the deployment

If you have properly configured your application then you should be able to create an initial deployment. Simply run

npm run force_deploy

to create a deployment given the current code in github. In the future, deployments will happen automatically anytime you make a push to your repo.

If your lab coordinator set up the slack features of your base project then join the #smile-deploy slack channel for your lab. A robot 🤖 there will let you know that your project was deployed and provide you with a web link to live site.

If that didn't happen/work then continue reading to learn more about deployments including debugging tips.

From here on out any time you make a change to any file (except in the docs/ folder or a few specifically named branches), commit it, and push that change to your project repository the Slack bot will confirm your code has been uploaded to the live webserver and is theoretically ready for participants.

5. Begin developing!

Next you can begin testing and developing your app!

Simply type

npm run dev

to run the development server and see the current, default setup of the site. More information about developing is available here.