-
Notifications
You must be signed in to change notification settings - Fork 4
Installing an instance of CWRC GitWriter on your own server
This tutorial guides you through the basic steps to have the default configuration of CWRC-GitWriter installed on your own server. If you want to create a new version of the CWRC-Writer that is configured to work with your own document repository, or you want to customize it in any shape or form, please consider looking at the CWRC-GitWriter GitHub repo.
This tutorial assumes a user with minimum knowledge of Javascript, Node.JS & NPM, and Unix / Linux. The steps described here were done using a remote server on Digital Ocean with Ubuntu 19.10 installed. The same instructions may work in different operating systems with minor changes.
If your server is already setup to serve files over the web (e.g., Nginx or apache) and already have Node.js and PM2 installed, jump to step 2.
To run CWRC-GitWriter on a server, you need:
- A web server manager, e.g., Nginx
- Set up an encrypt TLS/SSL certificate (optional)
- Node.js (>=12.13)
- NPM (>= 6.13)
- PM2 (Node Manager)
You may need superuser privileges to install these components
Installing a web server is out of the scope of this tutorial, but it is needed to run CWRC-GitWriter. You can find one approach to install Nginx here: https://www.digitalocean.com/community/tutorials/how-to-install-nginx-on-ubuntu-18-04
For CWRC-GitWriter work property, you need to set up a Server Block. Take a look at step 5 of previous tutorial https://www.digitalocean.com/community/tutorials/how-to-install-nginx-on-ubuntu-18-04
The code below is one approach to configure your server block.
server {
listen 80 default_server;
listen [::]:80 default_server ipv6only=on;
server_name [putYourDomainHere. e.g., example.com];
return 301 https://$server_name$request_uri;
}
server {
listen 443 ssl default_server;
server_name [putYourDomainHere. e.g., example.com;]
ssl_certificate [fullPathToSSLCertificate. E.g, /etc/letsencrypt/live/[YourDomain]/fullchain.pem]; # managed by Certbot
ssl_certificate_key [fullPathToSSLCertificateKey. E.g, /etc/letsencrypt/live/[YourDomain]/privkey.pem]; # managed by Certbot
location / {
root [fullPathToCWRC-GitWriter/build e.g., home/cwrc/CWRC-GitWriter/build];
}
location /github {
proxy_pass http://localhost:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection ‘upgrade';
proxy_set_header Host $host;
proxy_cache_bypass $http_upgrade;
}
location /schema {
proxy_pass http://localhost:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection ‘upgrade';
proxy_set_header Host $host;
proxy_cache_bypass $http_upgrade;
}
}
This approach assumes a server with TLS/SSL certificate (see below).
Please note that the locations and ports used here should match the location where you put the CWRC-GitWriter files, and the configurations on CWRC-GitServer (config.js).
sudo systemctl restart Nginx
Your web server should be ready to host CWRC-GitWriter.
Installing a TLS/SSL certificate is optional and out of the scope of this tutorial. Here is one approach to configuring your server to provide HTTPS using Let's Encrypt and Nginx: https://hackernoon.com/configuring-your-server-to-provide-https-using-lets-encrypt-and-nginx-e46a5ae93e41
This link lists different approaches for several operating systems: https://nodejs.org/en/download/package-manager/#debian-and-ubuntu-based-linux-distributions
One approach for Ubuntu:
sudo apt update
sudo apt install nodejs
sudo apt install npm
PM2 is a process manager for Node.js. Among other things, it restarts CWRC-GitWriter if it crashes for any reason.
sudo pm install pm2 -g
sudo pm2 startup systemd
The last line of the resulting output includes a command that you must run with superuser privileges.
After that, you can check if the service is working.
sudo systemctl status pm2-[user]
Before you start this part, make sure you have a web server in place with Node.js installed. See the instructions above. These are the steps we have used to install CWRC-GitServer currently running in the sandbox version of the CWRC-GitWriter:
- Copy files and Install dependencies
- Create Github oAuth
- Configure CWRC-GitServer
- Run CWRC-GitServer as a service
- Setup CWRC-GitWriter (step 3)
Clone CWRC-GitServer repository to the server, or copy the files to the server.
git clone https://github.com/cwrc/CWRC-GitServer.git
On the server switch into the CWRC-GitServer directory and run:
npm install -only=prod
(to install the npm packages on the server)
Next, you need to create an OAuth app so that CWRC-GitServer can access GitHub on behalf of the user. Follow this tutorial: https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/
Once you have the client ID and client secret for your OAuth app, you need to edit the config.js file.
On CWRC-GitServer folder, run:
nano config.js
When you are done, exit and save the file.
github_client_cors: Set to true if CWRC-GitServer is at a different origin than CWRC-GitWriter. github_client_origin: The origin for CWRC-GitWriter (used if github_client_cors is true). E.g.: http://localhost:8080 or https://[putYourDomainHere] github_client_id: The client ID for your OAuth app. github_client_secret: The client secret for your OAuth app. github_oath_callback: The URL that GitHub should redirect to after the user authorizes the OAuth app. It should lead to the github/callback route, as seen here. E.g.: http://localhost:3000/github/callback or https://[putYourDomainHere]/github/callback github_oath_callback_redirect: The URL that CWRC-GitServer should redirect to, after handling the OAuth callback. It should lead to your installation of CWRC-GitWriter. E.g.: http://localhost:8080 or https://[putYourDomainHere]
If you have not installed it yet, run (you may need superuser privileges):
sudo npm install pm2 -g
Switch into the CWRC-GitServer directory and run
pm2 start ./bin/www
You can check if the process is running:
pm2 list
Now that you have CWRC-GitServer running as a service on your web server, you can install CWRC-GitWriter.
CWRC-GitWriter contains two main files: the app file and the config file. The app file does not contain much code itself; its main purpose is to load/require other packages and then configure and instantiate the CWRC-Writer. It must first be built in order to be useable. There are two ways to handle this part:
- Build on the server
- Build locally, on your local machine, and then copy the files to the server.
If your server has Git and npm support, you can clone and build this repository directly on your server. The advantage of this approach is that it is easier to keep CWRC-GitWriter updated. You need to pull the new version from Github and build the source code.
If you cannot build on the server and prefer to do this operation locally, make sure you have Node.js and NPM installed. You can download them from Node.js official website.
Follow these steps on the server or your local machine:
- Copy files and install dependencies
- Build the source code
Clone CWRC-GitWriter repository.
git clone https://github.com/cwrc/CWRC-GitWriter.git
Switch into the CWRC-GitWriter directory and run:
npm install
(to install the npm packages on the server)
If you dont have it already, you need to install Less globally to compile CSS files. You may need superuser privileges.
sudo npm install less -g
run:
npm run build
The built code resides in the newly created build directory. It contains the app, along with all the necessary CSS, XML, and image files.
If you build on your local machine, you need to copy the build folder to your server, usually the same server from which you would serve the CWRC-GitServer.
It is advised to restart CWRC-GitServer every time you build CWRC-GitWriter
pm2 restart www
CWRC-GItWriter should be up and running on the URL and port you configured on Nginx. e.g., https://[yourDomain.com]