A tile-based word-forming game based on the popular Banagrams game. https://bananagrams.com/games/bananagrams
With WebSockets, users can play a word game together over a network.
Uses WebAssembly to manage browser logic.
A small database can be used to store user account names, encrypted passwords, and points. Users get ten points for each game won and one point when they are beaten by someone else. Users must use either a Postgres, Mongo, or Firestore database.
New dependencies are automatically added to go.mod when the project is built.
- pq provides the Postgres database driver for storing user passwords and points
- mongo-driver provides the Mongodb database driver for storing user passwords and points
- firestore provides the firestore database driver for storing user passwords and points
- Gorilla WebSocket are used for bidirectional communication between users and the server
- jwt is used for stateless web sessions
- crypto is used to encrypt passwords with bcrypt
- Font-Awesome provides the "copyright", "github," "linkedin", and "gavel" icons on the about page; they were copied from version 5.13.0 to resources/template/fa.
-
Run
make serve
to build and run the application. -
Run
make serve-tcp
to build and run on port 80 for HTTP and port 443 for HTTPS (default TCP ports). Using these ports requiressudo
(root) access.
Go 1.18 is used to build the application.
Make is used to by Makefile to build and runs the application. Run make
without any arguments to build the server with the client and other resources embedded in it. This will likely need to be done before using an IDE in order to generate some files and populate the embedded filesystem used by the the server.
Aspell is used to generate the en_US dictionary to validate words on player boards.
- Note: An integration test depends on aspell-en 2020.12.07-0. This version is used by Docker. Follow the steps below to install the version on your computer:
- Download https://ftp.gnu.org/gnu/aspell/dict/en/aspell6-en-2020.12.07-0.tar.bz2
- unzip the archive with
tar -xf aspell6-en-2020.12.07-0.tar.bz2
- configure and install it:
cd aspell6-en-2020.12.07-0 ./configure make sudo make install
Node is needed to run WebAssembly tests.
Launching the application with Docker requires minimal configuration.
- Install docker-compose
- Set environment variables in the
.env
file in project root (next to Dockerfile).PORT=8000 NO_TLS_REDIRECT=true HTTP_PORT=8001 HTTPS_PORT=8000 DATABASE_URL=postgres://selene:selene123@127.0.0.1:5432/selene_bananas_db POSTGRES_DB=selene_bananas_db POSTGRES_USER=selene POSTGRES_PASSWORD=selene123 POSTGRES_PORT=54320
Optionally, start database first:
-
Run
docker-compose up postgres-db
to launch a Postgres database in docker. To run a mongo database, rundocker-compose up mongo-db
after changing theDATABASE_URL
tomongodb://selene-bananas-db-mongo:27017/
indocker-compose.yml
file. -
Run
docker-compose up --build web
to launch the application, rebuilding parts of it that are stale. -
Access application by opening http://127.0.0.1:8000. TLS certificates will be copied to Docker. Environment variables are used from the
.env
file. -
Run
docker-compose down
after running the application to ensure the web database servers shut down.
To run a Mongo database instead of Postgres, make the following changes:
- In
docker-compose.yml
: change the line afterdepends-on:
frompostgres-db:
tomongo-db:
- In
.env
: setDATABASE_URL
tomongodb://127.0.0.1:27017/
To run using a cloud firestore database, remove the depends-on:
section and change the DATABASE_URL
environment variable as described above to be like firestore://PROJECT_ID
Environment variables in the .env
file are needed to customize the server.
Minimal config:
PORT=8000
NO_TLS_REDIRECT=true
For development, set CACHE_SECONDS
to 0
to not cache static and template resources.
Optionally, the app stores user information in either a a Postgresql, Mongodb, or Firestore database. The database to use is specified by the DATABASE_URL
environment argument. When the app starts, the database is initialized. For SQL databases, files in the resources/sql folder are run to ensure database objects functions are fresh.
- The computer must be authenticated for the projectID by running the command
gcloud auth application-default login
- A Firestore connection is made when
DATABASE_URL
is similar tofirestore://PROJECT_ID
.
A Mongo database is very easy to set up when using the docker image.
- Run
docker-compose up --build mongo-db
to start the database in a terminal. - Run the following command to query the database in a terminal:
docker exec -it selene-bananas-db-mongo mongo
- Set the
DATABASE_URL
environment variable tomongodb://127.0.0.1:27017/
before starting the web server to connect to the local mongo server.
A Postgresql database can be created with the command below. Change the PGUSER
and PGPASSWORD
variables. The command requires administrator access.
PGDATABASE="selene_bananas_db" \
PGUSER="selene" \
PGPASSWORD="selene123" \
PGHOSTADDR="127.0.0.1" \
PGPORT="5432" \
sh -c ' \
sudo -u postgres psql \
-c "CREATE DATABASE $PGDATABASE" \
-c "CREATE USER $PGUSER WITH ENCRYPTED PASSWORD '"'"'$PGPASSWORD'"'"'" \
-c "GRANT ALL PRIVILEGES ON DATABASE $PGDATABASE TO $PGUSER" \
&& echo DATABASE_URL=postgres://$PGUSER:$PGPASSWORD@$PGHOSTADDR:$PGPORT/$PGDATABASE'
The app can be run on HTTP over TLS (HTTPS). If running on TLS, most HTTP requests are redirected to HTTPS.
If the server handles HTTPS by providing its own certificate, use the PORT variable to specify the HTTPS port. When POST is defined, no HTTP server will be started from HTTP_PORT and certificates are not read. Use this in combination weth NO_TLS_REDIRECT=true
to prevent the server trying to check the TLS headers on requests.
Use mkcert to configure a development machine to accept local certificates.
go get github.com/FiloSottile/mkcert
mkcert -install
Generate certificates for localhost at 127.0.0.1
mkcert 127.0.0.1
Then, replace the resources/tls-cert.pem
and resources/tls-key.pem
files with the certificates. Update the .env
file with the parameters below. Make sure to remove the PORT
variable, if present.
HTTP_PORT=8001
HTTPS_PORT=8000
The server can verify its identity over HTTP to pass a Automatic Certificate Management Environment (ACME) HTTP-01 challenge. Using a local certificate generated in the previous step by mkcert, add the ACME environment parameters listed below with necessary values to the .env
file. This makes the HTTP server respond to challenge requests correctly. After the certificates are created, remove the ACME_* parameter and replace the resources/tls-cert.pem
and resources/tls-key.pem
files with the certificates. See letsencrypt.org for more information about challenges.
ACME_CHALLENGE_TOKEN=token123
ACME_CHALLENGE_KEY=s3cr3t_key