You must have a working Go and Node.js installation in order to run this project.
If you are new to developing with tools (or new in general), consider installing with your system's package manager when possible. Please ensure your language and runtime versions match the ones below.
- go version 1.9 [install] - For running the webserver for the backend
Make sure you have a
GOHOMEdirectory set up
- dep - Dependency manager for go - install with
go get -u github.com/golang/dep/cmd/depafter go is working
- Node.js version 8.9.4 [download] - Used to build and run the frontend in development
- yarn [install] - Dependency manager for Node.js (use
npmat your own risk!)
- Postgres - Relational database used as our primary datastore
Optional: If you are working on the backend, install
go get github.com/codegangsta/gin) for live-reloading capabilities.
This is a (semi-opinionated) guide to getting started with these tools and languages on MacOS.
"Package managers are great! Use them!" - Andrew Dai Feb 15 2018
To follow along, setup homebrew if you have not already.
We will be installing all the tools in the previous section with
another package/version manager whenever possible.
# Install go with homebrew brew install go # You might need to setup certain environment variables for go to work. # Do that now. # See go's install documentation # (and also look for resources for go with homebrew and MacOS) # Install the dep dependency manager for go go get -u github.com/golang/dep/cmd/dep # (Optional tool for backend development) go get github.com/codegangsta/gin # Check if dep was installed properly (and your go setup) dep version # Outputs the version and build information # Install n, a node version manager brew install n # Install Node.js 8.9.4 (currently LTS version we are using) n 8.9.4 # Install yarn with homebrew brew install yarn --without-node # Install Postgres.app with homebrew cask (open the App) brew cask install postgres # Find and open the Postgres app in your Applications folder
n is a version manager for Node.js and makes it very easy to switch versions painlessly.
It is highly recommended to use a tool like this to install and run different versions of Node.js.
n 8.9.4 installs Node.js version 8.9.4 and sets it as the current version.
You can confirm with
go env is very helpful in debugging go environment variables.
Get the source code:
go get github.com/HackGT/SponsorshipPortal
You may get an error
no buildable Go source files; this is harmless.
For development work run the frontend and backend separately.
Install frontend dependencies:
# from project root cd client yarn
Install backend dependencies:
# from project root dep ensure
Make sure that PG_URL contains the connection string SponsorshipPortal will use to connect to Postgres.
NOTE: The golang library
sslmode defaults to
require which may cause issues if you do not
have SSL configured. This may not be an issue on
# connect as default user (`postgres`) to default database with sslmode disabled export PG_URL="postgres://postgres@localhost:5432/?sslmode=disable" # connect as `portal` user with password `secret` # to `dev` database with ssl disabled export PG_URL="postgres://portal:secret@localhost:5432/dev?sslmode=disable" # same connection as above in an alternate form # (this will work but not be parsed correctly by `config/config.go`) export PG_URL="host=localhost port=5432 user=portal password=secret sslmode=disable"
More information and examples on Postgres docs
Generate ECDSA Key Pair
The backend is currently configured to use secp521r1. First, download and install OpenSSL if you do not already have it (most flavors of Linux come with OpenSSL):
sudo apt install openssl
Navigate to your working directory for the SponsorshipPortal and generate your secp521r1 key pair:
openssl ecparam -name secp521r1 -out secp521r1.pem openssl ecparam -in secp521r1.pem -genkey -noout -out ecprivatekey.pem openssl ec -in ecprivatekey.pem -pubout -out ecpublickey.pem
Once you have your key pair, set the
EC_PUBLIC_KEY environment variables to the contents of ecprivatekey.pem and ecpublickey.pem respectively.
Start the app!
Run the database migrations (see
migrations/README.md for more info)
go run main.go --migrate # or if you do not want to set PG_URL for the current session PG_URL="<connection string>" go run main.go --migrate
Start the backend
# from project root go run main.go # if you are working on the backend and have gin installed # (go get github.com/codegangsta/gin) gin run main.go # or set PG_URL for the command and run PG_URL="<connection string>" go run main.go # also works with `gin` PG_URL="<connection string>" gin run main.go
Then, in a new shell, start the frontend and navigate to
# from project root cd frontend npm start
Building and running
Build the front-end
# build frontend # from project root... cd frontend npm run build
Build and run the server
# build backend # from project root... go build . # set connection string # run migrations and start server export PG_URL="<connection string>" ./SponsorshipPortal --migrate ./SponsorshipPortal
The frontend is a standard React (https://reactjs.org/) app with Redux for state management.
If you are working only on the backend or the frontend, you can build (and start)
the other part and leave it running while you do your development.
Example: build the frontend and then build and run the backend with
reloads. See above instructions on how to build each part.
The directory structure:
main.go Boot script for the server routes.go Register non-controller routes go here server.go Initialize server and setup components Gopkg.toml Gopkg.lock config/ App server config package controllers/ App controllers go here controller.go Root controller, register other controllers here database/ Utility package for initializing a database connection from config logger/ Utility package for initializing a logger from loaded config models/ App models go here migrations/ Database migrations (sql scripts) go here client/ Front-end project root package.json yarn.lock src/ Source code for React app static/ Public static assets - this is not used in development node_modules/ Dependencies, do not edit this directory - managed by yarn vendor/ Dependencies, do not edit this directory - managed by dep