groupdocs/conversion-cloud repository overview

⁠Document Conversion in the Cloud

Product Page⁠ | Docs⁠ | Demos⁠ | Swagger UI⁠ | Examples⁠ | Blog⁠ | Search⁠ | Free Support⁠ | Free Trial⁠

GroupDocs.Conversion Cloud is a REST API for converting over 50 documents and image formats to Words, Excel, HTML, PDF, PowerPoint and image formats for the whole document, page by page or custom range of pages. This Docker image makes it possible to use GroupDocs Conversion Cloud API on a single machine or integrate into your existing application or system solution.

⁠Quick Start

GroupDocs.Conversion can be started in trial and licensed modes. Optionally you can enable authentication by setting predefined credentials.

⁠Start in Trial Mode

To start the container and run GroupDocs.Conversion Cloud in trial mode type the following.

⁠Windows (PowerShell)

docker run `
    -p 8080:80 `
    -v "${pwd}/data:/data" `
    --name conversion_cloud `
    groupdocs/conversion-cloud

⁠Linux (bash)

docker run \
    -p 8080:80 \
    -v $(pwd)/data:/data \
    --name conversion_cloud \
    groupdocs/conversion-cloud

Wait for the startup process to complete you should see the following log:

info: GroupDocs.Conversion.Cloud.Web.Startup[0]
      "License" parameters are omitted, the app works in trial mode.
...

As you can see from the messages above GroupDocs.Conversion Cloud is working in a trial mode so trial limitations are applied:

• You can convert only two first pages of the document.
• Evaluation watermarks added to the output.

⁠Start in Licensed Mode

In case you already have the license keys we can run GroupDocs.Conversion Cloud in licensed mode. To do so pass license private and public keys as environment variables as shown below.

⁠Windows (PowerShell)

docker run `
    -p 8080:80 `
    -v "${pwd}/data:/data" `
    -e "LICENSE_PUBLIC_KEY=public_key" `
    -e "LICENSE_PRIVATE_KEY=private_key" `
    --name conversion_cloud `
    groupdocs/conversion-cloud

⁠Linux (bash)

docker run \
    -p 8080:80 \
    -v $(pwd)/data:/data \
    -e LICENSE_PUBLIC_KEY=public_key \
    -e LICENSE_PRIVATE_KEY=private_key \
    --name conversion_cloud \
    groupdocs/conversion-cloud

After the container is started you should see the message that indicates that license has been set successfully:

info: GroupDocs.Conversion.Cloud.Web.Startup[0]
      The license has been set.
...

You can get metered license consumtion by calling API method described here⁠

⁠Enable Authentication

To enable authentication set CLIENT_ID/CLIENT_SECRET parameters as it shown below. Please note, authentication is required in case you're going to use SDK⁠.

The TOKEN_SECRET is used as the symmetric key for signing JWT tokens with the HMAC-SHA256 algorithm. • If the TOKEN_SECRET environment variable is set, its value will be used as the signing key. • If the TOKEN_SECRET is not set, the application will generate a random 256-bit secret at runtime. This random secret is not persisted and will change every time the application restarts.

⁠Windows (PowerShell)

docker run `
    -p 8080:80 `
    -v "${pwd}/data:/data" `
    -e "CLIENT_ID=client_id" `
    -e "CLIENT_SECRET=client_secret" `
    -e "TOKEN_SECRET=aifvtf67769fydrdjh089y86f7cfnr6e5ev856db7ii8t787rtb6r689f07t897tk907tn8f6b68d987yh0u" `    
    --name conversion_cloud `
    groupdocs/conversion-cloud

⁠Linux (bash)

docker run \
    -p 8080:80 \
    -v $(pwd)/data:/data \
    -e CLIENT_ID=client_id \
    -e CLIENT_SECRET=client_secret \
    -e TOKEN_SECRET=aifvtf67769fydrdjh089y86f7cfnr6e5ev856db7ii8t787rtb6r689f07t897tk907tn8f6b68d987yh0u \    
    --name conversion_cloud \
    groupdocs/conversion-cloud

⁠Enable Google Cloud Storage

By default, a local storage used inside container for file operations. It's possible to connect a Google Cloud storage by setting GOOGLE_APPLICATION_CREDENTIALS and GOOGLE_STORAGE_BUCKET environment variables.

⁠Windows (PowerShell)

docker run `
    -p 8080:80 `
    -v "${pwd}/data:/data" `
    -e "GOOGLE_APPLICATION_CREDENTIALS=/data/key.json" `
    -e "GOOGLE_STORAGE_BUCKET=bucket_id" `
    --name conversion_cloud `
    groupdocs/conversion-cloud

⁠Linux (bash)

docker run \
    -p 8080:80 \
    -v $(pwd)/data:/data \
    -e GOOGLE_APPLICATION_CREDENTIALS=/data/key.json \
    -e GOOGLE_STORAGE_BUCKET=bucket_id \
    --name conversion_cloud \
    groupdocs/conversion-cloud

⁠Enable AWS S3 Cloud Storage

By default, a local storage used inside container for file operations. It's possible to connect a AWS S3 Cloud storage by setting environment variables:

⁠Windows (PowerShell)

docker run `
    -p 8080:80 `
    -v "${pwd}/data:/data" `
    -e "S3_STORAGE_BUCKET=main_bucket" `
    -e "S3_STORAGE_ACCESS_KEY=XXXXXXXXXXXXXXXXXXX" `
    -e "S3_STORAGE_SECRET_KEY=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" `
    -e "S3_STORAGE_REGION=us-west-2" `
    --name conversion_cloud `
    groupdocs/conversion-cloud

⁠Linux (bash)

docker run \
    -p 8080:80 \
    -v $(pwd)/data:/data \
    -e S3_STORAGE_BUCKET=main_bucket \
    -e S3_STORAGE_ACCESS_KEY=XXXXXXXXXXXXXXXXXXX \
    -e S3_STORAGE_SECRET_KEY=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX \
    -e S3_STORAGE_REGION=us-west-2" \
    --name conversion_cloud \
    groupdocs/conversion-cloud

⁠Health Check

When the container and GroupDocs.Conversion Cloud started you can check service status by calling GET http://localhost:8080/. The successful response status is 200 which means that service is up and running.

⁠Windows (PowerShell)

Invoke-WebRequest -Uri http://localhost:8080/

⁠Linux (bash)

curl -i http://localhost:8080/

⁠Using the UI

After starting, you can use Swagger UI at http://localhost:8080/swagger/⁠ and start exploring the API.

⁠Stopping

To stop the running Docker container, just use Ctrl+C in the same terminal where the container is running. Alternatively, you can stop the container by name.

docker stop conversion_cloud

⁠Automatic shutdown and restart

Since v24.2, an automatic shutdown feature was added. By default, if out-of memory exception occurs, the application and container stops gracefully. To continue runnung the container in this case, an automatic restart option should be applied, when starting the container:

⁠Windows (PowerShell)

docker run `
    --restart always `
    -p 8080:80 `
    -v "${pwd}/data:/data" `
    --name conversion_cloud `
    groupdocs/conversion-cloud

⁠Linux (bash)

docker run \
    --restart always \
    -p 8080:80 \
    -v $(pwd)/data:/data \
    --name conversion_cloud \
    groupdocs/conversion-cloud

In addition, to have more control of the container stability, a new parameter was added: CONVERSIONS_LIMIT. When it set, the service counts the number of conversions, and if the number exceeds the limit, the application and container stops gracefully. To continue runnung the container, as in previous case, an automatic restart option should be applied:

⁠Windows (PowerShell)

docker run `
    --restart always `
    -p 8080:80 `
    -v "${pwd}/data:/data" `
    -e "CONVERSIONS_LIMIT=100" `
    --name conversion_cloud `
    groupdocs/conversion-cloud

⁠Linux (bash)

docker run \
    --restart always \
    -p 8080:80 \
    -v $(pwd)/data:/data \
    -e CONVERSIONS_LIMIT=100 \
    --name conversion_cloud \
    groupdocs/conversion-cloud

⁠Container Configuration

⁠Volumes

⁠Parameters

⁠Things to Remember

• If "License" parameters are omitted, the app will work in trial mode.
• If "CLIENT_ID" parameter is set, each request requires "Authorization" header (JWT Authentication).
• The URL to obtain token is "/connect/token".

⁠Next Steps

We generate our SDKs in different languages so you may check if yours is available in the following list. If you don't find your language, feel free to request for it on our Support Forum⁠, or use raw REST API requests as detailed on GroupDocs.Conversion Cloud for cURL⁠.

⁠GroupDocs.Conversion Cloud SDKs in Popular Languages

Product Page⁠ | Docs⁠ | Demos⁠ | Swagger UI⁠ | Examples⁠ | Blog⁠ | Search⁠ | Free Support⁠ | Free Trial⁠