Getting Started - jzohrab/lute GitHub Wiki

This documentation is deprecated/obsolete. Lute v2 has been replaced by Lute v3, a full Python rewrite. Please see the Lute v3 manual which includes notes on installation. If you have Lute v2, you can easily migrate to v3. Thank you!

The easiest way to get started using Lute is with Docker. See Setting up Docker if you don't have Docker on your system yet.

Unfortunately, Docker is not available for some systems, including various versions of Windows. If you can't use Docker, click here for alternate installation instructions, or see the other links for getting started on other systems.

1. Create a directory anywhere on your machine and download and unzip the latest release to that folder (I'll call this the "lute_release" folder)
2. Create a backup directory anywhere on your machine (I'll call this the "lute_backup" folder)
3. In the "lute_release" folder, delete the existing ".env" file, and rename ".env.example.docker" to ".env"

NOTE: depending on your system, the ".env" files may be hidden, but they're there! You can show hidden files on your system in different ways: on a Mac, you can hit Command + Shift + ., on Windows play with Windows Explorer settings. Holy smokes computers are annoying sometimes.

4. Open the ".env" file with any text editor, and replace the XXX on the "BACKUP_HOST_DIR=XXX" with your "lute_backup" folder (e.g., BACKUP_HOST_DIR=~/Dropbox/LuteBackup for Mac, or BACKUP_HOST_DIR=C:\Users\YOURUSERNAME\Desktop\lute_backup for Windows). Then close the file and save your changes.

Windows users can open and edit the ".env" file with Notepad. Mac can use TextEdit. Hardcore geeks can use emacs, vim, or sed ... or whatever they want, really.

Now you can build and run your Docker image, and start the container, using the existing docker-compose.yml. From the command line:

cd /path/to/lute_release
docker compose build
docker compose up -d

In your web browser, open http://localhost:8000. You should see the Lute home screen, with some sample stories. Click around, check it out. Then, I recommend you work through the Tutorial in your Lute, it provides an overview of Lute's main features.

When you're ready to really start using Lute, you may want to set the various BACKUP_ settings in the .env file in your "lute_release" directory, and re-start the container for these changes to take effect.

Cheers and best wishes! Hopefully we'll see you on the Lute Discord.

Once you've built your image and container using docker compose build, docker compose up, they get reused. You shouldn't need to rebuild (unless you're updating Lute), but just in case, here's how to do it (from the command line):

# Stop all running containers
docker stop $(docker ps -a -q)

# Delete all containers
docker rm $(docker ps -a -q)

# Remove all images
docker rmi $(docker images -q)

Then docker compose build should build everything from scratch.