Skip to main content

Setup: Local

Downloading the Code​

The codebase for An Scéalaí can be found on GitHub here. The repository includes all code for the project, including both the front and back ends. Documentation for downloading and running the code can also be found on the front page of this repository.

Setting up the project environment​

Backend​

To run the server for An Scéalaí on your local machine, you will need to have installed Node.js. Node is an open-source, cross-platform, JavaScript runtime environment that allows you to run JavaScript (or TypeScript) on your machine.

In addition to Node, you need to use npm (or yarn, or any other package manager) in order to manage third party libraries that have been added to the project. Npm does the following:

  1. Reads and understands the package.json file created using Node
  2. Downloads external JavaScript modules. These modules, or libraries, are stored in the created node_modules folder. Both the frontend and the backend of An Scéalaí have their own folder of node modules.
  3. Runs scripts mentioned in package.json. Examples of such scripts are for serving the code, running tests, etc.

External node modules are developed by the public and published to npm. Searching this library for snippets of code to integrate into An Scéalaí can save a lot of time and effort during development. These libraries can then be installed and managed using npm.

Here are a couple links to tutorials that go into detail on Node.js and npm as well as how to download and use the tools.

In addition to setting up Node, you also need to set up the sendinblue service. This service is what An Scéalaí uses for managing emails, such as verification emails when users create a new account. This tutorial goes into further detail on how this service works. Details on setting up sendinblue to work on your local machine can be found on the GitHub page. Even if you are not going to test sending emails, the backend can't run without this service having been set up.

Frontend​

The frontend of An Scéalaí is written in TypeScript/HTML/SCSS, and it is managed using the TypeScript framework Angular. Once you have Node and npm working locally on your machine, you can download the Angular CLI (via npm) to use Angular tools for frontend development. The Install the Angular CLI section of this tutorial lists the steps required to install the CLI to your machine. The CLI, or command-line interpreter, lets you use the Angular framework from the shell. Details on using Angular for An Scéalaí can be found in this doc.

Gramadoir-ts​

We also have a private node package for grammar checking, hosted on phonlab-tcd's GitHub packages. In order to install this, you'll need to be part of the phonlab-tcd organization – you can ask someone at the lab to add your GitHub account to this group. Once you've been added, you can then follow this tutorial on authenticating for GitHub package installation – in short, you’ll need to provide a secret token to identify your GitHub account, which will give you permission to install the package. Feel free to email me at oinolan@tcd.ie if you have any trouble with this.

To use this package you must be a member of the phonlab-tcd GitHub organization. To authenticate you can put a GitHub Personal Access Token (PAT) in the ./ngapp/.npmrc file in this format:

Note: use a GitHub classic PAT and make sure it has the “read:packages” permission.

//npm.pkg.github.com/:_authToken=TOKEN

Database​

The database for An Scéalaí is the NoSQL database MongoDB. Since this database is stored on the Abair server and is used solely for the hosted website, you can create a local database for testing and development purposes. Any writes or reads that you make during development will only be from this local database and won’t interfere with the database for the actual project.

Instructions for setting up a local DB for development can be found on the GitHub page.

Running the code locally​

Once the environment is set up and the repository is downloaded, the code can then be hosted on your local machine. Currently, both the backend and the frontend of the application have to be run individually.

Backend​

From the command line, navigate to An-Scealai/api.

  • Install any node modules: npm i
  • Run the following command: npm run start:nocheck

(This command uses Node to run the server.js file while ignoring any tests. To run the tests as well, leave off the :nocheck part of the command.)

Frontend​

From a new tab in the command line, navigate to An-Scealai/ngapp.

  • Install any node modules: npm i
  • Run the following command: npm start
  • After initial setup, this command only needs to be run if new packages have been added/removed.
  • Alternative ways for running the code (such as using tmux) can be found on the GitHub page.

Once the backend and frontend of the project are running with no errors, you can navigate to http://localhost:4200/ in your browser to view the application.

Version Control: Using Git​

An Scéalaí uses GitHub for storing the code, version control, and general project management. Once your personal GitHub account has been added to the repository as a collaborator, you will be able to make changes to the codebase. Here are the official docs that go into detail on using Git and GitHub. A more beginner-friendly tutorial can be found here. It is very important to know how these tools work in order to contribute to An Scéalaí.

Making changes to the code​

The main code that is served on the Abair server is found on the master branch. Ideally, this branch has no errors and is not used for experimentation. Once new features are added and tested elsewhere, they can then be merged into this branch, which are then made live on the server. This process is carried out by using Pull Requests. Therefore, the following steps should be taken when making changes to the codebase:

  1. Create a new branch where you are going to make all of your edits. (This branch can be derived from master or any other branch already opened)
  2. Commit and push any changes to this branch until you are ready to merge it into the main codebase
  3. Raise a pull request (PR) for your branch. Once a PR has been made, any other collaborator on the project can view the changes in the code and give a review. It is good practice to give a decent description with screenshots or pictures in your PR so others can understand your changes. You can still push new code and make edits to this branch even after the PR has been raised.
  4. The PR will indicate if your branch has any conflicts with the master branch. If so, you can fix these conflicts either on GitHub directly or from the command line.
  5. Once there are no conflicts and the rest of the team is happy with the changes, you can merge this branch into master. The PR is then closed.

Given the modularity of branches and pull requests, you can have several branches open at any given time to work on different features without worrying that the changes will interfere with each other or the main codebase. This allows for isolating features and issues.

GitHub Issues​

The GitHub issues section of the repository lists not only bugs in the code, but also serves as a running TODO list for the project. After creating a new issue, you can give it labels such as bug, enhancement, etc. to categorize the item. You can also assign certain developers to the issues so you can keep track of who is working on what. Finally, you can also create a new branch directly from the issue. When this branch is closed, the issue is automatically closed as well.