Skip to content

Commit 1132163

Browse files
m-messerm-messer
authored
Initial commit
0 parents  commit 1132163

File tree

8 files changed

+467
-0
lines changed

8 files changed

+467
-0
lines changed

‎.github/workflows/build.yml‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
name: Build Evaluation Function Image
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
pull_request:
8+
workflow_dispatch:
9+
10+
jobs:
11+
build:
12+
uses: lambda-feedback/evaluation-function-workflows/.github/workflows/build.yml@main
13+
with:
14+
build-target: final
15+
permissions:
16+
contents: read
17+
id-token: write
18+
packages: write

‎.github/workflows/deploy.yml‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
name: Deploy to Lambda Feedback
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
- master
8+
workflow_dispatch:
9+
10+
jobs:
11+
setup:
12+
runs-on: ubuntu-latest
13+
permissions:
14+
contents: read
15+
id-token: write
16+
steps:
17+
- name: Checkout
18+
uses: actions/checkout@v4
19+
with:
20+
fetch-depth: 0
21+
22+
- name: Check Wolfram Licence Key
23+
env:
24+
MATHPASS: ${{ secrets.WOLFRAM_ENGINE_MATHPASS }}
25+
if: ${{ env.MATHPASS == '' }}
26+
run: |
27+
echo "Set WOLFRAM_ENGINE_MATHPASS in secrets"
28+
exit 1
29+
30+
deploy:
31+
uses: lambda-feedback/evaluation-function-workflows/.github/workflows/deploy.yml@main
32+
needs: setup
33+
with:
34+
template-repository-name: "lambda-feedback/evaluation-function-boilerplate-wolfram"
35+
build-target: final-private
36+
permissions:
37+
contents: read
38+
id-token: write
39+
packages: write
40+
secrets:
41+
aws-key-id: ${{ secrets.LAMBDA_CONTAINER_PIPELINE_AWS_ID }}
42+
aws-secret-key: ${{ secrets.LAMBDA_CONTAINER_PIPELINE_AWS_SECRET}}
43+
function-admin-api-key: ${{ secrets.FUNCTION_ADMIN_API_KEY}}
44+
build-secrets: |
45+
"mathpass=${{ secrets.WOLFRAM_ENGINE_MATHPASS }}"

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
mathpass

‎Dockerfile‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
FROM ghcr.io/lambda-feedback/evaluation-function-base/wolfram:latest AS final
2+
3+
# Use the WSTP server as a kernel backend
4+
ENV WSTP_SERVER="true"
5+
6+
# Command to start the evaluation function with
7+
ENV FUNCTION_COMMAND="wolframscript"
8+
9+
# Args to start the evaluation function with
10+
ENV FUNCTION_ARGS="-f,/app/evaluation_function.wl"
11+
12+
# Interface to use for the evaluation function
13+
ENV FUNCTION_INTERFACE="file"
14+
15+
# Copy the evaluation function to the app directory
16+
COPY ./evaluation_function.wl /app/evaluation_function.wl
17+
18+
# Final layer for private images, which contains the wolfram licence key,
19+
# and is started with the shimmy handle command.
20+
FROM final AS final-private
21+
22+
# Copy the mathpass secret to the Wolfram Engine licensing directory.
23+
# See https://hub.docker.com/r/wolframresearch/wolframengine for more information.
24+
RUN --mount=type=secret,id=mathpass \
25+
mkdir -p /tmp/home/.WolframEngine/Licensing && \
26+
cp /run/secrets/mathpass /tmp/home/.WolframEngine/Licensing/mathpass
27+
28+
29+
RUN apt-get update && apt-get install -y \
30+
netcat \
31+
&& rm -rf /var/lib/apt/lists/*
32+
33+
COPY ./entrypoint.sh /entrypoint.sh

‎README.md‎

Lines changed: 265 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,265 @@
1+
# Wolfram Language Evaluation Function
2+
3+
This repository contains the boilerplate code needed to create a containerized evaluation function written in Wolfram Language.
4+
5+
## Quickstart
6+
7+
This chapter helps you to quickly set up a new Wolfram evaluation function using this template repository.
8+
9+
> [!NOTE]
10+
> After setting up the evaluation function, delete this chapter from the `README.md` file, and add your own documentation.
11+
12+
#### 1. Create a new repository
13+
14+
- In GitHub, choose `Use this template` > `Create a new repository` in the repository toolbar.
15+
16+
- Choose the owner, and pick a name for the new repository.
17+
18+
> [!IMPORTANT]
19+
> If you want to deploy the evaluation function to Lambda Feedback, make sure to choose the Lambda Feedback organization as the owner.
20+
21+
- Set the visibility to `Public` or `Private`.
22+
23+
> [!IMPORTANT]
24+
> If you want to use GitHub [deployment protection rules](https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment#deployment-protection-rules), make sure to set the visibility to `Public`.
25+
26+
- Click on `Create repository`.
27+
28+
#### 2. Clone the new repository
29+
30+
Clone the new repository to your local machine using the following command:
31+
32+
```bash
33+
git clone <repository-url>
34+
```
35+
36+
#### 3. Configure the evaluation function
37+
38+
When deploying to Lambda Feedback, set the evaluation function name in the `config.json` file. Read the [Deploy to Lambda Feedback](#deploy-to-lambda-feedback) section for more information.
39+
40+
#### 4. Develop the evaluation function
41+
42+
You're ready to start developing your evaluation function. Head over to the [Development](#development) section to learn more.
43+
44+
#### 5. Update the README
45+
46+
In the `README.md` file, change the title and description so it fits the purpose of your evaluation function.
47+
48+
Also, don't forget to delete the Quickstart chapter from the `README.md` file after you've completed these steps.
49+
50+
## Usage
51+
52+
You can run the evaluation function either using [the pre-built Docker image](#run-the-docker-image) or build and run [the binary executable](#build-and-run-the-binary).
53+
54+
### Run the Docker Image
55+
56+
The pre-built Docker image comes with [Shimmy](https://github.com/lambda-feedback/shimmy) installed.
57+
58+
> [!TIP]
59+
> Shimmy is a small application that listens for incoming HTTP requests, validates the incoming data and forwards it to the underlying evaluation function. Learn more about Shimmy in the [Documentation](https://github.com/lambda-feedback/shimmy).
60+
61+
The pre-built Docker image is available on the GitHub Container Registry. You can run the image using the following command:
62+
63+
```bash
64+
docker run -p 8080:8080 ghcr.io/lambda-feedback/evaluation-function-boilerplate-wolfram:latest
65+
```
66+
67+
### Run the Script
68+
69+
You can choose between running the Wolfram evaluation function itself, ore using Shimmy to run the function.
70+
71+
**Raw Mode**
72+
73+
Use the following command to run the evaluation function directly:
74+
75+
```bash
76+
wolframscript -f evaluation_function.wl request.json response.json
77+
```
78+
79+
This will run the evaluation function using the input data from `request.json` and write the output to `response.json`.
80+
81+
**Shimmy**
82+
83+
To have a more user-friendly experience, you can use [Shimmy](https://github.com/lambda-feedback/shimmy) to run the evaluation function.
84+
85+
To run the evaluation function using Shimmy, use the following command:
86+
87+
```bash
88+
shimmy -c "wolframscript" -a "-f" -a "evaluation_function.wl" -i file
89+
```
90+
91+
## Development
92+
93+
### Prerequisites
94+
95+
- [Docker](https://docs.docker.com/get-docker/)
96+
- [Wolfram Engine](https://www.wolfram.com/engine/)
97+
- [Wolfram Engine License](#development-license)
98+
99+
### Repository Structure
100+
101+
```bash
102+
.github/workflows/
103+
build.yml # builds the public evaluation function image
104+
deploy.yml # deploys the evaluation function to Lambda Feedback
105+
106+
evaluation_function.wl # evaluation function source code
107+
108+
config.json # evaluation function deployment configuration file
109+
```
110+
111+
### Development Workflow
112+
113+
In its most basic form, the development workflow consists of writing the evaluation function in the `evaluation_function.wl` file and testing it locally. As long as the evaluation function adheres to the Evaluation Function API, a development workflow which incorporates using Shimmy is not necessary.
114+
115+
Testing the evaluation function can be done by running the script using the Wolfram Engine / WolframScript like so:
116+
117+
```bash
118+
wolframscript -f evaluation_function.wl request.json response.json
119+
```
120+
121+
> [!NOTE]
122+
> Put the input data in the `request.json` file, and the output will be written to the `response.json` file.
123+
124+
### Building the Docker Image
125+
126+
To build the Docker image, run the following command:
127+
128+
```bash
129+
docker build -t my-wolfram-evaluation-function .
130+
```
131+
132+
## Deployment
133+
134+
This section guides you through the deployment process of the evaluation function. If you want to deploy the evaluation function to Lambda Feedback, follow the steps in the [Lambda Feedback](#deploy-to-lambda-feedback) section. Otherwise, you can deploy the evaluation function to other platforms using the [Other Platforms](#deploy-to-other-platforms) section.
135+
136+
### Deploy to Lambda Feedback
137+
138+
Deploying the evaluation function to Lambda Feedback is simple and straightforward, as long as the repository is within the [Lambda Feedback organization](https://github.com/lambda-feedback).
139+
140+
After configuring the repository, a [GitHub Actions workflow](.github/workflows/deploy.yml) will automatically build and deploy the evaluation function to Lambda Feedback as soon as changes are pushed to the main branch of the repository.
141+
142+
**Configuration**
143+
144+
The deployment configuration is stored in the `config.json` file. Choose a unique name for the evaluation function and set the `EvaluationFunctionName` field in [`config.json`](config.json).
145+
146+
> [!IMPORTANT]
147+
> The evaluation function name must be unique within the Lambda Feedback organization, and must be in `lowerCamelCase`. You can find a example configuration below:
148+
149+
```json
150+
{
151+
"EvaluationFunctionName": "compareStringsWithWolfram"
152+
}
153+
```
154+
155+
### Deploy to other Platforms
156+
157+
If you want to deploy the evaluation function to other platforms, you can use the Docker image to deploy the evaluation function.
158+
159+
Please refer to the deployment documentation of the platform you want to deploy the evaluation function to.
160+
161+
If you need help with the deployment, feel free to reach out to the Lambda Feedback team by creating an issue in the template repository.
162+
163+
## Wolfram Engine License
164+
165+
Wolfram Engine requires a valid license to run. For developing purposes, you can obtain a free Wolfram Engine license. This process is described in the following steps. If you want to read more about licensing, please refer to the [Wolfram Engine Licensing Documentation](https://hub.docker.com/r/wolframresearch/wolframengine).
166+
167+
### Production License
168+
169+
**1. Sign in to Wolfram Cloud**
170+
171+
Head over to the [Wolfram Cloud](https://www.wolframcloud.com/) and sign in or create a new Wolfram ID. If you don't have a Wolfram subscription, you can sign up for a free Wolfram Cloud Basic subscription.
172+
173+
**2. Create License Entitlement**
174+
175+
After signing in, open a Wolfram Cloud notebook and evaluate the [`CreateLicenceEntitlement`](https://reference.wolfram.com/language/ref/CreateLicenseEntitlement.html) function.
176+
177+
```text
178+
In[1]:= entitlement = CreateLicenseEntitlement[]
179+
180+
Out[1]= LicenseEntitlementObject[O-WSTD-DA42-GKX4Z6NR2DSZR, ...]
181+
```
182+
183+
**3. Obtain the License Key**
184+
185+
Run the following command to obtain the entitlement ID:
186+
187+
```text
188+
In[2]:= entitlement["EntitlementID"]
189+
190+
Out[2]= O-WSTD-DA42-GKX4Z6NR2DSZR
191+
```
192+
193+
**4. Use the License Key**
194+
195+
Create an environment variable named `WOLFRAMSCRIPT_ENTITLEMENTID` with the entitlement ID:
196+
197+
```text
198+
WOLFRAMSCRIPT_ENTITLEMENTID=O-WSTD-DA42-GKX4Z6NR2DSZR
199+
```
200+
201+
This environment variable activates Wolfram Engine when running the `wolframscript` command.
202+
203+
### Development License
204+
205+
**1. Sign in or create a Wolfram ID.**
206+
207+
Head over to the [Wolfram Account Portal](https://account.wolfram.com/login/create) and sign in or create a new account.
208+
209+
**2. Get the Wolfram Engine license**
210+
211+
[Obtain the free license](https://www.wolfram.com/engine/free-license/) by following the instructions.
212+
213+
**3. Activate the Wolfram Engine license**
214+
215+
Run the following command and enter your Wolfram Account credentials to generate a password for the license:
216+
217+
```bash
218+
docker run -it wolframresearch/wolframengine
219+
```
220+
221+
While still in the container, run the following command to print the password:
222+
223+
```plain
224+
In[1] := $PasswordFile // FilePrint
225+
1e1d781ed0a3 6520-03713-97466 4304-2718-2K5ATR 5095-179-696:2,0,8,8:80001:20190627
226+
```
227+
228+
This gives you a password that you can copy to a `mathpass` file on your host machine.
229+
230+
**4. Run the Wolfram Engine container**
231+
232+
Run the following command to start the Wolfram Engine container with the license:
233+
234+
```bash
235+
docker run -it --rm -v $(pwd)/mathpass:/home/wolframengine/.WolframEngine/Licensing/mathpass wolframresearch/wolframengine
236+
```
237+
238+
This command assumes that you have a `mathpass` file in the current directory, and the container is started with the `wolframengine` user.
239+
240+
## FAQ
241+
242+
### Pull Changes from the Template Repository
243+
244+
If you want to pull changes from the template repository to your repository, follow these steps:
245+
246+
1. Add the template repository as a remote:
247+
248+
```bash
249+
git remote add template https://github.com/lambda-feedback/evaluation-function-boilerplate-wolfram.git
250+
```
251+
252+
2. Fetch changes from all remotes:
253+
254+
```bash
255+
git fetch --all
256+
```
257+
258+
3. Merge changes from the template repository:
259+
260+
```bash
261+
git merge template/main --allow-unrelated-histories
262+
```
263+
264+
> [!WARNING]
265+
> Make sure to resolve any conflicts and keep the changes you want to keep.

‎config.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
"EvaluationFunctionName": ""
3+
}

0 commit comments

Comments
 (0)