The missing link for teams working with collaboration platforms, social media, and version control.
SKTimeline site. Feel free to register an account and see a sample system in action.A development version of this tool is available at the
OS X Development Setup Instructions
If not yet done so, install python verion 2.7 & virtualenv.
brew install python pip install virtualenv
Note: If you receive an error that the command
brew is not found, you must install Homebrew first.
Clone this repository, change directories to project working directory, then setup and activate the virtual enviroment:
git clone REPOSITORY_URL_GOES_HERE cd SKTimeline virtualenv --no-site-packages . source bin/activate
Downgrade to pip v8.1.1 and install pip-tools: (note: this is currently needed for pip-tools as used to manage packages)
bin/pip install --upgrade pip==8.1.1 bin/pip install pip-tools
Install needed project packages from requirements.txt in the virtualenv via pip-sync:
Configuration Setup for Development
Install MySQL Server if not already on your machine.
brew install mysql
Confirm the MySQL server started by running:
brew services start mysql
Connect to MySQL server to setup a new database for the application.
Note: MySQL installs without a root password by default, if using another development setup, you may need to enter a password here or find a way to setup
Create the sktimeline database on my MySQL shell with the command
CREATE DATABASE sktimeline;
mysql> CREATE DATABASE sktimeline; Query OK, 1 row affected (0.01 sec)
At this point the application can create the needed database schema via SQLAlchemy. First we must tell the local instance how to connect to the database in the local config.
config.py file into
instance/config.py file is ignored by version control, so all local application instance which shouldn't be made public (database settings, API keys, etc) should be placed in this file.
cp config.py instance/config.py
Modify the line
SQLALCHEMY_DATABASE_URI = 'mysql://user:password@localhost/dbname' with your database settings. For instance, if using the database name
sktimeline with user
root and no password like database we created above it should read as following:
SQLALCHEMY_DATABASE_URI = 'mysql://root@localhost/sktimeline'
If you instance is using a different username, password, server address, or database, you must modify this database URI reflect this. For more information see the SQLAlchemy documentation
Finally, we can create the database schema by running the following command.
bin/python migration.py setup_db
At this point the application server is ready to run!
Running the Instance
Now you should be able to retup the Flask application server
Generating and Entering API Credentials
In order to download the activity from GitHub, Twitter, & Slack, you must enter API credentials into
Twitter API Credentials
- Go to https://apps.twitter.com and login to your Twitter account
- Press Create New App, enter a name, description, and website. It is fine to use a placeholder value for the website URL like
- Click on the tab Keys and Access Tokens
- Click Access Level and change to "read only" (this is so that if these credentials were ever stolen that they cannot make changes to your account and act on your behalf)
- Copy the Consumer Key (API Key) value and place in the
- Copy Consumer Secret (API Secret) and place in
- Press Generate Access Token and Token Secret
- Copy Access Token and place in
- Copy Access Token Secret and place in
GitHub API Credentials
These GitHub access tokens are used to use the GitHub API over Basic Authentication in the PyGithub module.
- Go login to your GitHub account, go to https://github.com/settings/developers and click Register New Application
- Enter an Application Name and Homepage URL and press save. Note: It is fine to use a placeholder homepage URL like
http://127.0.0.1:5000/since this will just be visible to you.
- Copy the Access Token value and place in the
- Copy Client Secret and place in
Slack API Credentials
- Go to https://api.slack.com/apps, login to any Slack team with an account, and press "Create New App".
- Fill in a app name, short & long description, select a team.
- In the Redirect URI(s) field you must enter the OAuth callback URIs for where this app will be hosted.
For local development this will likely be
For development on a remote web server you will need to enter
Note: this can be changed and added to in the future, so if you do not know all the places this will be hosted; it is fine to leave blank for now
4. After submitting form, click the OAuth and Permissions menu item.
5. Copy the Client ID value and place in the
SLACK_CLIENT_ID value of
6. Click Show under Client Secret then copy the value into
Once these API credentials are present, you may need to restart the web server for these configuration values take effect.
scheduler.py for downloading timeline activity
The code which triggers the downloading the timeline activity is seperate from the Flask application server in the file
scheduler.py. On a web server, we set this process to run using supervisor (more info about this in the
etc/README.md file); however, for development it's easiest to run this file independantly via
This process is a schedule which checks for items in newly added feeds every 1 minute and items in prior updated feeds every 15 minutes. Because this time delay may be inconvinent for testing during development, an alternative method way to trigger the feed updates is by running the Flask application shell:
bin/python shell.py then run a specific classes' update or populate method:
TwitterFeedSetting.start_populate_new_items() GithubFeedSetting.start_populate_new_items() TwitterFeedSetting.update_items() SlackFeedSetting.update_items() [...]
pip-tools for package management
I've setup this project to use the
requirements.in file to manage all python packages that are needed in the code.
If a new package is needed, add it to the
requirements.in file then run
bin/pip-compile. This generates the
requirements.txt file which locks the package to a version.
When upgrading a code change from the repo that requires a new package to be d, run
bin/pip-sync which will install/upgrade/uninstall everything so that the virtualenv exactly matches what's in
Custom Styles in
I've setup this file to be compiled using SASS and the the grunt task runner, so
these should not be edited directly and instead use the SCSS files in
Using gulp to compile SCSS:
Install node/npm if not on your system if not already available
brew install node
Install gulp and gulp-sass run
npm install gulp && npm install gulp-sass --save-dev
While developing, tell gulp to watch and compile the SCSS whenever it is changed by running
I also recommend sending the process into a background process which makes it a little easier for development so the task does not require it's own terminal window.
gulp sass:watch &