househunt

Househunt - A complete Go web application

After learning Go's syntax and building a few single package projects, you now want to build a web application.

However, it's daunting to start and organize your first bigger Go project:

• Where do you put your files?
• How do structure your application?
• How do you combine the different packages?
• How do you write unit and integration tests?
• .. and many more questions.

One way to learn all this this is by reading existing source code.

There are a lot of existing Go repositories out there, but most of them are not made for self-learning. They are either overwhelmingly big, too trivial or lack documentation.

This is where the househunt project comes in. Househunt is a fully featured Go web application with the explicit aim of being an example web application.

It uses the standard library where possible and is well documented.

The househunt project

Househunt will be a web app where real estate agents can post listings and house hunter can respond to them. You can find out more in this article.

The production server

You can see househunt in action at examplego.com, this is considered the production environment for the app.

Build in public

Househunt is being build in public by Willem Schots, you can follow along on Twitter.

Running househunt locally

The recommended way to run the project locally is using docker compose, this will ease management of env variable based settings.

1. Create a directory for storing the local data in the project root directory:

mkdir .localdev

1. Configure .env file based on the data in .env.sample.
2. Run docker compose up. This will build the app and run it. You should see the database migrations being triggered and the HTTP server starting up.
3. Navigate to http://localhost:8888 to see househunt in action.

Frontend development

The recommended way with the frontend locally is to first run househunt as described above.

While househunt is running at http://localhost:8888, take the following steps:

1. Run npm install --prefix assets to install all dependencies.
2. Run npm run --prefix assets dev to run the development server.
3. Navigate to http://localhost:3000 to reach the frontend server.

Apart from the requests for the Javascript and CSS bundles the frontend server forwards everything to the househunt server. In addition it injects code for:

• Hot reloads when the Javascript or CSS bundles change.
• Auto refreshes when the view files change.

The provided Docker Compose configuration always loads view files from disk, so any changes are immediately reflected without having to rebuild the container image.