Skip to main content

Installation

info

This guide covers the installation and configuration of the on-premise (self hosting) version of Texterify. If you are using the cloud version you can ignore this installation instructions, because all of the things are already covered by the Texterify team for you.

Requirements#

Tools:

  • docker
  • docker-compose

Accounts/Servers:

  • Email server or email provider account (optional but recommended)
  • DeepL account (optional)
  • Google Cloud Account (optional)

Starting the service#

To get you up as easy as possible run the following commands to get a complete docker-compose setup up and running:

# Clone the docker-compose configuration.
git clone https://github.com/texterify/texterify-docker-compose-setup.git
cd texterify-docker-compose-setup
# Generate a secret key for the app.
# Make sure to keep this private.
echo SECRET_KEY_BASE=`openssl rand -hex 64` > secrets.env
# Open the .env file and replace "example.com" with your host (if you
# are trying to run Texterify locally just use "localhost" as host).
# Also make sure to check out the other configuration options (see below).
# Start the service.
docker volume create --name=texterify-database
docker volume create --name=texterify-assets
docker-compose up --always-recreate-deps
# After everything has started create the database in another terminal.
docker-compose exec app bin/rails db:create db:migrate db:seed

The service is now available at http://localhost (or whatever you have set your APP_HOST to). ๐ŸŽ‰

Creating the admin account#

After installation you should immediately create an account, because the first registered user on the system is the instance admin account.

Updating the service#

To update the service change the TEXTERIFY_TAG to a new version. Make sure to backup your database so no data is lost in case of a failure. You can then run the following commands to update Texterify to the new version:

# Stop the current service.
docker-compose down
# Get the latest changes to the docker-compose setup.
# See https://github.com/texterify/texterify-docker-compose-setup for changes.
git pull
docker-compose build
# Start the service which will update Texterify to the new version.
docker-compose up --always-recreate-deps
# In case there are database changes apply them.
docker-compose exec app bin/rails db:migrate db:seed

Configuration#

The table below gives an overview of things you can configure in your Texterify instance. Make sure to also check out the .env file.

NameDefaultDescription
MAILER_HOSTexample.comSet the domain of the emails sent from Texterify (e.g. no-reply@example.com for the default value).
APP_HOSTexample.comThe fully qualified name of the web server (for example used for constructing email links).
ASSET_HOSTexample.comThe fully qualified name of the asset server. This is normally the same as the APP_HOST.
EMAIL_CONFIRMATION_REQUIREDfalseWhether email confirmation is required or not. If set to true make sure to also configure your email server.
DB_PROD_HOSTdbThe database host.
DB_PROD_USERNAMEpostgresThe database username.
DB_PROD_DATABASEtexterify_productionThe name of your database.
DB_PROD_PASSWORDThe password of your database user if needed.
http_proxySpecify a HTTP proxy for your application.

External services#

Texterify makes use of some external services. Below you find instructions on how to configure them.

E-Mail#

You need to configure a mail server so Texterify can send emails (e.g. password forgot emails). Make use of the following configuration options to integrate your mail server or provider:

NameDefaultDescription
SMTP_ADDRESSlocalhostThe address of the mail server.
SMTP_PORT25The port of the mail server.
SMTP_DOMAINIf you need to specify a HELO domain.
SMTP_USER_NAMESpecify a username if your server requires authentication.
SMTP_PASSWORDSpecify a password if your server requires authentication.
SMTP_AUTHENTICATIONYou can specify the authentication type here. Choose one of the following if needed:
  • plain (will send the password in the clear)
  • login (will send password Base64 encoded)
  • cram_md5 (combines a Challenge/Response mechanism to exchange information and a cryptographic Message Digest 5 algorithm to hash important information)
SMTP_ENABLE_STARTTLS_AUTOtrueDetermines if STARTTLS is enabled in your SMTP server and starts to use it.
SMTP_OPENSSL_VERIFY_MODEWhen you use TLS you can define how OpenSSL checks the certificate. Choose one of the following if needed:
  • none
  • peer
SMTP_TLSfalseEnables the SMTP connection to use SMTP/TLS (SMTPS: SMTP over direct TLS connection).

Machine translation#

Texterify does all the handling around machine translation for you, but the text is finally translated by DeepL. Therefore if you want to use machine translation you need to configure DeepL:

NameDefaultDescription
DEEPL_API_TOKENIf you want to use machine translation you need to create an account on www.deepl.com and set your API token here.
info

This feature requires communication outside of your network. If a proxy is required for communication you can set the proxy with the http_proxy environment variable.

Over the air translations#

The over the air feature works by hosting the translation files on the Google Cloud. If you need to make use of this feature you will have to create a storage bucket and configure it:

NameDefaultDescription
GOOGLE_CLOUD_PROJECTThe name of your Google Cloud project.
GOOGLE_CLOUD_KEYFILEThe Google Cloud key file used for authentication. See here for more information.
GOOGLE_CLOUD_OTA_BUCKET_NAMEThe name of the bucket used for storing the translation bundles.
info

This feature requires communication outside of your network. If a proxy is required for communication you can set the proxy with the http_proxy environment variable.

Debugging#

If you experience any issues you can always check the logs of the application which might give a hint about the issue you are currently facing. To view the logs start the app and then execute the following commands:

docker exec -it texterify-docker-compose-setup_app_1 /bin/sh
cat log/production.log

This will give you the logs of the application server.