README.md

DevDash is a terminal dashboard for developers who want the most up-to-date data they need, per project, at one place.

Why using DevDash?

• All the metrics you specifically need, at one place.
• Pull data from Github, Google Analytics or Google Search Console. More services to come!
• Unlimited amount of different dashboards with different configurations.
• Widgets' data refreshed automatically.
• A huge amount of flexibility compared to other terminal dashboards:
  • Choose the widgets you want.
  • Place your widgets where you want.
  • Choose the color, the data and a lot of other things for each widget.
• It's in the terminal so it's cool!

Menu

• Installation
• Getting Started
• Authorization and permissions
• Configuration examples
• Structure of the config file
• Widget types
• Configuration reference
• General references
• Acknowledgement
• Contribute
• Licence

Installation

Linux

You can simply grab the latest released binary file and put it wherever you want.

Here's a simple way to download and put DevDash in /usr/local/bin, which should be part of your path.

cd /usr/local/bin && sudo curl -LO https://github.com/Phantas0s/devdash/releases/download/0.1.0/devdash && sudo chmod 755 devdash && cd -

Manual installation

You need go installed to compile DevDash.

Then, simply run go get -u github.com/Phantas0s/devdash/cmd/devdash/

Getting started

For now, you can access four APIs (services) via DevDash:

• Google Analytics (ga)
• Google Search Console (gsc)
• A monitoring service (mon)
• Github (github)

To see DevDash in action and get familiar with the config file, you can easily configure the monitoring service:

Here the config to create this (very simple) dashboard:

---
general:
  refresh: 600
  keys:
    quit: "C-c"

projects:
  - name: Quickstart
    services:
      monitor:
        address: "https://www.web-techno.net"
    widgets:
      - row:
          - col:
              size: "M"
              elements:
                - name: mon.box_availability
                  options:
                    border_color: green

You can:

• Copy past the config in a new file (monitoring.yml, for example)
• Run DevDash: devdash -config monitoring.yml

Congratulation! You just created your first dashboard. DevDash will simply send a request every 600 seconds to https://www.web-techno.net and display the response's status code.

Authorization and permissions

Some services need credentials and permissions for DevDash to pull the data into your shiny terminal. Following the detailed step by step tutorial to create these permissions:

Github

1. Go to your Github account in your favorite browser
2. Click on your avatar (top right corner)
3. Click on "Settings"
4. Click on "Developer settings"
5. Click on "Personal access tokens"
6. You don't need to select any scope for DevDash, except if you want to read data from your private repositories.
7. Generate a new token you will add in your DevDash configuration.

Google Analytics / Google Search Console

Obviously, you need to have a Google Analytics account or Google Search account to access these two services.

Downloading the authorization JSON file

1. Go to [https://console.developers.google.com/apis/api/webmasters.googleapis.com/credentials](Google APIs Credentials).
2. Select Service account key.
3. Create a new service account.
4. Select the role Project -> Viewer for a read access only.
5. Add a name.
6. Click on the button create.
7. Save the Service account ID somewhere. We will need it later.
8. Download the JSON file. Its path need to be specified in the config of your DevDash dashboard.

Pulling data from Google Analytics

1. Go to your Google Analytics account.
2. Click on Admin in the menu (last element of the menu)
3. Select the application you want to use with DevDash in the property column (just below the column name property).
4. Click on the + button and add a user.
5. Click on user management of the same column.
6. Enter the email address you saved before (the Service account ID of step 7, above).
7. Click on View settings on the View column and copy the View ID into your DevDash configuration file.

Pulling data from Google Search Console

1. Go to your Google Search Console account
2. Click the property you want to access with DevDash.
3. Click on Settings in the menu on the left.
4. Click on Users and permissions and add a user with the Service Account ID as email address (see step 7 of Downloading the authorization JSON file above).

Configuration examples

You can click on each screenshot to see the config of these dashboards.

Google Analytics

Google Search Console

Github

Real life dashboard

Structure of the config file

Since a diagram is better than a wall of text, here we go:

Widget types

There are three category of widgets:

• box - a single value in a box
• bar - a bar diagram with multiple values overtime (dates on the x-axis)
• table - data in a table

Configuration reference

Monitoring

Service configuration

    services:
      monitor:
        address: "https://www.my-website.net"

Widgets available

Data Options

None.

Display Options

Github

Service configuration

    services:
      github:
        token: myToken
        owner: myName
        repository: myCoolRepo

The repository is not mandatory. However, you will need to precise the repository for each widget fetching data for a specific one.

Widgets available

Widget Options

Table Widgets

Data Options

Name Description Default value Examples Not available for row_limit Limit the number of rows 5 5, 100

order Order of the list updated created, updated, pushed, full_name github.table_branches, github.table_issues metrics Column display stars,watchers,forks,open_issues stars,forks github.table_branches, github.table_issues

Display Options

Google Analytics

Service configuration

    services:
      google_analytics:
        keyfile: goanalytics-abc123.json
        view_id: 456789123

Widgets available

Widget Options

Bar Widgets

Data Options

Name Description Default value Examples Not available for start_date Start date of time period 7_days_ago 2018-01-01, 2_weeks_ago

end_date End date of time period today 2018-01-31, 2_weeks_ago

time_period Time period represented by a bar days days, months, years

metric Google analytics metric sessions page_views, bounces, entrances ga.bar_pages, ga.bar_returning dimensions Google analytics dimensions. Multiple value possible separated with a comma

page_path, user_types ga.bar_pages, ga.bar_bounces, ga.bar_returning filters Query filter (prefix - to exclude)

value, -value

Display Options

Table widgets

Data Options

Name Description Default value Examples Not used by start_date Start date of time period 7_days_ago 2018-01-01, 2_weeks_ago

end_date End date of time period today 2018-01-31, 2_weeks_ago

metrics Google analytics metrics. Multiple values possible separated with a comma sessions,page_views,entrances,unique_page_views bounces,sessions, entrances

dimension Google analytics dimension page_path 2018-01-31, 2_weeks_ago ga.table_traffic_sources orders Order of the result. Multiple value possible separated with a comma sessions desc sessions desc,page_views asc. page_views

filters Query filter (prefix - to exclude)

value, -value

row_limit Limit the number of rows 5 5, 100

character_limit Limit the number of characters of the dimension column 1000 100, 200

Display Options

Box widgets

Data Options

Display Options

Google Search Console

Service configuration

    services:
      google_search_console:
        keyfile: goanalytics-abc123.json

Widgets available

Widget Options

Table widgets

Data Options

Name Description Default value Examples Not used by start_date Start date of time period 7_days_ago 2018-01-01, 2_weeks_ago

end_date End date of time period today 2018-01-31, 2_weeks_ago

metrics Google Search Console metrics (multiple values possible separated with comma) clicks,impressions,ctr,position query, page gsc.table_pages dimension Google Search Console dimension (multiple values possible separated with comma) quert, 2018-01-31, 2_weeks_ago

orders Order of the result (multiple values possible separated with comma) sessions desc sessions desc,page_views asc. page_views

filters Filter the default dimension (prefix - to exclude)

value, -super value

row_limit Limit the number of rows 5 5, 100

character_limit Limit the number of characters for the first column (dimension) 1000 100, 200

Display Options

General references

Options values

Colors

The list of colors you can use in DevDash configuration.

Their display will depend of the colors you've configured for your terminal.

Size

DevDash is based on a 12 columns grid.

You can indicate the width of a widget in number of column (1 to 12), or using the equivalent t-shirt size as described below:

Time range

The start_date and end_date options accept dates following this format: 2016-01-02.

You can use as well aliases relative to the present day.

The same alias can be a different date depending if it's used for the start_date or the end_date option.

You can replace every x in the names by numerical values.

Name start_date end_date today current day current day yesterday yesterday yesterday x_days_ago xth day before the current day xth day before the current day

this_week first day of the actual week last day of the actual week last_week first day of the last week last day of the last week x_weeks_ago first day of the xth week before the current week last day of the xth week before the current week

this_month first day of the actual month last day of the actual month last_month first day of the last month last day of the last month x_months_ago first day the xth month before the current month last day the xth month before the current month

this_year first day of the actual year last day of the actual year last_year first day of the last year last day of the last year x_years_ago first day the xth year before the current year last day the xth year before the current year

Acknowledgement

Thanks to MariaLetta for the awesome and beautiful Gopher pack she made! I used it for my logo on top.

DevDash was inspired from other open source projects:

• wtf
• tdash

Contribute

First of all, thanks a lot if you want to contribute to DevDash!

I think the "talk, then code" practice is pretty good to avoid misunderstandings and hours of work for nothing.

Therefore:

"Every new feature or bug fix should be discussed with the maintainer(s) of the project before work commences. It’s fine to experiment privately, but do not send a change without discussing it first."

Licence

Apache Licence 2.0