Provide automated setup script

This commit is contained in:
Sascha Ißbrücker 2019-12-26 18:49:10 +01:00
parent 991025d13e
commit b833726f19
3 changed files with 68 additions and 11 deletions

View file

@ -15,32 +15,47 @@ The name comes from:
## Installation ## Installation
The easiest way to run linkding is to use [Docker](https://docs.docker.com/get-started/). There is also the option to set up the installation manually which I do not support, but can give some pointers on below. The easiest way to run linkding is to use [Docker](https://docs.docker.com/get-started/). The Docker image should be compatible with ARM platforms, so it can be run on a Raspberry Pi.
### Docker There is also the option to set up the installation manually which I do not support, but can give some pointers on below.
### Docker setup
To install linkding using Docker you can just run the image from the Docker registry: To install linkding using Docker you can just run the image from the Docker registry:
``` ```
docker run --name linkding -p 9090:9090 -d sissbruecker/linkding:latest docker run --name linkding -p 9090:9090 -d sissbruecker/linkding:latest
``` ```
The Docker image should be compatible with ARM platforms, so it can be run on a Raspberry Pi. By default it runs on port `9090`, but you can map it to a different port by modifying the command above. By default the application runs on port `9090`, but you can map it to a different host port by modifying the command above.
Next, you need to create a user so that you can access the frontend. Replace the credentials in the following command and run it: However for **production use** you also want to mount a data folder on your system, so that the applications database is not stored in the container, but on your hosts file system. This is safer in case something happens to the container and makes it easier to update the container later on, or to run backups. To do so you can use the following extended command, where you replace `{host-data-folder}` with the absolute path to a folder on your system where you want to store the data:
``` ```
docker exec -it linkding python manage.py createsuperuser --username=joe --email=joe@example.com docker run --name linkding -p 9090:9090 -v {host-data-folder}:/etc/linkding/data -d sissbruecker/linkding:latest
``` ```
The command will prompt you for your password.
If everything completed successfully the application should now be running and can be accessed at http://localhost:9090, provided you did not change the port mapping. If everything completed successfully the application should now be running and can be accessed at http://localhost:9090, provided you did not change the port mapping.
### Manual ### Automated Docker setup
If you can not or don't want to use Docker you can install the application manually on your server. To do so you can basically follow the steps from the *Development* section below while cross-referencing the Dockerfile on how to make the application production-ready. If you are using a Linux system you can use the following [shell script](https://github.com/sissbruecker/linkding/blob/master/install-linkding.sh) for an automated setup. The script does basically everything described above, but also handles updating an existing container to a new application version (technically replaces the existing container with a new container built from a newer image, while mounting the same data folder).
The script can be configured using using shell variables - for more details have a look at the script itself.
### User setup
Finally you need to create a user so that you can access the frontend. Replace the credentials in the following command and run it:
```
docker exec -it linkding python manage.py createsuperuser --username=joe --email=joe@example.com
```
The command will prompt you for a secure password. After the command has completed you can start using the application by logging into the UI with your credentials.
### Manual setup
If you can not or don't want to use Docker you can install the application manually on your server. To do so you can basically follow the steps from the *Development* section below while cross-referencing the `Dockerfile` and `bootstrap.sh` on how to make the application production-ready.
### Hosting ### Hosting
The application runs in a web-server called [uWSGI](https://uwsgi-docs.readthedocs.io/en/latest/) that is production-ready and that you can expose to the web. If you don't know how to configure your server to expose the application to the web there are several more steps involved. I can not support support the process here, but I can give some pointers on what to search for: The application runs in a web-server called [uWSGI](https://uwsgi-docs.readthedocs.io/en/latest/) that is production-ready and that you can expose to the web. If you don't know how to configure your server to expose the application to the web there are several more steps involved. I can not support support the process here, but I can give some pointers on what to search for:
- get the app running (described in this document) - first get the app running (described in this document)
- open the port that the application is running on in your servers firewall - open the port that the application is running on in your servers firewall
- depending on your network configuration, forward the opened port in your network router, so that the application can be addressed from the internet using your public IP address and the opened port - depending on your network configuration, forward the opened port in your network router, so that the application can be addressed from the internet using your public IP address and the opened port
@ -50,7 +65,7 @@ For backups you have two options: manually or automatic.
For manual backups you can export your bookmarks from the UI and store them on a backup device or online service. For manual backups you can export your bookmarks from the UI and store them on a backup device or online service.
For automatic backups you want to backup the applications database. Using Docker you can [mount](https://stackoverflow.com/questions/23439126/how-to-mount-a-host-directory-in-a-docker-container) the `/etc/linkding/data` folder from the container to the host and use the backup tool of your choice to backup the contents of that folder. For automatic backups you want to backup the applications database. As described above, for production setups you should [mount](https://stackoverflow.com/questions/23439126/how-to-mount-a-host-directory-in-a-docker-container) the `/etc/linkding/data` directory from the Docker container to a directory on your host system. You can then use a backup tool of your choice to backup the contents of that directory.
## Development ## Development

View file

@ -1,5 +1,4 @@
#!/usr/bin/env bash #!/usr/bin/env bash
./build-static.sh ./build-static.sh
#docker build -t sissbruecker/linkding .
docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v7 -t sissbruecker/linkding:latest --push . docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v7 -t sissbruecker/linkding:latest --push .

43
install-linkding.sh Normal file
View file

@ -0,0 +1,43 @@
#!/usr/bin/env bash
# Script for creating or updating a linkding installation / Docker container
# The script uses a number of variables that control how the container is set up
# and where the application data is stored on the host
# The following variables are available:
#
# LD_CONTAINER_NAME - name of the Docker container that should be created or updated
# LD_HOST_PORT - port on your system that the application will use
# LD_HOST_DATA_DIR - directory on your system where the applications database will be stored
#
# Variables can be from your shell like this:
# export LD_HOST_DATA_DIR=/etc/linkding/data
# Provide default variable values
if [ -z "${LD_CONTAINER_NAME}" ]; then
LD_CONTAINER_NAME="linkding"
fi
if [ -z "${LD_HOST_PORT}" ]; then
LD_HOST_PORT=9090
fi
if [ -z "${LD_HOST_DATA_DIR}" ]; then
LD_HOST_DATA_DIR=/etc/linkding/data
fi
echo "Create or update linkding container"
echo "Container name: ${LD_CONTAINER_NAME}"
echo "Host port: ${LD_HOST_PORT}"
echo "Host data dir: ${LD_HOST_DATA_DIR}"
echo "Stop existing container..."
docker stop ${LD_CONTAINER_NAME} || true
echo "Remove existing container..."
docker rm ${LD_CONTAINER_NAME} || true
echo "Update image..."
docker pull sissbruecker/linkding:latest
echo "Start container..."
docker run -d \
-p ${LD_HOST_PORT}:9090 \
--name ${LD_CONTAINER_NAME} \
-v ${LD_HOST_DATA_DIR}:/etc/linkding/data \
sissbruecker/linkding:latest
echo "Done!"