Skip to main content

Deploy

Currently, Docker is the only supported way to deploy Cherry.

Deploy with Docker

docker run -d --name cherry -v cherry_data_v1:/data \
-p "8000:8000" \
-e "JWT_SECRET=some-secret-string" \
-e "ENABLE_PUBLIC_REGISTRATION=1" \
ghcr.io/haishanh/cherry:main

By default the SQLite database file will be created under /data, you should map a Docker volume(or bind mount) to /data like the command above. -e ENABLE_PUBLIC_REGISTRATION=1 will enable registration, you probably want to remove this or set it to 0 to disable registration if you already registered.

Cherry listens on port 8000 for HTTP traffic, in most of the cases you will want to expose Cherry with something like Nginx, Caddy, Traefik or Cloudflare tunnel for SSL etc.

info

You may see this message in the docker logs

Listening on 0.0.0.0:5173

This is printed by SvelteKit, a framework/library that powers Cherry. You should treat this port as a internal thing, don't use or expose this port outside of the container.

note on cookie

Cherry uses Secure cookie which only works with HTTPS. It works with "localhost" in some browsers too, so you should try use "localhost:8000" instead of "127.0.0.1:8000" or "0.0.0.0:8000" when running locally.

If that doesn't work, try set the environment variable USE_INSECURE_COOKIE to 1. You shouldn't set this flag after you've setup reverse proxy and got HTTPS working.

Environment Variables

JWT_SECRET (required)

This string will be used to sign user's PAT (Personal Access Token). PAT is in the format of a JWT (JSON Web Token), it's used to verify and identify an Cherry user. You should keep your JWT_SECRET a secret to prevent others from forging tokens.

ENABLE_PUBLIC_REGISTRATION

This value determins whether registration is enabled from outside (of your Cherry Docker container instance). Set it to 1 to enable registration. By default, or with other values, registration is disabled. Most likely you want to enable registration after the fresh deployment and disable it just after you've created the user.

note

Without setting ENABLE_PUBLIC_REGISTRATION to 1 you can still register an user via the internal admin API inside the Docker container.

USE_INSECURE_COOKIE

By default Cherry uses Secure cookie which only works with HTTPS. But if you want to try run Cherry on your localhost you may set this environment variable to 1 to temporarily disable secure cookie, or you may not able to sign in.

ENABLE_HTTP_REMOTE_USER, HTTP_REMOTE_USER_HEADER_NAME

Set ENABLE_HTTP_REMOTE_USER to 1 to enable authentication via the HTTP header "Remote-User"(can be changed use HTTP_REMOTE_USER_HEADER_NAME). This should only be enabled if you have an authentication gateway (like Authelia or Authentik) stands in front of Cherry that authenticates user. The value of the "Remote-User" header will be treated as username of a Cherry user. If this user doesn't exits, Cherry will create it automatically. In other places, Cherry may enforce you to use email as username, but it's not enforced in this case.

GOOGLE_OAUTH_CLIENT_ID, GOOGLE_OAUTH_CLIENT_SECRET, GOOGLE_OAUTH_REDIRECT_URI

These are required only if you want to enable "Sign in with Google". You can find your client ID and client secret after created the Google OAuth2 client. GOOGLE_OAUTH_REDIRECT_URI should be {YOUR_CHERRY_BASE_URL}/api/auth/callback/google, you will need to config it as one of the "Authorized redirect URIs" in your Goolge OAuth2 client.

Since you can have many "Authorized redirect URIs" in one client, you can acutally reuse this client for different applications(Of course this is a bad practice for serious stuff though). Note, it may take some time (5 minutes according to Google) for your "Authorized redirect URIs" change to take effect.

DATA_DIR

This specify the directory where files, like temporary export CSV files, will be saved. By default the value is /data.

DATABASE_PATH

This specify the location of the SQLite database file. By default the value is /data/cherry.sqlite.

PAGE_BOOKMARK_LIMIT

Bookmarks per page, default to 60.