Setup

Overview

The Quick Start page is a much faster way to get started and performs many of these steps automatically. Follow these steps to better understand how things work. takeout run –setup_only can also be used to create a simple setup that can be reviewed and/or modified later.

Requirements

This page assumes a Linux system is being used. Takeout is written in Go, so most other systems will also work fine. Please adjust commands below as needed. You can setup on a VPS using EC2, GCE, Digital Ocean, Linode, or use your spiffy computer at home or a Raspberry Pi.

System requirements vary, however, a reasonable setup will likely require about 5GB of storage for metadata/caching and the server requires about 128MB of RAM. Network requirements are minimal since media can be stored and streamed directly from S3.

Media

For cloud-based media storage, you need to have media stored in an S3 bucket somewhere. Some common services are AWS S3, Wasabi, Backblaze, and Minio. And if you’re using that spiffy home computer, you can also install Minio at home and make your local media available via S3 on your home network.

Takeout can also access local media files without needing S3. This may be your best option for home media access. Using S3 in the cloud is recommended if you want to have your media securely available wherever you go.

Please see media for further details on how you should organize your media is S3 or locally. rclone is an excellent tool to manage S3 buckets from the command line. Once that’s all done, proceed with the steps below.

Install Go

Download and install Go from https://go.dev/ as needed. Run the following command to ensure Go is correctly installed. You should have Go 1.22 or higher.

$ go version

Install Takeout

Download and build the takeout server from source.

$ go install takeoutfm.dev/takeout/cmd/takeout@latest

This will build & install takeout in $GOPATH/bin. Don’t worry if you don’t have a GOPATH environment variable defined, Go will default to your home directory (~/go/bin). Ensure that $GOPATH/bin is in your command path. You should see a Takeout version displayed.

$ takeout version

Configuration

Takeout uses configuration files to customize behavior. See config for full details and examples. This page will cover some of the basics to get started.

Home Directory

Create the takeout home directory. This is the directory where config files, databases, and logs will be stored. Some good choices would be:

• /var/lib/takeout
• /home/takeout

# takeout.yaml
Server:
  DataDir: /var/lib/takeout

$ mkdir /var/lib/takeout

Cache Directories

Takeout can cache images and API responses to significantly faster operation.

# takeout.yaml
Server:
  ImageClient:
    CacheDir: /var/lib/takeout/imagecache

Client:
  CacheDir: /var/cache/takeout/httpcache

Auth Tokens

Takeout uses JWTs and TOTP for additional security. Each token has its own random (16 byte) secret which can be stored in a file or specified in the config.

Server:
  Auth:
    AccessToken:
      SecretFile: /var/lib/takeout/keys/access.key
    MediaToken:
      SecretFile: /var/lib/takeout/keys/media.key
    CodeToken:
      SecretFile: /var/lib/takeout/keys/code.key
    FileToken:
      SecretFile: /var/lib/takeout/keys/file.key
    TOTP:
      Issuer: TakeoutFM

Create key files using openssl to generate random secrets:

$ mkdir /var/lib/takeout/keys
$ chmod 700 /var/lib/takeout/keys
$ openssl rand -base64 12 > /var/lib/takeout/keys/access.key
$ openssl rand -base64 12 > /var/lib/takeout/keys/media.key
$ openssl rand -base64 12 > /var/lib/takeout/keys/code.key
$ openssl rand -base64 12 > /var/lib/takeout/keys/file.key
$ chmod 400 /var/lib/takeout/keys/*.key

Media Directory

Create a media directory to store media specific configuration and databases. Media isn’t stored here, just related config files and databases.

# takeout.yaml
Server:
  MediaDir: /var/lib/takeout/media

$ mkdir /var/lib/takeout/media

Media Configuration

Inside the media directory (MediaDir) are sub-directories for each media configuration. Each sub-directory name is the name of the media configuration. Multiple configurations can be useful to have different media available for different users.

Example for three different configurations: mom, data, and kids.

$ mkdir /var/lib/takeout/media/mom
$ mkdir /var/lib/takeout/media/dad
$ mkdir /var/lib/takeout/media/kids

In each directory, create a config file called config.yaml.

Mom’s media

Local files with music, shows and movies.

# config.yaml - mom
Buckets:
  - Media: music
    FS:
      Root: /data/mom/Music
  - Media: tv
    FS:
      Root: /data/mom/TV
  - Media: film
    FS:
      Root: /home/mome/Movies

Client:
  CacheDir: /var/cache/takeout/httpcache

Dad’s media

S3 bucket with music and movies.

# config.yaml - dad
Buckets:
  - Media: music
    s3:
      endpoint: s3.region1.provider.com
      region: region1
      accessKeyID: ****************
      secretAccessKey: ****************
      bucketName: mybucket
      objectPrefix: MyMusic
      URLExpiration: 15m
      UseSSL: true
  - Media: film
    s3:
      endpoint: s3.region1.provider.com
      region: region1
      accessKeyID: ****************
      secretAccessKey: ****************
      bucketName: mybucket
      objectPrefix: MyMovies
      URLExpiration: 15m
      UseSSL: true

Client:
  CacheDir: /var/cache/takeout/httpcache

Kids media

Local files with music, shows and movies.

# config.yaml - kids
Buckets:
  - Media: music
    FS:
      Root: /data/kids/Music
  - Media: tv
    FS:
      Root: /data/kids/TV
  - Media: film
    FS:
      Root: /home/kids/Movies

Client:
  CacheDir: /var/cache/takeout/httpcache

You should have these files:

/var/lib/takeout/media/mom/config.yaml
/var/lib/takeout/media/dad/config.yaml
/var/lib/takeout/media/kids/config.yaml

Create Users

Takeout requires users to login with a userid and password. Users are mapped to media configurations; media can be shared or unique to each user.

$ cd /var/lib/takeout
$ takeout user --add --user=mom --pass=mompassword --media=mom
$ takeout user --add --user=dad --pass=dadpassword --media=dad
$ takeout user --add --user=kid1 --pass=kid1password --media=kids
$ takeout user --add --user=kid2 --pass=kid2password --media=kids
$ takeout user --add --user=kid3 --pass=kid3password --media=kids

Generate TOTP

For additonal security, assign a TOTP to a user:

$ cd /var/lib/takeout
$ takeout user --user=mom --generate_totp

This command will output a QR code to the screen along with the otpauth URL.

Sync Media

Takeout will check for new media and auto sync hourly. The first time around though it may be best to sync manually to ensure things look good before starting the server. See media for more details on required media naming conventions.

$ cd /var/lib/takeout/media/mom
$ takeout sync

This may take a while so be patient. When complete, the media directory will have sqlite databases and bleve search indices populated with metadata.

config.yaml
film.bleve/
film.db
music.bleve/
music.db
podcast.bleve/
podcast.db
tv.bleve/
tv.db

Create Radio Stations

Takeout can create radio stations from music media. These are like super smart playlists or similar things. Several stations (created using bleve search queries) are configured by default. Create the stations:

$ cd /var/lib/takeout/media/mom
$ takeout radio

Internet Radio

Takeout can reference Internet radio stations (streams) and present them for streaming with the app, watch app, etc. Add this to Mom’s configuration:

Music:
  RadioStreams:
  - Creator: "BAGeL Radio"
    Title: "BAGeL Radio"
    Description: "Live-hosted award-winning commercial-free indie rock music radio."
    Image: "https://cdn-profiles.tunein.com/s187420/images/logod.jpg"
    Source:
    - ContentType: "audio/aac"
      URL: "https://www.bagelradio.com/s/bagelradio.pls"
    - ContentType: "audio/mpeg"
      URL: "http://ais-sa3.cdnstream1.com/2606_128.mp3"

  - Creator: "SomaFM"
    Title: "Christmas Rocks!"
    Description: "Have your self an indie/alternative holiday season!"
    Image: "https://somafm.com/img3/xmasrocks-400.png"
    Source:
    - ContentType: "audio/aac"
      URL: "https://somafm.com/xmasrocks130.pls"
     - ContentType: "audio/mpeg"
      URL: "https://somafm.com/xmasrocks.pls"

Setup a TLS Server

It’s best to setup a TLS front-end to the Takeout server. Nginx is a popular option. Let’s Encrypt can be used to get a free TLS certificate. An Nginx config example would be: (replace myserver.org with your own domain)

server {
	listen 0.0.0.0:80;
	server_name myserver.org;
	return 301 https://$host$request_uri;
}

upstream myapp {
	server 127.0.0.1:3000;
	keepalive 8;
}

server {
	listen 443 ssl http2;
	server_name myserver.org;

	ssl_certificate /etc/letsencrypt/live/myserver.org/fullchain.pem;
	ssl_certificate_key /etc/letsencrypt/live/myserver.org/privkey.pem;
	ssl_trusted_certificate /etc/letsencrypt/live/myserver.org/chain.pem;

	access_log /var/log/nginx/myserver.org.log;

	location / {
	  proxy_set_header X-Real-IP $remote_addr;
	  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
	  proxy_set_header Host $http_host;
	  proxy_set_header X-NginX-Proxy true;
	  proxy_pass http://myapp/;
	  proxy_redirect off;
	}
}

Start the Server

$ cd /var/lib/takeout
$ takeout serve