Skip to content

Develop

Jump to bottom
Matt Holt edited this page Feb 4, 2025 · 7 revisions

To develop Timelinize, you will need to compile from source.

First, clone the repository:

$ git clone https://github.com/timelinize/timelinize.git

Dependencies

Make sure the necessary dependencies are installed:

Go

Necessary for compiling the application.

Generic x64 Linux instructions (bash):

GO="$(curl -s https://go.dev/dl/?mode=json | grep -o 'go.*.linux-amd64.tar.gz' | head -n 1 | tr -d '\r\n' )"
wget "https://dl.google.com/go/$GO"
sudo tar -C /usr/local -xzf "$GO"
rm "$GO"
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
source ~/.bashrc

NOTE: Unless you're on Arch, do NOT use the distro-provided Go packages; they are often too old to be compatible.

libvips

For generating thumbnails and preview images.

This can usually be installed from your distro's package manager. You may need to install the -dev variant, for example:

$ sudo apt install -y libvips-dev
$ sudo pacman -S libvips
$ brew install libvips

libheif

To view/process HEIC/HEIF files (commonly from iPhones), libheif may be needed. We recommend this method of installing it on Ubuntu:

sudo add-apt-repository ppa:ubuntuhandbook1/libheif
sudo apt update
sudo apt install libheif-dev libheif1 -y

Arch:

$ sudo pacman -S libheif

libsqlite3

On some bare-bones distros, it may be necessary to install sqlite3 explicitly:

$ sudo apt install libsqlite3-dev

The following dependencies are not required to compile; they are strictly runtime dependencies:

ffmpeg

For processing videos.

$ sudo apt install ffmpeg
$ sudo pacman -S ffmpeg
$ brew install ffmpeg

Or, you can use webinstall.dev for easy installation regardless of platform.

uv

For semantic search.

Follow the very simple install instructions on the uv documentation.

Compile

To build from source, make sure the dependencies above are installed and configured correctly for your system. Then:

$ go build

or, to immediately run (useful for iterative development):

$ go run main.go

If you've already got a browser tab open, you can use serve to only start the server and not open a web browser:

$ go run main.go serve

Manual instructions for Windows

If you're not using WSL, this is the easiest way I have found to get the project compiling on Windows, but let me know if there's a better way.

  1. Make sure you don't already have MSYS2 installed and C:\msys64 does not exist.
  2. Install MSYS2. Don't run after installing, since it likely brings up the wrong shell (UCRT; we want MINGW64 - yes, UCRT is recommended as it's more modern, but I don't feel confident that our dependencies are available as UCRT packages yet).
  3. Run the MSYS2 MINGW64 application (this is MSYS2's MINGW64 environment).
  4. Install mingw64 with relevant tools, and libvips, and libheif: 
    pacman -S --needed base-devel mingw-w64-x86_64-toolchain mingw-w64-x86_64-libvips mingw-w64-x86_64-libheif
  5. Go to Windows environment variables setting for your account, and make sure:
    • Path has C:\msys64\mingw64\bin
    • PKG_CONFIG_PATH has C:\msys64\mingw64\lib\pkgconfig
  6. Restart any running programs/terminals/shells, then run gcc --version to prove that gcc works. vips and heif-* commands should also work. It is likely that the libraries are also installed properly then too.
  7. Running go build should then succeed, assuming the env variables above are set properly. You might need to set CGO_ENABLED=1 ($env:CGO_ENABLED = 1)

NOTE: Setting the CC env var to the path of MSYS's MINGW64 gcc isn't sufficient if a different gcc is in the PATH. You will need to prepend the correct gcc folder to the PATH!

For compilation targeting the same platform (OS and architecture) as your dev machine, go build should suffice.

Script for Windows + WSL

Alternatively, if you are on Windows with WSL, our community has contributed an all-in-one script you can run to get started with development. It has been verified to work for Windows Store's Ubuntu 24.04.1 LTS WSL 2 distro.

#!/bin/bash

set -e  # Exit on any error

# Define variables
REPO_URL="https://github.com/timelinize/timelinize.git"
INSTALL_DIR="$HOME/timelinize"
BIN_DIR="$INSTALL_DIR/.bin"
FINAL_BINARY="/usr/local/bin/timelinize"

echo "[+] Updating system and installing dependencies..."
sudo apt update
sudo apt install -y git make wget tar ffmpeg libvips-dev

echo "[+] Adding PPA for libheif..."
sudo add-apt-repository -y ppa:ubuntuhandbook1/libheif
sudo apt update

echo "[+] Installing libheif and libsqlite3-dev..."
sudo apt install -y libheif-dev libheif1 libsqlite3-dev

echo "[+] Installing Go..."
cd "$HOME"
GO="$(curl -s https://go.dev/dl/?mode=json | grep -o 'go.*.linux-amd64.tar.gz' | head -n 1 | tr -d '\r\n' )"
wget "https://dl.google.com/go/$GO"
sudo tar -C /usr/local -xzf "$GO"
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
export PATH=$PATH:/usr/local/go/bin  # Apply immediately
rm "./$GO"  # Cleanup

echo "[+] Cloning the repository..."
git clone "$REPO_URL" "$INSTALL_DIR"

echo "[+] Fixing permissions..."
sudo chown -R $(whoami):$(whoami) "$INSTALL_DIR"

echo "[+] Installing Zig (version 0.13.0)..."
wget https://ziglang.org/download/0.13.0/zig-linux-x86_64-0.13.0.tar.xz
tar -xf zig-linux-x86_64-0.13.0.tar.xz
sudo mv zig-linux-x86_64-0.13.0 /usr/local/zig
echo 'export PATH="/usr/local/zig:$PATH"' >> ~/.bashrc
export PATH="/usr/local/zig:$PATH"  # Apply immediately
rm zig-linux-x86_64-0.13.0.tar.xz  # Cleanup

echo "[+] Installing uv package manager..."
curl -fsSL https://astro-build.github.io/uv/install.sh | sh
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
export PATH="$HOME/.local/bin:$PATH"  # Apply immediately

echo "[+] Building timelinize..."
mkdir -p "$BIN_DIR"
cd "$INSTALL_DIR"
GOOS=linux GOARCH=amd64 go build -o "$BIN_DIR/timelinize" -buildvcs=false

echo "[+] Moving binary to /usr/local/bin/..."
sudo mv "$BIN_DIR/timelinize" "$FINAL_BINARY"
sudo chmod +x "$FINAL_BINARY"

echo "[+] Installation complete! Verifying..."
timelinize help

echo "Timelinize is successfully installed!"

Makefile

A community-maintained Makefile installs all dependencies and cross-compiles to a single binary in the .bin folder (cross-compilation may not work from all platforms to all platforms due to external libraries):

$ make all
$ make run

Test footer

Clone this wiki locally