self-hosted/joplin
1
0
Fork 0
mirror of https://github.com/laurent22/joplin.git synced 2025-01-23 18:53:36 +02:00
Code Issues Releases Activity

Update README.md (#6295)

Browse Source
This commit is contained in:
ScriptInfra 2022-04-10 05:53:44 -04:00 committed by GitHub
parent 0b32a29cce
commit 0d4978223e
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 36 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

60
packages/server/README.md
View File

@ -1,23 +1,24 @@
# Installing
## Configuration
## Requirements
First copy `.env-sample` to `.env` and edit the values in there:
- Docker Engine runs Joplin Server. See [Install Docker Engine](https://docs.docker.com/engine/install/) for steps to install Docker Engine for your operating system.
- Docker Compose is required to store item contents (notes, tags, etc.) if PostgreSQL is not used. See [Install Docker Compose](https://docs.docker.com/compose/install/) for steps to install Docker Compose for your operating system.
- `APP_BASE_URL`: This is the base public URL where the service will be running. For example, if you want it to run from `https://example.com/joplin`, this is what you should set the URL to. The base URL can include the port.
- `APP_PORT`: The local port on which the Docker container will listen. You would typically map this port to 443 (TLS) with a reverse proxy.
## Configure Docker for Joplin Server
## Running the server
To start the server with default configuration, run:
1. Copy `.env-sample` (located [here](https://github.com/laurent22/joplin/blob/dev/.env-sample)) to the location of your Docker configuration files. Example: /home/[user]/docker
2. Rename the file `.env-sample` to `.env`.
3. Run the following command to test starting the server using the default configuration:
```shell
docker run --env-file .env -p 22300:22300 joplin/server:latest
```
This will start the server, which will listen on port **22300** on **localhost**. By default it will use SQLite, which allows you to test the app without setting up a database. To run it for production though, you'll want to connect the container to a database, as described below.
The server will listen on port **22300** on **localhost**. By default, the server will use SQLite, which allows you to test the app without setting up a database. When running the server for production use, you should connect the container to a database, as described below.
## Supported docker tags
## Supported Docker tags
The following tags are available:
@ -29,7 +30,7 @@ The following tags are available:
## Setup the database
You can setup the container to either use an existing PostgreSQL server, or connect it to a new one using docker-compose
You can setup the container to either use an existing PostgreSQL server, or connect it to a new database using docker-compose.
### Using an existing PostgreSQL server
@ -44,39 +45,48 @@ POSTGRES_PORT=5432
POSTGRES_HOST=localhost
```
Make sure that the provided database and user exist as the server will not create them. When running on macOS or Windows through Docker Desktop, a mapping of localhost is made automatically. On Linux, you can add `--net=host --add-host=host.docker.internal:127.0.0.1` to the `docker run` command line to make the mapping happen. Any other `POSTGRES_HOST` than localhost or 127.0.0.1 should work as expected without further action.
Ensure that the provided database and user exist as Joplin Server will not create them. When running on macOS or Windows through Docker Desktop, a mapping of localhost is made automatically. On Linux, you can add `--net=host --add-host=host.docker.internal:127.0.0.1` to the `docker run` command line to make the mapping happen. Any other `POSTGRES_HOST` than localhost or 127.0.0.1 should work as expected without further action.
### Using docker-compose
A [sample docker-compose file](https://github.com/laurent22/joplin/blob/dev/docker-compose.server.yml
) is available to show how to use Docker to install both the database and server and connect them:
1. Using the [sample docker-compose file](https://github.com/laurent22/joplin/blob/dev/docker-compose.server.yml), create a docker compose file in the location of your Docker configuration files. Example: /home/[user]/docker/docker-compose.yml
2. Update the fields in the docker-compose file as seen in the sample file.
## Setup reverse proxy
Once Joplin Server is running, you will then need to expose it to the internet by setting up a reverse proxy, and that will depend on how your server is currently configured, and whether you already have Nginx or Apache running:
This step is optional.
Configuring a reverse proxy is not required for core functionality and is only required if Joplin Server needs to be accessible over the internet. See the following documentation for configuring a reverse proxy with Apache or Nginx.
- [Apache Reverse Proxy](https://httpd.apache.org/docs/current/mod/mod_proxy.html)
- [Nginx Reverse Proxy](https://docs.nginx.com/nginx/admin-guide/web-server/reverse-proxy/)
## Setup storage
By default, the item contents (notes, tags, etc.) are stored in the database and you don't need to do anything special to get that working.
This step is optional.
However since that content can be quite large, you also have the option to store it outside the database by setting the `STORAGE_DRIVER` environment variable.
By default, the item contents (notes, tags, etc.) are stored in the database and no additional steps are required to get that working.
However, since that content can be quite large, you have the option to store it outside the database by setting the `STORAGE_DRIVER` environment variable.
### Setting up storage on a new installation
Again this is optional - by default items will simply be saved to the database. To save to the local filesystem instead, use:
This step is optional.
To save item contents (notes, tags, etc.) to the local filesystem instead, use:
STORAGE_DRIVER=Type=Filesystem; Path=/path/to/dir
Then all item data will be saved under this `/path/to/dir` directory.
After this is set, all item contents will be saved under the defined `/path/to/dir` directory.
### Migrating storage for an existing installation
Migrating storage is a bit more complicated because the old content will have to be migrated to the new storage. This is done by providing a fallback driver, which tells the server where to look if a particular item is not yet available on the new storage.
This step is optional.
To migrate from the database to the file system for example, you would set the environment variables like so:
Migrating storage is a bit more complicated because the old content will have to be migrated to the new storage. This is done by providing a fallback driver, which tells the server where to look if a particular item is not yet available on the new storage.
To migrate from the database to the file system, you would set the environment variables as follows:
STORAGE_DRIVER=Type=Filesystem; Path=/path/to/dir
STORAGE_DRIVER_FALLBACK=Type=Database; Mode=ReadAndWrite
@ -111,13 +121,15 @@ Besides the database and filesystem, it's also possible to use AWS S3 for storag
STORAGE_DRIVER=Type=S3; Region=YOUR_REGION_CODE; AccessKeyId=YOUR_ACCESS_KEY; SecretAccessKeyId=YOUR_SECRET_ACCESS_KEY; Bucket=YOUR_BUCKET
## Setup the website
## Verify access to the admin page
Once the server is exposed to the internet, you can open the admin UI and get it ready for synchronisation. For the following instructions, we'll assume that the Joplin server is running on `https://example.com/joplin`.
Once Joplin Server is exposed to the internet, open the admin UI. For the following instructions, we'll assume that Joplin Server is running on `https://example.com/joplin`.
### Secure the admin user
If Joplin Server is running running locally only, access the Admin Page using `http://[hostname]:22300`
By default, the instance will be setup with an admin user with email **admin@localhost** and password **admin** and you should change this. To do so, open `https://example.com/joplin/login` and login as admin. Then go to the Profile section and change the admin password.
### Update the admin user credentials
By default, Joplin Server will be setup with an admin user with email **admin@localhost** and password **admin**. For security purposes, the admin user's credentials should be changed. On the Admin Page, login as the admin user. In the upper right, select the Profile button update the admin password.
### Create a user for sync