Welcome to the News Apps team! We know you're probably dying to get started, but first there are a few things we have to do to get it ready for all the cool stuff you're going to build.
- Set up your News Apps environment
Everything we do here is only going to work if you have admin privileges. How do you know if you have it?
- Open your
System Preferences. - Click on
Users & Groups. - Do you see your name with
Adminwritten below it on the left? Awesome! You're the admin.
Don't have admin powers? Reach out to the team and we'll help get you set up.
If your computer is brand new, you may have a few outstanding operating system updates. Make sure to grab those first. Use this guide to update.
The terminal is going to be your BFF, so it might as well not look terrible.
Open Terminal. It can be found in your Applications folder, or, search for it with Spotlight – it's the cute little magnifying glass at the top right of your screen next to your name. Type Terminal and it should come right up!
Currently it's just a white box with black text. Let's fix that.
With Terminal in focus, open the Preferences. Up at the top of the box, click on Profiles and pick a cute color scheme that speaks to you from the side menu, or get crazy and click that little + at the bottom of the menu and make your own. At the bottom of the side menu next to the + you'll see a button for Default – click that after you've made your selection.
Beautiful! There's a whole world of color schemes out there that go beyond the defaults. We encourage you to seek them out when you want to spice things up!
Three editors are primarily used here at The Texas Tribune – Atom, Sublime Text and VS Code. We have no particular preference – try them both out! (You're welcome to use anything else, too.)
Download the installer and install as normal.
Atom does this automatically on install. You should be able to type atom <path> in your terminal to open files and folders with Atom.
Check out the Atom Flight Manual – it's a good overview on how Atom works.
Download the installer and install as normal.
If you want to be able to open Sublime Text from your Terminal, you'll need to follow this guide.
Now you can type subl <path> in your terminal and Sublime will open that file or folder.
Download the installer and install as normal.
If you want to be able to open VS Code from your Terminal on your Mac, you'll need to follow this guide.
Now you can type code <path> in your terminal and VS Code will open that file or folder.
Homebrew describes itself as "The missing package manager for MacOS." This means that it helps with the installation of many of the tools you'll use.
First, we need to make sure your OS and Xcode is cool with Homebrew. Run this in your terminal:
xcode-select --installGo to Homebrew's site, look for Install Homebrew, and grab the command there. Because it could potentially change, we won't be providing that command here, but it should start with something that looks like ruby -e "$(curl....
It'll then ask for your computer's admin password – normally this isn't a good idea, but this will prevent you from ever having to run a command with sudo.
Next, run Homebrew's status check:
brew doctorThis will make sure everything is cool. If you get any warnings, we'll need to handle those before moving forward. Do what it asks – or grab someone else on the team for help – until brew doctor comes back clean.
Now we need to tell our computer where our cool new package manager and all of the packages live.
The first Homebrew package we're going to install is Python. "But wait," you say, "my computer already has Python!"
You're right! But it's a good idea to not monkey around with your computer's installed software. There's some fragile stuff in there that your computer depends on to function, so we try our best not to disturb it. Plus it is much easier to troubleshoot if you know exactly where your version of Python lives.
Homebrew has dedicated an entire document to how it works with Python. It's worth a quick read.
The Data Visuals team defaults to Python 3. If are in the rare situation where you still need Python 2, let someone know and we can help.
brew install python
pip install --upgrade pipIf you get an error message about pip, check out this discussion for a potential fix:
brew unlink python && brew link pythonPyenv can help manage python versions on your computer. You can install with the following:
brew install pyenvYou can also download the Python Wrangler to keep track of python versions on your computer.
When you start working on group projects, it's important to make sure that everyone's working environment is as close to identical as possible. Virtual environments keep a Python project's installs in their own little boxes so there are no conflicts between versions being used in other projects, or those already installed on your computer.
Currently, the team uses pipenv to create virtual environments. To install, run:
brew install pipenvThat's all you will need to do for now. You will use them more as you get up and running on projects that use them. A few include the salaries app and the Republic API.
Note: If you are using python 3.9, you may run into this issue when installing packages like numpy inside a pipenv environment. To fix, try running:
export SYSTEM_VERSION_COMPAT=1
pipenv installNode.js makes is possible to build server-side apps using JavaScript. At the Tribune, we use it to run our project building tools.
Let's install it! We use nvm to manage versions. Here's a direct link to the install instructions.
Now, if you run nvm ls-remote, you'll be able to see all the versions of Node.js that are available.
We currently base all of our projects on the current Long-term Support (LTS) version.
To install that, run the following:
nvm install --lts
nvm use --ltsAt any point, you can check the versions these are using by running:
nvm lsIf you need to set a newer version of node as your default, you can run:
nvm alias default 22.3We also use npx with our kit that is used to create graphics, which will be explained later. In the meantime, make sure it's installed by running:
npxIf that doesn't work, run:
npm install -g npxYou'll need a GitHub account and be a member of the Texas Tribune organization. Someone should help you get this set up – don't worry!
To get this started, install git:
brew install gitNow we need to set some defaults for the git client. First we need to your name for commits.
This should not be your GitHub user account name. It's meant to be your real name – like Jenny Smith – but you are not required to do so. This name will be public and attached to every one of your commits. Feel free to use a pseudonym!
To set your name, run the following:
git config --global user.name "<your-name>"Next we'll set your email. This needs to be an email account associated with your Github account. Like the name, this email will be publicly available and attached to each of your commits. If you don't know which emails are under your GitHub account, you can check on GitHub.
git config --global user.email "<your-email>"Don't want your email public? GitHub can help with that. On the email settings page, there is a setting at the bottom labeled
Keep my email address private. You can then use the proxy email GitHub provides.
Next we'll set up authentication. The Homebrew install of git adds a helper that allows it to use MacOS's built-in Keychain.
Run the following to tell git to use it:
git config --global credential.helper osxkeychainWe also need to tell git to use https for cloning.
git config --global hub.protocol httpsIf it's your first time using Github in terminal on the computer you're using, you will need to generate a personal access token and use that instead of a password the first time you clone or commit. For more information on git and GitHub, check out this interactive tutorial or this walk through to get started.
Our team has a kit that is designed to provide you with a framework for creating graphics. Included is the basic page structure, files to put SCSS and javascript in, a simple workflow for working with Google spreadsheets and a way to test your project locally and deploy to a server.
Setting the kit up and creating your first graphic is documented in its own readme. Fellows will definitely want to go through through that setup.
At this point, you will need several files added to the home directory on your computer ('Users/yourname'), which will provide you with the credentials needed to run the kit and other team projects. They include:
.tt_kit_google_client_secrets.json.aws/config.aws/credentials
For fellows and full-time employees, these are stored in 1Password, which you should have access to after you go through the onboarding process. The tt_kit_google_client_secrets.json info is a downloadable file. When you download it, you need to manually add the . back into the filename (this is easier to change in terminal than Finder!). The aws files are stored in the AWS credentials note. Please don't share these on Slack or over email.
Once you've got these set up, you'll need one more, which you will generate with your Google account after you create your first graphic. You should see a url pop up in your terminal, which will direct you to a Google Drive page that says News Apps Graphics Kit wants to access your Google Account. Hit Allow. After you are redirected, the page will look broken, but you can copy the page URL and paste it back in your terminal. The token file will be generated and put in your home directory.
This file is:
.google_drive_fetch_token
Once you deploy your graphic, you will be prompted to enter your account information. The file will automatically be generated on your computer once you're done.
We use Illustrator to create many of our graphics. A team password for the Adobe Creative Cloud is available in 1Password.
As part of our setup, we also use ai2html to convert Illustrator files to HTML to put on our site. To set this up, check out our instructions on Confluence.
Although not required, our team uses QGIS to run geographical analysis. This and other mapping tips are avaiable in the geo-setup file.
NOTE: This is only required for full-time staffers
Docker is a tool for containerizing apps. We use it for deploys and database management. You'll need Docker for Mac.
NOTE: This is optional for fellows, depending on if they will be working on database projects during their fellowship. It can always be installed later if you're not sure.
Nearly all of our projects use PostgreSQL as their backend. Instead of installing it with Homebrew, we use Postgres.app instead.
Visit http://postgresapp.com/ and download the installer. After installing, run the app. You should get a pop up window and see a cute little elephant romping around in your menu bar in the top right. If you see the elephant, Postgres.app is live.
Separate credentials are required for setting up our explorers. Instructions for these explorers are in a separate readme.
On your first day, you won't need to worry about setting them up.
Below are some things you can set up that aren't necessary, but can be very useful.
Run this command in your terminal to show hidden files in Finder:
defaults write com.apple.finder AppleShowAllFiles YESNext, you'll need to restart Finder for the change to take effect.
killall FinderIn the next Finder window you open, you'll start seeing hidden files!
hub is an extension for git that adds extra functionality. Read more about the perks.
To install, we'll use Homebrew:
brew install hubNext, we'll need to alias hub to point to git in your .bash_profile. (Don't forget to source!)
alias git=hub