nusorbital

Setup Instructions

NOTE: The $ sign that comes before a line of code denotes the prompt, and should not be copied and pasted as part of the command.

Create .env and .air.conf

In the project root directory are .env.default and .air.conf.sample files. They will serve as the file templates for the .env file and the .air.conf file.

• Make a copy of .env.default as .env. You should only have to change DATABASE_URL, GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET. More on those later.
• Make a copy .air.conf.sample as .air.conf.
  • Windows Users: You will have to change all occurrences of 'main' to 'main.exe' inside .air.conf file (under 'cmd' and 'bin')
• TODO: maybe switch from air to modd for live reload instead?

Get OAuth2 credentials

1. Obtain Google Oauth2 Client ID and Client Secret from here.
   • Add the following authorized redirect urls to the oauth2 credential in your google api credential console.

   http://localhost:8080/join/callback
   http://localhost:8080/login/callback
   

   • Update GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET in .env accordingly.

PostgreSQL Server Setup

You will not be running the postgres database directly in your computer, but rather in a Virtualbox VM. The reason is because we need the plpgsql_check extension but it is heinously difficult to compile postgres extensions on Windows.

1. Install Virtualbox.
2. Download the latest Ubuntu ISO.
3. Setup a new Virtualbox VM with the Ubuntu ISO.
   • 2GB RAM & 8GB Disk, dynamically allocated. Adjust RAM and Disk sizes to taste.
   • username: pg, password: pg. Or use any username/ password you wish, just remember it.
4. Boot into the VM and install the Virtualbox guest additions. Restart if necessary.
5. Inside the VM, open a terminal and run this command. It will download the ubuntu-postgres-bootstrap.sh install script that installs postgres as well as the plpgsql_check postgres extension. It creates a user called 'pg' with password 'pg' and a database 'skylab_dev'.

$ wget https://raw.githubusercontent.com/nusorbital/nusorbital/master/cmd/ubuntu-postgres-bootstrap.sh && chmod +x ubuntu-postgres-bootstrap.sh && ./ubuntu-postgres-bootstrap.sh

1. Setup port forwarding for the Virtualbox VM. The default port that postgres runs on the Guest VM is port 5432, but we will be forwarding the Guest VM's 5432 port to the Host OS's 5433 port (so as not to clobber the Host's own 5432 port reserved for its local postgres database). The VM postgres should be then accessible via localhost:5433 on your own machine (the Host machine).
   • Settings > Network (you should see Adapter 1, NAT) > Advanced > Port Forwarding
   • Then add a new rule. Name: postgres (you can name it anything), Protocol: TCP, Host IP: <blank>, Host Post: 5433, Guest IP: <blank>, Guest Port: 5432
2. Run the following commands in a terminal in the Ubuntu VM.
   • sudo vim /etc/postgresql/*/main/postgresql.conf
     • Find the line in postgresql.conf with listen_addresses = 'localhost', uncomment that and change it to listen_addresses = '*'
   • sudo vim /etc/postgresql/*/main/pg_hba.conf
     • Find the line in pg_hba.conf under the IPV4 section and change the line to: host all all all md5
   • Restart the postgres server for the config changes to take effect
     • sudo systemctl restart postgresql
     • Check that it restarted successfully: sudo systemctl status postgresql

PostgreSQL Client Setup

Although we have installed the postgres in a VM, we still need to install postgres locally in order to be able to connect to the postgres in the VM using psql. Below are instructions for ensuring you have a executable psql command in Command Prompt/Terminal.app/etc.

Windows

1. Install the latest version of Postgres. Also include the Command Line Tools (i.e. psql) and pgAdmin.
   • During install, you will be prompted to set a password for the default 'postgres' user. Make sure to note it down as you will need it in pgAdmin.
2. Once installed, check that you can access the psql command by opening a Command Prompt window and running psql --help.

If you get an error like below, it means that psql was not installed successfully.

'psql' is not recognized as an internal or external command, operable program or batch file.

Check if psql.exe is in your computer in the following directory: C:\Program Files\PostgreSQL\<postgres version>\bin. If you installed a 32-bit version of postgres, check C:\Program Files (x86)\PostgreSQL\<postgres version>\bin instead. If psql.exe is there, it means that C:\Program Files\PostgreSQL\<postgres version>\bin is not in your PATH (a list of directories that windows searches in when you run a program from the command line). Follow this tutorial for adding to your PATH and add the directory C:\Program Files\PostgreSQL\<postgres version>\bin. You will have to restart your computer for PATH changes to take effect. Once restarted, try running psql --help again.

macOS

1. brew install postgresql
2. Install pgAdmin.

Can you connect to the database?

The connection string

In general, a url string is all you need to specify in order to connect to a postgres database. The url string takes the following format:

postgres://<username>:<password>@<host>:<port>/<database name>?<options>

Connecting to the database from inside the VM

First, try to connect to the database directly from inside the VM. Run this command in a terminal inside the Ubuntu VM

# run this -INSIDE- the Ubuntu VM
$ psql postgres://pg:pg@localhost:5432/skylab_dev?sslmode=disable

If that works, it means the database is up and running. Next, try to connect to the database from outside the Ubuntu VM.

Connecting to the database from outside the VM

Since you port forwarded the VM port 5432 to the Host port 5433, you will try to connect to the same connection url from the outside but on port 5433 instead. Run the following command from Command Prompt/ Terminal.app/ etc

# run this -OUTSIDE- the Ubuntu VM, in cmd.exe/ Terminal.app/ etc
$ psql postgres://pg:pg@localhost:5433/skylab_dev?sslmode=disable

if you get an error psql: error: could not connect to server: could not receive data from server: Software caused connection abort (0x00002745/10053) check if you finished steps 6 and 7 for the PostgreSQL Server Setup.

Connecting to the database from pgAdmin

Although you can use psql to interface with the database, a more user friendly option would be to do it from a GUI interface like pgAdmin instead. Here are the steps for setting it up.

1. Make sure you have already downloaded pgAdmin and open it. It will ask you for the password of the 'postgres' user, which you have already noted down in step 1 of the PostgreSQL Client Setup.
2. From the navbar, select Object > Create > Server. A server setup window will appear.
   • In the General tab:
     • Fill in 'Name' with 'orbital_dev'. It can also be any name you want.
   • In the Connection tab:
     • Fill in 'Host name/address' with '127.0.0.1'. That is a synonym for 'localhost'. Take note that 'localhost' will not work here, it has to be '127.0.0.1'.
     • Fill in 'Port' with '5433'
     • Leave 'Maintenance database' as 'postgres'
     • Fill in 'Username' with 'pg'
     • Fill in 'Password' with 'pg'
     • You can tick 'Save Password?' if you want
   • In the SSL tab:
     • Change 'SSL mode' to 'Disable'
   • You can leave the other tabs alone. Press 'Save'.
3. Check that you can connect to the database under 'orbital_dev'.

Make sure the database url is inside the .env file

1. If there isn't an .env file in the project root, create one. If creating the .env file, also copy the contents of .env.default into .env.
2. Inside .env, ensure the line with DATABASE_URL= has the correct database url.

Node setup

Install node and npm

Follow the platform-specific instructions at https://nodejs.org/en/download. If you want to use a package manager like homebrew or apt-get instead, go ahead. At the end of the installation, make sure you can run the npm command in your command prompt/terminal.

All commands should be run from the project root directory.

Install npm packages

$ npm install

Build the tailwind.css file with tailwindcss command

# Windows
$ node_modules\.bin\tailwind.cmd build .\static\base.css -o .\static\tailwind.css

# macOS
$ node_modules\.bin\tailwind build ./static/base.css -o ./static/tailwind.css

Build the javascript files with webpack

# Windows
$ node_modules\.bin\webpack-cli.cmd --mode=development

# macOS
$ node_modules/.bin/webpack-cli --mode=development

Webpack should build a bunch of files into the static/ directory.

Go setup

Follow the platform-specific instructions at https://golang.org/dl/. At the end of the installation, make sure you can run the go command in your command prompt/terminal.

Use an IDE like GoLand with your free student license from JetBrains. Or use vim. Or vscode.

All commands should be run from the project root directory.

sqload

sqload is a user-written helper program that populates the database with dummy data. You can view the source code in cmd/sqload/main.go.

# Windows
go build -o sqload.exe .\cmd\sqload\main.go

# macOS
go build -o sqload ./cmd/sqload/main.go

Once compiled, you should have a sqload.exe/sqload binary in the project root directory. Populate the database by running .\sqload.exe or ./sqload. Then, check the number of tables in the database with this command

# works in both Windows (use Powershell for this) and macOS
echo '\dtv' | psql postgres://pg:pg@localhost:5433/skylab_dev?sslmode=disable

Delve

$ go get -u github.com/go-delve/delve/cmd/dlv
$ sudo /usr/sbin/DevToolsSecurity -enable # macOS only

Air

Install air for live-reloading your go app without manually recompiling

# Windows (use Powershell for this)
(New-Object System.Net.WebClient).DownloadFile('https://raw.githubusercontent.com/cosmtrek/air/master/bin/windows/air.exe', "$(Get-Location)\air.exe")

# macOS
$ curl -fLo "$PWD/air" https://raw.githubusercontent.com/cosmtrek/air/master/bin/darwin/air && chmod a+x "$PWD/air"

Putting it all together

At this point you should have

• A .env file with a valid database url (that you can access using psql)
• A tailwind.css file in the static/ directory (generated using tailwindcss)
• A populated database using sqload
• An air.exe/air binary that you downloaded into the project root directory

Start the server

# Windows
.\air.exe

# macOS
./air

Start webpack --watch

# Windows
$ node_modules\.bin\webpack-cli.cmd --mode=development --watch

# macOS
$ node_modules/.bin/webpack-cli --mode=development --watch

• cd $GOPATH/src/github.com/golang-migrate/migrate/cmd/migrate && go install