Code as Collage

Making Your First Open Source Project Public

Last week, I recently open-sourced Teamline, my final group project for Flatiron. I’d created many public repos beforehand on my own account, and contributed to open source by creating the OmniAuth strategy for Jawbone, but this was the biggest project I’ve ever open-sourced. From that process, I learned about a few steps a beginner might have to take before open-sourcing his or her project. I’ve distilled that process, plus a few other things I’ve recently learned about open source and some thoughts I have on how to improve my project now that I’ve made it open.

Check out my repo here btw.

Step 1: Create an application.yml file

This is a local file that lives in your .gitignore and thus is not pushed up to GitHub. This is the place where you keep your secret keys and tokens for different third-party applications you might be authenticating with. If you already have one, you can use that.

Step 2: Hide your secret token

Rails uses a secret token to allow you to verify the integrity of signed cookies. Thus, for security reasons, you probably don’t want everyone to have the ability to know and use that token. It is found in config/initializers/secret_token.rb. If you’ve already open-sourced your project without taking these precautions to hide your secret token, you’ll probably want to rake secret to generate a new token. If you do that, you’ll need to restart your server. If you haven’t open-sourced your project yet, you can use your existing token, but you’ll want to move it to your application.yml file, and reference it in your secret_token.rb file as an environmental variable (which has scope throughout the whole application —> look at how rake tasks and the task: TASK_NAME => :environment do line to see how rake tasks require the whole application environment in order to have scope throughout the app). Create a line in your application.yml file that is something like APP_SECRET_TOKEN: "xxxxxxxxxxxxxxxxxxxxxxxxxxx" with the x’s being your secret token from the secret_token.rb file. In your secret_token.rb file, change the code to App::Application.config.secret_token = ENV['APP_SECRET_TOKEN'].

Step 3: Hide your database names

Exposing your database names opens you up to attack. Changing them from the default name Rails suggests will also help you heighten your security. Either way, you definitely don’t want them out in the open. In your config/database.yml file, in the development, test, and production sections, change the line that starts with “database” to something like database: <%= ENV['APP_DEVELOPMENT_DATABASE'] %>, database: <%= ENV['APP_TEST_DATABASE'] %>, and database: <%= ENV['APP_PRODUCTION_DATABASE'] %>. I tried it without using erb, and it didn’t work, so I recommend doing that, just to be safe. In your application.yml file, make environmental variables called ENV['APP_DEVELOPMENT_DATABASE], ENV['APP_TEST_DATABASE], and ENV['APP_PRODUCTION_DATABASE].

Step 4: Hide your deploy user and server

Exposing your server username and IP address also opens you up to attacks – you can imagine someone taking that username@IP and trying out passwords to ssh into your server. Better that didn’t happen. In your config/deploy.rb file, change the set user line to set :user, ENV['APP_USER'] and the three role: web, role: app, and role: db lines to role :web, ENV['APP_SERVER'], role :app, ENV['APP_SERVER'], role :db, ENV['APP_SERVER'], instead of listing out your actual server IP address in those lines.

Step 5: Git fixes

Okay, push those changes up to master – maybe do rails s and test it first, for any mistakes you might have made or some bugs that emerge. Now, you’ll want to clear your history of any reference to your actual database, server, or secret token. Copy those files you’ve just created somewhere else, outside of your app. Then you’ll want to run git filter-branch --tree-filter 'rm -f config/deploy.rb' HEAD to remove that file, git filter-branch --tree-filter 'rm -f config/database.yml' HEAD, and git filter-branch --tree-filter 'rm -f config/initializers/secret_token.rb' HEAD to remove all traces of that file in your branch. You may need to force this if it doesn’t work automatically. You’ll then want to commit that change and push it up. You may also need to force push or force merge those changes. It’s what you want to do though. Then your branch has no traces of that file. You’ll want to do this for every branch you keep in your final project (you could also consider squashing vestigial branches where all chanegs are merged). Finally, you’ll want to create those files in your app once again, and paste the files that you’ve copied elsewhere.

Step 6: Open source!

This is an exciting moment. Open source your project for the world to use! I recently went to an interview, and one of the people I met with suggested to me that the best way to get acquainted with an open-source project would be to run its test suite. That way, you literally get to see how it “should” work. In terms of thinking about my next steps now that I’ve open-sourced Teamline, making my test suite really robust is one of the big ones. Another big thing I’ve thought about in making my app more robust is changing its scope to be a multi-tenant application, so that the “teamlines” (i.e. stories of a team over time) of multiple teams can be created. Improving my documentation and identifying and fixing bugs is another one. I’ve also got the refactoring from good to great video on my YouTube queue, so going through my code and refactoring it will be important as well. I’m sure for your project, you also have some steps you’d like to take to improve it, and open-sourcing it (safely!) is a great motivation for that. Plus people can fork you, and that’s always exciting.

Let me know if you have any feedback/improvements/tips/success stories to add!