LinkLetter is meant to be a small, self contained, web application that allows groups to collaborate and share interesting articles and links through an automated emailing system.
While this is far from a complete listing (mostly because I'm slightly afraid of having to keep it up-to-date), here's a brief description of some parts of the project structure
LinkLetter
|
| main.go : The main executable for LinkLetter. The entry point for the Go compiler
| .travis.yml : Defines what should happen on Travis CI on commits
| Procfile : Heroku configuration
|
| vendor/ : Go dependencies for the application, created using [Godep](https://github.com/tools/godep) (see below)
| templates/ : Templates, following the built in Go html/template format, for HTML pages. Filenames should follow the format [template_name].tmpl
| static/ : All purpose static folder for the web application. ***Everything in here get's exposed publicly by the web server so be thoughtful about what you put in here***
| migrations/ : Container for SQL files to be executed to create and migrate the database. Filename should follow the format "[number]_[description].sql". Files will be executed in increasing numerical order (if files share the same "number", it's indeterminant which will execute first). Actual logic to run all of this is in the application code (currently in database/migrate.go)
|
| mangage/ : A set of scripts to assist in getting started and using LinkLetter
| |
| | setup-database : Attempts to install and setup a Docker image of postgres on OSX. Should be taken with a grain of salt and I expect it has several issues
| | test : Executes tests as they'll run on Travis CI (essentially, ignoring vendor tests)
| | prepare-commit : Assists in making sure everything is in order before committing. Currently it installs and runs Godep to make sure all required dependencies are properly vendored and runs the manage/test script to test if there's any tests broken.
The other folders are most likely just Go source code. Having all the source code be in the top level along with non source folders feels incredibly dirty and should be cleaned up but unfortunatly, here, my knowlede of Go is lacking. It seems like moving all the source code into a folder like "src" would mean, due to Go's packaging conventions that the package namepace would become github.com/cj-dimaggio/LinkLetter/src, which seems dirty too.
The actual development of this application is meant to be a fun, collabroative effort. As such, attempts should be made to keep the barrier of entry to getting setup as low as possible.
| Dependency | Function/Reasoning |
|---|---|
| Go | Used as the main programming language for the web application. Chosen for being, relatively, lightweight and fast, statically compiled (allowing for a more self-contained application), and because I kind of wanted to learn it |
| PostgreSQL | Used as the main datastore. There was much thought into using SQLite instead (to keep aligned with the previous desire for a low entry barrier), while using SQLite would undoubtedly make the initial setup process easier it would make putting the application on services like Heroku or Elastic Beanstalk much more difficult/impossible, which would screw ease-of-use-up drastically in another direction. Then the other option was "why not support both SQLite and a more traditional server-based SQL?" Then the issue sways towards how do we manage the inevitable database migrations as the application expands? SQLite has very limited support for altering schema so would we have to come up with some kind of mapper? How would that complicate the code? Will it run the risk of becoming unmanageable and unapproachable? So, as it stands now, we're just using Postgres. It provides much more power and flexibility than SQLite and it really shouldn't be that big of a burden to set it up; and if it is, the argument can be made that being able to setup a database server is a good skill to have. |
| Godep | Used to vendor Go dependencies. This is both because of Go's, in this writer's opinion, silly and dangerous built in dependency resolution system which has no real concept of versioning and because vendoring is required for Heroku, which is currently rigged up with our travis deployment. |
| Docker (optional) | By no means required. Only mentioned because it is used by the setup-database script to try to mitigate some of the concerns about ease-of-use in relation to Postgres, as mentioned above. |
- As this project is built in Go, the first step is to setup a Go environment. This can be done by following the Getting Started tutorial, however this repo has been created to assist with this and includes a script to try to walk through the process on OSX. It's very possible the script has bugs, but hopefully in these cases it can be read manually to get a general idea of the steps.
- Getting the binary compiled should be a simple procedure. All executable dependencies should already be in
vendorbut in case they are not it is propbably through an incomplete commit, try running ./manage/prepare-commit to make sure all dependencies are properly downloaded and versioned. Building can be accomplished by runninggo build. - Getting the tests to run should only be slightly harder. Godep, by default, doesn't vendor test-only dependencies so you will likely need to run
go get -tto download these to your go workspace. After this you should be able to run manage/test to execute the tests. - A connection to a Postgres server is required to run the application.
manage/setup-databaseattempts to assist with this on OSX by trying to install Docker and a Postgres image, however this is not necessary. Postgres can be downloaded directly from https://www.postgresql.org/download/, however I do think that keeping it provisioned in a docker image is a cleaner solution if you can get it rigged up. (Just keep in mind that all data stored is ephemerial and should be used for development only) - Starting the application at this point should hopefully be as simple as running
./LinkLetter. The default configs should work with the manage/setup-database end result, however runLinkLetter -hfor a description of all accepted flags and their defaults. (Several environment variables are also supported for setting config options. The code where these are defined, at the time of writing, is inconfig/config.go)