Skip to content

Getting Started

Jump to bottom
Michael Rosenberg edited this page Jul 29, 2024 · 7 revisions

Getting set up withe ReadToMyShoe is a bit complicated right now, as it requires a Google Cloud account for text-to-speech services. This page is a full guide on getting set up.

Docker

You can skip the below section if you use Docker.

The Dockerfile in the main directory should Just Work. Run docker run readtomyshoe -p 9382:9382 to start ReadToMyShoe on port 9382. Currently, this does not support storing audio files on an external volume. This is an open issue.

Fly.io: We also support one-click deployment on Fly.io. To deploy, simply pick a new app name in fly.toml, make an app with that name in your Fly.io account, and run flyctl deploy. This uses the Dockerfile for deployment, so any changes there will change your Fly.io deployment.

Installation

Local setup

Here we describe how to install ReadToMyShoe to a local folder on your machine.

  1. Clone this repo: git clone https://github.com/rozbb/readtomyshoe.git
  2. Step into the directory: cd readtomyshoe
  3. Install trafilatura, the Python-based article text extraction utility: pip3 install trafilatura -t python_deps.
    • Note: for this you need Python 3 installed. To install pip3 on a Mac: brew install python3 (this requires Homebrew). On Ubuntu: sudo apt-get install python3-pip.
  4. Install OpenSSL and pkg-config. On Ubuntu and Debian, run sudo apt-get install libssl-dev pkg-config. On Mac, run brew install openssl pkg-config.
  5. Make sure you have rustup installed. Follow the directions here. Make sure to add $HOME/.cargo/bin to your PATH.
  6. Install the WASM target so Rust knows how to output code for the browser: rustup target add wasm32-unknown-unknown
  7. Install trunk, a utility that packages the website's frontend assets: cargo install trunk

We're nearly done. The last step is to get an API key for Google Cloud's text-to-speech and put it in the appropriate place so the readtomyshoe/ server can find it.

Google Cloud

ReadToMyShoe uses Google Cloud for text-to-speech services. In order to get up and running, you need to make an account.

  • Make a Google Cloud account.
  • You will have to set up billing.
  • Create a new project
  • Set up alerts and quotas to limit unexpected charges on your account:
    • Go to the API Quotas page, select the quota of "Count of characters in all requests per minute", and click Edit Quotas. You can set this number to something much lower than 500,000. Most articles won't exceed 20,000 characters. If a hacker got your API key, a 500k cap will cost you up to $8/min for every minute you don't revoke the key.
    • Set budget alerts. Back in billing, go to "Budgets & Alerts" and make a new budgets with whatever alerts you want. This will let you know if you're spending too much money.
  • Now we have to make an API key. Go to the credentials page. Click "Create Credentials" at the top of the page and select "API Key"
  • You can copy the API key right now or click "Edit API key" and restrict its capabilities. To restrict:
    • Click "Edit API key"
    • Under "API restrictions" click "Restrict key"
    • Select "Cloud Text-to-Speech API"
  • Now copy your API key to the clipboard

Once you've got your API key, you need to give it to the ReadToMyShoe server:

  • Create a new file in the server/ directory, called gcp_api.key
  • Paste the API key into that file

Updating

Once everything is set up, updating is easy. Make sure you're in the readtomyshoe/ folder. Then:

  • To upgrade ReadToMyShoe, run git pull and restart the server.
  • To upgrade trafilatura, the article text extraction utility, run pip3 install --upgrade trafilatura -t python_deps

Running the server

To run the server, first make sure you're in readtomyshoe/. Then run ./scripts/prod.sh. This will start the "production" version of the server. Production defaults:

  • Address: 0.0.0.0. This means the server is publicly addressable, i.e., anyone on your network (or on the internet, if you're not behind a router or firewall) can access your instance.
  • Port: 9382
  • Rate-limiting: None. This means that anyone with access to your server can use your instance, and text-to-speech without any limits. This can be expensive, so strongly consider either not publicizing your instance URL, setting up a budget in Google Cloud (explained here), or setting a rate limit. For reference, an average size English news article is about 6500 characters.

To change these defaults, open up prod.sh and edit the flags. All the flag documentation is in there.

NOTE: If you run ReadToMyShoe on your local network or generally without HTTPS, most web browsers will NOT cache anything. This is because Service Workers are only allowed in "secure contexts" (meaning via HTTPS or on localhost).

HTTPS

If you want to expose your instance to the internet, you probably want to set up an HTTPS reverse proxy (ie a public HTTPS server the points to your local ReadToMyShoe instance). Some options:

  • Caddy reverse-proxy.
  • Use nginx with certbot. Tutorial. NOTE: You should set client_max_body_size 100M; in your nginx config. The nginx default max size for POSTs is 1MB, which is far too small for some web pages.

In any of the options, make sure to point the reverse proxy at your local port 9382.

Clone this wiki locally