Skip to content

Commit

Permalink
WIP Update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@tobiasnteireho
tobiasnteireho authored Dec 20, 2023
1 parent 592a44b commit 1b7c65d
Showing 1 changed file with 34 additions and 103 deletions.
137 changes: 34 additions & 103 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,9 @@ Before following the instructions for setup below. It is assumed that you have
- Currently only node 16 is supported. You must have nodejs and npm installed on your system for these instructions to work
- According to John, you cannot run this on Windows machines at all due to the path length limitation of 256 characters. This is actually a limitation of the Windows API, not the NTFS file system, but it makes it almost impossible to work on reasonably complex javascript projects on Windows.

A2J Author currently requires an *AMP stack (Apache, MySQL, PHP) to be running. For local development on non-linux environments CALI uses MAMP. Make sure to update MAMP's webroot setting to the proper directory. See the [wiki](./wiki/Dev Environment MAMP.md) document for more details on setting up a MAMP environment.

For production, in addition to the above, A2J Author requires a functional drupal 7 environment. A basic installation can be performed by following the directions [here](https://www.drupal.org/docs/7/install/step-1-download-and-extract-drupal)

## To setup:

Expand All @@ -35,9 +38,12 @@ node dependencies from the root folder of the app by running the following comma



## To build the server code:
## To build the main application:

From the root folder (`a2jauthor/`) run
1.) clone the repo as a subfolder in the root of the drupal install


2.) From the root folder (`a2jauthor/`) run
```
$ npm run deploy
```
Expand All @@ -55,32 +61,48 @@ $ npm test

There are two

### Server Configuration
### Server Configuration: config.json

In production mode, the server uses a configuration file called `config.json`
that is expected to be in the parent directory of the folder where the git repo
is cloned. This file should have the following structure:
```
{
"isProductionServer": true,
"LOCAL_USER": "45",
"SERVER_URL": "http://bitovi.a2jauthor.org/",
"GUIDES_DIR": "f:/www/caja.cali.org/caja/userfiles/",
"GUIDES_DIR": "/www/caja.cali.org/caja/userfiles/",
"GUIDES_URL": "/caja/userfiles/",
"SQL_HOST": "localhost",
"SQL_USERNAME": "z",
"SQL_PASSWD": "z",
"SQL_DBNAME": "caja",
"SQL_USERNAME": "SQL USERNAME",
"SQL_PASSWD": "SQL PASSWD",
"SQL_DBNAME": "SQL DBNAME",
"SQL_PORT": 3356,
"DRUPAL_HOST": "localhost",
"DRUPAL_USERNAME": "z",
"DRUPAL_PASSWD": "z",
"DRUPAL_DBNAME": "D7commons",
"DRUPAL_USERNAME": "DRUPAL USERNAME",
"DRUPAL_PASSWD": "DRUPAL PASSWD",
"DRUPAL_DBNAME": "DRUPAL DBNAME",
"DRUPAL_PORT": 3356
"VIEWER_PATH": "/path/to/viewer/a2j-viewer/viewer",
"WKHTMLTOPDF_PATH": "/usr/bin/local/wkhtmltopdf",
"WKHTMLTOPDF_DPI": 300,
"WKHTMLTOPDF_ZOOM": 1.6711
}
```
The SERVER_URL and GUIDES_DIR properties are used by the Node server, but
this file will also be used by CONFIG.PHP, which also uses the database
The `SERVER_URL` and `GUIDES_DIR` properties are used by the Node server, but
this file will also be used by `CONFIG.PHP`, which also uses the database
connection information.

`GUIDES_DIR` must be web accessible
`isProductionServer` is optional for production

### Server Configuration: config_env.ini
config_env.ini is used to setup allowed file types, analytics, and a2j.org




### Debugging the server:

Prepend any of the `npm` commands above with `DEBUG=A2J:*`
Expand All @@ -102,13 +124,6 @@ and go to [http://localhost:3000/js/author/index.production.html](http://localho
or [http://localhost:3000/js/viewer/index.production.html](http://localhost:3000/js/viewer/index.production.html)


### Keep in mind when setting a production environment:

You need to make sure `author/index.production.html` and `viewer/index.production.html` are loaded instead of `author/index.html` and `viewer/index.html` because the latter will load the development files one by one even if you follow the instructions to build the app.

The simplest way to accomplish this is to rename `author/index.html` to something like `author/index.dev.html` and then rename `author/index.production.html` to `author/index.html` (same thing should be done to the viewer index file).


## To run client tests:

```
Expand All @@ -118,87 +133,3 @@ $ npm test
or, if your local server is running (you ran `npm start` before) you can run tests in your browser
by loading [http://localhost:3000/js/author/test/](http://localhost:3000/js/author/test/) or
[http://localhost:3000/js/viewer/test/](http://localhost:3000/js/viewer/test/)


## To generate the viewer app distributable files:

From the root folder (`CAJA`) run the following command:

```
$ npm run build:viewer-zip
```

That will build the viewer app and it will create a ZIP file located in the same
directory where the repo folder is located, that ZIP file will contain the built
app along with some other files needed to run the standalone viewer app in a
production environment.


## Documentation
*Note: these commands should run in the `CAJA/js` directory.*

To build the documentation *and* update the documentjs template, run:

```
$ npm run build-docs
```

To build the documentation and view the documentation, run:

```
$ npm run serve-docs
```

The documentation site should be running at `http://localhost:8080`.

## To deploy the author (and viewer) app

There is a deploy script available in the `deploy` folder, it basically sets up
an ssh connection to a remote server and executes the commands to make sure the
minified scripts along with other assets and files required to run the app in a
production environment are copied over to the remote server.

Before you run that bash script, you need to provide some configuration options,
for that open in a text editor the file `deploy.conf`, let's say you have a staging
environment hosted at `staging.a2jauthor.org`, your username in that server is `jmayer`
and you'd like to use the following path `/home/jmayer/public_html/CAJA` to locate
the app assets. Your `deploy.conf` would look like this:

```
[staging]
user jmayer
host staging.a2jauthor.org
path /home/jmayer/public_html/CAJA
needs_tty yes
```

With that in place, you just need to run in your terminal the following command:

```
$ ./deploy/deploy.sh staging
```

By default, the deploy script will build the app, run the tests and continue to
deploy the files to the host server if everything went well. You can skip the build
process or the tests, if you want to take a look at the available options, just run:

```
$ ./deploy/deploy.sh -h
```

The deployment configuration file also allows you to set up commands to be executed
before and/or after the deployment is done, if for instance you want to restart
all of the NodeJS apps running in the staging environment mentioned above after the
deployment has been completed (assuming you're using [`pm2`](https://github.com/Unitech/pm2)
as your NodeJS process manager), you just need to change your `deploy.conf` to
look like this:

```
[staging]
user jmayer
host staging.a2jauthor.org
path /home/jmayer/public_html/CAJA
needs_tty yes
post-deploy pm2 restart all
```
and you're done!

0 comments on commit 1b7c65d

Please sign in to comment.