Configuration ​

Before starting your instance for the first time, some configuration is required. All core configuration of SideStore Connect is done using environment variables. This is true for both docker-based installs as well as locally run instances.

Environment Variables ​

The environment variables can either be supplied using a .env file in the same directory as the docker-compose.yml (recommended) or directly below the app service's environment directive in the docker-compose.yml file.

For installs without docker, the environment variables for the frontend and backend should be placed in .env files in the respective project root folders.

An example for an .env file with all relevant configuration options is shown below:

FLASK_ENV=production
FLASK_SECRET_KEY=

# Database settings
FLASK_SQLALCHEMY_DATABASE_URI=sqlite:///database.sqlite
FLASK_SQLALCHEMY_TRACK_MODIFICATIONS=False

FLASK_JWT_SECRET_KEY=

# These are required values and should not be changed.
FLASK_JWT_TOKEN_LOCATION=["headers", "json", "cookies"]
FLASK_JWT_COOKIE_SECURE=True
FLASK_JWT_COOKIE_SAMESITE=strict
FLASK_JWT_JSON_KEY=access_token
FLASK_JWT_REFRESH_JSON_KEY=refresh_token
FLASK_JWT_ACCESS_CSRF_HEADER_NAME=X-Xsrf-Token

# CORS settings
FLASK_CORS_ORIGINS=*

# Mail settings
FLASK_MAIL_SERVER=mail.example.com
FLASK_MAIL_PORT=587
FLASK_MAIL_USE_TLS=1
FLASK_MAIL_USE_SSL=0
FLASK_MAIL_USERNAME=[email protected]
FLASK_MAIL_PASSWORD=
FLASK_MAIL_DEFAULT_SENDER=SideStore Connect <[email protected]m>

# Database admin interface settings
DB_ADMIN_INTERFACE_ENABLED=False

# SideStore Connect Info
PUBLIC_URL=
REPOSITORY_NAME=SideStore Connect
REPOSITORY_IDENTIFIER=

# Storage
LOCAL_STORAGE_PATH=/data/storage

# Initial user email
INITIAL_USER_EMAIL=

# Two factor authentication
AUTH_TOTP_VALID_WINDOW=

# Enter GitHub OAuth Info to enable Sign in with GitHub 
GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=

FLASK_ENV=production
FLASK_SECRET_KEY=

# Database settings
FLASK_SQLALCHEMY_DATABASE_URI=sqlite:///database.sqlite
FLASK_SQLALCHEMY_TRACK_MODIFICATIONS=False

FLASK_JWT_SECRET_KEY=

# These are required values and should not be changed.
FLASK_JWT_TOKEN_LOCATION=["headers", "json", "cookies"]
FLASK_JWT_COOKIE_SECURE=True
FLASK_JWT_COOKIE_SAMESITE=strict
FLASK_JWT_JSON_KEY=access_token
FLASK_JWT_REFRESH_JSON_KEY=refresh_token
FLASK_JWT_ACCESS_CSRF_HEADER_NAME=X-Xsrf-Token

# CORS settings
FLASK_CORS_ORIGINS=*

# Mail settings
FLASK_MAIL_SERVER=mail.example.com
FLASK_MAIL_PORT=587
FLASK_MAIL_USE_TLS=1
FLASK_MAIL_USE_SSL=0
FLASK_MAIL_USERNAME=[email protected]
FLASK_MAIL_PASSWORD=
FLASK_MAIL_DEFAULT_SENDER=SideStore Connect <[email protected]m>

# Database admin interface settings
DB_ADMIN_INTERFACE_ENABLED=False

# SideStore Connect Info
PUBLIC_URL=
REPOSITORY_NAME=SideStore Connect
REPOSITORY_IDENTIFIER=

# Storage
LOCAL_STORAGE_PATH=/data/storage

# Initial user email
INITIAL_USER_EMAIL=

# Two factor authentication
AUTH_TOTP_VALID_WINDOW=

# Enter GitHub OAuth Info to enable Sign in with GitHub 
GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=

Flask ​

The values that need to be changed from the template configuration above are the following:

• FLASK_SECRET_KEY
  Used for signing session cookies and other security related tasks. Generate it according to the official Flask documentation with

  bash

  python -c 'import secrets; print(secrets.token_hex())'

  python -c 'import secrets; print(secrets.token_hex())'

  1
  

• FLASK_JWT_SECRET_KEY
  Used for signing and verifying JWT tokens. Generate it the same way as the FLASK_SECRET_KEY.

• FLASK_CORS_ORIGINS
  The host of your domain where SideStore Connect will be hosted. Default is * which allows all hosts.

Database ​

• FLASK_SQLALCHEMY_DATABASE_URI
  The uri for connecting to your database.
  When using PostgresSQL, it should look like postgresql://username:password@host:port/sidestore-connect. If deployed through docker-compose, the host can be set to the name of the service of your database, e.g. db.
  When using SQLite and docker, the uri should be set to sqlite:////data/database.sqlite and an additional mount of ./data/database.sqlite:/data/database.sqlite needs to be added to the volumes directive of your docker-compose.yml. If docker is not used, set it to sqlite:///database.sqlite.

E-Mail ​

• FLASK_MAIL_SERVER
  The address of your SMTP server.

• FLASK_MAIL_PORT
  The port of your SMTP server.

• FLASK_MAIL_USE_TLS, FLASK_MAIL_USE_SSL
  Integer ∈ {0, 1} indicating whether your SMTP server uses a secure SSL connection or if the connection itself is unencrypted but the data should be encrypted using TLS.

• FLASK_MAIL_USERNAME
  The user name required to log in to SMTP server.

• FLASK_MAIL_PASSWORD
  The password required to log in to SMTP server.

• FLASK_MAIL_DEFAULT_SENDER
  The sender used for all E-Mail sent by SideStore Connect.

Storage ​

• LOCAL_STORAGE_PATH
  The path used by the local storage driver to store ipa files, app screenshots and icons as well as news banner images.
  For docker-compose-based installs, this should be set according to your mount option in the docker-compose.yml, which is /data/storage for default installations.
  For locally running instances, this can be any path, relative or absolute, as long as the user running the server has access to that folder.

Setup ​

• PUBLIC_URL
  The full public url to the SideStore Connect instance, used for building links and the "Add Source to SideStore" button.

• REPOSITORY_NAME
  The name for your source as shown in SideStore.

• REPOSITORY_IDENTIFIER
  A unique identifier for your SideStore Source. The easiest option is to use the host of your instance url in reverse domain name notation, e.g. ml.sidestore.connect.

• INITIAL_USER_EMAIL
  When SideStore Connect is first started, it creates a default organization and an invite for a user with the email address specified in this environment variable. See the inital setup documentation for more details.

• AUTH_TOTP_VALID_WINDOW (optional) Allows to accept the n valid TOTPs from before and after the currently valid one.
  Default: 0.

• GITHUB_CLIENT_ID (optional)
  The client id of your GitHub OAuth application used for providing "Sign in with GitHub" functionality. For configuring the OAuth application, please refer to GitHub's documentation.
  If this functionality should not be available on your SideStore Connect instance, leave this value blank.
  Default: (blank)

• GITHUB_CLIENT_SECRET (optional)
  The client secret of your GitHub OAuth application used for providing "Sign in with GitHub" functionality.
  If this functionality should not be available on your SideStore Connect instance, leave this value blank.
  Default: (blank)

Reverse Proxy (optional) ​

When exposing SideStore Connect to the public internet, a reverse proxy can be used for further access control and for making the service available alongside others on the same port (most likely 443 for SSL).

There are many different applications that provide reverse proxy functionality available. The following is an example for the web server software nginx. Examples for other applications may be added in the future.

server {
    server_name your.domain.here;
    listen 80;

    return 301 https://$host$request_uri;
}

server {
    server_name your.domain.here;
    listen 443 ssl;

    ssl_certificate your/ssl/cert-chain.pem;
    ssl_certificate_key your/ssl/private-key.pem;
    
    # If you use certbot for ssl certificate management:
    # include /etc/letsencrypt/options-ssl-nginx.conf;
    # ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;

    location / {
        # Change '5G' to what you want to accept as maximum ipa file size
        client_max_body_size 5G;
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Frame-Options SAMEORIGIN;
        proxy_pass_header X-CSRF-TOKEN;

        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        # Replace PORT with the port set in your docker-compose.yml
        proxy_pass http://127.0.0.1:PORT;
    }
}

server {
    server_name your.domain.here;
    listen 80;

    return 301 https://$host$request_uri;
}

server {
    server_name your.domain.here;
    listen 443 ssl;

    ssl_certificate your/ssl/cert-chain.pem;
    ssl_certificate_key your/ssl/private-key.pem;
    
    # If you use certbot for ssl certificate management:
    # include /etc/letsencrypt/options-ssl-nginx.conf;
    # ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;

    location / {
        # Change '5G' to what you want to accept as maximum ipa file size
        client_max_body_size 5G;
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Frame-Options SAMEORIGIN;
        proxy_pass_header X-CSRF-TOKEN;

        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        # Replace PORT with the port set in your docker-compose.yml
        proxy_pass http://127.0.0.1:PORT;
    }
}

Starting your Instance ​

If you have configured and saved your environment variables it is time to start your instance for the first time.

Docker ​

For docker-compose-based installs, simply run

docker-compose up -d

docker-compose up -d

to start your application and database containers.

Your instance should now be up and running! 🎉
If not, refer to the Troubleshooting section of this page.

Manual Install ​

To serve the frontend locally for development purposes, use:

npm run dev

npm run dev

If you want to build the frontend, use

npm run build

npm run build

and make sure that the GITHUB_CLIENT_ID variable is set if "Sign in with GitHub" should be used.

Troubleshooting ​

If you have issues with your install, you should look at the server logs first. On docker-compose-based installs the logs can be viewed in real-time using:

docker-compose logs -f

docker-compose logs -f